TIBCO ActiveMatrix BPM BPM Developers Guide

Software Release 1.3 March 2012

Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, The Power of Now, TIBCO Enterprise Message Service and TIBCO ActiveMatrix are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright 2005-2012 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

Contents i

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii xxiii xxiii xxiii

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
TIBCO ActiveMatrix BPM Components and Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 TIBCO ActiveMatrix BPM APIs and How to Obtain Them . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 BPM Web Service API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Java Service Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Obtaining Information From TIBCO Business Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Work Data Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Formal Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Migration Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Version 1.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 2 Developing a .NET Client Application Using the Web Service API . . . . . . . . . . . . . 11
The BPMTestApplication Example Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting the BPMTestApplication Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BPMTestApplication Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Service Model Code for BPM Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Choice Elements in the BPM API Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 13 13 14 15 15 15 16

Configuring Service Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Authenticating the Calling User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Obtaining the Calling Users GUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

TIBCO ActiveMatrix BPM - BPM Developers Guide

ii

| Contents
Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Writing Adapter Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Writing the Application Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Rendering a Form for a Work Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FormRedirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The onTIBCOFormRunnerLoad Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 34 34 36 37

Chapter 3 Developing a Client Application Using the Java Service Connector API . . . . . . . . 43
Overview of the Java Service Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Enabling the Java Service Connector for Your Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 44 The Sample Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting the SampleApp Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 47 47 49

Instantiating and Configuring the Service Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Setting up the Security Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Authenticating the Calling User. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Executing the Service Connector API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Implementing the Client User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Rendering a Form for a Work Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying the Work Item Data as a TIBCO form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The onTIBCOFormRunnerLoad Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 62 62 66 67

Chapter 4 Authenticating Access to a TIBCO ActiveMatrix BPM Service . . . . . . . . . . . . . . . . 71

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Direct Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Single Sign-on (SSO) Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SSO Authentication Using an X.509 Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SSO Authentication Using a SAML Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Establishing a Trust Relationship Between TIBCO ActiveMatrix BPM and the Client Application. . . . . . . . .
TIBCO ActiveMatrix BPM - BPM Developers Guide

74 74 75 76

Contents iii

Runtime Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Implementing SSO Authentication Using a SAML Token. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Handling Time Differences Between the Client System and the BPM Runtime When Using Validity Periods in a SAML Assertion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Using the Service Connector SamlSenderVouchesSecurityHandler Method. . . . . . . . . . . . . . . . . . . . . . . . 80 Using TIBCO ActiveMatrix BPM as the Authority for SSO Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create the Public Root Certificate and BPM Truststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generate a Client Certificate and Keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create a SAML Assertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 82 83 84

Chapter 5 Working With Organization Models and LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Creating an LDAP Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Mapping Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Creating Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Navigating the Organization Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Listing Capabilities and Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Using LDAP Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Defining Secondary LDAP Sources in an LDAP Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Mapping Resource Attributes to LDAP Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Resource Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting LDAP Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 119 120 121

Organization Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Overriding Organization Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Chapter 6 Working With Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Listing Available Process Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listProcessTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . queryProcessTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . queryProcessTemplatesAlt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Available Process Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listProcessInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . queryProcessInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . queryProcessInstancesAlt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sorting and Filtering Lists of Process Templates and Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query Parameter Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query Parameter Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query Parameter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Date/Time Data Type Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query Parameter Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 129 132 135 145 146 147 149 151 151 152 154 156 157

Starting a Process Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

TIBCO ActiveMatrix BPM - BPM Developers Guide

iv

| Contents
Process Instance State Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Migrating a Process Instance to a Different Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Chapter 7 Working with Work Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Introduction to Work Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Retrieving a Work List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Sorting and Filtering Work Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Sort/Filter Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Sort/Filter Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Creating and Managing Supervised Work List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Chapter 8 Working with Work Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Introduction to Work Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Work Item Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Work Item States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Work Item State Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Retrieving Information on Work Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Offering and Allocating Work Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Allocating Work Item to a Target Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reallocating a Work Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reoffering a Work Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Progressing a Work Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . openWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . closeWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . completeWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . skipWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . saveOpenWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pendWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling a Work Item That Contains Business Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Hidden Work Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of Processing a Work Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing a Work Item with a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing Chained Work Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 201 207 209 212 212 213 214 214 215 215 215 216 218 220 222 223

Opening a Work Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Chapter 9 Working With Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Using TIBCO Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Binding the Client Application to a Channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

TIBCO ActiveMatrix BPM - BPM Developers Guide

Contents v

Identifying the Client Channel in a Service Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 Rendering a TIBCO Business Studio Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Displaying a Work Item Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Displaying a Form in a Pageflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Displaying a Form in a Business Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Using Custom Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Presentation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Data Format and Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Chapter 10 Working With Business Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Starting a Business Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Displaying a Form in a Business Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Injecting a Business Service Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Chapter 11 Working With Pageflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Starting and Processing a Pageflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Injecting a Pageflow Event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Chapter 12 Working with Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Executing a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registered Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Correlated Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Query Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter Expression Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Attributes in Query Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AUDIT Option Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PROCESS_METRICS Option Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PROCESS_STATS Option Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WORKITEM_STATS Option Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REGISTERED_QUERIES Option Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REGISTERED_COMPONENTS Option Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REGISTERED_ATTRIBUTES Option Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . USER_ACTIVITY Option Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Categories and Attribute Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 286 287 288 289 289 289 292 293 294 299 301 302 304 304 305 306 307

Example Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Event Measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Event Measure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

TIBCO ActiveMatrix BPM - BPM Developers Guide

vi

| Contents
requestProcessDurationMeasure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 requestProcessTemplateMeasure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 requestWorkItemPerformanceForTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Chapter 13 TIBCO ActiveMatrix BPM Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Business Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 API Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Business Resource Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 API Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Calendar Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 API Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Directory Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 API Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Event Collection Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 API Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Pageflow Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 API Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Process Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 API Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 Work Presentation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 API Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Chapter 14 AttributeService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

listBusinessParameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 getBusinessParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 setBusinessParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 getPushDestinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

TIBCO ActiveMatrix BPM - BPM Developers Guide

Contents vii

Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 setPushDestinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Chapter 15 BrowseModelService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

listModelVersions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Service Connector API (Java Method)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 openOrgModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Service Connector API (Java Method)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 browseModelNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 listOrgModelOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Service Connector API (Java Method)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 listCapabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Service Connector API (Java Method)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 listPrivileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Service Connector API (Java Method)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 getCapabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Service Connector API (Java Method)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 getPrivileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 Service Connector API (Java Method)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 listOrganizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Service Connector API (Java Method)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Chapter 16 BusinessDeadlineService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

calcBusinessDeadline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

TIBCO ActiveMatrix BPM - BPM Developers Guide

viii

| Contents
Chapter 17 BusinessService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
listCategories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 queryCategories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 listBusinessServices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 queryBusinessServices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 startBusinessService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 updateBusinessService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 injectBusinessServiceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 cancelBusinessService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

Chapter 18 CalendarService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

updateWorkingDays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 addWorkingDayExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 updateWorkingDayExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 deleteWorkingDayExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 getCalendarEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

TIBCO ActiveMatrix BPM - BPM Developers Guide

Contents ix

Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

Chapter 19 ContainerService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

listLDAPContainers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 getLDAPContainerDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 saveLDAPContainerDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 deleteLDAPContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

Chapter 20 EntityResolverService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

getResourceDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 listAssociatedResources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 lookupUser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

Chapter 21 EventCollectorQueryService. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

executeGenericQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 executeRegisteredGenericQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 getAllAttributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 getAttributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 getComponents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
TIBCO ActiveMatrix BPM - BPM Developers Guide

| Contents
Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 isQueryRegistered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 registerQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 unRegisterQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 lookupQueryByTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

Chapter 22 EventCollectorMeasuresService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

requestProcessDurationMeasure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 requestProcessTemplateMeasure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 requestWorkItemPerformanceForTemplate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 requestWorkItemPerformanceForResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

Chapter 23 ExporterService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

exportResources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 importResources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

Chapter 24 LDAPService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

listLDAPSources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 listLDAPEntities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
TIBCO ActiveMatrix BPM - BPM Developers Guide

Contents xi

Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 listLDAPAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 listLDAPAttributeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 listContainerResources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510

Chapter 25 MappingService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511

listMappedEntities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 mapEntities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 getResourceGuid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 deleteResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 updateCapabilityAssignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Chapter 26 OrganisationalEntityConfigService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525

getOrgEntityConfigAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 setOrgEntityConfigAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 getOrgEntityConfigAttributesAvailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 deleteOrgEntityConfigAttributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535

TIBCO ActiveMatrix BPM - BPM Developers Guide

xii

| Contents
Chapter 27 PageFlowService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
listPageFlows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 startPageFlow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 updatePageFlow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 injectPageFlowEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550 cancelPageFlow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

Chapter 28 ProcessManagerService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553

cancelProcessInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 cancelProcessInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 createProcessInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 getActivityInstanceStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 getParameterValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 getProcessInstanceStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 getProcessInstanceSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 getStarterOperationInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

TIBCO ActiveMatrix BPM - BPM Developers Guide

Contents xiii

Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 listProcessInstanceAttributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577 listSetofProcessInstanceAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 listProcessInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 listProcessTemplateAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 listProcessTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 listStarterOperations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 queryDone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 queryFirstPage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 queryLastPage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 queryNextPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 queryPreviousPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 queryProcessInstanceCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 queryProcessInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 queryProcessInstancesAlt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

TIBCO ActiveMatrix BPM - BPM Developers Guide

xiv

| Contents
SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 queryProcessTemplateCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 queryProcessTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 queryProcessTemplatesAlt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 resumeProcessInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 resumeProcessInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 setDeadlineExpiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 setPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 suspendProcessInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638 suspendProcessInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 getMigrationPoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642 setMigrationRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645 unsetMigrationRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 clearMigrationRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649 Java Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

TIBCO ActiveMatrix BPM - BPM Developers Guide

Contents xv

isSetMigrationRule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 SOAP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 Java Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 listMigrationRules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654

Chapter 29 ResourceQueryService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

executeQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

Chapter 30 SecurityService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

authenticateUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 getUserPrivileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 isActionAuthorised . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 listActionAuthorisedEntities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668 listAuthorisedOrgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

Chapter 31 UserSettingsService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

saveUserSettings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674 getUserSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676 deleteUserSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 listUserSettingIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680

TIBCO ActiveMatrix BPM - BPM Developers Guide

xvi

| Contents
Chapter 32 WorkItemManagementService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
getWorkItemHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684 openWorkItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687 closeWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691 allocateWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694 allocateAndOpenWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 allocateAndOpenNextWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702 unallocateWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705 completeWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709 skipWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711 reallocateWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714 reallocateWorkItemData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 getOfferSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720 saveOpenWorkItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722 Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 pendWorkItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725

TIBCO ActiveMatrix BPM - BPM Developers Guide

Contents xvii

Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726

Chapter 33 WorkListService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729

getWorkListItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 getAllocatedWorkListItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 previewWorkItemFromList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 getWorkItemOrderFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742 getResourceOrderFilterCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744 setResourceOrderFilterCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746

Chapter 34 WorkPresentationService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747

openWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750 cancelWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752 closeWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755 completeWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758 openNextWorkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760 Service Connector API (Java Method) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762 getBusinessServiceDetailsByModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763 Web Service API (SOAP Operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764

TIBCO ActiveMatrix BPM - BPM Developers Guide

xviii Contents

Service Connector API (Java Method). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

Appendix A System Actions Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767

System Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768 Scope of System Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773

Appendix B TIBCO Forms Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781

Integrating TIBCO Forms with Custom Client Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Injecting the Forms Runtime Adapter in the Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typical flow of events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Forms Runtime Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782 783 783 787

TIBCO ActiveMatrix BPM - BPM Developers Guide

| xix

Preface

TIBCO ActiveMatrix BPM is TIBCOs next-generation business process management platform. This document provides information for developers producing applications to be used with TIBCO ActiveMatrix BPM. For demonstration purposes only, Web service API (SOAP) examples shown in this guide have been generated using the open source tool soapUI (available from http://www.soapui.org.).

Topics
Changes from the Previous Release of this Guide, page xx Typographical Conventions, page xxi Connecting with TIBCO Resources, page xxiii

TIBCO ActiveMatrix BPM - BPM Developers Guide

xx

| Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide
This section itemizes the major changes from the previous release of this guide. Information on working with work items has been expanded and moved into its own chapter - see Working with Work Items on page 189. A failing process instance may change to Suspended instead of Failed in certain situations - see Process Instance State Transitions on page 159. Valid Format for ComplexSpec Business Data on page 216 describes how business data must be specified when used with different operations. Information on working with business services has been expanded and moved into its own chapter - see Working With Business Services on page 259. Information on working with pageflows has been expanded and moved into its own chapter - see Working With Pageflows on page 277. Information about integrating TIBCO forms with custom applications has been added - see TIBCO Forms Reference on page 781.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Preface xxi

Typographical Conventions
The following typographical conventions are used in this manual. Table 1 General Typographical Conventions Convention
TIBCO_HOME

Use Many TIBCO products must be installed within the same home directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME depends on the operating system. For example, on Windows systems, the default value is C:\Program Files (x86)\tibco. TIBCO ActiveMatrix BPM installs into a directory within TIBCO_HOME. The value depends on the operating system. For example on Windows systems, the default value is C:\Program Files (x86)\tibco\amx-bpm.

code font

Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use MyCommand to start the foo process.

bold code font

Bold code font is used in the following ways: In procedures, to indicate what a user types. For example: Type admin. In large code samples, to indicate the parts of the sample that are of particular interest. In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled:
MyCommand [enable | disable]

italic font

Italic font is used in the following ways: To indicate a document title. For example: See TIBCO ActiveMatrix BPM Concepts. To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName

Key combinations

Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

TIBCO ActiveMatrix BPM - BPM Developers Guide

xxii

| Typographical Conventions
Table 1 General Typographical Conventions (Contd) Convention Use The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances. The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result. The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken. Table 2 Syntax Typographical Conventions Convention
[ ]

Use An optional item in a command or code syntax. For example:

MyCommand [optional_parameter] required_parameter

A logical OR that separates multiple items of which only one may be chosen. For example, you can select only one of the following parameters:
MyCommand para1 | param2 | param3

{ }

A logical group of items in a command. Other syntax notations may appear within each logical group. For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4.
MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4:
MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4.
MyCommand param1 [param2] {param3 | param4}

TIBCO ActiveMatrix BPM - BPM Developers Guide

Preface xxiii

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.

How to Access TIBCO Documentation

You can access TIBCO documentation here: http://docs.tibco.com

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support as follows: For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: http://www.tibco.com/services/support If you already have a valid maintenance or support contract, visit this site: https://support.tibco.com Entry to this site requires a user name and password. If you do not have a user name, you can request one.

TIBCO ActiveMatrix BPM - BPM Developers Guide

xxiv Connecting with TIBCO Resources

TIBCO ActiveMatrix BPM - BPM Developers Guide

|1
Chapter 1

Introduction

This chapter provides some introductory material that you should be aware of before using the TIBCO ActiveMatrix BPM API to invoke BPM web services.

Topics
TIBCO ActiveMatrix BPM Components and Services, page 2 TIBCO ActiveMatrix BPM APIs and How to Obtain Them, page 4 Obtaining Information From TIBCO Business Studio, page 7 Migration Issues, page 9

TIBCO ActiveMatrix BPM - BPM Developers Guide

| Chapter 1

Introduction

TIBCO ActiveMatrix BPM Components and Services

TIBCO ActiveMatrix BPM is implemented as a number of independent components that expose services, exploiting the benefits of the Service Component Architecture (SCA) provided by the TIBCO ActiveMatrix runtime. These components are grouped into a set of logical nodes, of different types. (A logical node is a heterogeneous group of application fragments that must be deployed to the same physical node.) Figure 1 provides an overview of this architecture, illustrating: the main interactions between logical nodes. the main external services provided by TIBCO ActiveMatrix BPM.

Figure 1 TIBCO ActiveMatrix BPM - logical nodes and services

Web Service API endpoints Web Components (Workspace / Openspace)

Service virtualization

Process Manager Process services Event Collection services Calendar services

Work Manager Business Resource Management services Work Presentation services Pageflow services BPM Node BPM runtime Directory services Business services

Table 3 briefly summarizes the main functions provided by each logical node type.

TIBCO ActiveMatrix BPM - BPM Developers Guide

TIBCO ActiveMatrix BPM Components and Services 3

Table 3 TIBCO ActiveMatrix BPM logical node and service summaries Logical Node Process Manager Description Provides the following services: Process services - which execute business process management applications that have been designed in TIBCO Business Studio and deployed to the BPM runtime. Event Collection services - which collect and correlate business process events. Calendar services - which provide services such as working time and working availability information for BPM entities.

Work Manager

Provides a collection of services that deals with the management of human resources: Business Resource Management services - which are responsible for distributing and managing work. Directory services - which maintain the runtime organization model and provide all authentication and authorization services. Work Presentation services - which are used to get work presentation details for and perform actions on work items. Pageflow services - which are used to get information about and interact with deployed pageflows. Business services - which are used to get information about and interact with deployed business services.

Web Components (Workspace / Openspace clients)

Provides the runtime user interface to TIBCO ActiveMatrix BPM.

TIBCO ActiveMatrix BPM - BPM Developers Guide

| Chapter 1

Introduction

TIBCO ActiveMatrix BPM APIs and How to Obtain Them

TIBCO ActiveMatrix BPM provides two APIs that a client application can use to invoke services provided by the BPM runtime: BPM Web Service API Java Service Connector

BPM Web Service API

The BPM public web service API allows a client application to directly invoke BPM services using SOAP messages. You can obtain the BPM public web service API in two ways: You can download a zip file containing all the WSDL and supporting XSD files that constitute the BPM public web service API. (The data types used in the WSDL files are defined in external, shared XSDs. These XSDs are also included in this zip file.)

TIBCO ActiveMatrix BPM - BPM Developers Guide

TIBCO ActiveMatrix BPM APIs and How to Obtain Them 5

You can generate WSDL files for individual BPM services directly from TIBCO ActiveMatrix Administrator, as shown in the following example.

See the TIBCO ActiveMatrix Administrator documentation for more information about how to do this. A generated WSDL file contains just the definition of a specific service, including all XSD data types used by that service. Which Method Should I Use? If you are writing a large application that needs to access multiple BPM services, using the BPM public web service API may be preferable. When generating code-bindings, using external, shared XSDs can often produce easier to use code than duplicating the types at the top of each WSDL file.
TIBCO ActiveMatrix BPM - BPM Developers Guide

| Chapter 1

Introduction

If you are developing lightweight applications that access only a limited number of services, generated WSDLs may be suitable. For example, if you only wanted to access the EntityResolverService, using a generated WSDL would avoid the overhead of parsing the entire de.wsdl file, which provides access to all BPM Directory Services.

Java Service Connector

The Java Service Connector provides a Java wrapping for the BPM web service API, enabling a client application to invoke BPM services using local Java calls. See Overview of the Java Service Connector for more information.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Obtaining Information From TIBCO Business Studio 7

Obtaining Information From TIBCO Business Studio

A client application may need access to certain data about a BPM process that it cannot access programmatically at runtime. In this case, the application developer must build support for this data directly into the application, by: 1. obtaining the necessary information from the TIBCO Business Studio projects from which the BPM process is deployed. 2. modifying the client application as required to use this data. The following sections describe the data that must be obtained from TIBCO Business Studio: Work Data Models Formal Parameters

Work Data Models

A Work Data Model is an artifact that you can export from a TIBCO Business Studio project. It contains XML data definitions that a custom client application may need to enable it to handle XML data generated from user activities defined in the project processes (for work items, pageflow pages or business service pages). The client application cannot access this information programmatically. The following table shows the files included in a Work Data Model. File bomName.xsd Description Contains the generated XML schema for the bomName business object model. There will be a bomName.xsd file for: each business object model defined in the project. each business object model defined in a referenced project (whether or not data is referenced from that business object model).

You will need this information to handle a work item, pageflow or business service that uses any data fields or formal parameters that are defined (by external reference) as types in these schemas. See Handling a Work Item That Contains Business Data on page 216 for more information.

TIBCO ActiveMatrix BPM - BPM Developers Guide

| Chapter 1
File wt.xml

Introduction

Description Contains the XML data structures of all work types used in the project. (Each user activity in a business process has a work type associated with it. A work type defines the interface - input, output and inout parameters - to a work item.) You will need this information to display a work item using a custom form. See Using Custom Forms for more information.

pfActivityType.xml

Contains the XML data structure for each user activity in a pageflow process (or business service) in the project. You will need this information to display a page (for a pageflow or business service) using a custom form. See Using Custom Forms for more information.

wm.xml

Contains the XML data structures of all work models used in the project. Currently you do not need this information. For more information about Work Data Models and how to export them, see "Exporting Projects to a Work Data Model" in TIBCO Business Studio Process Modeling.

Formal Parameters
Various operations require you to specify the details of formal parameters used by a process. You cannot determine which data fields are formal parameters programmatically. Instead, you must obtain this information directly from the relevant project in TIBCO Business Studio.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Migration Issues 9

Migration Issues
This section describes issues that you should be aware of when migrating client applications to new versions of TIBCO ActiveMatrix BPM.

Version 1.3
Using getWorkListItems in a Client Application Up to and including version 1.2, the entityID element used by getWorkListItems is contained within a choice element.

In some programming environments (such as .NET in its default form), choice elements are represented by a parent entity (in this case, Item) which can be cast to any of the types which the choice allows. See Handling Choice Elements in the BPM API Schemas on page 16.

TIBCO ActiveMatrix BPM - BPM Developers Guide

10

| Chapter 1

Introduction

In version 1.3, the choice element has been removed.

An existing application built using the version 1.2 BPM web service API will continue to run against TIBCO ActiveMatrix BPM version 1.3. However, if you rebuild an existing application (that uses getWorkListItems) against the version 1.3 BPM web service API, you should change your code to directly use entityID (instead of casting).

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 11
Chapter 2

Developing a .NET Client Application Using the Web Service API

This chapter outlines the basic steps involved in using the web service API to develop a custom client application. It also describes an example .NET client application that is supplied with this guide to illustrate these steps.

Topics
The BPMTestApplication Example Client, page 12 Generating Service Model Code for BPM Services, page 15 Configuring Service Endpoints, page 19 Authenticating the Calling User, page 23 Obtaining the Calling Users GUID, page 25 Writing Adapter Methods, page 28 Writing the Application Layer, page 31 Rendering a Form for a Work Item, page 34

TIBCO ActiveMatrix BPM - BPM Developers Guide

12

| Chapter 2

Developing a .NET Client Application Using the Web Service API

The BPMTestApplication Example Client

BPMTestApplication is a simple Windows client application that uses the BPM web service API to call BPM services. The BPMTestApplication example is supplied "as is" with no warranties. The code in BPMTestApplication is intended as a simple illustration of the concepts and techniques needed to develop a custom client application. It is not intended as a basis for production-ready code and should not be used as such. BPMTestApplication provides the following functionality: It presents a LoginForm dialog that allows you to: select details of a BPM runtime (host, port and protocol). supply a username and password with which to login.

TIBCO ActiveMatrix BPM - BPM Developers Guide

The BPMTestApplication Example Client 13

It displays the worklist for the logged in user.

It allows you to open, close and submit work items from the work list, using standard TIBCO forms.

System Requirements
To be able to examine and run BPMTestApplication you must have the following software installed: Microsoft Visual Studio 2010 Microsoft .NET Framework 4

Getting the BPMTestApplication Solution

1. Download the BPMTestApplication.zip file. 2. Unzip the file to a suitable local directory. 3. Open the BPMTestApplication\BPMTestApplication.sln solution file in Visual Studio.

TIBCO ActiveMatrix BPM - BPM Developers Guide

14

| Chapter 2

Developing a .NET Client Application Using the Web Service API

BPMTestApplication Architecture
The BPMTestApplication solution contains two projects: BPMTestApplication - implements the application layer, which provides the client user interface and end-user functionality. ProxyLayer - provides the interface between the application layer and BPM services.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Generating Service Model Code for BPM Services 15

Generating Service Model Code for BPM Services

Requirement
1. Obtain the WSDL/XSD files for the BPM services that your application needs to use (see BPM Web Service API and TIBCO ActiveMatrix BPM Services). 2. Use an appropriate tool - for example, the .NET Framework ServiceModel Metadata Utility Tool (Svcutil.exe) - to generate a service model code file containing code that represents the BPM services. 3. Import the service model code file into your application project.

Implementation
BPMTestApplication uses Windows Communication Foundation (WCF) to manage its communication with BPM services. The services.cs file, in the ProxyLayer project of the BPMTestApplication solution, is a service model code file that represents the Business Resource Management Services, Directory Services and Work Presentation Services. The services.cs file was created using the following procedure: 1. Download the zip file containing the BPM public web service API. 2. Open a Microsoft Visual Studio command prompt. 3. Change to the directory containing the WSDL/XSD files. 4. Run the command:
Svcutil.exe /out:Services.cs brm.wsdl de.wsdl wp.wsdl *.xsd

Alternatively, you could use the following command to generate a service model code file that contains the entire BPM web service API:
Svcutil.exe /out:Services.cs *.wsdl *.xsd

5. Import Services.cs into the ProxyLayer project of the BPMTestApplication solution.

TIBCO ActiveMatrix BPM - BPM Developers Guide

16

| Chapter 2

Developing a .NET Client Application Using the Web Service API

Handling Choice Elements in the BPM API Schemas

Some elements in the BPM API schemas use xsd:choice elements. In some programming environments (such as .NET in its default form), when you generate the services.cs file, choice elements are represented by a parent entity (in this case, Item) which can be cast to any of the types which the choice allows For example, the .NET framework represents such elements as the first common parent of both types - typically object, with XmlElementAttribute attributes to serialize the type as an instance of the different types available in the choice. This means that you will need to programmatically determine the correct type of the field at runtime to correctly handle an instance of the field. For example, FieldType is a complexType that defines a single data field. It is returned as part of an openWorkItemresponse.workItemBody.dataModel element, to define the INPUT, OUTPUT and INOUT parameters that define the work items data model.

The definition contains an xsd:choice element that determines whether the field value is of type: simpleSpec - a simple data type (such as an integer or string) complexSpec - a business data type (derived from a Business Object Model class).

TIBCO ActiveMatrix BPM - BPM Developers Guide

Generating Service Model Code for BPM Services 17

When you generate the services.cs file, the .NET Framework translates this part of the XML schema into the following code:
public partial class FieldType { . . /// <remarks/> [System.Xml.Serialization.XmlElementAttribute("complexSpec", typeof(FieldTypeComplexSpec), Form = System.Xml.Schema.XmlSchemaForm.Unqualified, Order = 0)] [System.Xml.Serialization.XmlElementAttribute("simpleSpec", typeof(FieldTypeSimpleSpec), Form = System.Xml.Schema.XmlSchemaForm.Unqualified, Order = 0)] public object Item { get { return this.itemField; } set { this.itemField = value; } } . .

The field is given the object type, but also carries two XmlElementAttribute attributes - one tells the serialization engine to serialize the type as a fieldTypeComplexSpec instance, the other to serialize the type as a fieldTypeSimpleSpec instance. This indicates that the field could be either a simple type or a complex type. If you need to handle a piece of FieldType data in your code, at runtime you must programmatically determine whether the instance is of type fieldTypeComplexSpec or fieldTypeSimpleSpec. For example: 1. Use an if .. is condition to determine the objects data type. 2. Explicitly cast the object to the correct data type before processing it.

TIBCO ActiveMatrix BPM - BPM Developers Guide

18

| Chapter 2

Developing a .NET Client Application Using the Web Service API

if (field.Item is FieldTypeSimpleSpec) { FieldTypeSimpleSpec item = (FieldTypeSimpleSpec)field.Item; // Process item as a piece of simple data } else { FieldTypeComplexSpec item = (FieldTypeComplexSpec)field.Item; // Process item as a piece of business data }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Configuring Service Endpoints 19

Configuring Service Endpoints

Requirement
You must configure your application to use the endpoint addresses exposed by the particular BPM services you need to use. The WSDL files used to generate the WCF clients contain default endpoint addresses: A WSDL extracted from the public API uses a default of http://localhost:8080/servicePath. For example:

<wsdl:service name="EntityResolverService"> <wsdl:port name="EntityResolverService_EP" binding="impl:EntityResolverService_EP"> <soap:address location="http://localhost:8080/amxbpm/EntityResolverService"/> </wsdl:port> </wsdl:service> <wsdl:service name="WorkListService"> <wsdl:port name="WorkListService_EP" binding="impl:WorkListService_EP"> <soap:address location="http://localhost:8080/amxbpm/WorkListService"/> </wsdl:port> </wsdl:service>

A WSDL generated for a service from TIBCO Administrator uses a default of http://0.0.0.0:8080/servicePath. For example:

<wsdl:service name="WorkManager_implementation.de_1.2.0.001_service_EntityResolverService_1.2. 0_EntityResolverService_EntityResolverService"> <wsdl:port name="EntityResolverService.soap" binding="tns:EntityResolverService.soap"> <soap:address location="http://0.0.0.0:8080/amxbpm/EntityResolverService"/> </wsdl:port> </wsdl:service>

If necessary, you should reconfigure these endpoints to values appropriate to your requirements (either programmatically or via configuration).

TIBCO ActiveMatrix BPM - BPM Developers Guide

20

| Chapter 2

Developing a .NET Client Application Using the Web Service API

Implementation
BPMTestApplication allows a user to select the BPM runtime to which they want to connect. It therefore includes logic to dynamically set the endpoint before calling a BPM service. The ServiceClientFactory.cs file defines the ServiceClientFactory class. This class is the central entry point used to acquire the WCF client classes (defined in the services.cs file) which are used to call the BPM services. ServiceClientFactory uses the following methods to configure the endpoints to be used to contact each BPM service. The methods use the data gathered from the user in the login dialog (Host, Port and Use HTTPS values) to dynamically configure each endpoint. Method GetEntityResolverClient, GetWorkItemManagementServiceClient, GetWorkListServiceClient GetEntityUrl, GetWorkItemManagementServiceURL, GetWorkListServiceURL GetUrl, GetBaseURL CreateHttpBinding Description Gets the WCF client that calls the indicated service

Returns the URL for the indicated service

Generic methods, used by the Get*Url methods, to generate a URL for the service endpoint Creates an HTTP or HTTPS binding for the endpoint

For example, the GetWorkListServiceClient method creates a new WorkListServiceClient object.

public WorkListServiceClient GetWorkListServiceClient() { WorkListServiceClient clnt = new WorkListServiceClient( CreateHttpBinding("WorkListService.soap"), new EndpointAddress(GetWorkListServiceUrl())); clnt.Endpoint.Behaviors.Add(SecurityBehavior); return (clnt); }

GetWorkListServiceClient uses the following methods: CreateHttpBinding is used to create the appropriate HTTP binding type defining whether the SOAP message will be sent over HTTP (unsecured) or

TIBCO ActiveMatrix BPM - BPM Developers Guide

Configuring Service Endpoints 21

HTTPS (secured). The _secure value is derived from the Use HTTPS checkbox in the login dialog.
private BasicHttpBinding CreateHttpBinding(String name) { BasicHttpBinding binding; if (_secure) { binding = new BasicHttpBinding(BasicHttpSecurityMode.Transport); binding.Security.Transport.ClientCredentialType= HttpClientCredentialType.None; } else { binding = new BasicHttpBinding(BasicHttpSecurityMode.None); } binding.Name = name; return binding; }

The name parameter supplied can be any string. There is no requirement to match the port name value used in the WSDL file. GetWorkListServiceUrl is used to build the endpoint address string. The _host, _port and _secure values are derived from the Host, Port and Use HTTPS fields from the login dialog.

private string GetWorkListServiceUrl() { return GetUrl("amxbpm/WorkListService"); } private string GetUrl(string endpoint) { string protocol; if (_secure) { protocol = "https://"; } else { protocol = "http://"; } return protocol + _host + ":"+_port+"/" + endpoint; }

TIBCO ActiveMatrix BPM - BPM Developers Guide

22

| Chapter 2

Developing a .NET Client Application Using the Web Service API

The path component of the endpoint address (amxbpm/WorkListService) must match the one shown in the WSDL file from which the WorkListServiceClient object was derived. For simplicity, it is passed directly to GetURL as a hard-coded string in this example.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Authenticating the Calling User 23

Authenticating the Calling User

Requirement
Every API call which the client application makes to a BPM service must include an appropriate WS-Security token in the SOAP header. The token must be either: a UsernameToken, which specifies the username and password of the user on whose behalf the call is being made. (This is termed direct authentication.) an X.509 certificate or SAML token, if SSO authentication is being used. (This is termed Single Sign-on (SSO) authentication.)

A TIBCO ActiveMatrix BPM LDAP authentication application (for example, amx.bpm.auth.easyAs) uses this token to authenticate the calling user. If the token does not identify a known TIBCO ActiveMatrix BPM user, the call is rejected. See Authenticating Access to a TIBCO ActiveMatrix BPM Service for more information about direct and SSO authentication methods and how to use them in different situations.

Implementation
BPMTestApplication uses a UsernameToken to authenticate the calling user. WCF provides standard mechanisms to add a UsernameToken to the SOAP header of an outgoing message. However, these mechanisms cannot be used for authentication against a BPM service because the UsernameToken produced does not comply with the WS-Security standard. (See http://social.msdn.microsoft.com/Forums/en-US/wcf/thread/4df3354f-0627-4 2d9-b5fb-6e880b60f8ee.) Instead, BPMTestApplication implements a custom behavior to insert a WS-Security-compliant UsernameToken into the SOAP header of an outgoing message: 1. UsernameHeader.cs defines a custom SOAP header that includes a WS-Security-compliant UsernameToken, using the username and password supplied in the login dialog. (See Obtaining the Calling Users GUID.) 2. UsernameBehavior.cs and UsernameHeaderInspector.cs define a custom endpoint behavior which overwrites the default SOAP header with the custom header when a message to the endpoint is constructed. 3. A ServiceClientFactory constructor (in ServiceClientFactory.cs) adds the custom endpoint behavior to each WCF client object.

TIBCO ActiveMatrix BPM - BPM Developers Guide

24

| Chapter 2

Developing a .NET Client Application Using the Web Service API

public ServiceClientFactory(string user, string password, string host, string port, bool secure) : this(host,port,secure) { SecurityBehavior = new UsernameBehavior(user, password); } public IEndpointBehavior SecurityBehavior { get; set; } public WorkListServiceClient GetWorkListServiceClient() { WorkListServiceClient clnt = new WorkListServiceClient( CreateHttpBinding("WorkListService.soap"), new EndpointAddress(GetWorkListServiceUrl())); clnt.Endpoint.Behaviors.Add(SecurityBehavior); return (clnt); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Obtaining the Calling Users GUID 25

Obtaining the Calling Users GUID

Requirement
Every TIBCO ActiveMatrix BPM user is identified by a Global Unique IDentifier (GUID). This GUID is needed to identify a user when calling various API operations - for example, to display a work list. The GUID can be obtained using the lookupUser operation from the EntityResolverService.

Implementation
BPMTestApplication obtains the users GUID when they log in: 1. The Main method (in BPMTestApplication.cs) creates a new loginForm object, which displays the LoginForm dialog in which the user can enter a name and password.
class BPMTestApplication { public static void Main() { LoginForm loginForm = new LoginForm(); DialogResult result = loginForm.ShowDialog(); if (result == DialogResult.OK) { Adapter _adapter = loginForm.ProxyAdapter; string _guid = loginForm.Guid; WorkList workList = new WorkList(_adapter,_guid); workList.ShowDialog(); } } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

26

| Chapter 2

Developing a .NET Client Application Using the Web Service API

2. The button1_Click method on the loginForm class (defined in LoginForm.cs): a. creates a new Adapter object, passing the data collected in the LoginForm dialog. b. calls the getGUID method on the ProxyAdapter object to obtain the GUID associated with that username.
private void button1_Click(object sender, EventArgs e) { // Gather the information required from the various fields // Now call into our adapter, to make the "login" try { ProxyAdapter = new Adapter(usernameBox.Text, passwordBox.Text, hostBox.Text, portBox.Text, useHTTPS.Checked); Guid = ProxyAdapter.GetGUID(usernameBox.Text); // Login worked, return the LoginCredentials object which will be used later DialogResult = DialogResult.OK; Hide(); } catch (Exception ex) { // Login failed, display an error dialog with the information MessageBox.Show(this, "Error logging in: " + ex.Message, "Error"); } }

If a login failure occurs, it indicates that the user name or password included in the SOAP header has been rejected by the TIBCO ActiveMatrix BPM LDAP authentication application. Although BPMTestApplication uses GetGUID to handle the users login, it is important to realize that GetGUID is not being used to authenticate the users credentials. 3. GetGUID (defined in Adapter.cs) obtains the GUID by invoking the lookupUser operation.
public string GetGUID(string resource) { EntityResolverServiceClient entityClient = _handler.GetEntityResolverClient(); lookupUser user = new lookupUser(); user.name = resource; user.getdetail = true; lookupUserResponse response = entityClient.lookupUser(user); return response.detail[0].guid; }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Obtaining the Calling Users GUID 27

4. The GUID is passed back up to Main, from which it is used to obtain the users worklist.
class BPMTestApplication { public static void Main() { LoginForm loginForm = new LoginForm(); DialogResult result = loginForm.ShowDialog(); if (result == DialogResult.OK) { Adapter _adapter = loginForm.ProxyAdapter; string _guid = loginForm.Guid; WorkList workList = new WorkList(_adapter,_guid); workList.ShowDialog(); } } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

28

| Chapter 2

Developing a .NET Client Application Using the Web Service API

Writing Adapter Methods

Requirement
Adapter methods provide an interface between application layer functionality and BPM service calls. The use of adapter methods is recommended, because they insulate the application layer from the implementation details of the service calls. Connection and security requirements can also be handled at this layer, as described in the preceding sections.

Implementation
The Adapter class (in Adapter.cs) implements the following methods to call specific BPM service operations. Method CancelWorkItem CloseWorkItem GetWorkList OpenItem SubmitWorkItem GetGUID Description Cancels a work item Closes a work item Gets the worklist of a user identified by their GUID Allocates and opens a selected work item Completes a work item Gets the GUID for the username specified in the LoginForm dialog. (See Obtaining the Calling Users GUID for more information about this method.) Invokes... cancelWorkItem operation from the WorkPresentationService closeWorkItem operation from the WorkPresentationService getWorkListItems operation from the WorkListService openWorkItem operation from the WorkPresentationService completeWorkItem operation from the WorkPresentationService lookupUser operation from the EntityResolverService.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Writing Adapter Methods 29

Each method uses a similar structure to provide its interface. For example, the GetWorkList method: 1. Creates an object from the class that represents the operation to be invoked - in this case, getWorkListItems.
public WorkItem1[] GetWorkList(string guid) { getWorkListItems getItems = new getWorkListItems();

2. Populates the object with appropriate parameter values for the request message. In this case, the required values have been determined by referencing the getWorkListItemsRequest element.
getItems.Item = new XmlModelEntityId(); getItems.getTotalCount = true; getItems.numberOfItems = 100; getItems.startPosition = 0; getItems.Item.entitytype = OrganisationalEntityType.RESOURCE; getItems.Item.guid = guid; getItems.Item.modelversion = -1;

3. Invokes the appropriate WCF client, calls the operation and stores the response - which in this case will be a getWorkListItemsResponse object.
WorkListServiceClient wlSvcClient = _handler.GetWorkListServiceClient(); getWorkListItemsResponse response = wlSvcClient.getWorkListItems(getItems);

4. Processes the response and adds exception handling as required.

if (response != null) { if (response.workItems != null) { WorkItem1[] items = response.workItems; return items; } } throw new Exception("Failed to get WorkList - call returned null"); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

30

| Chapter 2

Developing a .NET Client Application Using the Web Service API

The Adapter class also includes the GetBOMJSP, GetFormURL and GetJSURL methods. See Rendering a Form for a Work Item for more information about the use of these methods.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Writing the Application Layer 31

Writing the Application Layer

Requirements
The application layer should implement the client user interface, providing the required functionality to the end user. This layer should be largely independent of the BPM API, as it can call adapter functions to invoke BPM services to obtain data.

Implementation
The application layer is provided by the BPMTestApplication project. This project provides the following functionality: File BPMTestApplication.cs Description Creates and manages the BPMTestApplication object. This contains the program entry point method, Main, which manages the users login and displays their work list. Creates and manages the LoginForm object, which provides the LoginForm dialog. Creates and manages the WorkList object, which controls the users interaction with the work list. Creates and manages the ViewWorkItem object, which controls the users interaction with a specific work item. Manages the users interaction with the form that is displayed when a user opens a specific work item. See Rendering a Form for a Work Item for more information.

LoginForm.cs WorkList.cs ViewWorkItem.cs FormRedirect.htm

TIBCO ActiveMatrix BPM - BPM Developers Guide

32

| Chapter 2

Developing a .NET Client Application Using the Web Service API

The ShowWorkList method (defined in ViewWorkList.cs) illustrates how adapter functions are used to insulate the application layer from the implementation details of the BPM services.
private void ShowWorkList() { workListTable.Enabled = false; workListTable.ForeColor = Color.Gray; try { WorkItem1[] items = _adapter.GetWorkList(_guid); _items = items; DataSet dsForDGV = new DataSet(); BindingSource bs = new BindingSource(); DataTable dataTable1 = ConvertWorkItemsToDataTable(items); dsForDGV.Tables.Add(dataTable1); bs.DataSource = dsForDGV; bs.DataMember = dsForDGV.Tables[0].TableName; workListTable.DataSource = bs; workListTable.Columns[3].AutoSizeMode = DataGridViewAutoSizeColumnMode.Fill; } catch (Exception ex) { MessageBox.Show(this,"Error getting work list: "+ex.Message,"Error"); } workListTable.Enabled = true; workListTable.ForeColor = Color.Black; }

ShowWorkList is called by the Main method when a user has successfully logged in. ShowWorkList retrieves the contents of the users work list by calling the Adapter.GetWorkList method (which in turn calls the getWorkListItems operation provided by the WorkListService). The response, stored in items, is a getWorkListItemsResponse object, which contains full details of all the work items in the work list. ShowWorkList presents the data using a .NET dataTable. The ConvertWorkItemsToDataTable method is used to filter and convert the data

TIBCO ActiveMatrix BPM - BPM Developers Guide

Writing the Application Layer 33

returned in the getWorkListItemsResponse object into a dataTable object containing just the data to be displayed in the work list.
private DataTable ConvertWorkItemsToDataTable(WorkItem1[] items) { dataTable dataTable1 = new DataTable("MyTable"); dataTable1.Columns.Add(new DataColumn("Work Item ID")); dataTable1.Columns.Add(new DataColumn("State")); dataTable1.Columns.Add(new DataColumn("Name")); dataTable1.Columns.Add(new DataColumn("Description")); dataTable1.Columns.Add(new DataColumn("Process Template")); dataTable1.Columns.Add(new DataColumn("Work Item Priority")); dataTable1.Columns.Add(new DataColumn("Attribute 2")); int i = 0; foreach (WorkItem1 item in items) { dataTable1.Rows.Add(item.id); dataTable1.Rows[i][0] = item.id.id; dataTable1.Rows[i][1] = item.state; dataTable1.Rows[i][2] = item.header.name; dataTable1.Rows[i][3] = item.header.description; dataTable1.Rows[i][4] = item.header.itemContext.appName; dataTable1.Rows[i][5] = item.header.priority; if ((item.attributes != null) && (item.attributes.attribute2 != null)) { dataTable1.Rows[i][6] = item.attributes.attribute2; } else { dataTable1.Rows[i][6] = ""; } i++; } return dataTable1; }

TIBCO ActiveMatrix BPM - BPM Developers Guide

34

| Chapter 2

Developing a .NET Client Application Using the Web Service API

Rendering a Form for a Work Item

Requirements
When a work item is opened, the client application must display the work item data to the user, using either: a TIBCO form, which provides a web-based user interface to the work item data. a custom form. Development and use of custom forms is entirely the responsibility of the client application, so is not covered further in this guide.

The Forms Runtime Adapter is a JavaScript API provided as part of the BPM runtime. To display a TIBCO form, a client application must load and use the Forms Runtime Adapter in the browser control containing the form. See the TIBCO Business Studio Forms Users Guide for detailed information about the Forms Runtime Adapter.

Implementation
BPMTestApplication displays work item data as a TIBCO form. The ViewWorkItem method (defined in ViewWorkList.cs): 1. creates a web browser control to hold the form. 2. calls Adapter.OpenItem to open the work item and fetch its associated data. 3. calls ShowItem (which works with FormRedirect.htm) to render the form and display it to the user.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Rendering a Form for a Work Item 35

public ViewWorkItem(Adapter adapter, string guid, WorkItem1 workItem) { InitializeComponent(); webBrowser1.AllowWebBrowserDrop = false; //webBrowser1.IsWebBrowserContextMenuEnabled = false; webBrowser1.WebBrowserShortcutsEnabled = false; webBrowser1.ObjectForScripting = this; this.StartPosition = FormStartPosition.CenterParent; _adapter = adapter; _guid = guid; _workItem = workItem; try { _item = _adapter.OpenItem(_guid, workItem); ShowItem(); } catch (Exception ex) { MessageBox.Show("ERROR: Failed to open item: " + ex.Message); throw ex; } } public void ShowItem() { Text = "Viewing item: " + _item.presentation.activityName; HtmlDocument doc = webBrowser1.Document; string pathToHTML = Environment.CurrentDirectory + "/FormRedirect.htm"; StreamReader streamReader = new StreamReader(pathToHTML); string htmlText = streamReader.ReadToEnd(); streamReader.Close(); htmlText = htmlText.Replace("%%SCRIPT_LOCATION%%", _adapter.GetJSURL()); // Now create a temporary file for the HTML page with the correct host location string tempFile = Path.GetTempFileName(); FileStream File_Stream = new FileStream(tempFile, FileMode.Create, FileAccess.Write); StreamWriter FileWriter = new StreamWriter(File_Stream); try { FileWriter.BaseStream.Seek(0, SeekOrigin.End); FileWriter.Write(htmlText); } finally { FileWriter.Close(); } webBrowser1.Url = new Uri(tempFile); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

36

| Chapter 2

Developing a .NET Client Application Using the Web Service API

FormRedirect
FormRedirect.htm performs the following tasks: 1. Loading the Forms Runtime Adapter 2. Creating the onTIBCOFormRunnerLoad Function Loading the Forms Runtime Adapter The SCRIPT_LOCATION tag is used to define the runtime address of the Forms Runtime Adapter.
<html> <head> <meta http-equiv="X-UA-Compatible" content="IE=8" /> <!-- The following line uses a tag which will be substituted out for the real location of the Forms Runtime Adapter script file once we know which host we are connecting to --> <script type="text/javascript" language="javascript" src="%%SCRIPT_LOCATION%%"></script> <script type="text/javascript">

The following line in the ViewWorkItem.ShowItem method is used to replace the SCRIPT_LOCATION tag and load the Forms Runtime Adapter into the form object.
htmlText = htmlText.Replace("%%SCRIPT_LOCATION%%", _adapter.GetJSURL());

The tag is replaced with the string returned by adapter.GetJSURL

public string GetJSURL() { return _handler.GetBaseURL() + "bpmresources/formsclient/formsclient.nocache.js"; }

This method builds the runtime address of the Forms Runtime Adapter: GetBaseURL (from ServiceClientFactory.cs) is used to obtain the endpoint URL of the BPM runtime - for example, http://10.100.87.112:8080/. bpmresources is the name of the BPM runtime component that provides access to the Forms Runtime Adapter. formsclient/formsclient.nocache.js is the location of the Forms Runtime Adapter.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Rendering a Form for a Work Item 37

Creating the onTIBCOFormRunnerLoad Function FormRedirect.htm must contain a function called onTIBCOFormRunnerLoad. The Forms Runtime Adapter automatically searches for and runs this function as soon as it has loaded. The function must be called onTIBCOFormRunnerLoad. if you use a different name the form will not load.

The onTIBCOFormRunnerLoad Function

The onTIBCOFormRunnerLoad function performs the following tasks to render the work item data as a TIBCO form: 1. Setting the useJSONP Variable 2. Setting the Form URL 3. Obtaining the Initial Data to Populate the Form 4. Setting the BOM JavaScript path 5. Creating Action Handlers for User Actions 6. Rendering the Form Setting the useJSONP Variable The useJSONP variable must be set - in this case to false, indicating that the client application is running on a different machine to the BPM runtime that hosts the Forms Runtime Adapter.
var useJSONP = false;

Setting the Form URL The formURL variable holds the URL containing the JSON representation of the form, in the format required by the Forms Runtime Adapter loadForm method.
var formURL = window.external.GetFormURL();

The URL is built by calling ViewWorkItem.GetFormURL,

public string GetFormURL() { return _adapter.GetFormURL(_item); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

38

| Chapter 2

Developing a .NET Client Application Using the Web Service API

which in turn calls adapter.GetFormURL.

public string GetFormURL(workResponse response) { return _handler.GetBaseURL() + "bpmresources/" + response.presentation.formIdenitifier; }

This method builds the form URL: GetBaseURL (from ServiceClientFactory.cs) is used to obtain the endpoint URL of the BPM runtime - for example, http://10.100.87.112:8080/. bpmresources is the name of the BPM runtime component that provides access to the form resources of deployed BPM applications. response.presentation.formIdenitifier is the formIdentifier of the form used by this work item, obtained from the previous OpenItem call - for example, 1.0.0.201107291435/openspaceGWTPull_DefaultChannel/FindAddress/Get Address/Getuserdetails/Getuserdetails.gwt.json.

Obtaining the Initial Data to Populate the Form The initData variable holds the JSON data stream that will be used to populate the form when it is rendered.
var initData = window.external.GetInitData();

The data is obtained by calling ViewWorkItem.GetInitData.

public string GetInitData() { return (String)_item.payloadModel.Item; }

_item.payloadModel.Item is the payloadModel containing the JSON data stream for the work item, obtained from the previous OpenItem call.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Rendering a Form for a Work Item 39

Setting the BOM JavaScript path The bomJSPath variable holds the root folder path used for loading the BOM JavaScript files used by the form, in the format required by the Forms Runtime Adapter loadForm method.
var bomJSPath = window.external.GetBOMJSPath();

The URL is built by calling ViewWorkItem.GetBOMJSPAth,

public string GetBOMJSPath() { return _adapter.GetBOMJSPath(_item); }

which in turn calls adapter.GetFormURL.

public string GetBOMJSPath(workResponse item) { string formURL = item.presentation.formIdenitifier; return _handler.GetBaseURL() + "bpmresources/" + formURL.Substring(0, formURL.IndexOf('/')); }

This method builds the URL as follows: GetBaseURL (from ServiceClientFactory.cs) is used to obtain the endpoint URL of the BPM runtime - for example, http://10.100.87.112:8080/. bpmresources is the name of the BPM runtime component that provides access to the form resources of deployed BPM applications. formURL is the formIdentifier of the form used by this work item, obtained from the previous OpenItem call. formURL.Substring(0, formURL.IndexOf('/')) extracts the initial part of this string (the version number of the form resources), which identifies the root folder path used for loading the BOM JavaScript files used by the form - for example, 1.0.0.201107291435.

TIBCO ActiveMatrix BPM - BPM Developers Guide

40

| Chapter 2

Developing a .NET Client Application Using the Web Service API

Creating Action Handlers for User Actions The form provides Submit, Close and Cancel actions (displayed to the user as buttons). Handlers for these actions are added using the Runtime Forms Adapter setActionHandler method. The handlers are added once the form is successfully initialized, via the formLoadSuccessCallback function
var cancelHandler = function (actionName, form) { try { window.external.CancelForm(); form.destroy(); } catch (err) { alert("Error cancelling form: " + err.Description); } }; var closeHandler = function (actionName, form) { try { var data = form.getSerializedParameters(); window.external.CloseForm(data); } catch (err) { alert("Error closing form: " + err.Description); } } var submitHandler = function (actionName, form) { try { var data = form.getSerializedParameters(); window.external.SubmitForm(data); } catch (err) { alert("Error submitting form: " + err.Description); } } var formLoadSuccessCallback = function (form) { form.setActionHandler(form.ACTION_CANCEL, cancelHandler); form.setActionHandler(form.ACTION_CLOSE, closeHandler); form.setActionHandler(form.ACTION_SUBMIT, submitHandler); }; var formLoadErrorCallback = function (error) { alert('Form load failed with error: ' + error); };

When the user performs an action by clicking a button, the handler calls an appropriate method to process the action. For a Close or Submit action, data is passed back.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Rendering a Form for a Work Item 41

For example, the submitHandler calls the ViewWorkItem.SubmitForm method,

public void SubmitForm(string data) { try { _adapter.SubmitWorkItem(_workItem, _item.workTypeDetail.uid, _item.workTypeDetail.version, _guid, data); _formClosed = true; Close(); } catch (Exception e) { MessageBox.Show("Error closing form: " + e.Message); } }

which in turn calls the Adapter.SubmitWorkItem method. This method completes the work item, by building the request data for and then invoking a completeWorkItem operation from the WorkPresentationService.
public void SubmitWorkItem(WorkItem1 item, string workTypeUid, string workTypeVersion, string guid, string data) { WorkPresentationServiceClient wpSvcClient = _handler.GetWorkPresentationServiceClient(); WorkRequest workRequest = new WorkRequest(); WorkRequest.responsePayloadMode = payloadModeType.JSON; workRequest.payloadDetails = new dataPayload(); workRequest.payloadDetails.payloadMode = payloadModeType.JSON; workRequest.payloadDetails.Item = data; workRequest.channelId = "openspaceGWTPull_DefaultChannel"; workRequest.channelType = ChannelType.openspaceChannel; workRequest.workItem = new WorkItem(); workRequest.workItem.id = item.id.id; workRequest.workItem.version = -1; workRequest.workTypeDetail = new BaseWorkRequestWorkTypeDetail(); workRequest.workTypeDetail.uid = workTypeUid; workRequest.workTypeDetail.version = workTypeVersion; workRequest.workTypeDetail.openNextPiled = false; workResponse response = wpSvcClient.completeWorkItem(workRequest); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

42

| Chapter 2

Developing a .NET Client Application Using the Web Service API

Rendering the Form The Forms Runtime Adapter loadForm method is used to render the form for the user.
com.tibco.forms.client.FormRunner.loadForm(formURL, initData, bomJSPath, null, "formContainer", formLoadSuccessCallback, formLoadErrorCallback, useJSONP); } </script> <title>Form</title> </head> <body> <div id="formContainer"></div> </body> </html>

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 43
Chapter 3

Developing a Client Application Using the Java Service Connector API

This chapter outlines the basic steps involved in using the Java Service Connector API to develop a custom client application. It also describes an example client application that is supplied with this guide to illustrate these steps.

Topics
Overview of the Java Service Connector, page 44 The Sample Client Application, page 46 Instantiating and Configuring the Service Connector, page 50 Setting up the Security Handler, page 54 Authenticating the Calling User, page 55 Executing the Service Connector API Calls, page 58 Implementing the Client User Interface, page 59 Rendering a Form for a Work Item, page 62

TIBCO ActiveMatrix BPM - BPM Developers Guide

44

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Overview of the Java Service Connector

The Java Service Connector enables a client application to access the BPM runtime services that are hosted in a TIBCO ActiveMatrix container. The documentation sometimes refers to the Java Service Connector as Service Connector and these two terms are used interchangeably. A client application can communicate with the Java Service Connector using local Java calls. The Java Service Connector takes the information from the Java call and: 1. converts it to a SOAP request. 2. adds security information to the SOAP header to identify the calling user. See Setting up the Security Handler for details. 3. sends the SOAP request to the endpoint used by the appropriate service in the BPM runtime. When the BPM runtime returns the SOAP response, the Service Connector unwraps the SOAP response envelop and converts it to a data object. Data Handling The Service Connector contains stubs and data bindings (XML Beans) that are generated from the public WSDLs that are provided with this guide. The data bindings adhere to the public WSDL and XSD files provided. See TIBCO ActiveMatrix BPM Services for more information on the WSDL and XSD files.

Enabling the Java Service Connector for Your Development Environment

The Java Service Connector is provided as an archive service-connector.zip which is installed at TIBCO_HOME\service-connector\1.2 when you install the BPM runtime. To make the Java Service Connector available to your development environment, perform the following steps: 1. Unzip the archive file to a folder which is on the machine hosting your development environment, say C:\temp\serviceConnector. 2. Delete the servlet-api-2.5.jar if you have a servlet container setup. The Service Connector archive file contains the servlet API servlet-api-2.5.jar. However, if you already have a servlet container setup, this file is available in
TIBCO ActiveMatrix BPM - BPM Developers Guide

Overview of the Java Service Connector 45

the servlet containers library folder. To avoid any conflicts, you must delete the servlet-api-2.5.jar from the location where you unzipped the Service Connector archive file. 3. Edit the CLASSPATH to ensure that all the binary contents of the archive file are in the CLASSPATH. For example, add all the files available in C:\temp\serviceConnectorto the CLASSPATH.

TIBCO ActiveMatrix BPM - BPM Developers Guide

46

| Chapter 3

Developing a Client Application Using the Java Service Connector API

The Sample Client Application

SampleApp is a simple JSP-based client application that uses the Service Connector API to call BPM services. The SampleApp example is supplied "as is" with no warranties. The code in SampleApp is intended as a simple illustration of the concepts and techniques needed to develop a custom client application. It is not intended as a basis for production-ready code and should not be used as such. SampleApp provides the following functionality: It provides a Login form that allows you to: supply the credentials (username and password) with which to login. specify the protocol to be used select the BPM runtime by specifying the hostname and port number.

TIBCO ActiveMatrix BPM - BPM Developers Guide

The Sample Client Application 47

It displays the work list for the logged in user.

It allows you to open, complete (submit), cancel, or close the work items from the work list using standard TIBCO forms.

System Requirements
To be able to examine and run the SampleApp you must have the following software installed: A Java IDE such as Eclipse if you want to develop a client application. Apache Ant to build SampleApp and generate the deployable artifact. A servlet container such as Apache Tomcat (Version 6.0 or above) to deploy the client application. A browser such as Internet Explorer, Google Chrome, or Mozilla Firefox to run the sample client application.

Getting the SampleApp Solution

1. Download the SampleApp.zip file. 2. Unzip the file to a suitable local directory C:\temp\SampleApp.

TIBCO ActiveMatrix BPM - BPM Developers Guide

48

| Chapter 3

Developing a Client Application Using the Java Service Connector API

3. To view the source files and enhance the sample provided, open SampleApp in Eclipse or a suitable IDE. The solution project contains: Source files containing the classes and methods to develop the basic client application. JSP files which provide the client user interface. Other resources such as CSS files, images, etc. Libraries required to build and run the client application. SampleApp.zip does not include the Service Connector libraries. You must copy the libraries into the CLASSPATH of the sample application. For example, copy the libraries to WEB-INF\lib. Also, ensure that the Build Path is configured properly before running the sample application. 4. To run SampleApp, perform the following tasks: a. Edit the C:\temp\SampleApp\config.properties file to specify the location where all the binary files of the service connector are available. For example: service-connector-dir=C:\\temp\\service-connector See Enabling the Java Service Connector for Your Development Environment for details on how to obtain the service connector binaries. b. Open a console window and navigate to C:\temp\SampleApp. This folder contains the build.xml file. Execute the following command:
ant clean war

Upon successful completion, the script will have performed the following: copies the service connector binaries to the SampleApp WEB-INF folder (C:\temp\SampleApp\WebContent\WEB-INF\lib). builds the sampleapp.war file at C:\temp\SampleApp\build\dist which can be used to deploy the sample application to any web server. c. Copy the sampleapp.war file to the webapps folder of the servlet container. For example, C:\Program Files
(x86)\apache-tomcat-6.0.32\webapps.

d. Start the servlet container (or restart if it is already running). e. Open a browser window and navigate to http://localhost:9090/sampleapp to open the login form.

TIBCO ActiveMatrix BPM - BPM Developers Guide

The Sample Client Application 49

Architecture
The following diagram illustrates the architecture of the Java Service Connector example client.
action=<userAction>

Browser Login.jsp
UserName Password Server IP Port Is Secure

act

ion

= l

n ogi

Controller Servlets

Service Connector

BPM Services

Login

Display

J SP

JSP Files

The client user interface is designed using JSP files. These files are used for presentation and help communicate the user inputs to the Service Connector through the controller servlet and vice versa. The controller servlet handles the application flow. It also passes on the action performed by the user and any data supplied to the appropriate Service Connector API. The Service Connector converts the data object and security information into an appropriate SOAP request message and calls the corresponding BPM service. It also converts the SOAP response back into the corresponding data object before handing it over to the controller servlet. The controller servlet returns the appropriate JSP page to the user along with the data returned in the response. JSP renders the data returned by the controller servlet. TIBCO Forms are used to display any work related data such as work items, pageflows, and business services.

TIBCO ActiveMatrix BPM - BPM Developers Guide

50

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Instantiating and Configuring the Service Connector

Requirement You must create an instance of the Java Service Connector which can be used to access the BPM service API. This service connector instance must be configured to use the endpoint addresses exposed by particular BPM services. The Service Connector communicates with the service endpoints exposed by the BPM server. Unless you plan to run the client application on the same machine as the BPM services, you must configure the endpoints to the required BPM runtime server. Implementation The method setServiceConnector reads the protocol, host, and port number values from the request and calls the initializeServiceConnector method. Ensure that the security handler is set before creating the Service Connector instance. See Setting up the Security Handler for details on how to set up the security handler.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Instantiating and Configuring the Service Connector 51

/* * ===================================================== * METHOD : setServiceConnector * ===================================================== */ /** * Reads the protocol, host, and port values from the request and * initializes the ServiceConnector. * * @param req * @throws ServletException */ private void setServiceConnector(HttpServletRequest req) throws ServletException { // Read the protocol, host, and port values from the request. Configuration.Protocol protocol = req.getParameter("secure") == null ? Configuration.Protocol.HTTP : Configuration.Protocol.HTTPS; req.getSession().setAttribute("protocol", protocol.toString().toLowerCase()); String host = req.getParameter("host") == null ? "localhost" : req.getParameter("host"); req.getSession().setAttribute("host", host); int port = req.getParameter("port") == null ? 8080 : Integer.parseInt(req.getParameter("port")); req.getSession().setAttribute("port", port); initializeServiceConnector(req, protocol, host, port); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

52

| Chapter 3

Developing a Client Application Using the Java Service Connector API

The method initializeServiceConnector creates an instance of the Service Connector serviceConnector using the ServiceConnectorFactory. The Service Connector Factory provides a factory interface to get the reference of the service connector instance associated with a particular BPM server. This enables the same client application to communicate with multiple BPM servers which can be hosted in different locations. The serviceConnector instance created for the user is cached within the HTTP session associated with the logged in user.
private static final String SERVICECONNECTOR = "serviceConnector"; ... /* * ===================================================== * METHOD : initializeServiceConnector * ===================================================== */ /** * Creates the ServiceConnector instance. This example shows several ways to create the ServiceConnector. * Use of the ServiceConnectorFactory is recommended since it creates a single instance for a given * protocol, host, and port. * * @param protocol The protocol value. * @param host The host value. * @param port The port value. * @throws ServletException * @see ServiceConnector, ServiceConnectorFactory */ private void initializeServiceConnector(HttpServletRequest req, Configuration.Protocol protocol, String host, int port) throws ServletException { // Create a security handler for the logged in user. SecurityHandler securityHandler = new DefaultSecurityHandler(getUserName(req), getPassword(req)); ServiceConnector serviceConnector; // Example of passing the protocol, host, port, and securityHandler into the constructor. serviceConnector = ServiceConnectorFactory.getServiceConnector(protocol, host, port, securityHandler); // The ServiceConnector constructors can be used directly but use of the ServiceConnectorFactory is recommended. //serviceConnector = new ServiceConnector(protocol, host, port, securityHandler); req.getSession().setAttribute(SERVICECONNECTOR, serviceConnector); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Instantiating and Configuring the Service Connector 53

The Service Connector constructors can be used directly. However, the use of the Service Connector Factory is recommended. The method getServiceConnector is used to return the serviceConnector instance stored in the session.
/* * ===================================================== * METHOD : getServiceConnector * ===================================================== */ /** * Returns the ServiceConnector instance stored in the session. * * @param req * @return The ServiceConnector instance stored in the session. * @throws ServletException */ private ServiceConnector getServiceConnector(HttpServletRequest req) throws ServletException { ServiceConnector serviceConnector = (ServiceConnector) req.getSession().getAttribute(SERVICECONNECTOR); if (serviceConnector == null) { throw new ServletException("ServiceConnector is missing. A valid login is required."); } return serviceConnector; }

You can also configure the protocol, host, and port number properties after creating the service connector by passing properties to the configuration instance,.
// Example of passing configuration instance in. //Properties properties = new Properties(); // properties.setProperty(Configuration.Property.AMX_BPM_INSTANCE_P ROTOCOL.getValue(), protocol.toString()); // properties.setProperty(Configuration.Property.AMX_BPM_INSTANCE_H OST.getValue(), host); // properties.setProperty(Configuration.Property.AMX_BPM_INSTANCE_P ORT.getValue(), String.valueOf(port)); //Configuration configuration = new Configuration(properties); ////serviceConnector = new ServiceConnector(configuration, securityHandler); //serviceConnector = ServiceConnectorFactory.getServiceConnector(configuration, securityHandler);

TIBCO ActiveMatrix BPM - BPM Developers Guide

54

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Setting up the Security Handler

Requirement Every API call which the client application makes to a BPM service must include an appropriate security information in the header of the SOAP request envelop. In order to enforce the security constraints, a security handler must be created and registered for every user who logs in to the BPM runtime. Note that the security handler must be set before creating an instance of the Java Service Connector. Implementation To include the header information in the SOAP request, the client application must implement the SecurityHandler interface to set the default security handler for the logged in user.
// Create a security handler for the logged in user. SecurityHandler securityHandler = new DefaultSecurityHandler(getUserName(req), getPassword(req));

TIBCO ActiveMatrix BPM - BPM Developers Guide

Authenticating the Calling User 55

Authenticating the Calling User

Requirement Every API call which the client application makes to a BPM service must include an appropriate WS-Security token in the SOAP header. The token must be either: a UsernameToken, which specifies the username and password of the user on whose behalf the call is being made. (This is termed direct authentication.) a SAML token, if SSO authentication is being used. (This is termed Single Sign-on (SSO) authentication.)

A TIBCO ActiveMatrix BPM LDAP authentication application (for example, amx.bpm.auth.easyAs) uses this token to authenticate the calling user. If the token does not identify a known TIBCO ActiveMatrix BPM user, the call is rejected. See Authenticating Access to a TIBCO ActiveMatrix BPM Service for more information about direct and SSO authentication methods and how to use them in different situations. Implementation SampleApp uses UsernameToken to authenticate the calling user. The sample application allows a user to provide the username and password through the USERNAME and PASSWORD fields in login.jsp.
private String getUserName(HttpServletRequest req) throws ServletException { /**return the user name passed in the request*/ String username = req.getParameter("userName"); if (null == username) throw new ServletException("User Name cannot be null"); return username; } private String getPassword(HttpServletRequest req) throws ServletException { /**return the password passed in the request*/ String password = req.getParameter("pass"); if (null == password) throw new ServletException("Password cannot be null"); return password; }

TIBCO ActiveMatrix BPM - BPM Developers Guide

56

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Every BPM runtime user is identified by a Global Unique IDentifier (GUID). This GUID is needed to identify the user when calling various API methods - for example, to display a work list. The method authenticate in the SampleApp authenticates the username specified using the BPM service API lookupUser. The method lookupUser looks up the username and returns the corresponding GUID. This information is then saved for that particular session.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Authenticating the Calling User 57

/* * ===================================================== * METHOD : authenticate * ===================================================== */ /** * Authenticates the user login and retrieves the user guid. * * @param req * @param resp * @throws ServletException */ private void authenticate(HttpServletRequest req, HttpServletResponse resp) throws ServletException { try { String username = getUserName(req); String guid = null; LookupUserResponse lookupUserResponse = getServiceConnector(req).getEntityResolverService().lookupUser( getUserName(req), null, null, true); if (lookupUserResponse.getDetailArray().length > 0) { guid = lookupUserResponse.getDetailArray(0).getGuid(); } else { throw new ServletException("Unable to lookup user guid."); } lookupUserResponse.getDetailArray(0).getGuid(); LoginInfo loginInfo = new LoginInfo(username, guid); /**store the user info in the session*/ req.getSession().setAttribute(USER_INFO, loginInfo); displayWorklist(req, resp); } catch (InternalServiceFault e) { throw new ServletException(e); } catch (InvalidServiceRequestFault e) { throw new ServletException(e); } catch (com.tibco.n2.de.services.SecurityFault e) { throw new ServletException(e); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

58

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Executing the Service Connector API Calls

To execute the Service Connector API calls, you must invoke the method on the appropriate BPM service API. For example:
WorkResponse workResponse = getServiceConnector(req).getWorkPresentationService().completeWork Item(buildWorkRequest(req));

Schema validation When executing the Service Connector API calls, you must ensure that the inputs conform to the schema. This is necessary as schema validation for the inputs is not available in the Service Connector. For example, ensure that you provide values for all the mandatory fields.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Implementing the Client User Interface 59

Implementing the Client User Interface

Requirements
The client user interface provides the required functionality to the user.

Implementation
The application layer is provided by the SampleApp project. This project contains the following: File WorkProcessingServlet.java Description Creates and manages the SampleApp. The class WorkProcessingServlet contains all the methods required to handle the flow of the sample application. It orchestrates the JSP pages that are displayed and calls the appropriate Service Connector method based on the users actions and data supplied by the user. login.jsp Creates and manages the Login form, which provides the Login dialog. The Login form provides the entry point to the sample application. Creates and manages the users interaction with work lists. Creates and manages the users interaction with a specific work item. The process method in WorkProcessingServlet.java is called whenever the user performs an action. Based on the action performed, it calls the method to be executed next.

worklist.jsp openworkitem.jsp

TIBCO ActiveMatrix BPM - BPM Developers Guide

60

| Chapter 3

Developing a Client Application Using the Java Service Connector API

For example, when a user submits the login information, the following information is sent to the servlet by login.jsp:
<form action=""> <label for="username">Username:</label> <input type="text" name="userName" class="text" id="username"> <br /> <label for="password">Password:</label> <input type="password" name="pass" class="text" id="password"> <br /> <serverLabel for="protocol">Server:</label> <input type="checkbox" name="secure" value="secure" checked="checked">Secure (https)</input> <!-- <serverLabel for="protocol">Protocol:</serverLabel> <input type="radio" name="protocol" value="HTTP" checked="checked">HTTP</input> <input type="radio" name="protocol" value="HTTPS">HTTPS</input> --> <br /><br /> <serverLabel for="host">Host:</serverLabel> <input class="serverInput" type="text" name="host" class="text" id="host" value="localhost"> <br /><br /> <serverLabel for="port">Port:</serverLabel> <input class="serverInput" type="text" name="port" class="text" id="port" value="8080"> <br /><br /> <input type="submit" onclick="submitData('login');" class="submit" name="submit" value="Submit"> </form> </div> </body> </html>

The process method in WorkProcessingServlet.java identifies the action as login and hence executes the following:
public void process(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {if (getAction(req).equals(Actions.LOGIN)) { setServiceConnector(req); authenticate(req, resp); } ... orchestratePages(req, resp); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Implementing the Client User Interface 61

Once the user is authenticated, it calls the orchestratePages method which displays pages according to the action invoked by the user. For example, after the action LOGIN is completed, worklist.jsp is displayed to the user. worklist.jsp displays the list of worklist items available for the logged in user in a tabular form.
private void orchestratePages(HttpServletRequest req, HttpServletResponse resp) throws ServletException,IOException { if (getAction(req).equals(Actions.LOGIN)) { getServletContext().getRequestDispatcher("/worklist.jsp").forward(req, resp); } ... }

TIBCO ActiveMatrix BPM - BPM Developers Guide

62

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Rendering a Form for a Work Item

Requirements
When a work item is opened, the client application must display the work item data to the user, using either: a TIBCO form, which provides a web-based user interface to the work item data. a custom form. Development and use of custom forms is entirely the responsibility of the client application, so is not covered further in this guide.

The Forms Runtime Adapter is a JavaScript API provided as part of the BPM runtime. To display a TIBCO form, a client application must load and use the Forms Runtime Adapter in the browser control containing the form. See the TIBCO Business Studio Forms Users Guide for detailed information about the Forms Runtime Adapter.

Implementation
SampleApp displays work item data as a TIBCO form.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Rendering a Form for a Work Item 63

The login.jsp creates the HTML page containing the Login form. This form provides the entry point to the sample application. The form action submitted by the user is passed to the WorkProcessingServlet.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> ... <SCRIPT LANGUAGE="JavaScript"> function submitData(action){ document.forms[0].action="workprocessor?action="+action; document.forms[0].method="post"; document.forms[0].submit(); } </SCRIPT> </head> ... <form action=""> <label for="username">Username:</label> <input type="text" name="userName" class="text" id="username"> <br /> <label for="password">Password:</label> <input type="password" name="pass" class="text" id="password"> <br /> <serverLabel for="protocol">Server:</label> <input type="checkbox" name="secure" value="secure" checked="checked">Secure (https)</input> <!-- <serverLabel for="protocol">Protocol:</serverLabel> <input type="radio" name="protocol" value="HTTP" checked="checked">HTTP</input> <input type="radio" name="protocol" value="HTTPS">HTTPS</input> --> <br /><br /> <serverLabel for="host">Host:</serverLabel> <input class="serverInput" type="text" name="host" class="text" id="host" value="localhost"> <br /><br /> <serverLabel for="port">Port:</serverLabel> <input class="serverInput" type="text" name="port" class="text" id="port" value="8080"> <br /><br /> <input type="submit" onclick="submitData('login');" class="submit" name="submit" value="Submit"> </form> </div> </body> </html>

TIBCO ActiveMatrix BPM - BPM Developers Guide

64

| Chapter 3

Developing a Client Application Using the Java Service Connector API

The process method in WorkProcessingServlet.java handles all the requests and calls the appropriate method. The WorkProcessingServlet.java contains all the methods and control is passed over to the appropriate method. For example, when a user submits the username and password on the login page, the request is handled by the method process and the methods setServiceConnector, setServiceConnector and authenticate are called. Once completed, the method orchestratePages is called.

/* * ===================================================== * METHOD : process * ===================================================== */ /** * Selects the method called based on the request action. * * @param req * @param resp * @throws ServletException * @throws IOException */ public void process(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { if (getAction(req).equals(Actions.LOGIN)) { setServiceConnector(req); authenticate(req, resp); } else if (getAction(req).equals(Actions.OPEN_WORKITEM)) { openworkItem(req, resp); } ... else if (getAction(req).equals(Actions.SHOW_WORKLIST)) { displayWorklist(req, resp); } ... orchestratePages(req, resp); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Rendering a Form for a Work Item 65

The method orchestratePages checks for the action that has been processed and displays an appropriate JSP file to the user.

/* * ===================================================== * METHOD : orchestratePages * ===================================================== */ /** * Orchestrates JSP page flow for the application. * * @param req * @param resp * @throws ServletException * @throws IOException */ private void orchestratePages(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { if (getAction(req).equals(Actions.LOGIN)) { getServletContext().getRequestDispatcher("/worklist.jsp").forward(req, resp); } else if (getAction(req).equals(Actions.OPEN_WORKITEM)) { getServletContext().getRequestDispatcher("/openworkitem.jsp").forward(req, resp); } else if (getAction(req).equals(Actions.CLOSE_WORKITEM)) { displayWorklist(req, resp); getServletContext().getRequestDispatcher("/worklist.jsp").forward(req, resp); } else if (getAction(req).equals(Actions.COMPLETE_WORKITEM)) { displayWorklist(req, resp); getServletContext().getRequestDispatcher("/worklist.jsp").forward(req, resp); } else if (getAction(req).equals(Actions.SHOW_WORKLIST)) { getServletContext().getRequestDispatcher("/worklist.jsp").forward(req, resp); } ... else if (getAction(req).equals(Actions.LOGOUT)) { getServletContext().getRequestDispatcher("/login.jsp").forward(req, resp); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

66

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Displaying the Work Item Data as a TIBCO form

To display the work item data as a TIBCO form, openworkitem.jsp performs the following tasks: 1. Loading the Forms Runtime Adapter 2. Creating the onTIBCOFormRunnerLoad Function See the TIBCO Business Studio Forms Users Guide for details about the Form parameters and their usage. Loading the Forms Runtime Adapter The runtime address of the Forms Runtime Adapter is defined by
src="<%=request.getSession().getAttribute("protocol") + "://" + request.getSession().getAttribute("host") + ":" + request.getSession().getAttribute("port") %>/bpmresources/formsclient/formsclient.nocache.js">

The details about the BPM runtime is obtained from the session and the string /bpmresources/formsclient/formsclient.nocache.js is the location of the Forms Runtime Adapter. Creating the onTIBCOFormRunnerLoad Function openworkitem.jsp must contain a function called onTIBCOFormRunnerLoad. The Forms Runtime Adapter automatically searches for and runs this function as soon as it has loaded. The function must be called onTIBCOFormRunnerLoad. if you use a different name the form will not load.
function onTIBCOFormRunnerLoad(){ loadForm(); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Rendering a Form for a Work Item 67

The onTIBCOFormRunnerLoad Function

The onTIBCOFormRunnerLoad function performs the following tasks to render the work item data as a TIBCO form. 1. Setting the Form URL 2. Obtain the Initial Data to Load the Form 3. Set the BOM JavaScript Path 4. Create Action Handlers for User Actions 5. Render the Form Setting the Form URL The formURL variable holds the URL containing the JSON representation of the form, in the format required by the Forms Runtime Adapter loadForm method:
var formURL = "<%=urlConstruct%>";

This URL is constructed using the following expression

HttpSession reqSession = request.getSession(); String urls = reqSession.getAttribute("protocol") + "://" + reqSession.getAttribute("host") + ":" + reqSession.getAttribute("port") + "/bpmresources/"; String urlConstruct = urls+workItem.getPresentation().getFormIdenitifier();

All the Forms resources are served from the context bpmresources on the BPM runtime. Obtain the Initial Data to Load the Form The initData variable holds the data that will be used to populate the form when it is loaded.
var initData = '<%=workItem.getPayloadModel().getSerializedPayload()%>';

This data is obtained from the work item object returned by the previous openWorkItem call (in worklist.jsp).

TIBCO ActiveMatrix BPM - BPM Developers Guide

68

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Set the BOM JavaScript Path The bomJSPath variable holds the root folder path used for loading the BOM JavaScript files used by the form, in the format required by the Forms Runtime Adapter loadForm method.
var bomJSPath = "<%=bpmJSPath%>";

This variable is constructed using the following expression.

String bpmJSPath = urls+workItem.getWorkTypeDetail().getVersion(); String urls = reqSession.getAttribute("protocol") + "://" + reqSession.getAttribute("host") + ":" + reqSession.getAttribute("port") + "/bpmresources/";

TIBCO ActiveMatrix BPM - BPM Developers Guide

Rendering a Form for a Work Item 69

Create Action Handlers for User Actions The form provides Submit, Close, and Cancel actions which are displayed to the user as buttons. Handlers for these actions are added using the Runtime Forms Adapter setActionHandler method. The handlers are added once the form is successfully initialized, via the formLoadSuccessCallback function.
var cancelHandler = function(actionName, form) { var jsonPayload = "nodata"; // document.getElementById('jsonpayload').value = jsonPayload; submitData("cancelworkitem", jsonPayload); form.destroy(); }; var closeHandler = function(actionName, form) { var jsonPayload = form.getSerializedParameters(); document.getElementById('jsonpayload').value = jsonPayload; submitData("closeworkitem", jsonPayload); form.destroy(); }; var submitHandler = function(actionName, form) { var jsonPayload = form.getSerializedParameters(); document.getElementById('jsonpayload').value = jsonPayload; submitData("completeworkitem",jsonPayload); form.destroy(); }; var formLoadSuccessCallback = function(form) { form.setActionHandler(form.ACTION_CANCEL, cancelHandler); form.setActionHandler(form.ACTION_CLOSE, closeHandler); form.setActionHandler(form.ACTION_SUBMIT, submitHandler); }; var formLoadErrorCallback = function(error) { alert('Form load failed with error: ' + error); };

When the user performs an action by clicking a button, the handler calls an appropriate method to process the action.

TIBCO ActiveMatrix BPM - BPM Developers Guide

70

| Chapter 3

Developing a Client Application Using the Java Service Connector API

Render the Form The Forms Runtime Adapter loadForm method is used to render the form for the user.
if (initData.charAt(0) == '{') com.tibco.forms.client.FormRunner.loadForm(formURL, initData,bomJSPath, null, "formContainer", formLoadSuccessCallback,formLoadErrorCallback, true); else com.tibco.forms.client.FormRunner.loadFormWithRemoteData(formURL,initData, bomJSPath, null,"formContainer", formLoadSuccessCallback,formLoadErrorCallback, true); } </script> <div id="formContainer" width="100%"></div> <form name="workitemform" id="workitemform" method="post"><input type="hidden" id="jsonpayload" value="" /></form> </body> </html>

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 71
Chapter 4

Authenticating Access to a TIBCO ActiveMatrix BPM Service

This chapter describes the different methods you can use to include authentication information when invoking a TIBCO ActiveMatrix BPM service.

Topics
Introduction, page 72 Direct Authentication, page 73 Single Sign-on (SSO) Authentication, page 74 Using TIBCO ActiveMatrix BPM as the Authority for SSO Authentication, page 82

TIBCO ActiveMatrix BPM - BPM Developers Guide

72

| Chapter 4

Authenticating Access to a TIBCO ActiveMatrix BPM Service

Introduction
At runtime, security policies are enforced on the endpoint of every TIBCO ActiveMatrix BPM service to ensure that access is restricted to authenticated users. Every API call to a TIBCO ActiveMatrix BPM service must be made using the identity of a user who is registered in the BPM organization model. An API call that does not meet this requirement will be rejected. Web service security (WS-security) protocols are used to enforce authentication requirements. Every API call to a BPM service must include an appropriate token in the SOAP header that can be used to authenticate the calling user. The token must comply with one of the following WS-Security token validation protocols: Web Services Security UsernameToken Profile 1.0. This profile provides direct authentication - see Direct Authentication on page 73. Web Services Security X.509 Certificate Token Profile, or Web Services Security: SAML Token Profile (using the "sender-vouches" subject confirmation method). These profiles enable the use of single sign-on authentication - see Single Sign-on (SSO) Authentication on page 74.

Direct and single sign-on authentication, described in the following sections, are the basic methods required to authenticate access to a BPM service. Additional security mechanisms or techniques can be used to enhance the security of any call to a BPM service according to specific business requirements for example, the use of SSL or message-level encryption. These mechanisms and techniques are, however, not specifically needed to access BPM services, and so are not discussed further here. See the TIBCO ActiveMatrix runtime documentation for more information about security mechanisms and techniques used by the TIBCO ActiveMatrix runtime.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Direct Authentication 73

Direct Authentication
Direct authentication requires the calling application to provide valid TIBCO ActiveMatrix BPM login credentials when calling a TIBCO ActiveMatrix BPM service: 1. An API call to a BPM service must include a UsernameToken in the SOAP header, which specifies the username and password of the user on whose behalf the call is being made. 2. A TIBCO ActiveMatrix BPM LDAP authentication application (for example, amx.bpm.auth.easyAs) validates: the supplied username against the BPM organization model. the supplied password against the LDAP entity represented by that BPM user. Use of HTTPS is not mandatory when using direct authentication with a UsernameToken. However, if HTTPS is not used, every service invocation will include an unencrypted user name and password within the SOAP header. It is therefore essential for a secure system to use HTTPS. Direct authentication is the default method used by TIBCO ActiveMatrix BPM (and the only method supported by Workspace and Openspace). The sample client applications provided with this guide provide examples of how to implement direct authentication using a UsernameToken. If you are accessing BPM services using: the BPM public web service API, see Authenticating the Calling User. the Service Connector, see Setting up the Security Handler.

TIBCO ActiveMatrix BPM - BPM Developers Guide

74

| Chapter 4

Authenticating Access to a TIBCO ActiveMatrix BPM Service

Single Sign-on (SSO) Authentication

TIBCO ActiveMatrix BPM supports the use of X.509 certificates or SAML tokens to facilitate SSO authentication. This means that a user who already has a login session with the client application does not need to provide their login credentials again when calling a TIBCO ActiveMatrix BPM service (provided that their credentials are also valid for logging in to TIBCO ActiveMatrix BPM). SSO authentication requires that TIBCO ActiveMatrix BPM can: 1. verify that the incoming message is from a trusted source 2. validate the subject of the message as a registered TIBCO ActiveMatrix BPM user.

SSO Authentication Using an X.509 Certificate

An X.509 certificate represents a guarantee by a Certificate Authority (CA) that a public key is associated with a particular identity. Each user must have a unique public certificate, which: 1. identifies them as the subject of the certificate, using their X.509 Distinguished Name (DN). 2. is signed with the private key of the root certificate issued by the certificate authority. TIBCO ActiveMatrix BPM must hold the corresponding public root certificate issued by the same certificate authority. Any certificate signed by the corresponding private key of this root certificate will be trusted. When the client application invokes a BPM service, it must include the public certificate of the user (on whose behalf the call is being made) in the SOAP header. The Java Service Connector API does not support SSO authentication using an X.509 certificate. You must use the BPM web service API if you want to use X.509. TIBCO ActiveMatrix BPM: 1. verifies the signature of the incoming message against the public root certificate. This confirms that the message originates from a trusted source.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Single Sign-on (SSO) Authentication 75

2. validates that the supplied DN is associated with a registered user in the BPM organization model. This confirms that the subject of the message is a registered BPM user. No LDAP lookup or password checking is performed. The users credentials are assumed to have been validated already because the message has been received from a trusted source.

SSO Authentication Using a SAML Token

TIBCO ActiveMatrix BPM supports authentication by a SAML token using the "sender-vouches" subject confirmation method, whereby an intermediary (for example Microsoft Active Directory) vouches for the user making the request. The intermediary: 1. authenticates the user and generates a SAML assertion holding the user's identity (either a BPM username or a DN). 2. signs the assertion using its private key. TIBCO ActiveMatrix BPM must hold the corresponding public certificate of the private certificate used to sign the SAML assertion. When the client application invokes a BPM service, it must include the SAML assertion of the user (on whose behalf the call is being made) in the SOAP header. See Implementing SSO Authentication Using a SAML Token for more information. TIBCO ActiveMatrix BPM: 1. verifies the signature of the incoming message against the public certificate. This confirms that the message originates from a trusted source. 2. validates that the identity supplied in the SAML assertion is associated with a registered user in the BPM organization model. This confirms that the subject of the message is a registered BPM user. No LDAP lookup or password checking is performed. The users credentials are assumed to have been validated already because the message has been received from a trusted source.

TIBCO ActiveMatrix BPM - BPM Developers Guide

76

| Chapter 4

Authenticating Access to a TIBCO ActiveMatrix BPM Service

Establishing a Trust Relationship Between TIBCO ActiveMatrix BPM and the Client Application
TIBCO ActiveMatrix BPM must have runtime access to the corresponding public certificate of the private certificate that the client application used to sign the incoming message. To set up this trust relationship, obtain the relevant public certificate, then: 1. Add the public certificate to the appropriate TIBCO ActiveMatrix BPM trust store. 2. Configure the TIBCO ActiveMatrix BPM Web Service Security authentication application (amx.bpm.auth.wss.app) and its dependent resource templates and resources instances to use the truststore containing this certificate. See "Configuring TIBCO ActiveMatrix BPM to Use SSO to Authenticate Web Service Requests", in the BPM Administration guide, for detailed information about how to do this.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Single Sign-on (SSO) Authentication 77

Runtime Authentication
Once the trust relationship has been established, runtime authentication is carried out using the following steps (see Figure 2): Figure 2 SSO runtime authentication
1 Login session Keystore Client application Sign message 2 Private key

3 Authenticate

TIBCO ActiveMatrix BPM

Trust store Public certificate

TIBCO ActiveMatrix runtime

1. A user logs in to the client application, which verifies their username and password against the corporate LDAP directory. 2. An API call to a BPM service on behalf of that user must include an X.509 certificate and/or SAML token, that: a. is signed using the appropriate private key. b. identifies the user as the subject of the certificate or token (either by their username or LDAP Distinguished Name). If an LDAP DN is used, the DN must match the DN of the primary LDAP source of the LDAP container from which the user was derived.

TIBCO ActiveMatrix BPM - BPM Developers Guide

78

| Chapter 4

Authenticating Access to a TIBCO ActiveMatrix BPM Service

3. The TIBCO ActiveMatrix BPM Web Service Security authentication application (amx.bpm.auth.wss.app), on the BPM runtime: a. verifies the signature on the incoming message, using the appropriate public certificate. b. validates the user identified in the subject of the certificate/token against the BPM organization model.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Implementing SSO Authentication Using a SAML Token 79

Implementing SSO Authentication Using a SAML Token

The following sections describe some points that you must be aware of when using a SAML token for SSO authentication.

Handling Time Differences Between the Client System and the BPM Runtime When Using Validity Periods in a SAML Assertion
A SAML assertion can contain conditions limiting the validity period of a request. (This provides an additional precaution against identity theft.) When a validity period is defined, if the clocks on the client system and the BPM runtime are not synchronized, you must ensure that time differences between the two systems do not cause authentication failures due to the unexpected expiry of an assertions validity period. For example, suppose a client application is attempting to invoke a service on a BPM runtime. The client application generates a SAML assertion containing the following condition:
<saml:Conditions NotBefore="2011-09-01T14:25:54.622Z" NotOnOrAfter="2011-09-01T14:35:54.622Z" />

where the NotBefore condition is set to the clock time on the client system. However, the BPM runtimes clock has not yet reached this time, and it therefore rejects the call because the assertion is invalid. The methods used to handle this depend on which API the client application is using to invoke BPM runtime services: Web Service API - The client application generates (or obtains) the SAML assertion, so can control what timestamp it puts in the NotBefore and NotOnOrAfter fields in the assertion (or indeed if it uses them at all). Java Service Connector API - The SAMLSenderVouchesSecurityHandler generates the SAML assertion. Optional parameters can be defined to define and insert a validity period. (By default, no validity period is set.) See Using the Service Connector SamlSenderVouchesSecurityHandler Method for more information.

Whichever API it uses, the client application must ensure that any validity period used in the SAML assertion will be valid when the request is authenticated by the BPM runtime.

TIBCO ActiveMatrix BPM - BPM Developers Guide

80

| Chapter 4

Authenticating Access to a TIBCO ActiveMatrix BPM Service

Using the Service Connector SamlSenderVouchesSecurityHandler Method

If you are using the Java Service Connector API and want to implement SSO using a SAML token, the client application must use the SamlSenderVouchesSecurityHandler instead of the DefaultSecurityHandler. (See Setting up the Security Handler for more information about how to use the DefaultSecurityHandler.) The SamlSenderVouchesSecurityHandler method creates a Sender-Vouches SAML assertion for the LDAP Distinguished Name (DN) of the BPM user to be authenticated. The assertion is signed using a specified private keystore and certificate. The full syntax for the SamlSenderVouchesSecurityHandler method is:
public com.tibco.n2.service.connector.config.context SamlSenderVouchesSecurityHandler(String issuer, String keystoreFilePath, String keystorePassword, String aliasKey, String aliasKeyPassword String ldapDistinguishedName, boolean applyConditions, DateTime timeStamp, int validityDuration)

where: issuer identifies the issuer of the assertion (the Issuer value in the assertion). If this value is omitted, a default value of "www.tibco.com" is used. keystoreFilePath is the pathname for the private keystore file used to sign the assertion. Note that this is not an absolute path to the keystore file on the hosts file system. It is a pathname that needs to be resolved via the classpath (the same as for regular property files). The following are two examples: keystoreFilePath = /com/tibco/sample/app/amx-bpm-wss-keystore.jk The package name is com.tibco.sample.app (the .jar containing the package is in the classpath). keystoreFilePath = /resources/keystores/admin_keystore.jks The classpath contains the current directory (.), which causes the file ./resources/keystores/admin_keystore.jks to be readable. The BPM runtime must hold the corresponding public certificate of the private certificate used to sign the SAML assertion keystorePassword is the password for the keystore file.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Implementing SSO Authentication Using a SAML Token 81

aliasKey is the alias for the keystore certificate used to sign the SAML assertion. aliasKeyPassword is the password of the alias for the keystore certificate used to sign the SAML assertion. ldapDistinguishedName is the LDAP Distinguished Name (DN) of the BPM user to be authenticated. This DN must match the DN of the primary LDAP source of the LDAP container from which the BPM user was derived.

applyConditions specifies whether you want to define a validity period for the assertion, using the timeStamp and validityDuration values. The default value (0) is not to define these values, generating an assertion that is permanently valid. (See Handling Time Differences Between the Client System and the BPM Runtime When Using Validity Periods in a SAML Assertion.) timeStamp is the date/time that used to define when the assertion was issued (the IssueInstant value in the assertion). If this value is omitted, the current timestamp of the client machine will be used. validityDuration is the period of time for which the assertion will remain valid, in minutes. (The timeStamp and validityDuration values are used to set the NotBefore and NotOnOrAfter values in the assertion.) If this value is omitted or set to -1, a default value of 20 minutes is used.

TIBCO ActiveMatrix BPM - BPM Developers Guide

82

| Chapter 4

Authenticating Access to a TIBCO ActiveMatrix BPM Service

Using TIBCO ActiveMatrix BPM as the Authority for SSO Authentication

The information in this section is provided only as an example, intended for development purposes. It should not be used as the basis of an SSO implementation in a production environment. In a production environment, the client application will use its own processes and tools to generate the required certificates and keystores for SSO authentication. (See Single Sign-on (SSO) Authentication). However, when you are prototyping or testing a client application that uses SSO authentication, you may want to generate certificates independently, without using the full production environment mechanisms. In this situation, TIBCO ActiveMatrix BPM can act as its own certificate authority (CA).The following sections outline the steps required. To perform the steps described in the following sections, you must: use suitable external tools to generate key pairs and keystores, and to generate and sign CA keys and certificates. use TIBCO ActiveMatrix Administrator to configure the TIBCO ActiveMatrix runtime applications, resource instances (RI) and resource templates (RT) needed to access these keystores and certificates. (See "Configuring TIBCO ActiveMatrix BPM to Use SSO to Authenticate Web Service Requests", in the TIBCO ActiveMatrix BPM Administration guide, for more information.)

Create the Public Root Certificate and BPM Truststore

On the TIBCO ActiveMatrix BPM runtime: 1. Create the public root certificate. To do this: a. Create a private key, for example bpm-ca.key. The key should use the RSA algorithm, and have a password to be used to encrypt the file using the DES cipher. b. Create a self-signed X.509 certificate, for example bpm-ca.crt, containing the public key of the bpm-ca.key private key that you created in the previous step. 2. Generate the TIBCO ActiveMatrix BPM trust store (by default, BPM_CONFIG_FOLDER\tibco\data\bpm\configuration\amx-bp m-wss-truststore.jks) from the bpm-ca.crt public root certificate.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using TIBCO ActiveMatrix BPM as the Authority for SSO Authentication 83

3. Using TIBCO ActiveMatrix Administrator, configure the TIBCO ActiveMatrix BPM Web Service Security authentication application (amx.bpm.auth.wss.app) and its dependent resource templates and resources instances to use this truststore. TIBCO ActiveMatrix BPM can now use this public root certificate to verify the signature of incoming messages.

Generate a Client Certificate and Keystore

1. On the machine on which the client application resides, generate an RSA keystore (for example, auser.jks) containing: for X.509 authentication, a public/private key pair for the TIBCO ActiveMatrix BPM user to be authenticated. The user should be identified by their X.509 DN, which must match the DN of the primary LDAP source of the LDAP container from which the user was derived for SAML authentication, any public/private key pair. (The identity of the user to be authenticated will, in this case, be supplied in the SAML assertion.) 2. Create a certificate request for this keystore entry (for example, auser.csr). 3. Sign the auser.csr certificate request, generating a signed certificate (for example, auser.crt). Use: the CAs private key (bpm-ca.key) to digitally sign the certificate. the CAs public certificate (bpm-ca.crt) to identify the issuer of the private key. (In this case, both entities are the same.) 4. Import the public root certificate issued by the CA (bpm-ca.crt) into the client keystore (auser.jks). Verify that you trust the certificate when importing it. (This step is necessary because TIBCO ActiveMatrix BPM is not a known CA. You must indicate that it can be trusted, so establishing a chain of trust for any certificates signed using bpm-ca.crt.) 5. Overwrite the existing (unsigned) keystore entry with the signed certificate (auser.crt). The client application can now include the signed certificate (auser.crt) in the SOAP header when it invokes a TIBCO ActiveMatrix BPM service.

TIBCO ActiveMatrix BPM - BPM Developers Guide

84

| Chapter 4

Authenticating Access to a TIBCO ActiveMatrix BPM Service

Create a SAML Assertion

If you want to use SAML authentication, you must also supply an appropriate SAML assertion to identify the user to be authenticated. The following code snippet provides a suitable example. The NameIdentifier value identifies the subject of the assertion. Replace AUser with the name of the TIBCO ActiveMatrix BPM user to be authenticated. The user can be identified using either: their TIBCO ActiveMatrix BPM login name, or their X.509 DN, which must match the DN of the primary LDAP source of the LDAP container from which the user was derived. If you are using the Service Connector API, you must use the users X.509 DN. See Using the Service Connector SamlSenderVouchesSecurityHandler Method.
<?xml version="1.0" encoding="UTF-8"?> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" AssertionID="h95483AAB699193993CA04E34887B9D8" IssueInstant="2011-03-01T18:17:55.507Z" Issuer="my.issuer.com" MajorVersion="1" MinorVersion="1"> <saml:Conditions NotBefore="2011-04-01T00:00:25.507Z" NotOnOrAfter="2018-06-01T23:00:25.507Z" /> <saml:AuthenticationStatement AuthenticationInstant="2011-06-01T18:17:49.415Z" AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"> <saml:Subject xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"> <saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="www.tibco.com">AUser</saml:NameIdentifier> <saml:SubjectConfirmation> <saml:ConfirmationMethod> urn:oasis:names:tc:SAML:1.0:cm:sender-vouches </saml:ConfirmationMethod> </saml:SubjectConfirmation> </saml:Subject> </saml:AuthenticationStatement> </saml:Assertion>

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 85
Chapter 5

Working With Organization Models and LDAP

This chapter describes the web service operations and Service Connector methods that allow you to work with organization models and LDAPs.

Topics
Creating an LDAP Container, page 86 Mapping Users, page 92 Navigating the Organization Model, page 109 Listing Capabilities and Privileges, page 111 Using LDAP Filters, page 113 Defining Secondary LDAP Sources in an LDAP Container, page 115 Mapping Resource Attributes to LDAP Attributes, page 118 Organization Relationships, page 123

TIBCO ActiveMatrix BPM - BPM Developers Guide

86

| Chapter 5

Working With Organization Models and LDAP

Creating an LDAP Container

An LDAP container is a collection of one or more LDAP1 sources. An LDAP source represents an LDAP server, which holds information about potential resources (users) who may need to use or participate in TIBCO applications. Before resources can be mapped to groups or positions in an organization model, you must create an LDAP container from which the resources can be selected. The following diagram shows an example of how calls to the Directory Services API can be used to create an LDAP container. Figure 3 Creating an LDAP Container
Client application Work Manager Services

listLDAPSources
1

listLDAPSourcesResponse List of LDAP source alias registered on Directory Engine

LDAPService

listLDAPAttributes
2

LDAP source alias

LDAPService

listLDAPAttributesResponse List of LDAP attributes and values

saveLDAPContainerDetail
3

Parameters provide details of new container

ContainerService

saveLDAPContainerDetailResponse Newly created LDAP container ID

1. Lightweight Directory Access Protocol, which is an application protocol for querying and modifying directory services.
TIBCO ActiveMatrix BPM - BPM Developers Guide

Creating an LDAP Container 87

The following step-by-step descriptions correspond to the numbered steps in the illustration above. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). (For an equivalent example using the Service Connector API (Java), see Creating an LDAP ContainerService Connector API Example (Java) on page 90.) 1. Find out the LDAP sources that are registered on the Directory Engine by calling the listLDAPSources operation. One of the returned sources must be specified as the primary LDAP source when calling the saveLDAPContainerDetail operation to create the LDAP container.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listLDAPSources> </ldap:listLDAPSources> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listLDAPSourcesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> <LdapSource ldap-alias="deLdap5" xmlns=""/> <LdapSource ldap-alias="deLdap4" xmlns=""/> <LdapSource ldap-alias="system" xmlns=""/> <LdapSource ldap-alias="deLdap6" xmlns=""/> <LdapSource ldap-alias="deLdap3" xmlns=""/> <LdapSource ldap-alias="deLdap2" xmlns=""/> <LdapSource ldap-alias="easyAs" xmlns=""/> </listLDAPSourcesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

88

| Chapter 5

Working With Organization Models and LDAP

2. Use the listLDAPAttributes operation (or listLDAPAttributeNames) to get LDAP attributes that can be used in the required LDAP search string when calling the listLDAPSources operation (see step 3).
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listLDAPAttributes alias="easyAs" dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees"> </ldap:listLDAPAttributes> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listLDAPAttributesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> <req-attributes ldap-alias="easyAs" ldap-attribute="departmentnumber" ldap-dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees" name="departmentnumber" xmlns=""> <value>FNB3</value> </req-attributes> <req-attributes ldap-alias="easyAs" ldap-attribute="employeetype" ldap-dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees" name="employeetype" xmlns=""> <value>Permanent</value> </req-attributes> <req-attributes ldap-alias="easyAs" ldap-attribute="employeenumber" ldap-dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees" name="employeenumber" xmlns=""> <value>1201</value> . . . <req-attributes ldap-alias="easyAs" ldap-attribute="objectClass" ldap-dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees" name="objectClass" xmlns=""> <value>organizationalPerson</value> <value>person</value> <value>inetOrgPerson</value> <value>top</value> </req-attributes> </listLDAPAttributesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

3. Use the saveLDAPContainerDetail operation to create and save a new LDAP container.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Creating an LDAP Container 89

The only required parameters are: name - This is the name you want assigned to the new LDAP container. It must be unique on the Directory Engine. primary-ldap.ldap-alias - You must specify a primary LDAP source. A list of the available LDAP sources on the Directory Engine can be obtained using the listLDAPSources operation on the LDAPService web service. primary-ldap.ldap-search-string - You must specify a query string for the primary LDAP (as well as each secondary LDAP, if they are being defined also). This string is used to identify the LDAP entries that are to be considered as candidates for resources (also referred to as "potential resources". For information about valid search strings, see Using LDAP Filters on page 113. LDAP attributes and their values can be obtained from listLDAPAttributeNames and listLDAPAttributes. Additional optional parameters are also available for adding secondary LDAP sources, setting up organizational relationships, etc. For information about those parameters, see saveLDAPContainerDetail on page 432. The following shows an example saveLDAPContainerDetail request containing the minimal amount of information, as well as the new LDAP container ID that is returned if the container creation is successful:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://container.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <con:saveLDAPContainerDetail name="Spokane" > <primary-ldap ldap-alias="easyAs" display-name-attributes="cn" ldap-search-string ="(objectClass=person)" /> </con:saveLDAPContainerDetail> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <saveLDAPContainerDetailResponse container-id="51" xmlns="http://container.api.de.n2.tibco.com"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

90

| Chapter 5

Working With Organization Models and LDAP

Creating an LDAP ContainerService Connector API Example (Java) The following example code illustrates creating an LDAP container using method calls available in the Service Connector API. The step numbers in the comments correspond to the steps in the illustration, Creating an LDAP Container on page 86.
private long createLDAPContainerExample() { long containerId = 0; try { // Step 1 : Get a list of the LDAP Sources available LdapSource[] sourceArray = serviceConnectorInstance.listLDAPSources(0); // Step 2: Use the required LDAP source ldap-alias to get a list of attributes for a particular resource // if we wanted to use the first LDAP source we could use : sourceArray[0].getLdapAlias() // in this example we use "easyAs" XmlLdapAttribute[] ldapAttributesArray = serviceConnectorInstance.listLDAPAttributes("easyAs", "ou=Clint Hill, ou=Swindon, ou=AllEmployees", null); // Step 3: // Create an XmlLdapContainer with details of the container we are creating XmlLdapContainer container = XmlLdapContainer.Factory.newInstance(); container.setName("Spokane"); // Create an XmlLdapContainerResource with details of the Primary LDAP to use for this container XmlLdapContainerResource containerResource = XmlLdapContainerResource.Factory.newInstance(); containerResource.setLdapAlias("easyAs"); containerResource.setDisplayNameAttributes("cn"); containerResource.setLdapSearchString("(objectClass=person)"); // Set the Primary LDAP in the container container.setPrimaryLdap(containerResource); // Save the container and get back the ID containerId = serviceConnectorInstance.saveLDAPContainerDetail(container); } catch (InvalidLDAPSearchFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidLDAPSourceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.de.services.InternalServiceFault e)

TIBCO ActiveMatrix BPM - BPM Developers Guide

Creating an LDAP Container 91

{ // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidLDAPContainerFault e) { // TODO Auto-generated catch block e.printStackTrace(); } return (containerId); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

92

| Chapter 5

Working With Organization Models and LDAP

Mapping Users
Mapping resources is an administrative task that will typically be performed before users start using the TIBCO BPM application. Mapping resources can then be performed on an ongoing basis as resources are added or removed from the system, or if the organization model is revised (new positions, groups, etc.). Mapping resources involves assigning resources to specific groups and/or positions in an organization model, which results in the resources receiving work items that are sent to the groups/positions to which the resources have been mapped. Resources can be mapped to: A group, which represents a job type within the organization. It allows resources to be grouped by their job characteristics. Groups can be hierarchical, i.e., you can have parent groups with sub groups. For example, you can have a CustomerServiceRepresentative group with subgroups of MotorInsuranceSpecialist, TravelInsuranceSpecialist, and HomeInsuranceSpecialist. Typically, sub-groups are specializations of the parent group. Groups can be nested several layers deep. If a group has sub-groups, you can assign resources to either the parent group or the sub-group. Resources that belong to sub-groups receive work items that are offered to their parent groups, as well as to the sub-group to which they belong. Using the example above, resources in the MotorInsuranceSpecialist group will also receive work items offered to the CustomerServiceRepresentative group. A position, which represents a set of responsibilities for a job within an organization unit. It allows resources to be grouped by job responsibility. Positions are subordinate to an organization unit in the organization model. An organization unit can have many positions. For example, you can have a TravelInsurance organization unit with positions of OfficeManagerTravel and TravelInsuranceCSR. Positions cannot be nested, although organization units can. Resources can be mapped to positions, but not organization units. Resources that belong to a position receive work items offered to the position, as well as work items offered to the organization unit that is the immediate parent of the position.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Users 93

Creating Resources
Before resources can log into a BPM application, they must be created1. There are two operations available that you can use to create a resource: getResourceGuid - This operation creates a resource (including assigning a GUID to the resource), but does not map the resource to a group or position. It allows the resource to log into a BPM application, although the resource will typically not receive work items until being mapped to a group or position. (This operation will also return an existing resources name if a resource GUID is passed in, but thats not its primary purpose.) mapEntities - This operation both creates a resource (if it doesnt already exist) and maps the resource to the specified groups and positions. When mapping resources to groups or positions with this operation: If the resource already exists, you can pass in the resources GUID. The GUID can be obtained from the listContainerResources operation (which only returns information about existing resources). If the resource does not exist yet, you can pass in an LdapReference from which the resource can be derived. The LdapReference can be obtained from the listLDAPEntities operation (which can return information from existing resources, as well as potential resourcesthose that have not been created yet). Two examples are shown below for mapping resourcesthey both use mapEntities, but one maps existing resources using the resources GUID; the other maps new resources by passing the LdapReference: 1. Example 1Mapping an Existing Resource Using a GUID illustrates mapping resources that already exist, using the resources GUID. 2. Example 2Mapping a Resource that Does Not Currently Exist illustrates mapping resources that do not exist yet, using an LdapReference for the resource.

1. You will also see the term "exists" for a resource that has been "created". In this context they are synonymous.
TIBCO ActiveMatrix BPM - BPM Developers Guide

94

| Chapter 5

Working With Organization Models and LDAP

Example 1Mapping an Existing Resource Using a GUID The following diagram shows an example of how calls to the Directory Services API can be used to map an existing resource using the resources GUID. Figure 4 Mapping an Existing Resource Using a GUID
Client application Work Manager Services

listOrgModelOverview
1

listOrgModelOverviewResponse List of entities in organization model

BrowseModelService

listContainerResources
2

listContainerResourcesResponse Returns GUIDs for existing resources in LDAP container mapEntities

3

LDAPService

MappingService

mapEntitiesResponse Map resource to specified position or group

The following step-by-step descriptions correspond to the numbered steps in the illustration above. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). (For an equivalent example using the Service Connector API (Java), see Mapping an Existing ResourceService Connector API Example (Java) on page 98.) 1. Find the available groups and positions to which resources can be mapped. The listOrgModelOverview operation can be used to list all available entities for a particular organization model version (model-version=-1 means to return entities from the latest organization model version).

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Users 95

The response from the listOrgModelOverview operation provides GUIDs for the positions and groups in the organization model.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:listOrgModelOverview model-version="-1"/> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listOrgModelOverviewResponse xmlns="http://browse.api.de.n2.tibco.com"> . . . <child entity-type="POSITION" guid="_9y7hYMpREd64gM7QE8RwxA" ideal-number="1" location-guid="_gqt1EMpREd64gM7QE8RwxA" model-version="3" name="VPIT" resource-count="9"> <selection-mode method="ANY" plugin=""/> </child> <child entity-type="POSITION" guid="_8NnJYMpREd64gM7QE8RwxA" ideal-number="1" location-guid="_gqt1EMpREd64gM7QE8RwxA" model-version="3" name="ITRepresentatives" resource-count="9"> <selection-mode method="ANY" plugin=""/> </child> . . . <root-node entity-type="GROUP" guid="_Jb8oYMpREd64gM7QE8RwxA" model-version="3" name="Employees" resource-count="9" xmlns=""> <selection-mode method="ANY" plugin=""/> </root-node> <root-node entity-type="GROUP" guid="_mHwlMMpUEd64gM7QE8RwxA" model-version="3" name="Consultants" resource-count="9" xmlns=""> <selection-mode method="ANY" plugin=""/> </root-node> . . . </listOrgModelOverviewResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

96

| Chapter 5

Working With Organization Models and LDAP

2. Find the available resources. The listContainerResources operation can be used to list all existing (already created) resources in the specified LDAP container (you can get the available LDAP containers using the listLDAPContainers operation). The response from the listContainerResources operation provides GUIDs for the resources in the container.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listContainerResources container-id="10"/> </soapenv:Body> </soapenv:Envelope> SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listContainerResourcesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> . . . <LdapResource guid="171DBF77-F205-4894-AEAA-F1941591548B" name="Richard Cresswell" resource-type="HUMAN" xmlns=""> <LdapReference container-id="10" container-name="easyAs" ldap-alias="easyAs" ldap-dn="OU=Richard Cresswell, OU=London, OU=AllEmployees, O=easyAsInsurance"/> <position entity-type="POSITION" guid="_XB0xADBTEd-x4cVy01Xlww" model-version="3" name="ReardenSalesManager"/> </LdapResource> . . . </listContainerResourcesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Users 97

3. Map the desired resource to the desired groups or positions. The mapEntities operation can be used to map resources. The response from the MapEntities operation returns the name of the resource mapped.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:map="http://mapping.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <map:mapEntities> <!--1 or more repetitions:--> <entityMapping> <target entity-type="POSITION" guid="_9y7hYMpREd64gM7QE8RwxA" > </target> <create resource-type="HUMAN" guid="D4E3C720-5500-4651-B105-6C60C613E226"> </create> </entityMapping> </map:mapEntities> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <mapEntitiesResponse xmlns="http://mapping.api.de.n2.tibco.com"> <result modified="1" xmlns=""> <resource guid="D4E3C720-5500-4651-B105-6C60C613E226" name="Leon Court" resource-type="HUMAN" xmlns:map="http://mapping.api.de.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"></reso urce> </result> </mapEntitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

98

| Chapter 5

Working With Organization Models and LDAP

Mapping an Existing ResourceService Connector API Example (Java) The following example code illustrates mapping an existing resource using method calls available in the Service Connector API. The step numbers in the comments correspond to the steps in the illustration, Mapping an Existing Resource Using a GUID on page 94.
private void mapExistingUserExample(long containerID) { try { // Step 1: Get the Org Model Overview XmlOrgModelNode[] orgModelNodeArray = serviceConnectorInstance.listOrgModelOverview(-1); // Find a Group or Position to map the user to // In this example we will use the first Group we find. XmlOrgModelNode mappingGroup = null; if (orgModelNodeArray != null && orgModelNodeArray.length > 0) { for (XmlOrgModelNode node : orgModelNodeArray) { if (node.getEntityType() == OrganisationalEntityType.GROUP) { mappingGroup = node; break; } // Consider the children, here we just deal with the first level children, // in a real implementation this would need to be recursive to deal with the lower level children if (node.getHasChildren()) { for (XmlOrgModelNode childNode : node.getChildArray()) { mappingGroup = node; break; } } } } // Step 2: Find available resources // For this example we will map the first resource we find. XmlResourceDetail[] resourceArray = serviceConnectorInstance.listContainerResources(containerID); XmlResourceDetail mapResource = null; print(resourceArray[0]); if (resourceArray != null && resourceArray.length > 0) { mapResource = resourceArray[0];

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Users 99

// Step 3: Map the resource // First create a mapping document XmlEntityMapping mapping = XmlEntityMapping.Factory.newInstance(); // Add a new create mapping element XmlLdapEntity mapping1 = mapping.addNewCreate(); // Set the Resource for the mapping mapping1.setGuid(mapResource.getGuid()); mapping1.setName(mapResource.getName()); mapping1.setResourceType(mapResource.getResourceType()); mapping1.setLdapReference(mapResource.getLdapReference()); // Add a target for the mapping XmlModelEntityId target = mapping.addNewTarget(); target.setGuid(mappingGroup.getGuid()); target.setEntityType(mappingGroup.getEntityType()); target.setModelVersion(mappingGroup.getModelVersion()); // Create an arry of the mappings, in this case we only have one. XmlEntityMapping[] mappingArray = new XmlEntityMapping[]{mapping}; // Do the mapping XmlEntityInstantiatedList result = serviceConnectorInstance.mapEntities(mappingArray); print(result); } } catch (InvalidOrgModelVersionFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.de.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidLDAPSourceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidLDAPContainerFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidEntityReferenceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidResourceMappingFault e) {

TIBCO ActiveMatrix BPM - BPM Developers Guide

100

| Chapter 5

Working With Organization Models and LDAP

// TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidEntityTypeFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidServiceRequestFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Users 101

Example 2Mapping a Resource that Does Not Currently Exist The following diagram shows an example of how calls to the Directory Services API can be used to map a resource that has not been created yet by using an LdapReference for the resource. Figure 5 Mapping a Resource that Does Not Currently Exist
Client application Work Manager Services

listOrgModelOverview
1

listOrgModelOverviewResponse List of entities in organization model

BrowseModelService

listLDAPEntities
2

listLDAPEntitiesResponse Returns LdapReference for resources mapEntities

3

LDAPService

MappingService

mapEntitiesResponse Map resource to specified position or group

The following step-by-step descriptions correspond to the numbered steps in the illustration above. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). (For an equivalent example using the Service Connector API (Java), see Mapping a New ResourceService Connector API Example (Java) on page 106.) 1. Find the available groups and positions to which resources can be mapped. The listOrgModelOverview operation can be used to list all available entities for a particular organization model version (model-version=-1 means to return entities from the latest organization model version).

TIBCO ActiveMatrix BPM - BPM Developers Guide

102

| Chapter 5

Working With Organization Models and LDAP

The response from the listOrgModelOverview operation provides GUIDs for the positions and groups in the organization model.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:listOrgModelOverview model-version="-1"/> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listOrgModelOverviewResponse xmlns="http://browse.api.de.n2.tibco.com"> . . . <child entity-type="POSITION" guid="_9y7hYMpREd64gM7QE8RwxA" ideal-number="1" location-guid="_gqt1EMpREd64gM7QE8RwxA" model-version="3" name="VPIT" resource-count="9"> <selection-mode method="ANY" plugin=""/> </child> <child entity-type="POSITION" guid="_8NnJYMpREd64gM7QE8RwxA" ideal-number="1" location-guid="_gqt1EMpREd64gM7QE8RwxA" model-version="3" name="ITRepresentatives" resource-count="9"> <selection-mode method="ANY" plugin=""/> </child> . . . <root-node entity-type="GROUP" guid="_Jb8oYMpREd64gM7QE8RwxA" model-version="3" name="Employees" resource-count="9" xmlns=""> <selection-mode method="ANY" plugin=""/> </root-node> <root-node entity-type="GROUP" guid="_mHwlMMpUEd64gM7QE8RwxA" model-version="3" name="Consultants" resource-count="9" xmlns=""> <selection-mode method="ANY" plugin=""/> </root-node> . . . </listOrgModelOverviewResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Users 103

2. Find the available resources that can be mapped to the desired groups and positions. The listLDAPEntities operation can be used to list all resources in the specified LDAP container (you can get the available LDAP containers using the listLDAPContainers operation). Note that the example below shows passing "false" in the existing-only parameter of the listLDAPEntities operation, which causes the operation to return both existing and non-existing resources. For the existing resources, it returns both the resources GUID, as well as an LdapReference. For non-existing resources, it returns only the LdapReference (as resources are not assigned a GUID until they are created). The LdapReference will be passed in the mapEntities operation to both create and map the resource.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listLDAPEntities model-version="-1" container-id="1" existing-only="false"/> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

104

| Chapter 5

Working With Organization Models and LDAP

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listLDAPEntitiesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> <LdapResource name="Jon Parkin" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="easyAs" ldap-alias="easyAs" ldap-dn="ou=Jon Parkin,ou=Paris,ou=AllEmployees,o=easyAsInsurance"/> </LdapResource> <LdapResource guid="7AAB6AE7-CA2E-4211-BBF8-E081659526FE" name="Clint Hill" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="easyAs" ldap-alias="easyAs" ldap-dn="ou=Clint Hill,ou=Swindon,ou=AllEmployees,o=easyAsInsurance"/> <group entity-type="GROUP" guid="_Jb8oYMpREd64gM7QE8RwxA" model-version="3" name="Employees"/> <position entity-type="POSITION" guid="_yAXSQMpREd64gM7QE8RwxA" model-version="3" name="CFO"/> <privilege entity-type="PRIVILEGE" guid="_I8YiEMpSEd64gM7QE8RwxA" model-version="3" name="BaseUser"> <origin entity-type="GROUP" guid="_Jb8oYMpREd64gM7QE8RwxA" model-version="3" name="Employees"/> </privilege> <privilege entity-type="PRIVILEGE" guid="_HIl0IF-KEd-rno5lLiXABg" model-version="3" name="SuperviseVPs"> <origin entity-type="POSITION" guid="_yAXSQMpREd64gM7QE8RwxA" model-version="3" name="CFO"/> </privilege> . . . </listLDAPEntitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Users 105

3. Create and map the desired resource to the desired groups or positions. The mapEntities operation can be used to create and map resources. The response from the mapEntities operation returns the name and GUID of the resource created and mapped.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:map="http://mapping.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <map:mapEntities> <entityMapping> <target model-version="-1" entity-type="POSITION" guid="_6lTHwMpREd64gM7QE8RwxA"/> <create resource-type="HUMAN" name="Jon Parkin" startDate="2011-07-22T06:59:59.000Z" endDate="2011-07-26T06:59:59.000Z"> <LdapReference container-id="1" container-name="easyAs" ldap-alias="easyAs" ldap-dn="ou=Jon Parkin,ou=Paris,ou=AllEmployees,o=easyAsInsurance"/> </create> </entityMapping> </map:mapEntities> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <mapEntitiesResponse xmlns="http://mapping.api.de.n2.tibco.com"> <result modified="1" xmlns=""> <resource endDate="2011-07-26T06:59:59.000Z" guid="C4A8178F-2E88-4187-9C5A-AA3F7673E0F3" name="Jon Parkin" resource-type="HUMAN" startDate="2011-07-22T06:59:59.000Z" xmlns:map="http://mapping.api.de.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <LdapReference container-id="1" container-name="easyAs" ldap-alias="easyAs" ldap-dn="ou=Jon Parkin,ou=Paris,ou=AllEmployees,o=easyAsInsurance"/> </resource> </result> </mapEntitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

106

| Chapter 5

Working With Organization Models and LDAP

Mapping a New ResourceService Connector API Example (Java) The following example code illustrates mapping a new resource (that is, one that does not currently exist) using method calls available in the Service Connector API. The step numbers in the comments correspond to the steps in the illustration, Mapping a Resource that Does Not Currently Exist on page 101.
private void mapNewUserExample(long containerID) { try { // Step 1: Get the Org Model Overview XmlOrgModelNode[] orgModelNodeArray = serviceConnectorInstance.listOrgModelOverview(-1); // Find a Group or Position to map the user to // In this example we will use the first Group we find. XmlOrgModelNode mappingGroup = null; if (orgModelNodeArray != null && orgModelNodeArray.length > 0) { for (XmlOrgModelNode node : orgModelNodeArray) { if (node.getEntityType() == OrganisationalEntityType.GROUP) { mappingGroup = node; break; } // Consider the children, here we just deal with the first level children, // in a real implementation this would need to be recursive to deal with the lower level children if (node.getHasChildren()) { for (XmlOrgModelNode childNode : node.getChildArray()) { mappingGroup = node; break; } } } } // Step 2: Find available resources // For this example we will map the first resource we find. XmlResourceDetail[] resourceArray = serviceConnectorInstance.listLDAPEntities(containerID, false); XmlResourceDetail mapResource = null; print(resourceArray[0]); if (resourceArray != null && resourceArray.length > 0) { mapResource = resourceArray[0];

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Users 107

// Step 3: Map the resource // First create a mapping document XmlEntityMapping mapping = XmlEntityMapping.Factory.newInstance(); // Add a new create mapping element XmlLdapEntity mapping1 = mapping.addNewCreate(); // Set the Resource for the mapping mapping1.setName(mapResource.getName()); mapping1.setResourceType(mapResource.getResourceType()); mapping1.setLdapReference(mapResource.getLdapReference()); // Add a target for the mapping XmlModelEntityId target = mapping.addNewTarget(); target.setGuid(mappingGroup.getGuid()); target.setEntityType(mappingGroup.getEntityType()); target.setModelVersion(mappingGroup.getModelVersion()); // Create an arry of the mappings, in this case we only have one. XmlEntityMapping[] mappingArray = new XmlEntityMapping[]{mapping}; // Do the mapping XmlEntityInstantiatedList result = serviceConnectorInstance.mapEntities(mappingArray); print(result); } } catch (InvalidOrgModelVersionFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.de.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidLDAPSourceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidLDAPContainerFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidEntityReferenceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidResourceMappingFault e) { // TODO Auto-generated catch block

TIBCO ActiveMatrix BPM - BPM Developers Guide

108

| Chapter 5

Working With Organization Models and LDAP

e.printStackTrace(); } catch (InvalidEntityTypeFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidLDAPSearchFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Navigating the Organization Model 109

Navigating the Organization Model

The Directory Services API enables applications to navigate the organization model to locate a particular organizational entity for work allocation. The following diagram shows an example of how calls to the Directory Services API can be used to navigate the organization model.
Client application Work Manager Services

listModelVersions() listModelVersionsResponse Version list - list of major organization model versions

BrowseModelService

listOrgModelOverview(version) Version specifies a major organization model version

BrowseModelService

listOrgModelOverviewResponse Type, name and GUID of every organization, organization unit, position, group and location

listAssociatedResources(entity-guid) The GUID of the entity being queried

EntityResolverService

listAssociatedResourcesResponse Attributes of all resources associated with the specified entity

Initially, a listModelVersions call can be used to return a list of all major versions of the organization model that have been deployed. The listOrgModelOverview call specifies one of the versions returned from that list and returns a tree structure containing an outline of the organization model. It lists the following organization model entities: Organization

TIBCO ActiveMatrix BPM - BPM Developers Guide

110

| Chapter 5

Working With Organization Models and LDAP

Organization Unit Position Group Location

It also returns the unique ID of each of these entities. An application can select one of these entities and drill into it for further information by supplying the ID and version of the entity to the listAssociatedResources call. This call returns a list of those resources associated with the specified organization model entities, identified by their GUIDs. If a resource is associated with more than one of the identified model entities, it will only be listed once. If the type of organization model entity being queried is: an organization unit, the result includes those resources that hold positions within the organization unit. a group, the result includes resources that hold positions within the group being queried, and also includes resources associated with any of that group's sub-groups.

Combinations of these calls enable an application to navigate the organizational model tree to locate a required organization model entity. Navigating Large Organizations As shown above, the listOrgModelOverview operation can be used to get information for an entire organization model with one service call. This works fine for smaller organizations. However, if you have a large organization, it may be better to use the openOrgModel operation to get the root-nodes of the organization model, then the child elements from the openOrgModel response can be used to construct a request for the browseModelNode operation. Similarly, a child element from the browseModelNode response could then be used to create another request for browseModelNode, and so on, allowing you to "drill-down" into the organization model The "has-children" attribute of the child elements indicate whether passing that child identifier to browseModelNode would return entities nested beneath that child element in the organizational hierarchy.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Capabilities and Privileges 111

Listing Capabilities and Privileges

You can use Directory Services API calls to list capabilities or privileges and to assign capabilities to a resource as shown in the following diagram. You can also use the API to list a resources inherited privileges.
Client application Work Manager Services

listAssociatedResources(guid) Specifies the GUID of the entity being queried

EntityResolverService

listAssociatedResourcesResponse Gets the GUID of all resources associated with the specified entity
getPrivileges provides the same functionality for privileges rather than capabilities

getCapabilities(guid) Specifies the GUID of the resource being queried

BrowseModelService

listOrgModelOverviewResponse Returns the capabilities associated with that resource

updateCapabilityAssignments resource GUID, capability GUID, remove=TrueFalse updateCapabilityAssignmentsResponse successful

MappingService

You can use listAssociatedResources to obtain the ID of a resource. You can then use getCapabilities, specifying the resource ID, to return a list of the capabilities for a given organization model entity (such as a group or position) or for a resource (meaning a user mapped to an organization model entity). The getCapabilities call returns the following information:

TIBCO ActiveMatrix BPM - BPM Developers Guide

112

| Chapter 5

Working With Organization Models and LDAP

For an organizational entity, the capabilities assigned to it in the organization model. These are the capabilities that the resource assigned to that entity should possess, which is the "entry criteria" for a group or position. For a resource, the actual capabilities that the selected resource possesses.

You can use updateCapabilityAssignments to change the capabilities assigned to a resource. The call specifies the ID of any capability to be changed, plus a remove flag, which is a Boolean value indicating whether or not the operation is to remove a capability that the resource may already possess (remove defaults to FALSE, which assigns the capability).

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using LDAP Filters 113

Using LDAP Filters

An LDAP filter can be specified as a parameter to the following requests: listLDAPAttributeNames and saveLDAPContainerDetail. Query strings must be enclosed in parentheses. This allows you to specify multiple strings, each one enclosed in its own parentheses (see the examples below). You can use the following special characters with query strings: Special Character * &

Meaning Wild card character. Matches zero or more of any character. Logical AND. Returns resources that satisfy the first string AND the second string. Place this special character to the left of the first query string, then enclose the entire expression in parentheses, as follows:
(&(string1)(string2))

Logical OR. Returns resources that satisfy the first string OR the second string. Place this special character to the left of the first query string, then enclose the entire expression in parentheses, as follows:
(|(string1)(string2))

NOT. This means that you want all resources that do NOT match the specified value. Place this special character to the left of the query string to which it applies, inside of the parentheses:
(!(string))

The following are some examples. The following query returns all resources that have sn attribute values beginning with s:
(sn=s*)

TIBCO ActiveMatrix BPM - BPM Developers Guide

114

| Chapter 5

Working With Organization Models and LDAP

The following query returns all resources that have sn attribute values beginning with s or p:
(|(sn=s*)(sn=p*))

The following query returns all resources with carlicense attribute values equal to Full and employeetype attribute values equal to Permanent:
(&(carlicense=Full)(employeetype=Permanent))

The following query returns all resources where sn attribute values dont start with s and dont start with p:
(&(!(sn=s*))(!(sn=p*)))

Depending on the specific LDAP Server being used, the query syntax can vary. If the syntax described above does not return the expected results, consult the documentation for your LDAP Server.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Defining Secondary LDAP Sources in an LDAP Container 115

Defining Secondary LDAP Sources in an LDAP Container

Each LDAP container that you define must include one primary LDAP source. It can also include one or more secondary LDAP sources. If there are secondary LDAP sources defined, they will be used to find additional information about each potential resource from the primary LDAP source. Lookups are performed into each secondary LDAP source. If an exact match of a potential resource can be found in every secondary LDAP source, the data from all sources is merged together. In other cases, the potential resource may be omitted or labeled invalid. It determines that based on attribute relationships you specify when adding a secondary LDAP source to your container. The following are reasons you might want to define a secondary LDAP source: The business process needs to access attribute data that is in both the primary and secondary LDAP sources. the business process needs to access attribute data from an LDAP source that is not used for login authentication (the primary LDAP source is always used for authentication). As an example, suppose you have two LDAP sources: Acme-Employees and Acme-Developers. The Acme-Employees LDAP source includes sales and support resources, as well as developers. The Acme-Developers LDAP source includes Acme employees who are developers, as well as developer contractors who are not Acme employees. If you want the list of potential resources to include all Acme employees that are developers, and the business process needs attribute data from both LDAP sources, you would add both sources to one container, using filter criteria to filter out all resources other than Acme developers. Conversely, if the attribute data needed by the business process is available in one of the LDAP sources, it is much more efficient to include only the one LDAP source in the container. Potential resources are the resources in an LDAP container that can be created and mapped to groups and positions. A list of potential resources is created by the system as follows: It starts with a list of potential resources from the primary LDAP source (that satisfy the specified query string in the primary-ldap.ldap-search-string parameter of the saveLDAPContainerDetail operation). An attempt is made to match those potential resources with entries in each secondary LDAP source. If an exact match is found in every secondary LDAP source, the data from the secondary sources is merged in with the data from the primary source.

TIBCO ActiveMatrix BPM - BPM Developers Guide

116

| Chapter 5

Working With Organization Models and LDAP

If a potential resource is not found inside one or more of the secondary LDAP sources, the potential resource is eliminated from the list. If matches are found in every secondary LDAP source, they must uniquely identify only one LDAP entry in each source. If one or more match multiple items, the item remains in the potential resources list but is marked as invalid. This primary / secondary match is accomplished using the attributes specified in the container-mapping element when calling the saveLDAPContainerDetail operation:
<secondary-ldap ldap-alias="Global" ldap-search-string="(cn=*)" display-name-attributes="ou"> <container-mapping primary-attribute="ou" secondary-attribute="displayname"/> </secondary-ldap>

The goal of comparing primary / secondary attributes is to ensure that data from the secondary LDAP source is only merged together with the appropriate potential resource from the primary LDAP source. Where a match cannot be found, or where it is not one-to-one, the potential resource will not have a complete, accurate set of information, and it will be either omitted (where no match is found) or marked as invalid (where the match isn't one-to-one). For example, if there are several resources with the same last name, you need to map more than just the last name; maybe mapping first name too will be enough, or maybe you need to map more attributes (because there may be multiple resources in the secondary LDAP source with the same first and last nameit would not know which to include). Maybe there are other types of data, such as an employee ID that would work better and would avoid inconsistencies in data entry (typos, nicknames, abbreviations, etc.). You can get the LDAP attributes and their values to use in the primary-attribute and secondary-attribute attributes using the listLDAPAttributeNames operation. In the example shown above, we know that the ou attribute in the primary LDAP source contains the complete name of the resources, the displayname attribute in the secondary LDAP source contains the same information. So those attributes would be prime candidates to map the primary and secondary LDAP sources.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Defining Secondary LDAP Sources in an LDAP Container 117

If you choose attributes that contain names, always be aware that there may be differences in the way those names were entered in the different LDAP sources, for example, Bob vs. Robert, Mike vs. Michael, or simple misspellings. Things like employee numbers tend to make good attributes to map.

TIBCO ActiveMatrix BPM - BPM Developers Guide

118

| Chapter 5

Working With Organization Models and LDAP

Mapping Resource Attributes to LDAP Attributes

When an organization model is created using the TIBCO Business Studio Organization Modeler, you can also create resource attributes. These attributes can contain data that the business process may access during runtime. The following shows an example of some resource attributes that were created in TIBCO Business Studio:

These attributes are available for each resource that you create or map to groups or positions. For example, each resources cell phone number can be stored in the CellPhone attribute.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Resource Attributes to LDAP Attributes 119

Getting Resource Attributes

You can get a list of the available resource attributes using the listBusinessParameters operation. For example, the following shows an excerpt from the response from the listBusinessParameters operation:
<listBusinessParametersResponse xmlns="http://attribute.api.de.n2.tibco.com"> <param-desc default-value="" description="" guid="_looEEMpSEd64gM7QE8RwxA" model-version="3" name="CellPhone" type="String" xmlns=""/> <param-desc default-value="" description="" guid="_n2CW0MpSEd64gM7QE8RwxA" model-version="3" name="ClearanceExpiration" type="DateTime" xmlns=""/> <param-desc default-value="" description="" guid="_qr04MMpSEd64gM7QE8RwxA" model-version="3" name="DeskPhone" type="String" xmlns=""/> <param-desc default-value="" description="" guid="_sfdZAMpSEd64gM7QE8RwxA" model-version="3" name="DeveloperLevel" type="Enum" xmlns=""> <enum-val>Advanced</enum-val> <enum-val>Intermediate</enum-val> <enum-val>Beginner</enum-val> </param-desc> . . .

This example shows four resource attributes: CellPhone, ClearanceExpiration, DeskPhone, and DeveloperLevel. The DeveloperLevel attribute also has three enumerated values1.

1. Note that resource attributes of type "Enum" and "EnumSet" cannot be mapped to LDAP attributes.
TIBCO ActiveMatrix BPM - BPM Developers Guide

120

| Chapter 5

Working With Organization Models and LDAP

Getting LDAP Attributes

Each LDAP source also provides attributes in which data about the resources in that LDAP source is stored. You can get a list of these using the listLDAPAttributes operation. For example, the following shows an excerpt from the response from the listLDAPAttributes operation:
<listLDAPAttributesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> <req-attributes ldap-alias="easyAs" ldap-attribute="departmentnumber" ldap-dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees" name="departmentnumber" xmlns=""> <value>FNB3</value> </req-attributes> <req-attributes ldap-alias="easyAs" ldap-attribute="employeetype" ldap-dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees" name="employeetype" xmlns=""> <value>Permanent</value> </req-attributes> <req-attributes ldap-alias="easyAs" ldap-attribute="employeenumber" ldap-dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees" name="employeenumber" xmlns=""> <value>1201</value> </req-attributes> . . .

This example shows three LDAP attributes: departmentnumber, employeetype, and employeenumber.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Mapping Resource Attributes to LDAP Attributes 121

Mapping Attributes
You may need to map one or more of the resource attributes to attributes in the LDAP sources you have defined in your LDAP container. You may need to do this because the business process does not have direct access to the attributes in the LDAP sources, but it does have access to the resource attributes in the organization model. When you map a resource attribute to an LDAP attribute, it gives the business process access to the data in the LDAP attribute at runtime. To map resource attributes to LDAP attributes, use the attribute-mapping element in the saveLDAPContainerDetail operation1. For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://container.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <con:saveLDAPContainerDetail name="Field6" description="Field personnel" > <primary-ldap id="5" ldap-alias="deLdap2" ldap-search-string="(objectClass=person)" display-name-attributes="displayname"/> <secondary-ldap id="6" ldap-alias="easyAs" ldap-search-string="(objectClass=person)" display-name-attributes="ou"> <container-mapping primary-attribute="displayname" secondary-attribute="sn"/> </secondary-ldap> <secondary-ldap id="7" ldap-alias="deLdap4" ldap-search-string="(objectClass=person)" display-name-attributes="ou"> <container-mapping primary-attribute="displayname" secondary-attribute="sn"/> </secondary-ldap> <attribute-mapping ldap-resource-id="6" business-attribute-id="_7seVwMpSEd64gM7QE8RwxA" ldap-attribute="mail"/> <attribute-mapping ldap-resource-id="7" business-attribute-id="_nekK8AEZEd-SRt13X0LOYA" ldap-attribute="departmentnumber"/> </con:saveLDAPContainerDetail> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

122

| Chapter 5

Working With Organization Models and LDAP

In this example, there are three LDAP sources: one primary and two secondary. And there are two resource attributes mapped to LDAP attributes. Note that the primary-ldap.id and secondary-ldap.id values are just made up they can be any value you choose. Their only purpose is to be able to reference that ID value in the attribute-mapping.ldap-reference-id attribute so that it knows which LDAP source to get the LDAP attribute from. So in the example above, the "mail" LDAP attribute is obtained from the LDAP source was identified as "6", and the "departmentnumber" LDAP attribute is obtained from the LDAP source that was identified as "7". If an LDAP container's details are retrieved with the getLDAPContainerDetail operation, the ldap-reference-id values will be assigned. The caller can re-use the same ID values when making a request to update the existing LDAP container, or they can be assigned arbitrary values againthey are only used to link the attribute-mapping element to the corresponding primary or secondary LDAP source element.

1. Note that TIBCO Business Studio refers to attributes defined there as "resource attributes", whereas the attribute-mapping element refers to them as "business attributes". They are the same thing.
TIBCO ActiveMatrix BPM - BPM Developers Guide

Organization Relationships 123

Organization Relationships
When you are creating or editing an LDAP container (using the saveLDAPContainerDetail operation), you can specify that that container have a relationship with one or more organizations. (This, of course, is applicable only if you have multiple organizations in your organization model.) When organization relationships are defined for any container, it can affect resources that are created in that container in the following ways: That resource will be able to view only the organization(s) to which his container has a relationship, as well as organizations that do not have any relationship with a container. This allows you to partition resources so that they cannot see organizations to which they dont belong. Note that this ability to partition does not apply to groups, as they are separate from, and outside, the organization structure in the organization model. That is, you cannot prevent a resource from seeing a particular group. It limits the positions into which the resource can be mapped. Resources can be mapped only to positions in organizations to which their container has a relationship, as well as to positions in organizations that have no explicit relationships to any container.

If a resource has been mapped to a position, then an organization relationship is set up that would bar that resource from membership to that position, it results in an invalid membership. Resources that have been mapped to invalid memberships should be removed (the mapEntities operation can be used to remove memberships). Organization relationships are specified using the administered-organisation element when calling the saveLDAPContainerDetail operation.

TIBCO ActiveMatrix BPM - BPM Developers Guide

124

| Chapter 5

Working With Organization Models and LDAP

When a relationship is set up, it can effect the response from the following operations (unless the caller has a system action that overrides organization relationshipssee Overriding Organization Relationships on page 124): BrowseModelService listOrgModelOverview - Only includes those organizations (and sub-elements) to which the calling user has access (because of organization relationships). openOrgModel - Only includes those organizations (and sub-elements) to which the calling user has access (because of organization relationships). browseModelNode - Only includes those organizations (and sub-elements) to which the calling user has access (because of organization relationships). ContainerService listLDAPContainers - Returns only the LDAP containers that have a relationship with the LDAP container in which the caller was created, or that have no organization relationships set up. LDAPService listContainerResources - Returns an empty response if the calling user does not have access to an organization to which a LDAP container is associated (because of organization relationships). listLDAPEntities - Returns an empty response if the calling user does not have access to an organization to which a LDAP container is associated (because of organization relationships).

Overriding Organization Relationships

System actions are provided that override organization relationships, giving the caller access to all organizations, regardless the organization relationships that have been set up. These system actions are typically given to administrative users. The system actions that override organization relationships are: organizationAdmin - This system action is only applicable to BrowseModelService operations. Users with this system action will see all organizations when calling the listOrgModelOverview, openOrgModel, and browseModelNode operations, regardless the organization relationships set up. Note that to call any operation in the BrowseModelService, the user must also possess the browseModel system actionholders of the organizationAdmin system action get additional access (if there are organization relationships defined).

TIBCO ActiveMatrix BPM - BPM Developers Guide

Organization Relationships 125

LDAPAdmin - This system action is only applicable to ContainerService and LDAPService operations. Users with this system action will see all organizations when calling the listLDAPContainers, listContainerResources, and listLDAPEntities operations, regardless the organization relationships set up. Note that to call the listLDAPContainers, listContainerResources, and listLDAPEntities operations, the caller must possess either the resourceAdmin or LDAPAdmin system action. If the caller has the only resourceAdmin system action, the organizations he can see are restricted by organization relationship. If he also has (or has only) the LDAPAdmin system action, he can see all organizations, regardless the organization relationships set up.

You can determine if a user has a specific system action using the listAuthorisedOrgs operation.

TIBCO ActiveMatrix BPM - BPM Developers Guide

126

| Chapter 5

Working With Organization Models and LDAP

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 127
Chapter 6

Working With Processes

This chapter describes the web service operations and Service Connector methods that allow you to work with processes.

Topics
Listing Available Process Templates, page 128 Starting a Process Instance, page 138 Listing Available Process Instances, page 145 Sorting and Filtering Lists of Process Templates and Instances, page 151 Process Instance State Transitions, page 159 Migrating a Process Instance to a Different Version, page 161

TIBCO ActiveMatrix BPM - BPM Developers Guide

128

| Chapter 6

Working With Processes

Listing Available Process Templates

The ProcessManagerService service provides three operations to retrieve the process templates that are defined on a node. Each of these operations requires a different set of criteria. listProcessTemplates queryProcessTemplates queryProcessTemplatesAlt

Figure 6 Listing Available Process Templates

Client application

Process Manager Services

listProcessTemplates Can limit request to specific module, template, or version

processManagement

basicProcessTemplates
-- or --

queryProcessTemplates Returns templates according to SQL query

processManagement

queryProcessTemplatesOutput
-- or --

queryProcessTemplatesAlt Alternative method of specifying SQL query queryProcessTemplatesOutput

processManagement

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Available Process Templates 129

listProcessTemplates
The listProcessTemplates operation returns the process templates that match the input criteria. It allows you to limit the process templates returned according to those in a specified module, those with a specified template name, or those of a specified version. Leaving all parameters blank causes the operation to return all process templates. Web Service API example (SOAP):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName></proc:moduleName> <proc:processName></proc:processName> <proc:version></proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

130

| Chapter 6

Working With Processes

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <basicProcessTemplates xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <basicProcessTemplate> <processQName> <moduleName>/HelpDesk/Process Packages/HelpDesk.xpdl</moduleName> <processName>InternalHelpDesk</processName> <version>1.0.0.201105061158</version> </processQName> <description>*** Generated by TIBCO Business Studio.</description> </basicProcessTemplate> <basicProcessTemplate> <processQName> <moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</moduleName> <processName>WelcomeUsers</processName> <version>1.0.0.201106290831</version> </processQName> <description/> </basicProcessTemplate> . . . </basicProcessTemplates> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Available Process Templates 131

Service Connector API example (Java):

private void listProcessTemplatesExample() { // Create an empty QualifiedProcessName as we want to query all process templates QualifiedProcessName process = QualifiedProcessName.Factory.newInstance(); try { // Query the process templates BasicProcessTemplate[] templates = serviceConnectorInstance.listProcessTemplates(process); } catch (IllegalArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (OperationFailedFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

132

| Chapter 6

Working With Processes

queryProcessTemplates
The queryProcessTemplates operation returns the process templates that match the provided SQL query. Web Service API example (SOAP):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:queryProcessTemplatesInput> <proc:query>SELECT * FROM process WHERE DEFINITION.NAME='WelcomeUsers' ORDER BY DEFINITION.VERSION</proc:query> <proc:pageSize>0</proc:pageSize> </proc:queryProcessTemplatesInput> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Available Process Templates 133

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryProcessTemplatesOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <processTemplates> <processTemplate> <basicTemplate> <processQName> <moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</moduleName> <processName>WelcomeUsers</processName> <version>1.0.0.201106290731</version> </processQName> <description/> </basicTemplate> <priority>NORMAL</priority> <creationTime>2011-06-29T07:29:58.943-07:00</creationTime> </processTemplate> <processTemplate> <basicTemplate> <processQName> <moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</moduleName> <processName>WelcomeUsers</processName> <version>1.0.0.201106290831</version> </processQName> <description/> </basicTemplate> <priority>NORMAL</priority> <creationTime>2011-06-29T08:30:30.543-07:00</creationTime> </processTemplate> </processTemplates> <pagingID>0</pagingID> </queryProcessTemplatesOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

134

| Chapter 6

Working With Processes

Service Connector API example (Java):

private void queryProcessTemplatesExample() { try { // Query the process templates using a SQL query QueryProcessTemplatesOutput templates = serviceConnectorInstance.queryProcessTemplates( "SELECT * FROM process WHERE DEFINITION.NAME='SimpleProcess' ORDER BY DEFINITION.VERSION", 0); System.out.println(templates); } catch (IllegalArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (OperationFailedFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Available Process Templates 135

queryProcessTemplatesAlt
The queryProcessTemplatesAlt operation returns the process templates that match the specified set of search criteria. This operation is similar to the queryProcessTemplates operation, except the SQL query is broken into its constituent parts. Web Service API example (SOAP):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:queryProcessTemplatesAltInput> <proc:select></proc:select> <proc:where>DEFINITION.NAME='WelcomeUsers'</proc:where> <proc:orderBy>DEFINITION.VERSION</proc:orderBy> <proc:pageSize>0</proc:pageSize> </proc:queryProcessTemplatesAltInput> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

136

| Chapter 6

Working With Processes

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryProcessTemplatesOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <processTemplates> <processTemplate> <basicTemplate> <processQName> <moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</moduleName> <processName>WelcomeUsers</processName> <version>1.0.0.201106290731</version> </processQName> <description/> </basicTemplate> <priority>NORMAL</priority> <creationTime>2011-06-29T07:29:58.943-07:00</creationTime> </processTemplate> <processTemplate> <basicTemplate> <processQName> <moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</moduleName> <processName>WelcomeUsers</processName> <version>1.0.0.201106290831</version> </processQName> <description/> </basicTemplate> <priority>NORMAL</priority> <creationTime>2011-06-29T08:30:30.543-07:00</creationTime> </processTemplate> </processTemplates> <pagingID>0</pagingID> </queryProcessTemplatesOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Available Process Templates 137

Service Connector API example (Java):

private void queryProcessTemplatesAltExample() { try { // Query the process templates using a broken up SQL query QueryProcessTemplatesOutput templates = serviceConnectorInstance.queryProcessTemplatesAlt(null, "DEFINITION.NAME='SimpleProcess'", "DEFINITION.VERSION", 0); System.out.println(templates); } catch (IllegalArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (OperationFailedFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

138

| Chapter 6

Working With Processes

Starting a Process Instance

Starting a process instance involves "creating" an instance of a process template using the createProcessInstance operation. Note that a more common method of starting a process instance is to start a business service, which then starts the process instance. For information about starting a business service, see Starting a Business Service on page 260. The following diagram shows an example of how calls to the Process Services API can be used to start a process instance. Figure 7 Starting a Process Instance
Process Manager Services

Client application

listProcessTemplates
1

basicProcessTemplates List of defined process templates

processManagement

listStarterOperations
2

starterOperations List all starter operations in template

processManagement

getStarterOperationInfo
3

operationInfo List of parameter details for starter operation

processManagement

createProcessInstance
4

processID Unique ID of started process instance

processManagement

TIBCO ActiveMatrix BPM - BPM Developers Guide

Starting a Process Instance 139

The following step-by-step descriptions correspond to the numbered steps in the illustration above. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). (For an equivalent example using the Service Connector API (Java), see Starting a Process InstanceService Connector API Example (Java) on page 144.) 1. Find the available process templates. The listProcessTemplates operation can be used to list available process templates on the node. (You could also use the queryProcessTemplates or queryProcessTemplatesAlt operation to get a list of process templates.) The response from the listProcessTemplates operation provides module names, process name, and versions of the available process templates. These are needed when calling the createProcessInstance operation to start a process instance.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName></proc:moduleName> <proc:processName></proc:processName> <proc:version></proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

140

| Chapter 6

Working With Processes

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <basicProcessTemplates xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <basicProcessTemplate> <processQName> <moduleName>/SalesCallback/Process Packages/SalesCallback.xpdl</moduleName> <processName>SalesCallbackProcess</processName> <version>1.0.0.201106301052</version> </processQName> <description/> </basicProcessTemplate> <basicProcessTemplate> <processQName> <moduleName>/Supply/Process Packages/Supply.xpdl</moduleName> <processName>Supply</processName> <version>1.0.0.201105061158</version> </processQName> <description/> </basicProcessTemplate> . . . </basicProcessTemplates> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

2. Get starter operations. Starter operations refer to start events of processes. To be able to directly start an instance of a process template, the start event of the process must have a trigger type of "None" (as opposed to a trigger type of "Message", which requires that the process be started by a business service).
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName>/Supply/Process Packages/Supply.xpdl</proc:moduleName> <proc:processName>Supply</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Starting a Process Instance 141

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <starterOperations xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <starterOperation> <processQName> <moduleName>/Supply/Process Packages/Supply.xpdl</moduleName> <processName>Supply</processName> <version>1.0.0.201105061158</version> </processQName> <operation>StartEvent</operation> </starterOperation> </starterOperations> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

3. If the process template for which you are starting an instance has "start parameters" (also known as "formal parameters"), which are used to pass data into the process instance being started, you should also call the getStarterOperationInfo operation to get the names of the available start parameters.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:starterOperation> <proc:processQName> <proc:moduleName>/Supply/Process Packages/Supply.xpdl</proc:moduleName> <proc:processName>Supply</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:processQName> <proc:operation>StartEvent</proc:operation> </proc:starterOperation> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

142

| Chapter 6

Working With Processes

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <operationInfo xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <operationName>StartEvent</operationName> <parameters> <templateAttribute> <name>CustomerID</name> <type>java.lang.String</type> </templateAttribute> </parameters> </operationInfo> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

4. Start the process instance. The createProcessInstance operation is used to start the process instance and pass in start parameters, if required. The operation returns the process ID of the instance that is started.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:createProcessInstanceInput> <proc:processQName> <proc:moduleName>/Supply/Process Packages/Supply.xpdl</proc:moduleName> <proc:processName>Supply</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:processQName> <proc:operationName>StartEvent</proc:operationName> <proc:parameterMap> <!--Zero or more repetitions:--> <proc:parameter> <proc:name>CustomerID</proc:name> <proc:value>9987-345</proc:value> </proc:parameter> </proc:parameterMap> </proc:createProcessInstanceInput> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Starting a Process Instance 143

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:processID xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType">pvm:0a121b</proc:processID> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

144

| Chapter 6

Working With Processes

Starting a Process InstanceService Connector API Example (Java) The following example code illustrates starting a process instance using method calls available in the Service Connector API. The step numbers in the comments correspond to the steps in the illustration, Starting a Process Instance on page 138.
private void startProcessInstanceExample() { QualifiedProcessName process = QualifiedProcessName.Factory.newInstance(); try { // Step 1 : List the available templates BasicProcessTemplate[] templates = serviceConnectorInstance.listProcessTemplates(process); // Step 2 : Get the starter operations, in this example we use the first template we got back if (templates != null && templates.length > 0) { StarterOperation[] operations = serviceConnectorInstance.listStarterOperations(templates[0] .getProcessQName()); // Step 3 : Check the starter operation - in this example we use the first starter operation we got back if (operations != null && operations.length > 0) { OperationInfo info = serviceConnectorInstance.getStarterOperationInfo( templates[0].getProcessQName(), operations[0].getOperation()); String processId = serviceConnectorInstance.createProcessInstance(templates[0].getProcessQName(), operations[0].getOperation(), null); System.out.println(processId); } } } catch (IllegalArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (OperationFailedFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Available Process Instances 145

Listing Available Process Instances

The ProcessManagerService service provides three operations to retrieve the current process instances. Each of these operations requires a different set of criteria. listProcessInstances queryProcessInstances queryProcessInstancesAlt

Figure 8 Listing Available Process Instances

Process Manager Services

Client application

listProcessInstances Can limit request to specific module, template, or version

processManagement

processInstances
-- or --

queryProcessInstances Returns process instances according to SQL query queryProcessInstancesOutput

-- or -processManagement

queryProcessInstancesAlt Alternative method of specifying SQL query queryProcessInstancesOutput

processManagement

TIBCO ActiveMatrix BPM - BPM Developers Guide

146

| Chapter 6

Working With Processes

listProcessInstances
The listProcessInstances operation returns the process instances that match the input criteria. It allows you to limit the process instances returned according to those that were started from a template in a specified module, those started from a specified process template, or those of a specified template version. Leaving all parameters blank causes the operation to return all process instances. Web Service API example (SOAP):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName></proc:moduleName> <proc:processName>SalesCallbackProcess</proc:processName> <proc:version></proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <processInstances xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <processInstance> <processQName> <moduleName>/SalesCallback/Process Packages/SalesCallback.xpdl</moduleName> <processName>SalesCallbackProcess</processName> <version>1.0.0.201105061158</version> </processQName> <id>pvm:0a124</id> <state>ACTIVE</state> <startTime>2011-08-01T11:47:40.047-07:00</startTime> <completionTime xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <waitingWorkCount>1</waitingWorkCount> <parentProcessID/> </processInstance> </processInstances> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Available Process Instances 147

Service Connector API example (Java):

private void listProcessInstancesExample() { QualifiedProcessName process = QualifiedProcessName.Factory.newInstance(); try { // List all the available instances serviceConnectorInstance.listProcessInstances(process); } catch (IllegalArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (OperationFailedFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

queryProcessInstances
The queryProcessInstances operation returns the process instances that match the provided SQL query. Web Service API example (SOAP):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:queryProcessInstancesInput> <proc:query>SELECT ContactName FROM process WHERE INSTANCE.STATUS = 'ACTIVE'</proc:query> <proc:pageSize>10</proc:pageSize> <proc:attributeMap> <!--Zero or more repetitions:--> <proc:templateAttribute> <proc:name>ContactName</proc:name> <proc:type>string</proc:type> </proc:templateAttribute> </proc:attributeMap> </proc:queryProcessInstancesInput> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

148

| Chapter 6

Working With Processes

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryProcessInstancesOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <processInstances> <processInstance> <customAttributes> <customAttribute> <name>ContactName</name> <value>Ira Olson</value> </customAttribute> </customAttributes> </processInstance> <processInstance> <customAttributes> <customAttribute> <name>ContactName</name> <value>Walter Burfiend</value> </customAttribute> </customAttributes> </processInstance> </processInstances> <pagingID>-1859988354</pagingID> </queryProcessInstancesOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API example (Java):

private void queryProcessInstancesExample() { try { QueryProcessInstancesOutput instances = serviceConnectorInstance.queryProcessInstances( "SELECT * FROM process WHERE INSTANCE.STATUS = 'ACTIVE'", 0, null); System.out.println(instances); } catch (IllegalArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (OperationFailedFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Listing Available Process Instances 149

queryProcessInstancesAlt
The queryProcessInstancesAlt operation returns the process instances that match the specified set of search criteria. This operation is similar to the queryProcessInstances operation, except the SQL query is broken into its constituent parts. Web Service API example (SOAP):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManag erType"> <soapenv:Header/> <soapenv:Body> <proc:queryProcessInstancesAltInput> <proc:select>INSTANCE.NAME,INSTANCE.ID,Issue</proc:select> <proc:where>INSTANCE.STATUS = 'SUSPENDED'</proc:where> <proc:orderBy>INSTANCE.START_DATE</proc:orderBy> <proc:pageSize>10</proc:pageSize> <proc:attributeMap> <!--Zero or more repetitions:--> <proc:templateAttribute> <proc:name>Issue</proc:name> <proc:type>string</proc:type> </proc:templateAttribute> </proc:attributeMap> </proc:queryProcessInstancesAltInput> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

150

| Chapter 6

Working With Processes

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryProcessInstancesOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerTyp e"> <processInstances> <processInstance> <processQName> <processName>InternalHelpDesk</processName> </processQName> <id>pvm:0a12u</id> <customAttributes> <customAttribute> <name>Issue</name> <value>Forgot password</value> </customAttribute> </customAttributes> </processInstance> </processInstances> <pagingID>-94865740</pagingID> </queryProcessInstancesOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API example (Java):

private void queryProcessInstancesAltExample() { try { // Query the active instances serviceConnectorInstance.queryProcessInstancesAlt("INSTANCE. NAME, INSTANCE.ID", "INSTANCE.STATUS='ACTIVE'", "INSTANCE.START_DATE", 0, null); } catch (IllegalArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (OperationFailedFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Lists of Process Templates and Instances 151

Sorting and Filtering Lists of Process Templates and Instances

The following processManagement service operations can include a query parameter, which contains an expression defining the sort and/or filter criteria to be applied to different types of process list: queryProcessTemplates - List process templates that match certain criteria. queryProcessTemplatesAlt - List process templates that match certain criteria. (This is a variation of queryProcessTemplates in which the query string is divided into its constituent parts.) queryProcessTemplateCount - Count the number of process templates that match certain criteria. queryProcessInstances - List process instances that match certain criteria. queryProcessInstancesAlt - List process instances that match certain criteria. (This is a variation of queryProcessInstances in which the query string is divided into its constituent parts.) queryProcessTemplateCount - Count the number of process instances that match certain criteria.

The following sections describe how to define this query parameter.

Query Parameter Syntax

The query parameter must use the following SQL syntax:
SELECT attribute(s) FROM process WHERE [ORDER BY attribute(s) ASC|DESC];

condition

where: attribute is a valid process data attribute. See Query Parameter Attributes on page 152 for a list of valid attributes. condition is an expression that defines the filter to be used. The condition expression must use the following syntax:
attribute operator value

TIBCO ActiveMatrix BPM - BPM Developers Guide

152

| Chapter 6

Working With Processes

where: attribute is a valid process data attribute for the WHERE clause. See Query Parameter Attributes on page 152 for a list of valid attributes. operator is a valid operator for the WHERE clause. See Query Parameter Operators on page 154 for a list of valid attributes. value is a constant literal. The constant literal can be a numeric type, date/time type or text type. A text literal must be enclosed in single quotes e.g. mytext. SQL keywords such as SELECT, FROM and WHERE are case insensitive. The ORDER BY clause can be used to sort the data. Filtering can be done based on multiple conditions by the use of the AND and OR logical operators. Parenthesis can be used to form complex expressions. For example:
SELECT SELECT SELECT

attribute(s) FROM process WHERE condition1 AND condition2; attribute(s) FROM process WHERE condition1 OR condition2;

attribute(s) FROM process WHERE (condition1 OR condition2) AND condition3;

Only a subset of the SQL SELECT statement is supported. For example, the following features are not supported: SELECT in the WHERE clause JOIN GROUP BY SQL FUNCTIONS SELECT INTO

Query Parameter Attributes

All attributes can be used for both filtering and sorting. Note that: If the attribute specified is *, all attributes for the process template or process instance will be returned. All predefined attribute names (prefixed by DEFINITION, MODULE or INSTANCE) are case insensitive. User-defined attribute names are case sensitive.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Lists of Process Templates and Instances 153

The following attributes can be used to query process templates. Attribute Name DEFINITION.NAME DEFINITION.DESCRIPTION DEFINITION.VERSION DEFINITION.PRIORITY DEFINITION.CREATION_DATE MODULE.NAME Description Process name Process description Process version Process priority Process creation date Module name Type Text Text Text Numeric (short) Date/Time Text

The following attributes can be used to query process instances. Attribute Name MODULE.NAME INSTANCE.NAME INSTANCE.ID INSTANCE.VERSION INSTANCE.PRIORITY INSTANCE.STATUS INSTANCE.START_DATE INSTANCE.COMPLETION_DATE INSTANCE.WAITING_WORK_COUNT Description Module name Process instance name Process instance identifier Process instance version Process instance priority Process instance state/status Process instance start date Process instance completion date Process instance waiting work count Type Text Text Text Text Numeric (short) Text Date/Time Date/Time Numeric (integer)

TIBCO ActiveMatrix BPM - BPM Developers Guide

154

| Chapter 6

Working With Processes

Attribute Name User-defined attribute name

Description Process instance custom attribute

Type Text, Numeric, Date-Time, Boolean

Using User-Defined Attributes The attributeMap element (used by the queryProcessInstances and queryProcessInstancesAlt operations) should be used to specify the type of the user attributes for both the SELECT and ORDER BY clause. For a queryProcessInstanceCount operation (where the attributeMap element cannot be provided) you can specify a type casting as an in-place alternative. For example:
SELECT MODULE.NAME, INSTANCE.ID, LONG(BALANCE), DOUBLE(PAYMENT)

Query Parameter Operators

The following table lists the operators that can be used in the WHERE clause. Note that: The attribute and value operands must both be of the same data type.

Unless otherwise noted, each operator can be applied to all data types (Text, Numeric, Boolean and DateTime) Operator = Description Equals - compares two values for equality. Wildcards can be used when comparing attributes of type string. See Using Wildcards on page 155. <> > Not equal to Greater than Examples
INSTANCE.NAME = LoanApproval INSTANCE.PRIORITY = 3 IsLoanApproved = TRUE INSTANCE.COMPLETION_DATE = '2008-06-20T10:30:20' INSTANCE.PRIORITY <> 3 INSTANCE. PRIORITY > 5000 Balance > 300.53 TS

<

Less than

INSTANCE. PRIORITY < 5000

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Lists of Process Templates and Instances 155

Operator >= <= LIKE

Description Greater than or equal to Less than or equal to Pattern match comparison matches a string value against a pattern string containing wild-card characters. See Using Wildcards on page 155. Applies to Text data types only.

Examples
INSTANCE. PRIORITY >= 5000 INSTANCE. PRIORITY <= 5000

To match any processes with a module name that begins with module:
MODULE.NAME LIKE module%

To match any processes with a module name that begins with module number and ends with a single character):
MODULE.NAME LIKE module number _

BETWEEN

Range comparison - tests whether a value is between two other values

INSTANCE.PRIORITY BETWEEN 4000 AND 5000 INSTANCE.START_DATE between TS '2008-06-20T10:30:20' AND TS '2008-06-20T10:52:20';

IN

Implements comparison to a list of values, that is, it tests whether a value matches any value in a list of values. Applies to Text and Numeric data types only.

MODULE.NAME IN ('moduleBalance, 'modulePayment');

IS [NOT] NULL NOT

Tests whether the attribute has a value Inverts the result of a condition clause

MODULE.NAME IS NOT NULL Payment IS NULL MODULE.NAME NOT IN ('moduleBalance, 'modulePayment'); INSTANCE.PRIORITY NOT BETWEEN 4000 AND 5000

Using Wildcards The following wildcards can be used with the LIKE operator (and with the = operator when comparing attributes of type string): ? or _ matches any single character. * or % matches zero or more characters.
TIBCO ActiveMatrix BPM - BPM Developers Guide

156

| Chapter 6

Working With Processes

Wildcards can be escaped using the \ character. For example, \%. Escape characters can be escaped using \\ which evaluates to matching \. If escaping a non-wildcard character, the escape character will be ignored. For example, \abc" evaluates to matching abc. Note that the * wildcard can be used in selection clauses only for non-paginated queries (that is when the PageSize parameter is specified as 0 (zero) when calling the following operations: queryProcessInstances, queryProcessInstancesAlt, queryProcessTemplates, and queryProcessTemplatesAlt).

Date/Time Data Type Specification

The following date/time formats can be used: General Format YYYY YYYY-MM YYYY-MM-DD YYYY-MM-DDThh:mm+hh: mm YYYY-MM-DDThh:mm-hh: mm YYYY-MM-DDThh:mmZ YYYY-MM-DDThh:mm: ss YYYY-MM-DDThh:mm: ss+hh:mm YYYY-MM-DDThh:mm: ss-hh:mm YYYY-MM-DDThh:mm: ssZ Usage DATE YYYY DATE YYYY-MM DATE YYYY-MM-DD TS YYYY-MM-DDThh: mm+hh:mm TS YYYY-MM-DDThh: mm-hh:mm TS YYYY-MM-DDThh: mmZ TS YYYY-MM-DDThh: mm:ss TS YYYY-MM-DDThh: mm:ss+hh:mm TS YYYY-MM-DDThh: mm:ss-hh:mm TS YYYY-MM-DDThh: mm:ssZ Example(s)
DATE '1997' DATE '1997-07' DATE '1997-07-16' TS 1997-07-16T19:20+01:00

TS 1997-07-16T19:20-01:00

TS 1997-07-16T19:20Z

TS 1997-07-16T19:20:30

TS 1997-07-16T19:20:30+01:00

TS 1997-07-16T19:20:30-01:00

TS 1997-07-16T19:20:30Z

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Lists of Process Templates and Instances 157

General Format YYYY-MM-DDThh:mm: ss.s YYYY-MM-DDThh:mm: ss.s+hh:mm YYYY-MM-DDThh:mm: ss.s-hh:mm YYYY-MM-DDThh:mm: ss.sZ where:

Usage TS YYYY-MM-DDThh: mm:ss.s TS YYYY-MM-DDThh: mm:ss.s+hh:mm TS YYYY-MM-DDThh: mm:ss.s-hh:mm TS YYYY-MM-DDThh: mm:ss.sZ

Example(s)
TS 1997-07-16T19:20:30.45

TS 1997-07-16T19:20:30.45+01:00

TS 1997-07-16T19:20:30.45-01:00

TS 1997-07-16T19:20:30.45Z

YYYY = four-digit year MM = two-digit month (01=January, etc.) DD = two-digit day of month (01 through 31) hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) s = one or more digits representing a decimal fraction of a second

If no time zone information is given with a time representation, the time is assumed to be in local time.

Query Parameter Examples

Using boolean types:
SELECT * FROM process WHERE (isBalanceFull = TRUE ); SELECT * FROM process WHERE (isBalanceFull = FALSE );

Using numeric types:

SELECT * FROM process WHERE (Payment > 3.569 ); SELECT * FROM process WHERE (Payment < 50 );

Using complex conditions:

SELECT * FROM process WHERE (DEFINITION.NAME = Process1 OR DEFINITION.NAME = Process2 ) ORDER BY name DESC; SELECT * FROM process WHERE (DEFINITION.NAME = Process1 OR DEFINITION. NAME = Process2) ORDER BY DEFINITION. NAME ASC;

TIBCO ActiveMatrix BPM - BPM Developers Guide

158

| Chapter 6

Working With Processes

SELECT * FROM process WHERE (INSTANCE.ID > 20 AND MODULE.NAME = ModuleA AND order_amount > 10000) ORDER BY INSTANCE.ID DESC; SELECT * FROM process WHERE (INSTANCE.ID > 20 AND INSTANCE.ID < 100 ORDER BY INSTANCE.ID DESC; SELECT * FROM process WHERE (MODULE.NAME like 'module%'); SELECT * FROM process WHERE INSTANCE.START_DATE BETWEEN TS '2008-06-20T10:30:20Z' AND TS '2008-06-20T10:52:20Z'; SELECT MODULE.NAME, INSTANCE.VERSION, INSTANCE.NAME, INSTANCE.DESCRIPTION FROM process WHERE (MODULE.NAME = 'module_1' OR MODULE.NAME = 'module_2') ORDER BY MODULE.NAME DESC; SELECT * FROM process WHERE (isBalanceZero = TRUE) ORDER BY INSTANCE.ID DESC;

TIBCO ActiveMatrix BPM - BPM Developers Guide

Process Instance State Transitions 159

Process Instance State Transitions

The following diagram and table show what transitions a process instance may make between states, and what operations from the Process Services API are used to bring about each of the possible changes.

Create
createProcessInstance

Not-started Starting Resuming

suspendProcessInstance suspendProcessInstances resumeProcessInstance resumeProcessInstances

Active
cancelProcessInstance cancelProcessInstances

X
Cancelling Failing Completing

Suspending

cancelProcessInstance cancelProcessInstances

Suspended

Cancelled
purgelProcessInstances

Failed

Completed
purgelProcessInstances

Legend Public API operation Private API operation (or other internal transition)

Purged

suspendOnError decision point Public state Intermediate state Start/End state (Private)

TIBCO ActiveMatrix BPM - BPM Developers Guide

160

| Chapter 6

Working With Processes

Start State Not Started Active

End State Active Suspended

PM API operation createProcessInstance suspendProcessInstance suspendProcessInstances

Notes

A failing process instance may change to Suspended instead of Failed in certain situations - see "Configuring suspendOnError Behavior for Process Instances" in BPM Administration for more information. The process instance is cancelled and is purged from the database. This change in state is the result of unsuccessful running of the process. There is no API call that produces this transition. The process instance is failed and is purged from the database.

Active Active

Cancelled Failed

cancelProcessInstance cancelProcessInstances None

Active

Completed

None

This change in state is the result of running the process successfully. There is no API call that produces this transition. The process instance is completed and is purged from the database.

Suspended Suspended

Active Cancelled

resumeProcessInstance resumeProcessInstances cancelProcessInstance cancelProcessInstances The process instance is cancelled and is purged from the database.

In some cases there are similarly-named singular and plural operations, such as suspendProcessInstance and suspendProcessInstances. In this case: suspendProcessInstance suspends the specified process instance, suspendProcessInstances suspends all process instances for the specified process template.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Migrating a Process Instance to a Different Version 161

Migrating a Process Instance to a Different Version

Process migration is the ability to migrate a long running process instance to a different version of the process template from which it was generated. For a general overview of process migration, see "Process Migration" in TIBCO ActiveMatrix BPM Concepts Migration Points A migration point is a task in the process template at which a process instance can be migrated to a different version. Not all tasks are valid migration points - for example: tasks that are on a parallel path, or tasks that may have parallel executions due to multiple tokens flowing on a single path tasks in an embedded sub-process start events or boundary events un-named tasks. (The task name is used to identify a migration point. A well-formed process should therefore not use duplicate task names.)

Valid migration points are automatically identified (and marked internally in the BPEL file) by TIBCO Business Studio at design time. There are restrictions on the types of change that can be made between the two versions (source and destination) of a migrated process template, as follows: In a normal flow (not a cycle), a task that precedes the migration point in the source version should not be rearranged so that it follows the migration point in the destination version. A task that is concurrent with the migration point in the source version should not be rearranged so that it follows the migration point in the destination version. If compensation is triggered in the destination version for a task that completed in the source version, the compensation defined in the source version will be performed.

TIBCO ActiveMatrix BPM - BPM Developers Guide

162

| Chapter 6

Working With Processes

Migration Rules A migration rule defines when, how and to what version a process instance will migrate. A migration rule identifies: a qualified task name (module name, module version, process template name and task name) from which a process instance will migrate. the module/process template version to which the process instance will migrate.

How Process Instances Are Migrated At runtime, when a process instance task that is defined as a migration point executes, Process Manager checks if a migration rule is set (using the qualified task name). If a migration rule is set, Process Manager: 1. migrates the process instance to the new version of the process template defined in the migration rule. 2. issues a BX_INSTANCE_PROCESS_MIGRATED audit event to indicate that the process instance has migrated. The managedObjectVersion for this event is the process template version after migration. The managedObjectId for this event is the ID of the process instance. This remains the same after migration as it was before, and so it can be used to connect audit events before and after migration. 3. continues execution of the task using the migrated to version of the process instance. Process Migration Operations The following Process Services service operations allow you to control process migration: listMigrationRules - List the process instance migration rules that are set for one or more process templates. isSetMigrationRule - Test whether any migration rules are set for a particular qualified task name. getMigrationPoints - List the permissible process instance migration points for one or more process templates. setMigrationRules - Set one or more process instance migration rules.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Migrating a Process Instance to a Different Version 163

unsetMigrationRules - Unset one or more previously set process instance migration rules. clearMigrationRules - Clear all process instance migration rules for one or more process templates.

Authorization of Process Migration Operations A resource can only perform process migration if they have the necessary privileges to execute the handleProcessMigration system action. (The system-wide default value for this system action is Denied.) Process Manager will validate the calling resources privileges (by itself using Directory Services) whenever a process migration service operation is called. If the calling resource does not have the necessary authorization to execute the handleProcessMigration system action, the call will fail with an appropriate error. You can use Directory Services API SecurityService operations (for example, IsActionAuthorized) to test whether a resource has the necessary authorization before calling a process migration service operation. See System Actions on page 768 for more information about how to specify the handleProcessMigration system action when using the SecurityService operations.

TIBCO ActiveMatrix BPM - BPM Developers Guide

164

| Chapter 6

Working With Processes

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 165
Chapter 7

Working with Work Lists

This chapter describes using the Business Resource Management Services API to work with work lists.

Topics
Introduction to Work Lists, page 166 Retrieving a Work List, page 167 Sorting and Filtering Work Lists, page 169 Creating and Managing Supervised Work List Views, page 180

TIBCO ActiveMatrix BPM - BPM Developers Guide

166

| Chapter 7

Working with Work Lists

Introduction to Work Lists

The Business Resource Management Services API provides operations that allow you to manage work lists in your BPM runtime. Work lists represent lists of work items assigned to an organizational entity. Users see a list of those work items that they can view and work on. Web service operations are provided in the WorkListService to: Retrieve the items from a work list. Sort the items in a work list into a desired order, or to filter them according to various procedures.

The remainder of this chapter provides information about using these Business Resource Management Services operations to work with work lists. For information about working with the work items in a work list, see Working with Work Items on page 189.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Retrieving a Work List | 167

Retrieving a Work List

The WorkListService provides two operations to retrieve work lists for an organizational entity such as a position, a group, or a resource: getWorkListItemsThis operation gets the work item list, that is all offered and allocated work items, for the entity. getAllocatedWorkListItemsThis operation gets the allocated work list for the entity.

getWorkListItems This operation returns items in the work list for a specified organizational entity. The request for this operation must specify the GUID of an organizational entity. You can get the GUID by various means, for example from a previous executeQuery operation, or for a resource (user) from a previous lookupUser operation. Optionally the request can also specify how many items from the work list to return, and whether to include the total number of work items in the work list. It can also specify sort and filter criteria to be applied to the work items returned. The request element (getWorkListItems) contains the following information: entityIDthe GUID of the organizational entity whose work list you want to retrieve. startPositionthe position in the work list from which to start the page of results. The list is zero-based. To start at the first item, specify 0. numberOfItemsthe number of items from the work list to include.

Optionally, it can contain: getTotalCountwhether to include a count of the total number of work items in the list. This defaults to true. The count is returned in the totalItems value in the response. You should set getTotalCount to false unless you specifically need the total figure, because setting it to true is expensive in terms of database access time. Note that if you pass false in this attribute, and there is at least one item in the list, the totalItems value returned in the response is -1. However, if you pass false and there are no work items in the list, the totalItems value in the response is 0 (zero). orderFilterCriteriasort or filter criteria, or both, to determine how the work items are to be filtered and presented. See Sorting and Filtering Work Lists on page 169 for details of the syntax and content of these criteria.
TIBCO ActiveMatrix BPM - BPM Developers Guide

168

| Chapter 7

Working with Work Lists

The response for this operation returns full details of all the work list items that match the criteria specified in the request. For API reference information, see getWorkListItems on page 730. getAllocatedWorkListItems This operation is similar to getWorkListItems, except that: It returns only work items that are currently allocated to a resource, but were offered to an original offer set that included the specified organizational entity. It may not be used to get work list items for a resource (user).

The request element (getAllocatedWorkListItems) contains the following information: entityIDthe GUID of the organizational entity in the original offer set. This must not be a Resource. startPositionthe position in the work list from which to start the page of results. The list is zero-based. To start at the first item, specify 0. numberOfItemsthe number of items from the work list to include.

Optionally, it can contain: getTotalCountwhether to include a count of the total number of work items in the list. This defaults to true. The count is returned in the totalItems value in the response. You should set getTotalCount to false unless you specifically need the total figure, because setting it to true is expensive in terms of database access time. Note that if you pass false in this attribute, and there is at least one item in the list, the totalItems value returned in the response is -1. However, if you pass false and there are no work items in the list, the totalItems value in the response is 0 (zero). orderFilterCriteriasort or filter criteria, or both, to determine how the work items are to be filtered and presented. See Sorting and Filtering Work Lists on page 169 for details of the syntax and content of these criteria.

The response for this operation returns the same element as getWorkListItems. It contains full details of all the allocated work list items that match the criteria specified in the request. See Example 2 on page 184 for an example of the use of this operation. For API reference information, see getAllocatedWorkListItems on page 734.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Work Lists | 169

Sorting and Filtering Work Lists

The following WorkListService operations are concerned with defining the sort and/or filter criteria to be applied to a work item list: getWorkItemOrderFilter (Request message)Get the fields defined by BRM that can be used to define sort/filter criteria for a work item list. setResourceOrderFilterCriteria (Request message)Set sort/filter criteria for work lists for a resource. getResourceOrderFilterCriteria (Request message)Get (previously defined) sort/filter criteria for work lists for a resource.

These expressions can include an expression defining the sort and/or filter criteria to be applied to the work list. The following operations, used to retrieve work lists, can also include the same expressions: getWorkListItems (Request message)Get a work list for an organization model entity. getAllocatedWorkListItems (Request message)Get an allocated work list for an organization model entity.

The syntax and criteria for sort/filter expressions is the same for each of these operations. The default sort criteria, used to display a work list if no other sort is specified, are defined by the defaultSort property in the brm.properties file. See "Configuring TIBCO ActiveMatrix BPM Resource Management" in TIBCO ActiveMatrix BPM BPM Administration for this property. getWorkItemOrderFilter This operation returns a list of the work item fields that are defined by BRM as suitable to be used in expressions for sorting and filtering work items within work lists. See Sort/Filter Criteria for suitable fields. The request element (getWorktemOrderFilter) contains only: limitColumnsthe number of suitable fields about which information should be returned. Fields are returned in order of their ID, so if you enter a limitColumns value of 5, the response will include details of fields with id from 1 to 5. The table in Sort/Filter Criteria gives the IDs of the fields. Set limitColumns to 0 to get information about all fields.

TIBCO ActiveMatrix BPM - BPM Developers Guide

170

| Chapter 7

Working with Work Lists

The capability value in the response returned (getWorkItemOrderFilterResponse) includes whether each of the listed fields is suitable for sorting, for filtering, or for both. In the following example extract from a response, the id field (listed first because its own ID is 1) is suitable for both sort and filter expressions. The name field, however, can only be used in filter expressions.
<columnData capability="BOTH_ORDER_FILTER" description="The integer value that denotes the ID of the work item." id="1" name="id" type="COL_NUMERIC" xmlns=""/> <columnData capability="FILTER" description="The name of the work item." id="2" name="name" type="COL_STRING" xmlns=""/>

See Sort/Filter Criteria on page 172 for information on which types of field are defined as suitable for sort and filter expressions. For API reference information, see getWorkItemOrderFilter on page 741. setResourceOrderFilterCriteria This operation specifies a resource and sets the sort/filter criteria to be applied for that resources work lists. You would use this operation to enable a user to set their own sort and filter criteria; see Using Work Item Attribute Fields on page 178 for an example. The request element (setResourceOrderFilterCriteria) contains: resourceIDthe GUID of the resource for whom work list sort/filter criteria are to be set. You can get the GUID from a previous lookupUser operation. orderFilterCriteriathe criteria to be set.

For API reference information, see setResourceOrderFilterCriteria on page 745. getResourceOrderFilterCriteria This operation gets the currently defined sort/filter criteria for the work list for the specified resource. These would have been set by a previous setResourceOrderFilterCriteria operation. The request element (getResourceOrderFilterCriteria) contains: resourceIDthe GUID of the resource whose work list sort/filter criteria are to be retrieved. You can get the GUID from a previous lookupUser operation.

The response lists the sort and/or filter criteria that are set. For API reference information, see getResourceOrderFilterCriteria on page 743.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Work Lists | 171

Sort/Filter Expression Syntax

The syntax of sort/filter expressions is similar to that used in Java expressions. Expressions are made up of a set of terms that can be parenthetically separated using the ( and ) characters, and can be joined using the AND and OR operators. Delimiters are used as follows:

Text string fields are delimited using the ' character. Expressions denoting date/time ranges can use different delimiters with different meanings, as described in Using Date/Time Ranges on page 177. Other fields require no delimiters.
(priority = 1) OR ((priority < 12) AND (priority > 4)) OR (description='fred') (startDate>=2010-05-23T14:25:10) OR description='a_b*a' AND (priority<>13) OR (description='1?3*') (priority=35) OR description='a_b*a' AND (priority<>13) OR (description ='1?3*') visible=TRUE OR ((startDate>2010-05-23T14:25:10) AND (distributionStrategy=OFFERED)) [2010-05-23,2006-05-23T14:25:10.123Z] (startDate <= 2006-05-23T14:25:10.123Z) OR endDate<2010-05-23 priority=35 AND [2010-05-23T14:25:10,2006-05-23T14:25:10] attribute1=5346 OR attribute4=Urgent

Some examples of filter expressions are:

Wildcard Characters The following wildcard characters can be used: ? can be used to match any single character. * can be used to match any string of zero or more characters.

If you wish to search for a string that actually contains these characters you must escape them using \. For example, the string "fr\?d", with the ? character escaped, results in a query using "fr?d". Sort Expressions Sort direction can be defined using the ASC (ascending sort) or DESC (descending sort) keywords. Multiple sort criteria can be used in a single expression. Individual criteria should be comma-separated. For example:
TIBCO ActiveMatrix BPM - BPM Developers Guide

172

| Chapter 7

Working with Work Lists

id ASC, priority ASC, startDate ASC, endDate DESC

Sort/Filter Criteria
The following table describes the criteria that can be used to filter and/or sort work items in a users work list. Field ID in API 1

Name id

Type Numeric

Operators = <> > < >= <= = <> > < >= <=

Usage Sort and filter expressions.

Description ID of the work item. Can be any number specified with or without a decimal point.

name

String

Filter expressions only. Cannot be used in sort expressions. Filter expressions only. Cannot be used in sort expressions. Sort and filter expressions.

The name of the work item. Can be any text. Wildcards are specified using ? and *, single and multiple character matching. Description of the work item. Can be any text. Wildcards are specified using ? and *, single and multiple character matching. Priority of the work item. Can be any number, with or without a decimal point.

description

String

= <> > < >= <=

priority

Numeric

= <> > < >= <=

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Work Lists | 173

Field ID in API 5

Name startDate

Type Date/ Time

Operators = <> > < >= <= = <> > < >= <= = <>

Usage Sort and filter expressions.

Description Earliest date at which the work item can be started. See Using Date/Time Fields for details of the format. Date by which the work item should be completed. See Using Date/Time Fields for details of the format.

endDate

Date/ Time

Sort and filter expressions.

distributionStrategy

Enum (Dist. strategy)

Sort and filter expressions.

Whether the item was offered or allocated when it was scheduled. Must be either ALLOCATED or OFFERED. Whether or not the item is currently visible. Must be either TRUE or FALSE.

visible

Boolean

= <>

Filter expressions only. Cannot be used in sort expressions.

state

Enum (State)

= <>

Sort and filter expressions.

Current state of the work item. Must be one of: ALLOCATED OFFERED CREATED OPENED PENDED PENDHIDDEN CANCELLED SUSPENDED

TIBCO ActiveMatrix BPM - BPM Developers Guide

174

| Chapter 7
Field ID in API 10

Working with Work Lists

Name appInstance

Type String

Operators = <> > < >= <=

Usage Sort and filter expressions.

Description The id of the application instance that created the work item. Can be any text. Wildcards are specified using ? and *, single and multiple character matching.

11

appName

String

= <> > < >= <=

Sort and filter expressions.

The name of the application instance that created the work item. Can be any text. Wildcards are specified using ? and *, single and multiple character matching.

12

appInstance Description

String

= <> > < >= <=

Sort and filter expressions.

The description of the application instance that created the work item. Can be any text. Wildcards are specified using ? and *, single and multiple character matching.

13

attribute1

Numeric (Integer)

= <> > < >= <=

Sort and filter expressions

The integer value of the first custom work item attribute defined. See Using Work Item Attribute Fields on page 178. Must be an integer.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Work Lists | 175

Field ID in API 14-16

Name attribute2 attribute4

Type String

Operators = <> > < >= <=

Usage Sort and filter expressions.

Description The value of the second to fourth custom work item attributes defined. See Using Work Item Attribute Fields on page 178. Can be any text. Wildcards are specified using ? and *, single and multiple character matching.

17

attribute5

Numeric

= <> > < >= <=

Sort and filter expressions.

The decimal value of the fifth custom work item attribute defined. See Using Work Item Attribute Fields on page 178. Must be a Decimal. In filter expressions, you can specify values in exponential notation. For example: =1.234E+11 =1.234e-1 =-.234e-2

18-19

attribute6 attribute7

Date/ Time

= <> > < >= <=

Sort and filter expressions.

The value of the sixth to seventh custom work item attributes defined. See Using Work Item Attribute Fields on page 178. See Using Date/Time Fields for details of the format.

TIBCO ActiveMatrix BPM - BPM Developers Guide

176

| Chapter 7
Field ID in API 20-27

Working with Work Lists

Name attribute8 attribute14

Type String

Operators = <> > < >= <=

Usage Sort and filter expressions.

Description The value of the eighth to fourteenth custom work item attributes defined. See Using Work Item Attribute Fields on page 178. Can be any text up to a maximum of 20 characters. Longer strings will be truncated to 20. Wildcards are specified using ? and *, single and multiple character matching.

Using Date/Time Fields Date/Time fields (startDate, endDate, and attribute6 - attribute7) can appear any number of times within a filter expression. No wildcards are supported. If no hours, minutes, seconds or milliseconds are specified then the field adds the time and milliseconds as required by the operations being performed. The following formats for date/times are allowed: yyyy yyyy-MM yyyy-MM-dd yyyy-MM-ddTHH yyyy-MM-ddTHH:mm yyyy-MM-ddTHH:mm:ss yyyy-MM-ddTHH:mm:ss.SSS yyyyTD yyyy-MMTD yyyy-MM-ddTD

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Work Lists | 177

yyyy-MM-ddTHHD yyyy-MM-ddTHH:mmD yyyy-MM-ddTHH:mm:ssD yyyy-MM-ddTHH:mm:ss.SSSD

where D can be either of:

Z <+|-><HHmm|HH:mm|HH>
2010-03-03T23:45+01 2010-03-03T23:45+01:30 2010-03TZ 2010T-0100

For example:

The operators given in the table are used as follows: <startDate | endDate> <operator> <date/time> For example: startDate >= 2010-05-23T14:25:10 endDate <= 2010-05-23T14:25:10Z startDate > 2010-05-23T14:25:10.123 endDate < 2010-05-23T14:25:10.123Z

Using Date/Time Ranges You can specify a query for a date/time range, and use it in filter expressions (but not in sort expressions) to query a range of endDates, a range of startDates, or a startDate to endDate period. Different separator characters have the following effects: Separator [ ] { } Specifies that... The start of the range is exclusive. The end of the range is exclusive. The start of the range is inclusive. The end of the range is inclusive.

TIBCO ActiveMatrix BPM - BPM Developers Guide

178

| Chapter 7

Working with Work Lists

Separator , ^ !

Specifies that... startDate is specified first, endDate next. The whole range is endDate values. The whole range is startDate values.

All the date formats supported by startDate and endDate (see Sort/Filter Criteria) are supported. The following examples all use the date format yyyy-MM-dd: Filter Expression
[2010-05-23,2010-07-23]

Description
(start_date>'2010-05-23T23:59:59.997' AND end_date<'2010-07-23T00:00:00.000') (start_date>='2010-05-23T00:00:00.000' AND end_date<='2010-07-23T23:59:59.997') (start_date>'2010-05-23T23:59:59.997' AND end_date<='2010-07-23T23:59:59.997') (start_date>='2010-05-23T00:00:00.000' AND end_date<'2010-07-23T00:00:00.000') (end_date>'2010-05-23T23:59:59.997' AND end_date<'2010-07-23T00:00:00.000') (start_date>='2010-05-23T00:00:00.000' AND start_date<='2010-07-23T23:59:59.997')

{2010-05-23,2010-07-23}

[2010-05-23,2010-07-23}

{2010-05-23,2010-07-23]

[2010-05-23^2010-07-23]

{2010-05-23!2010-07-23}

Using Work Item Attribute Fields You can use the values of the custom work item attribute fields as criteria in both sort and filter expressions. These fields correspond to the customizable attributes workItemAttributes.attribute1 to workItemAttributes.attributen that you can set using the work item scripting methods described in the "Work Item Scripting" section of the Business Data Services guide. See the "Using Scripts" chapter of the TIBCO Business Studio BPM Implementation guide for information on defining scripts in your processes at design time. You can use these attributes to hold data associated with the work item. For example, you could use them to track data about the customer with whom the work item is associated. Assume that a script in your business process sets the following values, mapping fields from the business process to work item attributes:

TIBCO ActiveMatrix BPM - BPM Developers Guide

Sorting and Filtering Work Lists | 179

WorkManagerFactory.getWorkItem().workItemAttributes.attribute1=customer_number WorkManagerFactory.getWorkItem().workItemAttributes.attribute2=customer_name WorkManagerFactory.getWorkItem().workItemAttributes.attribute3=customer_contact

You could then use a setResourceOrderFilterCriteria operation to sort or filter by any of these values. For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:setResourceOrderFilterCriteria resourceID="8D10C-42DEBD01-C23D2B4"> <orderFilterCriteria> <order>attribute3 ASC</order> <filter>attribute1=0435</filter> </orderFilterCriteria> </api:setResourceOrderFilterCriteria> </soapenv:Body> </soapenv:Envelope>

This example filters the specified resources work list to show only work items from the customer whose reference number is 0435. Those items that are displayed are then shown in order of the customer contact person specified on the work item.

TIBCO ActiveMatrix BPM - BPM Developers Guide

180

| Chapter 7

Working with Work Lists

Creating and Managing Supervised Work List Views

A usertypically a manager or supervisormay have the ability to view work lists other than their own. This depends on: the organization model entities to which they belong (groups, positions, organization units, and organizations), the privileges that they hold as a result of membership of those entities, whether those privileges grant access to the work lists of other organization model entities, via the viewWorkList system action, whether that system action is scoped to apply to the specific group, organization unit, or position whose work list is to be supervised.

See "System Actions" in TIBCO ActiveMatrix BPM Concepts for an overview of system actions. See Scope of System Actions on page 773 for information about scoped system actions. The following examples illustrate how you can use API operations to determine what supervised work lists a user has access to, then retrieve the contents of those work lists for display to the user.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Creating and Managing Supervised Work List Views | 181

Example 1 From the client applications user interface, a user requests a list of available supervised work lists: Figure 9 Supervised Work Lists
Browser Client application Work Manager Services

User requests list of available supervised work lists 1 listActionAuthorisedEntities [guids] SecurityService

browseModelService [guid details]

BrowseModelService

Display list of available supervised work lists User selects a supervised work list getWorkListItems [work items] and/or getAllocatedWorkListItems Display contents of the selected supervised work list [work items] WorkListService WorkListService

1. Find out what work lists the user has access to, by calling listActionAuthorisedEntities for the viewWorkList system action. The

TIBCO ActiveMatrix BPM - BPM Developers Guide

182

| Chapter 7

Working with Work Lists

response contains a list of GUIDs. Each GUID identifies an organization model entity whose work list the calling user is authorized to view.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="http://security.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <sec:listActionAuthorisedEntities component="BRM" name="viewWorkList"/> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listActionAuthorisedEntitiesResponse xmlns="http://security.api.de.n2.tibco.com"> <guid xmlns="">_q2uCYDMeEeCrFvFvgjfN_w</guid> <guid xmlns="">_jWwQ4DMeEeCrFvFvgjfN_w</guid> <guid xmlns="">_i640QDMeEeCrFvFvgjfN_w</guid> <guid xmlns="">_pp_JgDMeEeCrFvFvgjfN_w</guid> </listActionAuthorisedEntitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

2. For each GUID returned in the listActionAuthorisedEntities response, call browseModelNode to obtain the organization model entitys entity-type, along with other detailsits name, whether it has any child entities and so on. You can use this information to present the available supervised work lists to the user in your desired manner. See also Navigating the Organization Model on page 109.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:browseModelNode guid="_i640QDMeEeCrFvFvgjfN_w"> </brow:browseModelNode> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Creating and Managing Supervised Work List Views | 183

SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <browseModelNodeResponse entity-type="ORGANIZATIONAL_UNIT" guid="_i640QDMeEeCrFvFvgjfN_w" has-children="true" model-version="1" name="GroupB" xmlns="http://browse.api.de.n2.tibco.com"> <selection-mode method="ANY" plugin="" xmlns=""/> <child entity-type="POSITION" guid="_q2uCYDMeEeCrFvFvgjfN_w" has-children="true" ideal-number="1" model-version="1" name="BackOfficerWorker2" resource-count="1" xmlns=""> <selection-mode method="ANY" plugin=""/> </child> </browseModelNodeResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

3. When the user selects a supervised work list to view, call either or both of: getWorkListItems, to retrieve the list of work items currently offered to this user. getAllocatedWorkListItems, to retrieve the list of work items currently allocated to this user. In either case, specify the organization model entitys entity-type and GUID as parameters to this call.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getWorkListItems startPosition="0" numberOfItems="5" > <entityID model-version="-1" entity-type="ORGANIZATIONAL_UNIT" guid="_i640QDMeEeCrFvFvgjfN_w" </entityID> </api:getWorkListItems> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

184

| Chapter 7

Working with Work Lists

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getWorkListItemsResponse xmlns="http://api.brm.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <endPosition xmlns="">3</endPosition> <totalItems xmlns="">4</totalItems> <workItems xmlns=""> <id id="5" version="0"/> <header distributionStrategy="OFFER" priority="50"> <name>GroupB</name> <description>GroupB</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i17</activityID> <activityName>GroupB</activityName> <appInstance>pvm:0a123</appInstance> <appName>AMXSupervisor</appName> <appID>_fQ0ZAHClEeCF3qXLa8gNUw</appID> <appInstanceDescription>dfghfgfgfgf</appInstanceDescription> </itemContext> </header> <attributes attribute1="789" attribute2="fhfhfhfh" attribute3="123.45" attribute4="GroupB"/> <state>OFFERED</state> <visible>true</visible> </workItems> <workItems xmlns=""> <id id="8" version="0"/> . . . </workItems> </getWorkListItemsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Example 2 You may want to provide views based on different filters of the data. For example, to allow a supervisor to select a particular process instance and see a particular users outstanding, allocated work for that process instance: 1. Get the process instance ID. You can get this information from any of the listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt operations.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Creating and Managing Supervised Work List Views | 185

2. Use listActionAuthorisedEntities and browseModelNode in the same way described in Example 1. 3. Call getAllocatedWorkListItems, specifying the organizational entity whose list you want to view, and with a filter set for the appropriate process instance.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getAllocatedWorkListItems numberOfItems="10" startPosition="0"> <entityID entity-type="ORGANIZATIONAL_UNIT" guid="_i640QDMeFvFvgjfN_w"/> <orderFilterCriteria> <filter>appInstance='pvm:0a125'</filter> </orderFilterCriteria> </api:getAllocatedWorkListItems> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getWorkListItemsResponse xmlns="http://api.brm.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <endPosition xmlns="">0</endPosition> <totalItems xmlns="">1</totalItems> <workItems xmlns=""> <id id="11" version="2"/> <header distributionStrategy="OFFER" priority="50"> <name>GroupB</name> <description>GroupB</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i21</activityID> <activityName>GroupB</activityName> <appInstance>pvm:0a125</appInstance> <appName>AMXSupervisor</appName> <appID>_fQ0ZAHClEeCF3qXLa8gNUw</appID> <appInstanceDescription>turbot</appInstanceDescription> </itemContext> </header> <attributes attribute1="789" attribute2="major" attribute3="123.45" attribute4="GroupB"/> <state>PENDED</state> <visible>true</visible> </workItems> </getWorkListItemsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

186

| Chapter 7

Working with Work Lists

Creating a Supervised Work List Service Connector API Example (Java) The following example illustrates creating a supervised work list and viewing work on a particular process instance, using the method calls available in the Java Service Connector API.
private void creatingAndManagingSupervisedWorkListViewsExample() { try { // Step 1: Find the GUIDS which we can view the work list for ListActionAuthorisedEntitiesResponse authorisedEntities = serviceConnectorInstance .listActionAuthorisedEntities("BRM", "viewWorkList"); // Step 2: Get the details of the GUIDS - in this example just the first one if (authorisedEntities.getGuidArray() != null && authorisedEntities.getGuidArray().length > 0) { XmlOrgModelNode node = serviceConnectorInstance.browseModelNode(-1, null, authorisedEntities.getGuidArray(0), null); // Step 3: Build up the entity we want to get the work list for XmlModelEntityId entity = XmlModelEntityId.Factory.newInstance(); entity.setGuid(node.getGuid()); entity.setEntityType(node.getEntityType()); entity.setModelVersion(node.getModelVersion()); // Get the work list for the specified GUID serviceConnectorInstance.getWorkListItems(OrderFilterCriteria.Factory.newInstance() , entity, 0, 100); // Example 2 for a specific instance ID OrderFilterCriteria oc = OrderFilterCriteria.Factory.newInstance(); oc.setFilter("appInstance='pvm:0a125'"); serviceConnectorInstance.getAllocatedWorkListItems(oc, entity, 0, 100); } } catch (SecurityFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidServiceRequestFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.de.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidOrgModelVersionFault e)

TIBCO ActiveMatrix BPM - BPM Developers Guide

Creating and Managing Supervised Work List Views | 187

{ // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidEntityReferenceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidEntityFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.brm.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (WorkItemOrderFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (WorkItemFilterFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.brm.services.SecurityFault e) { // TODO Auto-generated catch block e.printStackTrace(); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

188

| Chapter 7

Working with Work Lists

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 189
Chapter 8

Working with Work Items

This chapter describes using the Business Resource Management Services API to work with work items.

Topics
Introduction to Work Items, page 190 Work Item Versions, page 192 Work Item States, page 193 Retrieving Information on Work Items, page 199 Offering and Allocating Work Items, page 201 Progressing a Work Item, page 212

TIBCO ActiveMatrix BPM - BPM Developers Guide

190

| Chapter 8

Working with Work Items

Introduction to Work Items

Work items are the individual pieces of work within the system. A work item results from the process flow reaching a user task in the process; a work item is sent to the resources specified as the participants of the user task. Web service operations are provided that allow you to perform functions that control work items, such as opening, closing, cancelling, allocating, etc. There are two services that contain work item-related operations: WorkPresentationService - The operations in this service are used when the work item presents a form to the user, which is typically the case for most client applications. This service contains the following operations for working with work item forms: openWorkItem - Opens a work item form. Note that this operation (from WorkPresentationService) is also used if there is a pageflow associated with the user task. The response from the openWorkItem operation contains the pageflow details, which you use with the startPageFlow operation in the PageFlowService to start the pageflow (the pageflow then opens the form). closeWorkItem - Closes the form for the specified work item and updates the associated input and output data. The work item remains in the work list from which it was opened. This is typically called when the user clicks the Close button on the work item form. Also see the saveOpenWorkItem operation (which is in WorkItemManagementService) for information about saving changes that have been made on a work item form without closing the form. cancelWorkItem - Closes the form for the specified work item and discards any changes that were made on the form. The work item remains in the work list from which it was opened. This is typically called when the user clicks the Cancel button on the work item form. completeWorkItem - Closes the specified work item form and updates the associated input and output data. The work item is removed from the work

TIBCO ActiveMatrix BPM - BPM Developers Guide

Introduction to Work Items | 191

list from which it was opened, and the process advances. This is typically called when the user clicks the Submit button on the work item form. openNextWorkItem - Opens the work item form for the next work item in the specified resources work list. getBusinessServiceDetailsByModule - Returns details of the forms used by the page activity in the business service. For more information about the operations in this service, see WorkPresentationService on page 747. WorkItemManagementService - This service contains many operations that can be used to manage work items, such as allocating, skipping, getting offer set, etc. The thing to keep in mind, however, is that the three operations that this service has in common with WorkPresentationService (openWorkItem, closeWorkItem, and completeWorkItem) should be called from WorkItemManagementService only when the work item does not present a form to the user. In most cases, a form is presented to the user; when a form is displayed, use the operations in WorkPresentationService instead. For more information about the operations available in this service, see WorkItemManagementService on page 681. Also see Progressing a Work Item on page 212 for information about using the operations in the services described above to progress a work item through a process.

TIBCO ActiveMatrix BPM - BPM Developers Guide

192

| Chapter 8

Working with Work Items

Work Item Versions

Operations that directly specify a particular work item do so by giving the work item ID. This ID includes an optional version parameter. The version of a work item starts at 0, and increments by one whenever an operation is performed that changes the work items state or data. For example, the following extract shows a closeWorkItem operation increasing the version from 3 to 4:
<api:closeWorkItem> <workItemID id="2" version="3"/> </api:closeWorkItem> <closeWorkItemResponse <workItemID id="2" version="4" xmlns=""/> </closeWorkItemResponse>

As the closeWorkItem extract above shows, various operations also return a version number. If no version number is specified, the latest version is assumed. However, specifying the version can be good practice because it prevents clashes when two or more users attempt to operate on the same work item. For example, two users perform an allocateAndOpenWorkItem operation on a work item. If they do not specify a version number, the second allocateAndOpenWorkItem operation to be executed will fail because the work item is no longer in a suitable state to be allocated or opened. If both users specify the version number of the work item, the second operation will still fail, but it will do so with a version number error, as shown in the following extract:

<api:allocateAndOpenWorkItem> <workItemID id="2" version="1"/> <resource>6353AB5E-C395-409C-E706C02F22DA</resource> </api:allocateWorkItem>

<faultstring>The work item with id = 2 is currently at version 6, not at version 1</faultstring> <faultactor>PROVIDER</faultactor>

This enables your client application to know that you are attempting to use an out-of-date version of the work item, and to take appropriate action. For example, one possibility would be to use the getWorkItemHeader operation to retrieve the latest information for the work item and bring it back up to date. Another would be to use previewWorkItemFromList to obtain the current version of the work item.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Work Item States | 193

Work Item States

A BPM work item is always in one of a small number of defined states. Some of the operations used to manipulate work items cause an item to change its state, as defined in Work Item State Transitions on page 195. The following table shows the states that exist in the BPM runtime. Work Item State (Created) Offered Meaning This is a private state, accessed only by services that are restricted for internal use. This is the initial state of every work item that is made available on the BPM runtime. The work item is offered to those resources who correspond to the organizational entities specified at design time, and is placed in their work list. The work item is assigned to a particular resource to be worked on. A work item may be in the Allocated state more than once in its life cycle, since it can be reallocated to different resources. A work item is Opened when a resource (a user) begins work on it, either by selecting it from a work list or by having it automatically allocated and opened. A work item is suspended if its parent process instance is suspended. See Working With Processes for more information on suspending process instances. An open work item is cancelled when its parent process instance is cancelled. Work items that are not open are deleted when their parent process instance is cancelled. A cancelled work item can be closed by calling closeWorkItem with no associated data. No other operations may affect it. See Working With Processes for more information on cancelling process instances. Pended A work item may be paused or closed, for example between steps in its life cycle.

Allocated

Opened

Suspended

Cancelled

TIBCO ActiveMatrix BPM - BPM Developers Guide

194

| Chapter 8

Working with Work Items

Work Item State PendHidden

Meaning If a work item is Pended with a hiddenPeriod specified, it cannot be accessed for the time defined in that hiddenPeriod. The final state of a work item in the BPM runtime, when work on an Opened work item has been completed. It is no longer on the system and cannot be affected by any API operations.

Completed

TIBCO ActiveMatrix BPM - BPM Developers Guide

Work Item States | 195

Work Item State Transitions

The following diagram and table show what transitions a work item may make between states, and what operations from the Business Resource Management Services API are used to bring about each of the possible changes.

TIBCO ActiveMatrix BPM - BPM Developers Guide

196

| Chapter 8

Working with Work Items

Figure 10 State Transitions Diagram

Created
scheduleWorkItem

Offered
closeWorkItem unallocate WorkItem allocate WorkItem

suspend WorkItem

Suspended
suspend WorkItem suspend WorkItem

Resume WorkItem

Allocated
allocateAndOpen reallocateWorkItem WorkItem openWorkItem

reallocateWorkItem

Opened
openWorkItem
Cancel WorkItem Cancel WorkItem

completeWorkItem

Completed
Cancel WorkItem

Cancelled

closeWorkItem
Cancel WorkItem

Pend WorkItem
resumeWorkItem

Pended
Internal function calls (or timer expires)

Pend WorkItem
(with hiddenPeriod=0 or negative) resumeWorkItem (with hiddenPeriod)

PendHidden
Pend WorkItem Legend
(with hiddenPeriod)

Public API operation Public state

Private API operation Private state

TIBCO ActiveMatrix BPM - BPM Developers Guide

Work Item States | 197

The Business Resource Management Services API includes a number of private services which are intended only for internal use by the BPM runtime. These services should not be used by an external application. State transitions caused by private API service operations have been omitted from the following table.

Start State Offered

End State Allocated

BRM API Operation allocateWorkItem

Description The offered work item is allocated to the specified organization model entity. The allocated object is returned to its original offered state. The allocated work item is opened. The allocated work item is put into the pendHidden state for the duration of the specified hiddenPeriod. Note - The work item cannot be accessed while it is hidden. See Accessing Hidden Work Items on page 218.

Allocated

Offered Opened PendHidden

unallocateWorkItem openWorkItem pendWorkItem (with a hiddenPeriod specified)

TIBCO ActiveMatrix BPM - BPM Developers Guide

198

| Chapter 8

Working with Work Items

Start State Opened

End State Offered

BRM API Operation closeWorkItem

Description The open work item (which must contain no data changes) is closed and returned to its offered state. The open work item is reallocated to the specified organization model entity. It will be in the allocated state. The opened work item is complete. The open work item is closed and any new data copied. It is then put into the pended state. The pended work item is reallocated to another organization model entity and put into the allocated state. The pended work item is opened.

Allocated

reallocateWorkItem

Complete Pended

completeWorkItem closeWorkItem

Pended

Allocated

reallocateWorkItem

Opened

openWorkItem

TIBCO ActiveMatrix BPM - BPM Developers Guide

Retrieving Information on Work Items | 199

Retrieving Information on Work Items

The WorkItemManagementService and WorkListService services provide operations to retrieve information about a specified work item. These are: previewWorkItemFromList getWorkItemHeader getOfferSet

previewWorkItemFromList Use this operation to retrieve information on one or more specified work items in a work list. The request specifies the GUID of the requesting organizational entity, the IDs of one or more work items, and optionally a list of the fields about which information is required. You can use this operation: To get the type and value of one or more specific fields. You can filter the information returned by specifying one or more field names as requiredField parameters. If you do so, the operation returns information only on those named fields. To get information on all fields. If you do not include the requiredField parameter, the response returns the name, type, and value of all fields.

For API reference information, see previewWorkItemFromList on page 738. getWorkItemHeader Use this operation to retrieve the header information for a specified work item. The request specifies the workItemID of the required work itemwhich you can get from the response to a previous getWorkListItems or getAllocatedWorkListItems operationand the response returns the work item header information. The header information includes the work items: name description distributionStrategy priority startDate endDate

TIBCO ActiveMatrix BPM - BPM Developers Guide

200

| Chapter 8

Working with Work Items

These attributes can be used as criteria for sorting or filtering work items in a work item listsee Sort/Filter Criteria on page 172. You can use this operation to bring a work item up to date if you have called an obsolete version. See Work Item Versions on page 192 for more information. For API reference information, see getWorkItemHeader on page 682. getOfferSet Use this operation to get the initial offered set for a work itemthat is, the collection of organizational entities to which the work item was initially offered. The request specifies the unique ID of the required work item and the response returns the GUIDs of all entities in the offer set. This information can then be used to allocate the work item to a particular resource from within this setsee Allocating Work Item to a Target Resource on page 201. For API reference information, see getOfferSet on page 719.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Offering and Allocating Work Items | 201

Offering and Allocating Work Items

The following WorkItemManagementService operations offer and allocate work items to resources: Operation Name allocateWorkItem allocateAndOpenWorkItem When to Use To allocate an offered work item to a single resource, when you need not retrieve the associated input and output data. To allocate an offered work item to a single resource. The work item is immediately opened and the associated input and output data is retrieved. To allocate the next offered work item to a single resource and immediately open that work item to get the associated input and output data. The "next" work item is defined by the sort criteria set for the resource. If no sort criteria are set, the default criteria are used. reallocateWorkItem To reallocate an opened work item to a different resource, or to reallocate a pended work item to a resource. No data is changed. reallocateWorkItemData unallocateWorkItem To reallocate an opened or a pended work item to a different resource and write the new work item data. To reoffer a work item. A currently allocated work item is unallocated so that it is reoffered to the original offer set.

allocateAndOpenNextWorkItem

The following sections describe how to allocate work items to a target resource: Allocating Work Item to a Target Resource on page 201 Reallocating a Work Item on page 207 Reoffering a Work Item on page 209

Allocating Work Item to a Target Resource

You can choose to allocate a work item to a resource from one of the following: Initial Offered Set. You can query the initial offered set using the operation getOfferSet and select a resource from the offer set to allocate the work item to.

TIBCO ActiveMatrix BPM - BPM Developers Guide

202

| Chapter 8

Working with Work Items

World. If your system privileges include the reallocateWorkItemToWorld system action scoped at the organization model level, you can allocate the work item to a resource that was not included in the initial offered set. If there is more than one organization in your organization model, this can be any resource in an organization with which the current LDAP container has a relationship. See Organization Relationships for more details. Self. You can allocate the work item to yourself.

The following diagram shows an example of how you might take a work item from the list of items offered to an organizational entity such as a group or position, and allocate it to a specific resource within the original offer set. Figure 11 Allocating a Work Item

Client Work Manager application Services

Work Manager Work Manager Services

getOfferSet
1

[work item ID] getOfferSetResponse [list of GUIDs of entities in the offer set]

WorkListManagement

ListAssociatedResources
2

[GUID of one entity in the offer set] ListAssociatedResourcesResponse [list of GUIDs of resources mapped to that entity] allocateWorkItem

WorkItemManagement Service

[work item ID and GUID of a user from the offer set] allocateWorkItemResponse
WorkItemManagement Service

TIBCO ActiveMatrix BPM - BPM Developers Guide

Offering and Allocating Work Items | 203

1. Use getOfferSet, specifying the ID of a work item, to list the entities to which this work item was offered.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getOfferSet> <workItemID id="51"/> </api:getOfferSet> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getOfferSetResponse xmlns="http://api.brm.n2.tibco.com"> <entityGuid xmlns="">_5i1V0CfLEeChutsy_vK9tg</entityGuid> </getOfferSetResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

2. Use listAssociatedResources to identify the GUID of one resource (user) from the offer set.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:res="http://resolver.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <res:listAssociatedResources model-version="-1" start-index="0" soft-limit="0"> <entity-guid>_fE8zxSfJEeChutsy_vK9tg</entity-guid> </res:listAssociatedResources> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

204

| Chapter 8

Working with Work Items

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listAssociatedResourcesResponse xmlns="http://resolver.api.de.n2.tibco.com"> <resource guid="846D100C-77C8-42DE-BD01-C23D214D2BB4" name="Liam Lawrence" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="OU=Liam Lawrence, OU=London, OU=AllEmployees, O=easyAsInsurance"/> </resource> <resource guid="931F96FA-EC57-43B5-AA61-613784B1BD10" name="Leon Court" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="OU=Leon Court, OU=Paris, OU=AllEmployees, O=easyAsInsurance"/> </resource> </listAssociatedResourcesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

3. Use allocateWorkItem to allocate the required work item to an individual resource. In this case it is Liam Lawrence, as you can see by comparing the resource GUID with the two GUIDs returned in the previous operation.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:allocateWorkItem> <workItemID id="51" <resource>846D100C-77C8-42DE-BD01-C23D214D2BB4</resource> </api:allocateWorkItem> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Offering and Allocating Work Items | 205

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <allocateWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItem xmlns=""> <id id="51" version="1"/> <header distributionStrategy="OFFER" priority="50"> <name>DisplayMessage</name> <description>Display Message</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i11</activityID> <activityName>DisplayMessage</activityName> <appInstance>pvm:0a124</appInstance> <appName>WelcomeUsers</appName> <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID> </itemContext> </header> <state>ALLOCATED</state> <visible>true</visible> </workItem> </allocateWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>>

TIBCO ActiveMatrix BPM - BPM Developers Guide

206

| Chapter 8

Working with Work Items

Allocating a Work Item Service Connector API Example (Java) The following example illustrates allocating a work item to a target resource, using the method calls available in the Java Service Connector API. The step numbers in the comments correspond to the steps shown in Allocating a Work Item on page 202.
private void allocateWorkItemExample() { // Setup the ManagedObjectID for the work item we want the offer set for ManagedObjectID id = ManagedObjectID.Factory.newInstance(); id.setId(10); try { // Step 1: Get the offer set GUIDs for the work item String[] offerGUIDs = serviceConnectorInstance.getOfferSet(id); if (offerGUIDs != null && offerGUIDs.length > 0) { // Step 2: Get the associated resources for the offer set GUIDs XmlLdapEntity[] entities = serviceConnectorInstance.listAssociatedResources(offerGUIDs, 0, 100); if (entities != null && entities.length > 0) { // Step 3: For this example allocate the work item to the first GUID we found serviceConnectorInstance.allocateWorkItem(new ManagedObjectID[]{id}, new String[]{entities[0].getGuid()}); // Now re-offer the work item to put it back to how we found it serviceConnectorInstance.unallocateWorkItem(new ManagedObjectID[]{id}); } } } catch (InvalidVersionFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidWorkItemFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.brm.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidEntityReferenceFault e) { // TODO Auto-generated catch block e.printStackTrace(); }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Offering and Allocating Work Items | 207

catch (com.tibco.n2.de.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidOrgModelVersionFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidEntityFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.brm.services.SecurityFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

Reallocating a Work Item

When reallocating a work item to another resource, you need to choose whether to use reallocateWorkItem or reallocateWorkItemData. The principal difference is in the handling of the data associated with the work item: Using reallocateWorkItemData you can update the work item body with new data as part of the operation. Using reallocateWorkItem you do not allocate any new data, but you can choose what to do with the existing data associated with the work item, by setting the boolean element revertData: If you set revertData to "false", the work item is reallocated just as it is, with existing data unchanged. If you set revertData to "true", all existing data is discarded. The work item is returned to its original state by reverting to the snapshot taken when it was scheduled. You can reallocate an Opened or Pended work item. You can reallocate an Allocated item, but you cannot use reallocateWorkItemData to update the work item body. If you wish to reallocate and update the data for a work item that is already Allocated, change its status first. The following diagram shows an example of how you might reallocate a work item with fresh data, bearing in mind the need to determine whether it is in a suitable state.

TIBCO ActiveMatrix BPM - BPM Developers Guide

208

| Chapter 8

Working with Work Items

Figure 12 Reallocating a Work Item

Client Work Manager application Services

Work Manager Work Manager Services

getWorkListItems
1

[entity] getWorkListItemsResponse [list of work items in the work list]

WorkListManagement

Depending on the work item State ... openWorkItem [id of the required work item] openWorkItemResponse

WorkItemManagement Service

reallocateWorkItemData
4

[work item ID; GUID of a user; new work item data] reallocateWorkItemDataResponse

WorkItemManagement Service

1. To determine whether the work item is in a suitable state, call getWorkListItems, specifying the resource (user) or other organizational entity on whose work list the work item currently appears. The response to this operation returns among other data the work item state. 2. Determine whether the required work item is in a state in which the reallocateWorkItemData operation can be usedthat is, if it is in an Opened or Pended state. 3. If it is not, call the openWorkItem operation to put the work item in a suitable state to be reallocated. 4. Finally call the reallocateWorkItemData operation to reallocate the work item to a new user and pass new data to them. Reallocating to Offer Set or to World Depending on the system actions a user holds, they may be able to reallocate a work item more or less widely:

TIBCO ActiveMatrix BPM - BPM Developers Guide

Offering and Allocating Work Items | 209

reallocateToOfferSet This system action authorizes you to reallocate a work item to a resource in the original offer set. If for example the originally allocated resource is absent or overloaded, this might typically be sufficient to reallocate a work item to another member of the same team. reallocateWorkItemToWorld This system action authorizes you to reallocate a work item to any resourcethat is, to anybody in the "world" of the BPM runtime. You might need this level of authorization if for example it was decided that a work item needed reallocating to another department or to a resource with significantly different expertise, who was not in the original offer set.

Reoffering a Work Item

If a work item needs to be transferred from a user to whom it is currently allocated, but you want to reoffer it to the initial offered set rather than allocating it directly to a specific resource, you can use the unallocateWorkItem operation. This resets the work item to the Offered state, as shown in the following example. Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:unallocateWorkItem> <workItemID id="3" version="16"/> </api:unallocateWorkItem> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

210

| Chapter 8

Working with Work Items

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <unallocateWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItem xmlns=""> <id id="3" version="17"/> <header distributionStrategy="OFFER" priority="50"> <name>DisplayMessage</name> <description>Display Message</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001io</activityID> <activityName>DisplayMessage</activityName> <appInstance>pvm:0a123</appInstance> <appName>WelcomeUsers</appName> <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID> </itemContext> </header> <state>OFFERED</state> <visible>true</visible> </workItem> </unallocateWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Note that you cannot change the resources to which the work item is offered; you can only reallocate to the original offer set. If you need the work item to be assigned to a completely different resource you must possess the reallocateWorkItemToWorld system action and reallocate the work item using reallocateWorkItem, as described in Reallocating to Offer Set or to World.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Opening a Work Item | 211

Opening a Work Item

Opening a work item results in one of the following: A form is opened - If the user task was designed to display a form, use the openWorkItem request in the WorkPresentationService. For additional information about opening a work item and displaying a form, see Displaying a Work Item Form on page 239. If the user task was designed to display a custom form (rather than a TIBCO Business Studio form), also see Using Custom Forms on page 256. A pageflow is started - If the user task was designed to start a pageflow when it is opened, use the openWorkItem request in the WorkPresentationService. The response from the openWorkItem request contains the pageflow details, which you use with the startPageFlow request in the WorkPresentationService to start the pageflow. For additional information, and an example of starting a pageflow when a work item is opened, see Displaying a Form in a Pageflow on page 242. Work item data is retrieved (but no form is displayed) - If the user task was designed to neither open a form nor start a pageflow, use the openWorkItem request in the WorkItemManagementService. This returns all of the associated input and output data for the work item. Note that this is typically only used in special use-case client applications. To use either of the openWorkItem requests, the work item must currently be in a state of Allocated or Pended. If a work item is currently in a state of Offered, you can use the allocateAndOpenWorkItem and allocateAndOpenNextWorkItem requests in the WorkItemManagementService to allocate and open the work item at the same time. For more information about work item states, see Work Item States on page 193. For information about additional requests that can be made to progress a work item after opening it, see Progressing a Work Item on page 212.

TIBCO ActiveMatrix BPM - BPM Developers Guide

212

| Chapter 8

Working with Work Items

Progressing a Work Item

A number of service operations are provided that allow you to progress a work item through a business process. Each of these operations is applicable only to work items in a particular state or statesfor example, you cannot perform an openWorkItem on a work item that is already Opened. These operations will also change the state of the affected work itemto take openWorkItem as an example again, a successful openWorkItem call changes the state of the work item from Allocated or Pended to Opened. See Work Item States on page 193 and Accessing Hidden Work Items on page 218 for information about the possible states of work items and the possible changes between states. The following operations are used for progressing work items: openWorkItem closeWorkItem completeWorkItem cancelWorkItem skipWorkItem saveOpenWorkItem pendWorkItem

To identify which work item is affected, the requests for these operations require the unique ID of the work item as input. You can obtain the work item ID by several methods, for example from the response to a previous getWorkListItems or getAllocatedWorkListItems operation.

openWorkItem
Use this operation to open a work item and to retrieve the associated data. The work item must be Allocated or Pended, and its state is changed to Opened. The operation returns the body of the work item. Note that this operation is available in two different services: WorkPresentationService - The openWorkItem operation in this service should be used in the following situations: If the user task is designed to display a form. This is typical for most client applications. (If the work item is designed to display a custom form, rather

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 213

than a TIBCO Business Studio form, also see Using Custom Forms on page 256.) If the user task is designed to start a pageflow. The response from the openWorkItem request contains the pageflow details, which you use with the startPageFlow operation in the WorkPresentationService to start the pageflow. For API reference information for the openWorkItem operation in this service, see openWorkItem on page 748. WorkItemManagementService - The openWorkItem operation is this service is used only if the user task does not open a form nor start a pageflow. This would be used only in special use-case client applications. For API reference information for the openWorkItem operation in this service, see openWorkItem on page 685.

closeWorkItem
Use this operation to close a work item and to update the associated data with any changes the user has made while it was open. This operation is for work items that are not completed, but on which work has been paused. The work item must be Opened. The operation sets the state to either PendHidden, if a hiddenPeriod is specified as an input parameter for this operation, or to Pended. Note that this operation is available in two different services: WorkPresentationService - The closeWorkItem operation in this service should be used to close a form that was opened when the work item was opened with the openWorkItem operation. This is typically called in response to a user clicking the Close button on a work item form. For API reference information for the closeWorkItem operation in this service, see closeWorkItem on page 753. WorkItemManagementService - The closeWorkItem operation in this service is used only if the user task did not open a form when the work item was opened. This would be used only in special use-case client applications. One special use-case for using the closeWorkItem operation in WorkItemManagementService is to set the work item state to PendHidden so that it does not appear in the work list for a specified period of time. For more information, see Accessing Hidden Work Items on page 218. For API reference information for the closeWorkItem operation in this service, see closeWorkItem on page 688.
TIBCO ActiveMatrix BPM - BPM Developers Guide

214

| Chapter 8

Working with Work Items

completeWorkItem
Use this operation when work on a work item or pageflow has completed, and to update the associated data with any changes the user has made while the work item or pageflow was open. The work item must be Opened, and its state is changed to Completed. Note that this operation is available in two different services: WorkPresentationService - The completeWorkItem operation in this service should be used in the following situations: To complete a work item when a form was opened when the work item was opened with the openWorkItem operation. Input and output data associated with the work item is saved to the database. This is typically called in response to a user clicking the Submit button on a work item form. To complete the parent work item when a pageflow was started after the work item was opened with the openWorkItem operation. The work item form is closed and input and output data associated with the work item (and pageflow) is saved to the database. For API reference information for the completeWorkItem operation in this service, see completeWorkItem on page 756. WorkItemManagementService - The completeWorkItem operation in this service is used only if the user task does not open a form nor start a pageflow. This would be used only in special use-case client applications. For API reference information for the completeWorkItem operation in this service, see completeWorkItem on page 706.

cancelWorkItem
Use this operation (which is available in the WorkPresentationService) to cancel any changes that a user has made on a work item form. It closes the work item form, discards any changes on the form, and leaves the work item in the users work list. For API reference information for the cancelWorkItem operation in this service, see cancelWorkItem on page 751.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 215

skipWorkItem
Use this operation (which is in the WorkItemManagementService) to skip a work item, so that no action is carried out on it. This has a very similar effect to completing a work item, in that it means that no further work is required. However it can only be carried out: By a user who has authorization for the skipWorkItem system action, and On work items for which all required output and in/out data fields either: have default values defined, or in the case of input/output fields, have been give values before this work item, by a script or another activity. The work item must be Allocated, and once skipped its state is changed to Completed. For API reference information, see skipWorkItem on page 710.

saveOpenWorkItem
Use this operation (which is in the WorkItemManagementService) to save an open work item, updating the associated data with any changes the user has made while it was open. The work item must be Opened, and its state is not changed. For API reference information, see saveOpenWorkItem on page 721.

pendWorkItem
Use this operation (which is in the WorkItemManagementService) to set aside an unfinished work item as pending, and optionally to make that work item inaccessible for a specified period of time. Use the hiddenPeriod as follows: If no hiddenPeriod is specified, the work item must be Offered or Allocated, and its state is changed to Pended. A pendWorkItem call with a hiddenPeriod specified can be used to transition an Offered, Allocated or Pended work item into the PendHidden state. A pendWorkItem call with a hiddenPeriod of zero or a negative time specified can be used to change an item from a PendHidden state to a Pended state.

TIBCO ActiveMatrix BPM - BPM Developers Guide

216

| Chapter 8

Working with Work Items

See Accessing Hidden Work Items on page 218 for detail on the effects of specifying various hiddenPeriods. Note that you can transition an Opened work item into a Pended state using closeWorkItem, not pendWorkItem. For API reference information, see pendWorkItem on page 725.

Handling a Work Item That Contains Business Data

Business processes running in the BPM runtime may use their own business data. This consists of user-defined data types representing business-domain objects, such as a customer or an address. Business data types are defined in a Business Object Model in TIBCO Business Studio, after which they can be used as part of processes, pageflows or business services that are either part of or reference that project. To enable your client application to handle a work item (or pageflow page) that contains such business data, you must provide it with the details of the underlying schemas used to define that data. You cannot obtain this information programmatically. Instead, you must: 1. In TIBCO Business Studio, identify every project that contains: a process (business, pageflow or business service) with which the client application will interact. a Business Object Model (that defines or uses business data) that is used by one of these processes. 2. Export a Work Data Model for each of these projects. See Work Data Models for more information about how to do this. 3. Modify your client application to use the data definitions provided by the Work Data Models. Valid Format for ComplexSpec Business Data The following service requests allow business data (inputs, outputs, or inouts) to be passed into the request: closeWorkItem completeWorkItem reallocateWorkItemData saveOpenWorkItem

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 217

The business data passed into these requests is in the form of a dataModel element. The parameter data passed into the request can be either a simple type (simpleSpec) or a complex type (complexSpec, which is a BOM). For example, the following shows the saveOpenWorkItem request, in which inputs, outputs, or inouts can be passed as either simpleSpec or complexSpec data:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:saveOpenWorkItem> <workItemID id="?" version="?"/> <workItemPayload> <dataModel> <inputs name="?" type="?" optional="?" array="?"> <simpleSpec length="?" decimal="?"> <value>?</value> </simpleSpec> <complexSpec className="?"> <value>?</value> </complexSpec> </inputs> <outputs name="?" type="?" optional="?" array="?"> <simpleSpec length="?" decimal="?"> <value>?</value> </simpleSpec> <complexSpec className="?"> <value>?</value> </complexSpec> </outputs> <inouts name="?" type="?" optional="?" array="?"> <simpleSpec length="?" decimal="?"> <value>?</value> </simpleSpec> <complexSpec className="?"> <value>?</value> </complexSpec> </inouts> </dataModel> </workItemPayload> </api:saveOpenWorkItem> </soapenv:Body> </soapenv:Envelope>

If you pass ComplexSpec business data into one of the requests listed above (closeWorkItem, completeWorkItem, reallocateWorkItemData, or saveOpenWorkItem), the value can be either element-based or type-based.

TIBCO ActiveMatrix BPM - BPM Developers Guide

218

| Chapter 8

Working with Work Items

The following shows the valid format for element-based and type-based complexSpec data values. Element-based complexSpec Example
<value> <businessserviceformediation:CustomerElement xsi:type="businessserviceformediation:Customer" xmlns:businessserviceformediation= "http://example.com/businessserviceformediation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <age>40</age> <name>Fred</name> <address xsi:type="businessserviceformediation:Address"> <firstLine>First Line</firstLine> <secondLine>Second Line</secondLine> </address> </businessserviceformediation:CustomerElement> </value>

Type-based complexSpec Example

<value xsi:type="businessserviceformediation:Customer" xmlns:businessserviceformediation= "http://example.com/businessserviceformediation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <age>40</age> <name>Fred</name> <address xsi:type="businessserviceformediation:Address"> <firstLine>First Line</firstLine> <secondLine>Second Line</secondLine> </address> </value>

Accessing Hidden Work Items

If a hiddenPeriod is specified on a pendWorkItem or closeWorkItem operation the work item will transition to the PendHidden state, rather than Pended. Operations that work on the Pended state (for example, reallocateWorkItem) cannot then access the work item until either of the following occurs: the hiddenPeriod expires. a further pendWorkItem operation is specified with a hiddenPeriod of 0. This cancels the current hiddenPeriod. (A negative hiddenPeriod duration or a date that is in the past will have the same effect.)

When either of these occurs, the work item then transitions back to the Pended state.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 219

The duration of a hiddenPeriod can also be extended or reduced by issuing a further pendWorkItem operation with a new hiddenPeriod. The new hiddenPeriod overrides the existing hiddenPeriod and is calculated from the current date/time. For example, suppose that a work item was pended at 14:30 with a hiddenPeriod of 30 minutes. If a further pendWorkItem is issued at 14:45 with: a hiddenPeriod of 2 hours, the work item will remain hidden until 16:45. a hiddenPeriod of 5 minutes, the work item will remain hidden until 14:50. a hiddenPeriod of 0, the work item will immediately transition to the Pended state. a hiddenPeriod of -5 minutes, the work item will immediately transition to the Pended state.

TIBCO ActiveMatrix BPM - BPM Developers Guide

220

| Chapter 8

Working with Work Items

Example of Processing a Work Item

The following diagram shows a simple example of the possible flow of processing for a work item. Figure 13 Processing a Work Item
Work Manager Client Services application
WorkItemManagement Service operations
WorkItemManagementService

Work item item Work state state

allocateWorkItem

OFFERED ALLOCATED

[work item ID, resource GUID]

allocateWorkItemResponse

openWorkItem

WorkPresentationService

[work item ID]

openWorkItemResponse SaveOpenWorkItem
WorkItemManagementService

OPENED

[work item ID]

saveOpenWorkItemResponse
WorkPresentationService

OPENED

closeWorkItem

[work item ID, hiddenPeriod]

closeWorkItemResponse C PENDHIDDEN

hiddenPeriod expires
openWorkItem
WorkPresentationService

C PENDED OPENED

[work item ID]

openWorkItemResponse completeWorkItem
WorkPresentationService

[work item ID]

completeWorkItemResponse

C COMPLETED

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 221

In this example: 1. A work item appears in an organizational entitys work list. Its initial state is Offered. 2. To direct it to a resource (user) within that organizational entity, use the allocateWorkItem call, specifying the ID of the work item and the GUID of the resource as input parameters. The state of the work item changes to Allocated. 3. When the user opens the work item from their client user interface, the client application calls the openWorkItem operation, with the work item ID as an input parameter. The status of the work item changes to Opened. 4. The client application may make provision for the user to save the work item part way through completing it. This would be particularly useful if the work item displays a form containing a large number of fields or that may take some time to complete. In such circumstances the client application can call the saveOpenWorkItem operation. This saves the data associated with the work item, but does not change its stateit remains Opened. 5. In some applications a user may have to wait some time before finalizing a work item, for example to wait for another process to complete or for information to come in from an outside source. In that case the work item can be pended. If it is in an Opened state as in this example, that can be achieved by calling the closeWorkItem operation. If you call closeWorkItem and specify a hiddenPeriod, then that work item cannot be operated on for the specified period of time, or until the specified date and time is reached. Until then it is in the PendHidden state. 6. When the pendHidden deadline is reached a timer expires and the work item is put in the Pended state. 7. The user can now resume work on it. This is done by calling openWorkItem again, and returning the work item to the Opened state. 8. When the user has finished with the work item, and indicates this by pressing a Submit button or similar in their client applications user interface, the completeWorkItem operation is called and the state of the work item changed to Completed.

TIBCO ActiveMatrix BPM - BPM Developers Guide

222

| Chapter 8

Working with Work Items

Processing a Work Item with a Form

The following diagram shows a simple example of the possible flow of processing for a work item that presents information to the user using a custom form. See Displaying a Work Item Form for more information. Figure 14 Processing a Work Item with a Form
Work Forms Manager Runtime Services 1

Client Work Manager application Services

Business Resource Management Services Work ManagerServices: WorkItemManagementService allocateWorkItem

Work Manager Services: Work Manager Services WorkPresentationService

[work item ID, resource GUID]

allocateWorkItemResponse

2 Client invokes forms runtime to display form

openWorkItem

[work item ID]

openWorkItemResponse

4 5

User clicks Close button. Forms runtime notifies client and submits data

completeWorkItem

[work item ID]

completeWorkItemResponse

In this example: 1. A work item appears in an organizational entitys work list. To direct it to a resource (user) within that organizational entity, use the allocateWorkItem call from WorkItemManagementService, specifying the ID of the work item and the GUID of the resource as input parameters. 2. When the user opens the work item from their client user interface, the client application calls the openWorkItem operation from WorkPresentationService, with the work item ID as an input parameter. The WorkPresentationService operation is used instead of the operation of the same name in the WorkItemManagementService, because the work item makes a visual presentation to the user, and WorkPresentationService is optimized for the presentation of forms.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 223

3. The client application invokes the Forms runtime to display the work items initial form. It may make other calls to the Forms runtime for subsequent forms within the work item. See Working With Forms for further information on using the Forms runtime. 4. When the user has finished with the work item, and indicates this by pressing a Close button or similar in their client applications user interface, the Forms runtime notifies the client application. 5. The client then invokes the completeWorkItem operation from WorkItemManagementService. Throughout this example the state of the work item changes as described in Example of Processing a Work Item.

Processing Chained Work Items

When a business process is designed, several work items may be grouped together in an embedded sub-process and defined as chained. This means that they must be carried out in succession by the same user. See "Chained Execution" in the TIBCO Business Studio Process Modeling Users Guide for more information on chaining. In order to implement chained execution at runtime, when the first work item of a chained group is completed, the next work item in the chain must immediately be opened and allocated to the same resource who executed the first one. To achieve this, use the completeWorkItem operation in WorkPresentationService.

TIBCO ActiveMatrix BPM - BPM Developers Guide

224

| Chapter 8

Working with Work Items

Figure 15 Chained Work Items

Client Work Manager application Services
Business Resource Management Services Work ManagerServices: WorkItemManagementService allocateWorkItem 1 Work Manager Services: Work Manager Services WorkPresentationService

[work item ID, resource GUID]

allocateWorkItemResponse

openWorkItem 2

[work item ID]

openWorkItemResponse completeWorkItem

[work item ID]

completeWorkItemResponse [ID of second chained work item]

completeWorkItem

[work item ID]

completeWorkItemResponse [ID of third chained work item]

REPEATED UNTIL ... completeWorkItem

[work item ID]

completeWorkItemResponse [no chained work item data]

In this example: 1. A work item is assigned to a resource (user) by the allocateWorkItem call from WorkItemManagementService, as in Example of Processing a Work Item. 2. When the user opens the work item from their client user interface, the client application calls the openWorkItem operation from WorkPresentationService, with the work item ID as an input parameter. 3. When the user has finished with the work item, the client application invokes the completeWorkItem operation from WorkItemManagementService. The response to completeWorkItem returns the ID of the next work item in the chained subprocess.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 225

4. The completeWorkItem response automatically opens the next chained work item; the client application does not need to call openWorkItem again. Note that the next chained work item must arrive within the timeout period specified by the CHAINED_TIMEOUT property in the WPProperties.properties file. If no response is received within that period, the chain "breaks", and no further chained work items are executed. For more details of this and other properties, see the WPProperties.properties file in the "BPM Properties Files" section of the TIBCO ActiveMatrix BPM BPM Administration guide. 5. The completeWorkItem operation is called for as many times as necessary, each time returning the ID of the next chained work item. 6. Eventually completeWorkItem returns no chained work item information, which indicates that the chained subprocess is completed. Processing Chained Work Items Web Service API Example The following example shows the web service calls from WorkItemManagementService that this sequence of events would produce. It uses the "WelcomeUsersChained" process, produced in the BPM tutorial "How to Ensure that a Sequence of Tasks is Performed by the Same User". First, use openWorkItem to open the first work item (workItemID 24) and assign it to a resource. The resource in this case is the user Clint Hill, with the ID
2D6430DC-9A65-4F21-A3BE-798AA192E468:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.wp.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:baseWorkRequest> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <workItem id="24">?</workItem> <workTypeDetail/> </api:baseWorkRequest> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

226

| Chapter 8

Working with Work Items

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <workResponse xmlns="http://api.wp.n2.tibco.com"> <payloadModel payloadMode="JSON" xmlns=""> <serializedPayload>{items:[{"$param":"UserName","$value":[],"typ e":"String","mode":"OUT"}]}</serializedPayload> </payloadModel> <workTypeDetail pilingLimit="0" typePiled="false" uid="WT__D1uKcCoHEeCmTZqrA21YZg" version="1.0.0.201108121142" xmlns=""/> <presentation activityName="GetUsersName" formIdenitifier="1.0.0.201108121142/GIGWTPull_DefaultChannel/.de fault/ProcessPackage/WelcomeUsersChained/GetUsersName/GetUsersNa me.gwt.json" type="GI_FORM" version="1.0.0.201108121142" xmlns=""/> <workItem id="24" version="1" xmlns=""/> </workResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Use completeWorkItem to complete work item 24:

oapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.wp.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:workRequest> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <workItem id="24">?</workItem> <workTypeDetail openNextPiled="true"/> <payloadDetails> <!--You have a CHOICE of the next 2 items at this level--> <serializedPayload>{items:[{"$param":"UserName","$value":[Filipp o Scolari],"type":"String","mode":"OUT"}]}</serializedPayload> <XmlPayload/> </payloadDetails> </api:workRequest> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 227

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <workResponse xmlns="http://api.wp.n2.tibco.com"> <payloadModel payloadMode="" xmlns=""/> <workTypeDetail pilingLimit="0" typePiled="false" uid="WT__efo_sClUEeCJP69W825hSw" version="1.0.0.201108121142" xmlns=""/> <presentation activityName="SendOutWelcomePack" formIdenitifier="1.0.0.201108121142/GIGWTPull_DefaultChannel/.de fault/ProcessPackage/WelcomeUsersChained/SendOutWelcomePack/Send OutWelcomePack.gwt.json" type="GI_FORM" version="1.0.0.201108121142" xmlns=""/> <workItem id="25" version="1" xmlns=""/> </workResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Use completeWorkItem again to complete work item 25:

<api:baseWorkRequest> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <workItem id="25">?</workItem> <workTypeDetail/> </api:baseWorkRequest> <workResponse xmlns="http://api.wp.n2.tibco.com"> <payloadModel payloadMode="JSON" xmlns=""> <serializedPayload>{items:[{"$param":"UserName","$value":[],"typ e":"String","mode":"OUT"}]}</serializedPayload> </payloadModel> <workTypeDetail pilingLimit="0" typePiled="false" uid="WT__D1uKcCoHEeCmTZqrA21YZg" version="1.0.0.201108121142" xmlns=""/> <presentation activityName="MakeFollowUpCall" formIdenitifier="1.0.0.201108121142/GIGWTPull_DefaultChannel/.de fault/ProcessPackage/WelcomeUsersChained/GetUsersName/GetUsersNa me.gwt.json" type="GI_FORM" version="1.0.0.201108121142" xmlns=""/> <workItem id="26" version="1" xmlns=""/> </workResponse>

TIBCO ActiveMatrix BPM - BPM Developers Guide

228

| Chapter 8

Working with Work Items

Call completeWorkItem again to complete work item 26. This time the response shows no chained work item information.
<api:workRequest> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <workItem id="26">?</workItem> <workTypeDetail openNextPiled="true"/> <payloadDetails> <serializedPayload>[]}</serializedPayload> <XmlPayload/> </payloadDetails> </api:workRequest>

<workResponse isSuccessful="true" xmlns="http://api.wp.n2.tibco.com"/>

Processing Chained Work Items Service Connector API Example (Java) The following example code illustrates processing chained work items using method calls available in the Service Connector API. The step numbers in the comments correspond to the steps shown in Chained Work Items on page 224.
private void completeChainedWorkItem() { try { // Step 1: Allocate the work item // First we setup arrays containing the items to allocate and the resources to allocate to // The items to allocate ManagedObjectID[] itemsToAllocate = new ManagedObjectID[1]; ManagedObjectID itemToAllocate = ManagedObjectID.Factory.newInstance(); itemToAllocate.setId(84); itemsToAllocate[0] = itemToAllocate; // The resource to allocate to String[] resourcesToAllocate = new String[]{"tibco-admin"}; // Do the allocation com.tibco.n2.brm.api.WorkItem[] itemsAllocated = serviceConnectorInstance.allocateWorkItem(itemsToAllocate, resourcesToAllocate); // Step 2: Open the work item // Create a request to open the work item we are interested in BaseWorkRequest openRequest = BaseWorkRequest.Factory.newInstance(); WorkItem item = openRequest.addNewWorkItem(); // Use the ID we got back from the allocateWorkItem call, in this case we only have 1

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 229

item.setId(itemsAllocated[0].getId().getId()); openRequest.setResourceId("tibco-admin"); // Open the item WorkResponse openResponse = serviceConnectorInstance.openWorkItem(openRequest); // Step 3: Complete the item ( continue until no more items are available ) // Setup variable to hold details of the item we will complete, initially this will be // the item we opened, then it will be the item returned by the complete call for each item in the chain. long itemIdToComplete = openResponse.getWorkItem().getId(); long itemVersionToComplete = openResponse.getWorkItem().getVersion(); String itemWTUidToComplete = openResponse.getWorkTypeDetail().getUid(); String itemWTVersionToComplete = openResponse.getWorkTypeDetail().getVersion();

// Flag to indicate whether we have run out of items and should break out of the loop boolean nextItemAvailable = true; while (nextItemAvailable) { // Create a request WorkRequest completeRequest = WorkRequest.Factory.newInstance(); // Add the item to the request item = completeRequest.addNewWorkItem(); item.setId(itemIdToComplete); item.setVersion(itemVersionToComplete); completeRequest.setResourceId("tibco-admin"); // Add the work type to the request WorkTypeDetail detail = WorkTypeDetail.Factory.newInstance(); completeRequest.setWorkTypeDetail(detail); detail.setUid(itemWTUidToComplete); detail.setVersion(itemWTVersionToComplete); // Add the data to the request DataPayload payload = DataPayload.Factory.newInstance(); payload.setPayloadMode(PayloadModeType.JSON); payload.setSerializedPayload(""); completeRequest.setPayloadDetails(payload); // Complete the item WorkResponse completeResponse = serviceConnectorInstance.completeWorkItem(completeRequest); // Check the response to see if another item is available if (completeResponse.getWorkItem() == null) { // If no item available break out of the loop - chaining is now finished nextItemAvailable = false; } else {

TIBCO ActiveMatrix BPM - BPM Developers Guide

230

| Chapter 8

Working with Work Items

// Update the details for the item we will complete next itemIdToComplete = completeResponse.getWorkItem().getId(); itemVersionToComplete = completeResponse.getWorkItem().getVersion(); itemWTUidToComplete = completeResponse.getWorkTypeDetail().getUid(); itemWTVersionToComplete = completeResponse.getWorkTypeDetail().getVersion(); } } } catch (InvalidWorkRequestFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (WorkItemUnavailableFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.wp.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (WorkProcessingFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (ChainedTimeOutFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidWorkItemFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidEntityFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidVersionFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.brm.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.brm.services.SecurityFault e) { // TODO Auto-generated catch block e.printStackTrace();

TIBCO ActiveMatrix BPM - BPM Developers Guide

Progressing a Work Item | 231

} } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

232

| Chapter 8

Working with Work Items

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 233
Chapter 9

Working With Forms

This chapter describes how to use the WorkPresentationService, PageFlowService and BusinessService APIs to display forms for work items and pageflow/business service page activities in a client application.

Topics
Overview, page 234 Using TIBCO Forms, page 235 Displaying a Work Item Form, page 239 Displaying a Form in a Pageflow, page 242 Displaying a Form in a Business Service, page 251 Using Custom Forms, page 256

TIBCO ActiveMatrix BPM - BPM Developers Guide

234

| Chapter 9

Working With Forms

Overview
A client application may need to display a form to a user when that user: opens a work item. opens a work item that starts a pageflow. starts a business service.

The client application can render the form using either: a TIBCO form, which provides a web-based user interface to the work item data. See Using TIBCO Forms. a custom form developed as part of the client application. See Using Custom Forms.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using TIBCO Forms 235

Using TIBCO Forms

TIBCO forms provide web-based user interfaces for business processes. At design-time, process analysts and solution designers can use TIBCO Business Studio to design forms and associate them with user tasks in business processes or pageflow processes. (See the TIBCO Business Studio documentation for more information.) TIBCO Business Studio generates run-time implementations of these forms based on the use of channel types and presentation channels: A channel type defines a method employed to deliver and display a form to a user. The specification of a channel type defines: a delivery mechanism (for example, web client or email). a rendering technology (for example, TIBCO General Interface (GI) or Google Web Toolkit (GWT). A presentation channel is a container for a selection of available channel types; it defines the ways in which a form can be delivered and presented to users.

TIBCO Business Studio automatically generates an implementation of each form defined in a project for each channel type defined in the projects presentation channel(s). If no form has been defined for a user activity, default form implementations are automatically generated for the default presentation channel. When a project is deployed to the BPM runtime, the generated form artifacts are deployed as well. (bpmresources is the name of the BPM runtime component that provides access to the form resources of deployed BPM applications.) A client application can use the WorkPresentationService to access the form artifacts that have been deployed to the BPM runtime, and so display an appropriate TIBCO form for a work item or pageflow/business service page.

Binding the Client Application to a Channel

A client application must be bound to a single channel (identified by a channelId). The selected channel must be one that is used by the presentation channel of any TIBCO Business Studio process that the client application will process. The binding can be done declaratively or programmatically. For example, Workspace uses a configuration file entry.

TIBCO ActiveMatrix BPM - BPM Developers Guide

236

| Chapter 9

Working With Forms

The BPM runtime uses this channel to select the correct form artifact to use to display a form. If the client is not explicitly bound to a channelId, the default openspaceGWTPull_DefaultChannel (see below) is used.

Identifying the Client Channel in a Service Call

Most WorkPresentationService calls require you to identify the channel to be used, using the following items in the request message: channelId is the identifier of the channel to which the client is bound. channelType is an enumerated value associated with that channel type.

The following table shows: the channel types supported by TIBCO Business Studio. the format of different channelIds used to identify individual channels of each presentation type. ChannelName is the label of the parent presentation channel - for example, DefaultChannel or CustChannel1. the channelType enumeration that should be specified for each channelId. channelId openspaceGWTPull_ChannelName GIGWTPull_ChannelName MobileGWTPull_ChannelName GIGIPull_ChannelName EmailGIPush_ChannelName channelType openspaceChannel openspaceChannel MobileChannel GIChannel EmailChannel

TIBCO Business Studio channel type Openspace Google Web Toolkit Workspace Google Web Toolkit Openspace Mobile Workspace General Interface Workspace Email

The channelType enumerations JSPChannel, PageflowChannel and RssChannel are currently not supported. You cannot obtain channelIds programmatically. Instead, you must obtain them directly from TIBCO Business Studio. The following screenshot shows: the channel types used by the default presentation channel. (Form artifacts are automatically generated for each of these channel types.) how to obtain the channelId of a particular channel. In this example, openspaceGWTPull_DefaultChannel identifies the channel in the Default

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using TIBCO Forms 237

Channel presentation channel that uses the Openspace Google Web Toolkit channel type.

See "Using Presentation Channels to Display Tasks to Users" in TIBCO Business Studio BPM Implementation for more information.

TIBCO ActiveMatrix BPM - BPM Developers Guide

238

| Chapter 9

Working With Forms

Rendering a TIBCO Business Studio Form

The Forms Runtime Adapter is a JavaScript API provided as part of the BPM runtime. A client application can use the Forms Runtime Adapter to display TIBCO Business Studio forms for work items, pageflow pages and business service pages. To display a TIBCO form, the client application must: 1. Load the Forms Runtime Adapter in the browser control. The Forms Runtime Adapter provides an API that will display the form. 2. Pass in the URL of the JSON representation of the form. 3. Pass in the JSON payload (representing the payload associated with the user task of the displayed form) that will be used to populate the form. 4. Create action handlers for the Submit, Cancel and (if required) Close form actions. These will be used to notify the client application when that action takes place, passing back any updated data. 5. Render the form using the Forms Runtime Adapter loadForm method. For more information about how to perform these steps, see the following references: Integrating TIBCO Forms with Custom Client Applications provides detailed information about the Forms Runtime Adapter and how to use it. Rendering a Form for a Work Item provides an example of how to use the Forms Runtime Adapter in a custom client application that uses the web service API to access BPM services. Rendering a Form for a Work Item provides an example of how to use the Forms Runtime Adapter in a custom client application that uses the Service Connector to access BPM services.

The Forms Runtime Adapter handles the users interaction with the form. When the user submits, closes or cancels the form, the Forms Runtime Adapter notifies the client application that this has happened (using the callback handler registered) and returns the data from the form. For more information about how to integrate use of the Forms Runtime Adapter with calls to the BPM services, see: Displaying a Work Item Form Displaying a Form in a Pageflow Displaying a Form in a Business Service

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Work Item Form 239

Displaying a Work Item Form

The following diagram shows the sequence of calls a client application should make to display a work item form. (See Progressing a Work Item on page 212 for more information about opening a work item.)
Browser Client application Work Manager Services

User opens a work item openWorkItem 1 [work item data, form details]

WorkPresentation Service

Client invokes the Forms Runtime Adapter to display form User clicks Submit, Cancel or Close button. Forms Runtime Adapter notifies client of the users action and submits data 2

closeWorkItem, or cancelWorkItem or completeWorkItem [success]

WorkPresentation Service

The following step-by-step descriptions correspond to the numbered steps in the diagram. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). For an example of how to use the Service Connector API (Java) to display a work item, see Rendering a Form for a Work Item on page 62.

TIBCO ActiveMatrix BPM - BPM Developers Guide

240

| Chapter 9

Working With Forms

When a user opens a work item from the user interface: 1. Call openWorkItem. Use the following items in the baseWorkRequest element to specify form-related inputs to the call: channelId specifies the presentation channel to which the client application is bound. (If channelId is not specified, the default channel will be used.) channelType specifies the type of the channelId. responsePayloadMode specifies the format in which the work item data should be returned. This must be JSON. If the work item is associated with a single form (rather than a pageflow), the following items in the workResponse element contain the information needed to render the work item: payloadModel.serializedPayload contains the work item data as a JSON payload. presentation.formIdentifier identifies the JSON form artifact to be used to display the work item data). For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.wp.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:baseWorkRequest> <resourceId>A2DF6C05-AECA-4D59-A553-A7D029920D51</resourceId> <channelId>openspaceGWTPull_DefaultChannel</channelId> <channelType>openspaceChannel</channelType> <responsePayloadMode>JSON</responsePayloadMode> <workItem id="10" version="-1"></workItem> </api:baseWorkRequest> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Work Item Form 241

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <workResponse xmlns="http://api.wp.n2.tibco.com"> <payloadModel payloadMode="JSON" xmlns=""> <serializedPayload>{items:[{"$param":"PhoneNumber","$value":["666"], "type":"String","mode":"IN"},{"$param":"UserName","$value":["Martin"],"type":"St ring","mode":"IN"},{"$param":"Message","$value":["Please call Martin at 666."],"type":"String","mode":"INOUT"}]}</serializedPayload> </payloadModel> <workTypeDetail pilingLimit="0" typePiled="false" uid="WT__2H9PkMP5EeC3yLAVrheurQ" version="1.0.0.201108111305" xmlns=""/> <presentation activityName="Displayeverything" formIdenitifier="1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aph MyPackage/aphWelcomeUsers/Displayeverything/Displayeverything.gwt.json" type="GWT_FORM" version="1.0.0.201108111305" xmlns=""/> <workItem id="10" version="1" xmlns=""/> </workResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

2. Pass the work item data and form details to the Forms Runtime Adapter, which renders the form and handles the users interaction with it. (See Rendering a TIBCO Business Studio Form.) When the user submits, closes or cancels the form, the Forms Runtime Adapter notifies the client application that this has happened and returns the data from the form. 3. Call closeWorkItem, cancelWorkItem or completeWorkItem as appropriate.

TIBCO ActiveMatrix BPM - BPM Developers Guide

242

| Chapter 9

Working With Forms

Displaying a Form in a Pageflow

The following diagram shows the sequence of calls a client application should make to display a form in a pageflow. (See Progressing a Work Item on page 212 for more information about opening a work item.)
Browser Client application Work Manager Services

User opens a work item openWorkItem [pageflow details, form details] WorkPresentation Service

startPageflow [page data]

Pageflow Service

Client invokes Forms Runtime Adapter to display form for first page User clicks Submit or Cancel button. Forms Runtime Adapter notifies client of the users action and returns data 3

updatePageFlow 4 [page data]

Pageflow Service

...if the user clicked Submit, repeat steps 3 and 4 until the pageflow has completed or is cancelled completeWorkItem or cancelWorkItem 6 [success]

WorkPresentation Service

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Form in a Pageflow 243

The following step-by-step descriptions correspond to the numbered steps in the diagram. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). When a user opens a work item from the user interface: 1. Call openWorkItem. Use the following items in the baseWorkRequest element to specify form-related inputs to the call: channelId specifies the presentation channel to which the client is bound. (If channelId is not specified, the default channel will be used.) channelType specifies the type of the channelId. responsePayloadMode specifies the format in which the work item data should be returned. This must be JSON. If the work item is associated with a pageflow (rather than a single form), the following items in the workResponse element contain the information needed to render each page of the pageflow: pageFlowDetail.page-activity.page-reference.formIdentifier identifies the JSON form artifact that is to be used to display the data for the first page. pageFlowDetail.page-activity identifies the JSON form artifact to be used to display the page data. For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.wp.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:baseWorkRequest> <resourceId>A2DF6C05-AECA-4D59-A553-A7D029920D51</resourceId> <channelId>openspaceGWTPull_DefaultChannel</channelId> <channelType>openspaceChannel</channelType> <responsePayloadMode>JSON</responsePayloadMode> <workItem id="14" version="-1"></workItem> </api:baseWorkRequest> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

244

| Chapter 9

Working With Forms

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <workResponse xmlns="http://api.wp.n2.tibco.com"> <payloadModel payloadMode="JSON" xmlns=""> <serializedPayload>{items:[]}</serializedPayload> </payloadModel> <workTypeDetail pilingLimit="0" typePiled="false" uid="WT__lgyB-MP5EeC3yLAVrheurQ" version="1.0.0.201108111305" xmlns=""> <dataModel/> </workTypeDetail> <presentation formIdenitifier="http://localhost:8080/bpm/" type="FORM" xmlns=""/> <workItem id="14" version="1" xmlns=""/> <pageFlowDetail id="_sFSQwMP5EeC3yLAVrheurQ" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" name="GetName" url="APH_WelcomeUsersImplementSolution/.bpm/.processOut/pageflow/aph_test.xpdl/G etName.bpel" xmlns=""> <page-activity id="_faDz8MP8EeC3yLAVrheurQ" name="ShowCustName" xmlns="http://service.archive.wp.n2.tibco.com"> <page-reference guid="" name="ShowCustName.gwt.json" version="1.0.0.201108111305"> <relative-path>1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aphMy Package/GetName/ShowCustName</relative-path> <base-path>http://localhost:8080/bpm</base-path> </page-reference> </page-activity> <page-activity id="_s1Q8MMP5EeC3yLAVrheurQ" name="getFirstName" xmlns="http://service.archive.wp.n2.tibco.com"> <page-reference guid="" name="getFirstName.gwt.json" version="1.0.0.201108111305"> <relative-path>1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aphMy Package/GetName/getFirstName</relative-path> <base-path>http://localhost:8080/bpm</base-path> </page-reference> </page-activity> <page-activity id="_tTg-cMP5EeC3yLAVrheurQ" name="getSecondName" xmlns="http://service.archive.wp.n2.tibco.com"> <page-reference guid="" name="getSecondName.gwt.json" version="1.0.0.201108111305"> <relative-path>1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aphMy Package/GetName/getSecondName</relative-path> <base-path>http://localhost:8080/bpm</base-path> </page-reference> </page-activity> </pageFlowDetail> </workResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Form in a Pageflow 245

2. Call startPageFlow to open the first page in the pageflow. Use the following items in the startPageFlow element to specify form-related inputs to the call: formalParams specifies any data that needs to be passed to the pageflow as formal parameters. You cannot determine which data fields are formal parameters programmatically. Instead, you must obtain this information directly from TIBCO Business Studio. responsePayloadMode specifies the format in which the page data should be returned. This must be JSON. When the startPageFlowResponse element is returned: executionState indicates if the pageflow contains further pages (IN_PROGRESS) or if this is the last page (COMPLETED). pageData.payload.serializedPayload contains the page data as a JSON payload. For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pag="http://pageflow.api.pfe.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <pag:startPageFlow> <pageFlowDefinition moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305"/> <responsePayloadMode>JSON</responsePayloadMode> </pag:startPageFlow> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

246

| Chapter 9

Working With Forms

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <startPageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305"/> <processReference> <id>pvm:0a10s</id> <name>GetName</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001gs.4" activityModelId="_s1Q8MMP5EeC3yLAVrheurQ" activityName="getFirstName" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" processName="GetName"/> <payload payloadMode="JSON"> <serializedPayload>{"items":[{"$param":"FirstName","$value":[],"type":"String"," mode":"INOUT"},{"$param":"SecondName","$value":[],"type":"String","mode":"INOUT" }]}</serializedPayload> </payload> </pageData> </pageResponse> </startPageFlowResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

3. Pass the page data and form details to the Forms Runtime Adapter, which renders the form and handles the users interaction with it. (See Rendering a TIBCO Business Studio Form.) When the user submits or cancels the form, the Forms Runtime Adapter notifies the client application that this has happened and returns the data from the form. 4. If the executionState returned by startPageFlow was IN_PROGRESS, call updatePageFlow to a) update the pageflow with any data added or changed by the user and b) open the next page in the pageflow. Use the following items in the updatePageFlow element to specify form-related inputs to the call: context.processReference.id specifies the pageflow process instance that is to be updated. This value can be obtained from the previous startPageFlowResponse element. context.activityReference.activityId specifies the pageflow activity that is to be updated. This value can be obtained from the

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Form in a Pageflow 247

pageData.pageReference.activityId item in the previous startPageFlowResponse element. pageFields contains the page data that is to be updated, as returned by the form. responsePayloadMode specifies the format in which the page data should be returned for the next page. This must be JSON. When the updatePageFlowResponse element is returned: executionState indicates if the pageflow contains further pages (IN_PROGRESS) or if this is the last page (COMPLETED). pageData.payload.serializedPayload contains the page data for the next page as a JSON payload. For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pag="http://pageflow.api.pfe.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <pag:updatePageFlow> <context> <processReference> <id>pvm:0a10s</id> </processReference> <activityReference activityId="pvm:001gs.4"/> </context> <pageFields payloadMode="JSON"> <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"S tring","mode":"INOUT"},{"$param":"SecondName","$value":["Durrel"],"type":"String ","mode":"INOUT"}]}</serializedPayload> </pageFields> <responsePayloadMode>JSON</responsePayloadMode> </pag:updatePageFlow> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

248

| Chapter 9

Working With Forms

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <updatePageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305"/> <processReference> <id>pvm:0a10s</id> <name>GetName</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001gs.5" activityModelId="_tTg-cMP5EeC3yLAVrheurQ" activityName="getSecondName" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" processName="GetName"/> <payload payloadMode="JSON"> <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"S tring","mode":"INOUT"},{"$param":"SecondName","$value":["Durrel"],"type":"String ","mode":"INOUT"}]}</serializedPayload> </payload> </pageData> </pageResponse> </updatePageFlowResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

5. Loop through steps 3 and 4, making further updatePageFlow calls until a COMPLETED executionState is returned.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Form in a Pageflow 249

For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pag="http://pageflow.api.pfe.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <pag:updatePageFlow> <context> <processReference> <id>pvm:0a10s</id> </processReference> <activityReference activityId="pvm:001gs.7"/> </context> <pageFields payloadMode="JSON"> <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"S tring","mode":"INOUT"},{"$param":"SecondName","$value":["Fisher"],"type":"String ","mode":"INOUT"}]}</serializedPayload> </pageFields> <responsePayloadMode>JSON</responsePayloadMode> </pag:updatePageFlow> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <updatePageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <pageResponse executionState="COMPLETED" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305"/> <processReference> <id>pvm:0a10s</id> <name>GetName</name> </processReference> </context> <pageData> <payload payloadMode="JSON"> <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"S tring","mode":"INOUT"},{"$param":"SecondName","$value":["Fisher"],"type":"String ","mode":"INOUT"}]}</serializedPayload> </payload> </pageData> </pageResponse> </updatePageFlowResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

250

| Chapter 9

Working With Forms

6. Call completeWorkItem to complete the pageflows parent work item. In the workRequest element, use payloadDetails to pass the final state of the pageflow data back to the work item. (If the pageflow was cancelled, call cancelPageFlow and then cancelWorkItem instead.) For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.wp.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:workRequest> <resourceId>A2DF6C05-AECA-4D59-A553-A7D029920D51</resourceId> <channelId>openspaceGWTPull_DefaultChannel</channelId> <channelType>openspaceChannel</channelType> <responsePayloadMode>JSON</responsePayloadMode> <workItem id="14" version="-1"></workItem> <payloadDetails payloadMode="JSON"> <serializedPayload>{"items":[{"$param":"FirstName","$value":["Gerald"],"type":"S tring","mode":"INOUT"},{"$param":"SecondName","$value":["Fisher"],"type":"String ","mode":"INOUT"}]}</serializedPayload> </payloadDetails> </api:workRequest> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <workResponse isSuccessful="true" xmlns="http://api.wp.n2.tibco.com"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Form in a Business Service 251

Displaying a Form in a Business Service

The following diagram shows the sequence of calls a client application should make to display a form in a business service. (See Starting a Business Service on page 260 for more information about starting a business service.)
Browser Client application User starts a business service startBusinessService 1 [page data] getBusinessService DetailsByModule [form details] BusinessService Service Work Manager Services

WorkPresentation Service

Client invokes Forms Runtime Adapter to display form for first page User clicks Submit or Cancel button. Forms Runtime Adapter notifies client of the users action and submits data 3

updateBusinessService 4 [page data]

BusinessService Service

...if the user clicked Submit, repeat steps 3 and 4 until the business service has completed or is cancelled

The following step-by-step descriptions correspond to the numbered steps in the diagram. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP).

TIBCO ActiveMatrix BPM - BPM Developers Guide

252

| Chapter 9

Working With Forms

When a user starts a business service from the user interface: 1. Call startBusinessService to obtain the page data for the first page in the business service. Use the following items in the startBusinessService element to specify form-related inputs to the call: formalParams specifies any data that needs to be passed to the business service as formal parameters. You cannot determine which data fields are formal parameters programmatically. Instead, you must obtain this information directly from TIBCO Business Studio. responsePayloadMode specifies the format in which the page data should be returned. This must be JSON. When the startBusinessServiceResponse element is returned: executionState indicates if the business service contains further pages (IN_PROGRESS) or if this is the only page (COMPLETED). pageData.payload.serializedPayload contains the page data as a JSON payload For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <bus:startBusinessService> <businessServiceDefinition moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="aphStartProc" version="1.0.0.201108111305"/> <responsePayloadMode>JSON</responsePayloadMode> </bus:startBusinessService> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Form in a Business Service 253

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <startBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="aphStartProc" version="1.0.0.201108111305"/> <processReference> <id>pvm:0a1012</id> <name>aphStartProc</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g12.3" activityModelId="_9IfurcQDEeC3yLAVrheurQ" activityName="UserTask" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" processName="aphStartProc"/> <payload payloadMode="JSON"> <serializedPayload>{"items":[{"$param":"UserName","$value":[],"type":"String","m ode":"INOUT"},{"$param":"PhoneNumber","$value":[],"type":"String","mode":"INOUT" }]}</serializedPayload> </payload> </pageData> </pageResponse> </startBusinessServiceResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

2. Call getBusinessServiceDetailsByModule to get the details of the forms used by the page activity in the business service. The page-activity.page-reference element in the businessServiceDetailsResponse identifies the JSON form artifact to be used to display the page data for each page in the business service. For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.wp.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:businessServiceDetailsRequest> <moduleName>/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl</moduleName> <processName>aphStartProc</processName> </api:businessServiceDetailsRequest> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

254

| Chapter 9

Working With Forms

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <businessServiceDetailsResponse id="_86Cb0MQDEeC3yLAVrheurQ" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" moduleVersion="1.0.0.201108111305" name="aphStartProc" url="APH_WelcomeUsersImplementSolution/.bpm/.processOut/pageflow/aph_test.xpdl/a phStartProc.bpel" xmlns="http://api.wp.n2.tibco.com"> <page-activity id="_9IfurcQDEeC3yLAVrheurQ" name="UserTask" xmlns="http://service.archive.wp.n2.tibco.com"> <page-reference guid="" name="UserTask.gwt.json" version="1.0.0.201108111305"> <relative-path>1.0.0.201108111305/openspaceGWTPull_DefaultChannel/.default/aphMy Package/aphStartProc/UserTask</relative-path> <base-path>http://localhost:8080/bpm</base-path> </page-reference> </page-activity> </businessServiceDetailsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

3. Pass the page data and form details to the Forms Runtime Adapter, which renders the form and handles the users interaction with it. (See Rendering a TIBCO Business Studio Form.) When the user submits or cancels the form, the Forms Runtime Adapter notifies the client application that this has happened and returns the data from the form. 4. If the executionState returned by startBusinessService was IN_PROGRESS, call updateBusinessService to a) update the business service with any data added or changed by the user and b) open the next page in the business service. Use the following items in the updateBusinessService element to specify form-related inputs to the call: context.processReference.id specifies the business service (pageflow) process instance that is to be updated. This value can be obtained from the previous startBusinessServiceResponse element. context.activityReference.activityId specifies the business service activity that is to be updated. This value can be obtained from the pageData.pageReference.activityId item in the previous startBusinessServiceResponse element. pageFields contains the page data that is to be updated, as returned by the form. responsePayloadMode specifies the format in which the page data should be returned for the next page. This must be JSON.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Form in a Business Service 255

When the updateBusinessServiceResponse element is returned: executionState indicates if the business service contains further pages (IN_PROGRESS) or if this is the last page (COMPLETED). pageData.payload.serializedPayload contains the page data for the next page as a JSON payload. 5. Loop through steps 3 and 4, making further updateBusinessService calls until a COMPLETED executionState is returned. For example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <bus:updateBusinessService> <context> <processReference> <id>pvm:0a10t</id> </processReference> <activityReference activityId="pvm:001gt.3"/> </context> <responsePayloadMode>JSON</responsePayloadMode> </bus:updateBusinessService> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <updateBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="COMPLETED" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="aphStartProc" version="1.0.0.201108111305"/> <processReference> <id>pvm:0a10t</id> <name>aphStartProc</name> </processReference> </context> <pageData> <payload payloadMode="JSON"> <serializedPayload>{"items":[]}</serializedPayload> </payload> </pageData> </pageResponse> </updateBusinessServiceResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

256

| Chapter 9

Working With Forms

Using Custom Forms

Development and use of custom forms is entirely the responsibility of the client application. The same principles apply as for using TIBCO Business Studio forms, but you should note the following items.

Presentation Details
You should use the WorkPresentationService, PageFlowService and BusinessService APIs to display forms for work items and pageflow/business service page activities, but: ignore all elements concerned with presentation channel artifacts, as these can only be used to display TIBCO Business Studio forms. you cannot use the presentation details returned by openWorkItem when Displaying a Work Item Form or Displaying a Form in a Pageflow. you do not need to call getBusinessServiceDetailsByModule when Displaying a Form in a Business Service (as this will simply return presentation data that you cannot use).

Data Format and Structures

You should use XML instead of JSON as the data payload format. (The JSON returned by the BPM runtime is tailored for use with the Forms Runtime Adapter.) Your application must interpret and render the XML data payloads returned by the BPM runtime, which will require knowledge of their underlying data structures. You cannot obtain this information programmatically. Instead, you must obtain it from TIBCO Business Studio: Export a Work Data Model for every project that the client application will need to handle. This model contains a number of artifacts, including: a work type definition file (wt.xml), which defines the data structures of all work types used in the project. (Each user activity in a business process has a work type associated with it.) a pageflow activity definition file (pfActivityType.xml), which defines the data structure for each user activity in a pageflow process in the project. For more information about how to generate a Work Data Model, see "Exporting Projects to a Work Data Model" in TIBCO Business Studio Process Modeling.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Custom Forms 257

Note any formal parameters required by business processes or pageflow processes. When you start or inject data into a pageflow process or business service that requires formal parameters, you must specify the data for those formal parameters. (See the following element definitions: startPageFlow, injectPageFlowEvent, startBusinessService, injectBusinessServiceEvent.)

TIBCO ActiveMatrix BPM - BPM Developers Guide

258

| Chapter 9

Working With Forms

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 259
Chapter 10

Working With Business Services

This chapter describes the web service operations that allow you to carry out the functions listed in the topics below.

Topics
Starting a Business Service, page 260 Displaying a Form in a Business Service, page 269 Injecting a Business Service Event, page 270

TIBCO ActiveMatrix BPM - BPM Developers Guide

260

| Chapter 10

Working With Business Services

Starting a Business Service

Starting a business service involves listing all the available business services and then selecting a business service to start. The following diagram shows an example of how calls to the Work Manager Services API can be used to start and update a business service. Figure 16 Starting a Business Service
Browser Client application listCategories [categories] 1 Display categories User clicks ProcessPackage folder 2 Display child categories and business services in ProcessPackage folder User clicks a Business Service 3 Display details of the selected business service: name, version, module, category User starts a business service PageFlowEngine Service

Business Service

queryBusinessServices (ProcessPackage) [businessCategories]

Business Service

startBusinessService (moduleName, processName, and version) [executionState, process ID, activity ID, and the payload] getBusinessService DetailsByModule (moduleName, processName, and moduleVersion) [form details such as PageReference, FormIDentifier]

Business Service

WorkPresentation Service

Displays Form to user, if any User enters values in the Form fields and clicks Submit

updateBusinessService (process ID, activity ID, payload ) [executionState, process ID, activity ID, and the payload]

Business Service

TIBCO ActiveMatrix BPM - BPM Developers Guide

Starting a Business Service 261

The following step-by-step descriptions correspond to the numbered steps in the illustration above. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). (For an equivalent example using the Service Connector API (Java), see Starting a Business Service Service Connector API Example (Java) on page 266.) 1. When you login to a client, for example TIBCO Openspace, listCategories is called and all the available categories are listed in the Business Services tab. 2. When the user clicks on a category, queryBusinessServices is called and all the business services under the selected category are displayed. The response contains the details of all the business services under the selected category.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <bus:queryBusinessServices> <category>PageflowSolution/ProcessPackage</category> </bus:queryBusinessServices> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryBusinessServicesResponse xmlns="http://business.api.busserv.n2.tibco.com"> <businessServiceTemplate hasFormalParameters="false" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestCall" version="1.0.0.201108111516" xmlns=""/> </queryBusinessServicesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

3. Selecting a business service displays the details of that business service on the client, which are obtained from the response message of the queryBusinessServices call. 4. When the user clicks the button to start a new instance of business service, it calls the startBusinessService and passes the parameters module name, process name, and version number. The values for these parameters can be obtained by calling queryBusinessServices or listBusinessServices.

TIBCO ActiveMatrix BPM - BPM Developers Guide

262

| Chapter 10

Working With Business Services

The response returns the execution state, process ID, activity ID, and the payload.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com"> <soapenv:Header/> <Soapenv:Body> <bus:startBusinessService> <businessServiceDefinition moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestCall" version="1.0.0.201108111516"/> <responsePayloadMode>XML</responsePayloadMode> </bus:startBusinessService> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Starting a Business Service 263

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <startBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestCall" version="1.0.0.201108111516"/> <processReference> <id>pvm:0a101v</id> <name>RequestCall</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g1v.3" activityModelId="_qTxqOlnREd-qRKl4nKSPqA" activityName="CollectData" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" moduleVersion="1.0.0.201108111516" processName="RequestCall"/> <payload payloadMode="XML"> <XmlPayload> <inouts array="false" name="UserName" optional="true" type="String"> <simpleSpec/> </inouts> <inouts array="false" name="PhoneNumber" optional="true" type="String"> <simpleSpec/> </inouts> </XmlPayload> </payload> </pageData> </pageResponse> </startBusinessServiceResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

5. If the business service has a form associated with it, the operation getBusinessServiceDetailsByModule is called. The response contains the form details, which are then passed on to the Forms Adapter. 6. The Forms Adapter parses the data and displays an appropriate Form to the end user. Similarly, any input provided in the form is processed by the Form Adapter and handed back to the servlet.

TIBCO ActiveMatrix BPM - BPM Developers Guide

264

| Chapter 10

Working With Business Services

For details about how the data is passed to and received from the Forms Adapter, see Working With Forms. See TIBCO Business Studio Forms Users Guide for details about the TIBCO Forms APIs. 7. Once the user enters values in the Forms fields and clicks submit, updateBusinessService is called with the payload containing the values entered by the and user. Repeat steps 5 and 6 until the business service completes or is cancelled. The response returns the execution state, process ID, activity ID, and the payload. If the business service is complete, the execution state is COMPLETED.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <bus:updateBusinessService> <context> <processReference> <id>pvm:0a101v</id> </processReference> <activityReference activityId="pvm:001g1v.3"/> </context> <pageFields payloadMode="XML"> <XmlPayload> <inouts array="false" name="UserName" optional="true" type="String"> <simpleSpec> <value>TIB_USER1</value> </simpleSpec> </inouts> <inouts array="false" name="PhoneNumber" optional="true" type="String"> <simpleSpec> <value>987654321</value> </simpleSpec> </inouts> </XmlPayload> </pageFields> <responsePayloadMode>XML</responsePayloadMode> </bus:updateBusinessService> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Starting a Business Service 265

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <updateBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="COMPLETED" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestCall" version="1.0.0.201108111516"/> <processReference> <id>pvm:0a101v</id> <name>RequestCall</name> </processReference> </context> <pageData> <payload payloadMode="XML"> <XmlPayload xmlns:bus="http://business.api.busserv.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <inouts array="false" name="UserName" optional="true" type="String"> <simpleSpec> <value>TIB_USER1</value> </simpleSpec> </inouts> <inouts array="false" name="PhoneNumber" optional="true" type="String"> <simpleSpec> <value>987654321</value> </simpleSpec> </inouts> </XmlPayload> </payload> </pageData> </pageResponse> </updateBusinessServiceResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

266

| Chapter 10

Working With Business Services

Starting a Business Service Service Connector API Example (Java) The following example code illustrates starting a business service using the method calls available in the Service Connector API. The step numbers in the comments correspond to the steps in the illustration Starting a Business Service on page 260.
private void startBusinessServiceExample() { try { // Get all the business service categories that are available ListCategoriesResponse categories = serviceConnectorInstance.getBusinessService().listCategories( Long.valueOf(0), Long.valueOf(0), true, null, true, null); // Step 1: For this example we will pick the first category if (categories.getCategoryArray() != null && categories.getCategoryArray().length > 0) { // Query the business services for a particular category ( and all child categories by adding "/**" ) QueryBusinessServicesResponse response = serviceConnectorInstance.getBusinessService() .queryBusinessServices(categories.getCategoryArray(0).getName() + "/**", null, true); if (response.getBusinessServiceTemplateArray() != null && response.getBusinessServiceTemplateArray().length > 0) { // Get the first business service for the category BusinessServiceTemplate template = response.getBusinessServiceTemplateArray(0); // Step 2: Start the first business service StartBusinessServiceResponse startResponse = serviceConnectorInstance.getBusinessService() .startBusinessService(template, null, PayloadModeType.XML, Long.valueOf(0)); // Now we would use the forms API to open the Business Service and allow users to enter data // After form processing is complete update the business service with the new data // Build up a request context for the update call RequestContext requestContext = RequestContext.Factory.newInstance(); // We need a Process Reference for the context ProcessReference ref = ProcessReference.Factory.newInstance();

TIBCO ActiveMatrix BPM - BPM Developers Guide

Starting a Business Service 267

ref.setId(startResponse.getPageResponse().getContext().getProcessR eference().getId()); // We also need an Activity Reference for the context // For this example we will update the first activity in the business service ActivityReference actRef = ActivityReference.Factory.newInstance(); actRef.setActivityId(startResponse.getPageResponse().getPageDataAr ray(0).getPageReference() .getActivityId()); actRef.setActivityModelId(startResponse.getPageResponse().getPageD ataArray(0).getPageReference() .getActivityModelId()); actRef.setActivityName(startResponse.getPageResponse().getPageData Array(0).getPageReference() .getActivityName()); actRef.setModuleName(startResponse.getPageResponse().getPageDataAr ray(0).getPageReference() .getModuleName()); actRef.setModuleVersion(startResponse.getPageResponse().getPageDat aArray(0).getPageReference() .getModuleVersion()); actRef.setProcessName(startResponse.getPageResponse().getPageDataA rray(0).getPageReference() .getProcessName()); // update the request context with the Process Reference and Activity Reference requestContext.setProcessReference(ref); requestContext.setActivityReference(actRef); // setup the data payload with the new business service data, normally we would get this back when the form is closed or submitted DataPayload payload = DataPayload.Factory.newInstance(); payload.setPayloadMode(PayloadModeType.JSON); payload.setSerializedPayload(""); // Step 3: Update the business service UpdateBusinessServiceResponse updateResponse = this.serviceConnectorInstance.getBusinessService() .updateBusinessService(requestContext, null, PayloadModeType.XML); print(updateResponse); } } } catch (com.tibco.n2.busserv.services.InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace();

TIBCO ActiveMatrix BPM - BPM Developers Guide

268

| Chapter 10

Working With Business Services

} catch (com.tibco.n2.busserv.services.InvalidArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (com.tibco.n2.busserv.services.PageFlowExecutionFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

Displaying a Form in a Business Service 269

Displaying a Form in a Business Service

For step-by-step descriptions of the calls that a client application needs to make to display a form when starting a business service, see Displaying a Form in a Business Service on page 251.

TIBCO ActiveMatrix BPM - BPM Developers Guide

270

| Chapter 10

Working With Business Services

Injecting a Business Service Event

You can inject data to a business service multiple times while it is in progress, regardless of whether the flow from any previous occurrence is still in progress. You can use an event handler to do so. An event handler is a catch intermediate event with no specific trigger and incoming flow that can be triggered by an external client application using the BPM API. Note that the event handler does not have to happen for the business service to complete. The example here illustrates injecting a business service event. It involves listing all the deployed business services, starting a business service, and while it is running, injecting a business event. Figure 17 Injecting a Business Service Event
Client application listBusinessServices listBusinessServicesResponse List of business services startBusinessService 2 startBusinessServiceResponse Returns the process ID, activity ID, and the payload along with the execution status injectBusinessServiceEvent 3 injectBusinessServiceEventResponse Returns the complete details of the injected business service instance PageFlowEngine Service

The following step-by-step descriptions correspond to the numbered steps in the illustration above. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP). (For an equivalent example using the Service Connector API (Java), see Injecting a Business Service Event Service Connector API Example (Java) on page 275.) 1. Find out the list of deployed business services by calling the listBusinessServices operation. This operation returns the module version

TIBCO ActiveMatrix BPM - BPM Developers Guide

Injecting a Business Service Event 271

number, which is required as an input when calling the startBusinessService operation.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <bus:listBusinessServices getTotalCount="true" numberOfItems="10" startPosition="0"> <!--Optional:--> <includeFormalParameters>true</includeFormalParameters> </bus:listBusinessServices> </soapenv:Body> </soapenv:Envelope <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listBusinessServicesResponse xmlns="http://business.api.busserv.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <totalItems xmlns="">1</totalItems> <businessCategory name="EventHandler" xmlns=""> <ChildBusinessCategory name="EventHandler"> <BusinessServiceTemplate hasFormalParameters="true" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108111140"/> <BusinessServiceTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="dummyprocess" version="1.0.0.201108111140"/> </ChildBusinessCategory> </businessCategory> </listBusinessServicesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

2. You can choose to start one of the business services returned in Step 1. Call the startBusinessService operation and specify the parameters module name and process name to start the selected business service. This operation returns the

TIBCO ActiveMatrix BPM - BPM Developers Guide

272

| Chapter 10

Working With Business Services

instance ID which is required for the next step, injecting a business service event.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <bus:startBusinessService> <businessServiceDefinition moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108161235"/> <responsePayloadMode>XML</responsePayloadMode> </bus:startBusinessService> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <startBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108161235"/> <processReference> <id>pvm:0a1022</id> <name>EventHandlerProcess</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g22.8" activityModelId="_NeC_EL0REeCCNPLAO2IuzQ" activityName="UserTask" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" moduleVersion="1.0.0.201108161235" processName="EventHandlerProcess"/> <payload payloadMode="XML"> <XmlPayload> <inouts array="false" name="Field" optional="true" type="String"> <simpleSpec/> </inouts> </XmlPayload> </payload> </pageData> </pageResponse> </startBusinessServiceResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Injecting a Business Service Event 273

3. While the business service is running, you can inject a business service event using the injectBusinessServiceEvent operation. The request message requires you to provide the following parameters: moduleName, processName, eventName, processInstanceId (optional), formal parameters, payload, and optionally, the responsePayloadMode. This operation updates the value of the specified parameter(s) with the value(s) injected by the intermediate event.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://business.api.busserv.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <bus:injectBusinessServiceEvent> <eventDefinition moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" eventName="ReceiveINOUT" processInstanceId="pvm:0a1022"/> <formalParams payloadMode="XML"> <XmlPayload> <inouts array="false" name="Parameter9" optional="false" type="String"> <simpleSpec length="50"> <value>TIBCO Software</value> </simpleSpec> </inouts> </XmlPayload> </formalParams> <responsePayloadMode>XML</responsePayloadMode> </bus:injectBusinessServiceEvent> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

274

| Chapter 10

Working With Business Services

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <injectBusinessServiceEventResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108161235"/> <processReference> <id>pvm:0a1022</id> <name>EventHandlerProcess</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g22.d" activityModelId="_agO3UL6jEeCKPY5rB9JBjQ" activityName="UserTask5" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" moduleVersion="1.0.0.201108161235" processName="EventHandlerProcess"/> <payload payloadMode="XML"> <XmlPayload> <inouts array="false" name="Parameter9" optional="true" type="String"> <simpleSpec> <value>[Ljava.lang.String;@73e1829d</value> </simpleSpec> </inouts> </XmlPayload> </payload> </pageData> </pageResponse> </injectBusinessServiceEventResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

Injecting a Business Service Event 275

Injecting a Business Service Event Service Connector API Example (Java) The following example code illustrates creating an LDAP container using method calls available in the Service Connector API. The step numbers in the comments correspond to the steps in the illustration Injecting a Business Service Event on page 270. private void injectBusinessServiceEventExample()
{ try { // Step 1: List the available business services ListBusinessServicesResponse businessServicesList = serviceConnectorInstance.getBusinessService() .listBusinessServices(Long.valueOf(0), Long.valueOf(0), true, null, true, null); print(businessServicesList); // Step 2: Start the business service // First we setup a BusinessServiceTemplate with details of the service to start // Normally these would be retrieved by parsing the businessServicesList returned from the listBusinessServices call, // in this example we are hard-coding the value BusinessServiceTemplate template = BusinessServiceTemplate.Factory.newInstance(); template.setModuleName("/TestBS/Process Packages/ProcessPackage.xpdl"); template.setProcessName("CatchEventBS"); template.setVersion("1.0.0.201108111511"); // Start the service StartBusinessServiceResponse startResponse = serviceConnectorInstance.getBusinessService() .startBusinessService(template, null, PayloadModeType.XML, Long.valueOf(0)); // Step 3: Inject the event // First we setup an event containing the business service details and the name of the event EventDefinitionType event = EventDefinitionType.Factory.newInstance(); // Details of business service event.setModuleName(template.getModuleName()); event.setProcessName(template.getProcessName()); // Name of the event event.setEventName("IntermediateEvent");

TIBCO ActiveMatrix BPM - BPM Developers Guide

276

| Chapter 10

Working With Business Services

// The ID of the service we just started event.setProcessInstanceId(startResponse.getPageResponse().getCont ext().getProcessReference().getId()); // Now we need to setup the data to inject into the event the data is contained in a DataPayload DataPayload payload = DataPayload.Factory.newInstance(); payload.setPayloadMode(PayloadModeType.XML); // The DataModel contains FieldType values for each parameter we are passing DataModel model = DataModel.Factory.newInstance(); // Add a new In/Out field type and set its name, the parameter name is defined in the service in Business Studio FieldType field = model.addNewInouts(); field.setName("Parameter"); // For the field we must set the simple value, in this case it is a simple field type SimpleSpec simpleSpec = field.addNewSimpleSpec(); XmlString value = simpleSpec.addNewValue(); value.setStringValue("Example Value"); // Add the DataModel to the DataPayload payload.setXmlPayload(model); // Now we inject the event passing the event details, the data payload and the respose feed type InjectBusinessServiceEventResponse injectResponse = serviceConnectorInstance.getBusinessService() .injectBusinessServiceEvent(event, payload, PayloadModeType.XML); } catch (InternalServiceFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (InvalidArgumentFault e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (PageFlowExecutionFault e) { // TODO Auto-generated catch block e.printStackTrace(); } }

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 277
Chapter 11

Working With Pageflows

This chapter describes the web service operations that allow you to carry out the functions listed in the topics below.

Topics
Starting and Processing a Pageflow, page 278 Injecting a Pageflow Event, page 279

TIBCO ActiveMatrix BPM - BPM Developers Guide

278

| Chapter 11

Working With Pageflows

Starting and Processing a Pageflow

For step-by-step descriptions of the calls that a client application needs to make to start and process a pageflow, including displaying a form, see Displaying a Form in a Pageflow on page 242. Also note that you can configure the Pageflow Engine for optimum pageflow performance; for more information, see the PFEConfig.properties file in the "BPM Properties Files" section of the TIBCO ActiveMatrix BPM - BPM Administration guide.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Injecting a Pageflow Event 279

Injecting a Pageflow Event

You can inject data into a pageflow process multiple times while it is in progress, regardless of whether the flow from any previous occurrence is still in progress. You can use an event handler to do so. An event handler is a catch intermediate event with no specific trigger and incoming flow that can be triggered by an external client application using the BPM API. Note that the event handler does not have to happen for the pageflow process to complete. You can update a pageflow local data cache using an event handler. For example, an event handler updates the exchange rate information regularly. A pageflow process used to manage an order request can use the updated exchange rate information when issuing an invoice. The example here illustrates injecting a pageflow event. It involves listing all the deployed pageflows, starting a pageflow, and while it is running, injecting a pageflow event. Figure 18 Injecting a Pageflow Event
Client application listPageFlows listPageFlowsResponse
List of pageflows

PageFlowEngine Service

startPageFlow 2 startPageFlowResponse Returns the process ID, activity ID, and the payload along with the execution status injectPageFlowEvent 3 injectPageFlowEventResponse Returns the complete details of the injected pageflow instance

The following step-by-step descriptions correspond to the numbered steps in the illustration above. Note that the descriptions are from a web service operation point of view, and provide an example of performing the operations using the web service API (SOAP).

TIBCO ActiveMatrix BPM - BPM Developers Guide

280

| Chapter 11

Working With Pageflows

1. Find out the list of deployed pageflows by calling the listPageFlows operation. This operation returns the module version number, which is required as an input when calling the startPageFlow operation.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pag="http://pageflow.api.pfe.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <pag:listPageFlows startPosition="0" numberOfItems="10" getTotalCount="true"> <includeFormalParameters>true</includeFormalParameters> </pag:listPageFlows> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listPageFlowsResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <totalItems xmlns="">3</totalItems> <pageFlowTemplate hasFormalParameters="true" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestAdditionalDataPageflow" version="1.0.0.201108111516" xmlns=""/> <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305" xmlns=""/> <pageFlowTemplate hasFormalParameters="true" moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" processName="ProcessPackageProcess" version="1.0.0.201108161050" xmlns=""/> </listPageFlowsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

2. You can choose to start one of the pageflows returned in Step 1. Call the startPageFlow operation and specify the parameters module name and

TIBCO ActiveMatrix BPM - BPM Developers Guide

Injecting a Pageflow Event 281

process name to start the selected pageflow. This operation returns the instance ID, which is required for the next step, injecting a pageflow event.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pag="http://pageflow.api.pfe.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <pag:startPageFlow> <pageFlowDefinition moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" processName="ProcessPackageProcess" version="1.0.0.201108161050"/> <formalParams payloadMode="XML"> <XmlPayload> <inputs name="Names" type="Text" optional="true" array="false"> <simpleSpec length="50"> <value>TIBCO</value> </simpleSpec> </inputs> </XmlPayload> </formalParams> <responsePayloadMode>XML</responsePayloadMode> </pag:startPageFlow> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

282

| Chapter 11

Working With Pageflows

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <startPageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" processName="ProcessPackageProcess" version="1.0.0.201108161050"/> <processReference> <id>pvm:0a101f</id> <name>ProcessPackageProcess</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g1f.5" activityModelId="_VK4SIKh8EeCt2PSB39ZXYA" activityName="UserTasks" moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" moduleVersion="1.0.0.201108161050" processName="ProcessPackageProcess"/> <payload payloadMode="XML"> <XmlPayload/> </payload> </pageData> </pageResponse> </startPageFlowResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

3. While the pageflow is running, you can inject a pageflow event using the injectPageFlowEvent operation. The request message requires you to provide the following parameters: moduleName, processName, eventName, processInstanceId (optional), formal parameters, payload, and optionally,

TIBCO ActiveMatrix BPM - BPM Developers Guide

Injecting a Pageflow Event 283

the responsePayloadMode. This operation updates the value of the specified parameter(s) with the value(s) injected by the intermediate event.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pag="http://pageflow.api.pfe.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <pag:injectPageFlowEvent> <eventDefinition moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess2" eventName="IntermediateEvent" processInstanceId="pvm:0a101u"/> <formalParams payloadMode="XML"> <XmlPayload> <inputs array="false" name="Parameter" optional="false" type="String"> <simpleSpec length="50"> <!--Zero or more repetitions:--> <value>TIBX</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter2" optional="false" type="Integer Number"> <simpleSpec length="9"> <!--Zero or more repetitions:--> <value>147</value> </simpleSpec> </inputs> </XmlPayload> </formalParams> </pag:injectPageFlowEvent> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

284

| Chapter 11

Working With Pageflows

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <injectPageFlowEventResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess2" version="1.0.0.201108161235"/> <processReference> <id>pvm:0a101u</id> <name>EventHandlerProcess2</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g1u.9" activityModelId="_eMANL720EeC61dgFHyHHpQ" activityName="UserTask3" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" moduleVersion="1.0.0.201108161235" processName="EventHandlerProcess2"/> <payload payloadMode="XML"> <XmlPayload> <inputs array="false" name="Parameter" optional="true" type="String"> <simpleSpec> <value>[Ljava.lang.String;@2818fe57</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter2" optional="true" type="Integer Number"> <simpleSpec> <value>[Ljava.lang.String;@e21652</value> </simpleSpec> </inputs> <inouts array="false" name="Field" optional="true" type="String"> <simpleSpec/> </inouts> </XmlPayload> </payload> </pageData> </pageResponse> </injectPageFlowEventResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 285
Chapter 12

Working with Events

This chapter provides information about using the Event Collection Services API.

Topics
Executing a Query, page 286 Defining Query Filter Strings, page 289 Using Attributes in Query Filters, page 293 Example Queries, page 315 Event Measures, page 316

TIBCO ActiveMatrix BPM - BPM Developers Guide

286

| Chapter 12

Working with Events

Executing a Query
Queries can be executed as either dynamic or registered queries: Dynamic query: A query object is passed in at execution time, where it is parsed and executed by Event Collector. This approach is recommended for queries which are either performed infrequently, or which change often when called, because the filter expression has to be parsed whenever the query is run. Registered query: A query object is defined and registered with Event Collector, at which point it is parsed and stored. Whenever the query is subsequently called, a reference is made to the passed query, which improves efficiency both in data transport and in parsing costs. This approach is recommended for queries which are performed repeatedly over a period of time, because the filter expression only needs to be parsed once, but can be run many times. The target option specified in a query (in the Query object) defines the Event Collector database table against which the query will execute, which in turn determines the type of information to be retrieved. See Using Attributes in Query Filters on page 293 for more information.

Dynamic Queries
The following diagram shows how to execute a dynamic query.
Client Application Query Object EventCollector QueryService

new()
1

setFilter()

executeGenericQuery(Query, QueryOptions)

The client application does the following: 1. It instantiates a query object, which defines the filter expression and the list of attributes that are to be returned.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Executing a Query 287

2. It performs an executeGenericQuery operation, which returns the list of events matching the filter criteria. The requested attributes and values are returned for each event. The executeQuery operation has been deprecated and should no longer be used. Use the executeGenericQuery operation instead. The executeRegisteredQuery operation has been deprecated and should no longer be used. Use the executeRegisteredGenericQuery operation instead.

Registered Queries
The following diagram shows how to create and use a registered query.

Client Application

Query Object

EventCollector QueryService

new()
1

setFilter()

isQueryRegistered(QueryIdentifier)
2

registerQuery()

Loop
3

executeRegisteredGenericQuery (QueryIdentifier,QueryOptions)

unRegisterQuery(QueryIdentifier)

The client application does the following: 1. It instantiates a query object, which defines the filter expression and the list of attributes that are to be returned. 2. It uses isQueryRegistered to determine if the query is already registered, and if not, it calls the registerQuery operation to register the query, using the defined query object. Event Collector parses and stores the query for later use.
TIBCO ActiveMatrix BPM - BPM Developers Guide

288

| Chapter 12

Working with Events

3. It performs an executeRegisteredGenericQuery operation each time the query is needed. QueryOptions can be used to dynamically alter the query parameters without having to alter and re-register the query itself. (See Using Late-Bound Parameter Literals on page 291.) The operation returns the list of events matching the filter criteria. The requested attributes and values are returned for each event. The executeRegisteredQuery operation has been deprecated and should no longer be used. Use the executeRegisteredGenericQuery operation instead. The QueryIdentifier can identify the query using either its descriptive name (tag) or its GUID. Performance is improved when using GUID, so when calling a query many times it is recommended to look up the querys GUID using the lookupQueryByTag operation. 4. It performs an unRegisterQuery operation to remove the query when it is no longer needed. This removes the query from the Event Collector database table.

Correlated Events
When a query is executed with the executeGenericQuery operation, or registered with the registerQuery operation, the correlate parameter can be used to request that the query return not only the events that match the query, but also all correlated events. Correlated events are those in which the CorrelationId is the sameevents with the same CorrelationId are all part of the same service call. This ability to return correlated events allows you to see all events that have been triggered within a service call. Note, however, that this can cause a large amount of data to be returneduse it only when necessary.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Defining Query Filter Strings 289

Defining Query Filter Strings

The following EventCollectorQueryService operations can include an expression defining filter criteria to be applied to the query: executeGenericQuery (Request message) - Execute the specified query against the Event Collector database. registerQuery (Request message) - Register a query with Event Collector, so that it can be subsequently executed using the executeRegisteredGenericQuery operation.

The following sections describe how to define this filter expression.

Filter Expression Format

The filter expression must use the following syntax:
(operand operator operand [ operator operand... ])

All queries must be supplied on a single line. All non-quoted whitespace will be ignored.

Operands
The following table lists the supported operands. Operand Type Attribute name Syntax
name

Description The name of an attribute - see Using Attributes in Query Filters on page 293 for more information. A string literal to be used for comparison. See Using String Literals on page 290 for more information.

String literal

string str?ng str*ng str\?ng str\\ng

Integer literal Boolean literal

12345 TRUE

A numeric literal A boolean literal

or FALSE

TIBCO ActiveMatrix BPM - BPM Developers Guide

290

| Chapter 12

Working with Events

Operand Type DateTime literal

Syntax
YYYY-MM-DDThh:mm:ss.SSS

Description A date-time literal consisting of the relevant components. For ranges, a curly bracket indicates an exclusive value; a square bracket indicates an inclusive value. See Using DateTime Literals on page 290 for more information.

or for a range:
{|[YYYY-MM-DDThh:mm:ss.SSS, YYYY-MM-DDThh:mm:ss.SSS}!]

A query Late-bound parameter literal

(query)

A sub query to be evaluated before the main query A value which will be late bound to the expression. See Using Late-Bound Parameter Literals on page 291 for more information

::name

Using String Literals A string literal can be used to match strings. The following wildcards can be used: ? matches any single character * matches any number of characters.

Wildcards can be escaped using the \ character. For example, the literal my\?text will match the string my?text. Escape characters can be escaped using \\ characters. For example, the literal my\\text will match the string my\text. Using DateTime Literals A DateTime literal allows creation of an arbitrary DateTime which will be matched against any DateTime format AttributeValue. To allow for greater variety of matching, the following DateTime variations can be used:
YYYY[timzone] YYYY-MM[timzone] YYYY-MM-DD[timzone] YYYY-MM-DDTHhh[timzone] YYYY-MM-DDTHhh:mm[timzone] YYYY-MM-DDTHhh:mm:ss[timzone] YYYY-MM-DDTHhh:mm:ss.SSS[timzone]

TIBCO ActiveMatrix BPM - BPM Developers Guide

Defining Query Filter Strings 291

Timezones
timezone is optional, and can be specified as shown in the following table.

Syntax
Z +|-HH[:MM]

Description Coordinated Universal Time (UTC) Offset from UTC

For example:
2010Z 2010-01-01T01:00+01:00 2010-01-01T01:00.000-04:30

Ranges When specifying a range, a curly bracket indicates an exclusive value; a square bracket indicates an inclusive value. Square and curly brackets can be mixed in the same range. For example: Range
[2010,2011]

Description Greater than or equal to 01/01/2010 and less than or equal to 31/12/2011 Greater than 31/12/2010 and less than 01/01/2011 Greater than 31/12/2010 and less than or equal to 31/12/2011

{2010,2011} {2010,2011]

Using Late-Bound Parameter Literals A late-bound parameter literal (::name operand) can be used to assign a late bound parameter to the expression. The name parameter must be provided as part of the parameter array in the QueryOptions element, which is passed as part of an executeGenericQueryRequest or executeRegisteredGenericQueryRequest message. Late-bound parameters are useful when repeatedly executing the same query many times with different values. Using executeRegisteredGenericQuery with late-bound parameters means that the filter will be parsed once, then executed many times with the different values.

TIBCO ActiveMatrix BPM - BPM Developers Guide

292

| Chapter 12

Working with Events

Operators
The following table lists the supported operators. Symbol = <> >= <= < > AND OR NOT IN Description Equal To Not Equal To Greater than or equal to Less than or equal to Less than Greater than AND OR NOT IN Both operators must be booleans. Restrictions on use Both operators must be of the same type.

Where brackets are used, the contents must evaluate to a boolean; a bracketed operation will be used as a boolean from that point on in the expression.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 293

Using Attributes in Query Filters

Attributes define different types of information that you can obtain from Event Collector database tables. The target option specified in a query (in the Query object) defines the Event Collector database table against which the query will execute. The attributes that you can include in a query filter expression depend upon the target option specified in the query. The following sections describe the available attributes for each target option: AUDIT Option Attributes - for queries against the ec_event Event Collector database table, which stores information about events. (This is the default option if target is not specified in the query.) PROCESS_METRICS Option Attributes - for queries against the ec_stats Event Collector database table, which stores hourly measures about process templates. PROCESS_STATS Option Attributes - for queries against the ec_pe_status Event Collector database table, which stores measures about process instances. WORKITEM_STATS Option Attributes - for queries against the ec_wi_status Event Collector database table, which stores measures about work items. REGISTERED_QUERIES Option Attributes - for queries involving queries that have been registered with Event Collector. REGISTERED_COMPONENTS Option Attributes - for queries against the ec_query Event Collector database table, which stores information about queries that have been registered with Event Collector. REGISTERED_ATTRIBUTES Option Attributes - for queries against the ec_attribute Event Collector database table, which stores information about attributes that have been registered with Event Collector. USER_ACTIVITY Option Attributes - for queries against the ec_user_activity Event Collector database table, which stores information about user activity.

TIBCO ActiveMatrix BPM - BPM Developers Guide

294

| Chapter 12

Working with Events

AUDIT Option Attributes

A query that uses the AUDIT option operates against the ec_event Event Collector database table, which stores information about events. The following table describes the attributes that you can include in a filter expression in a query that uses the AUDIT option. When using the AUDIT option, you can use the getAllAttributes operation to list all the attributes registered against Event Collector in the ec_event table. All attributes can be returned in a query. However, only attributes listed in the following table can be used in a filter expression.

Attribute applicationActivityInstanceId applicationActivityModelId applicationActivityName

Description/Notes Unique identifier of the process activity associated with the event from the activity instance (runtime identifier). Unique identifier of the process activity associated with the event from the model (design time identifier). Name of the process activity associated with the event. For example: gateway, StartEvent, ScriptTask, DBTask, gateway, Success, Failure.

applicationName channelId componentId contextId

Name of the application that generated the event. Unique identifier of the presentation channel associated with the event. Identifier of the component that generated the event. The contextID is used with the correlationID and parentContextID to determine the series of events that have occurred. The contextID is set to a new value for each new service call made in a chain of events - thus identifying the contents of a specific service call.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 295

Attribute correlationId

Description/Notes CorrelationID of the event. The correlationID is used with the contextID and parentContextID to determine the series of events that have occurred. The correlationID will be set when a service request is received from an external source. It remains the same for the duration of that request (including any child service calls made).

creationTime entities

Timestamp that the event occurred. The offer set for the work item. This is the GUID, entity type, and model version, separated by the tab character. Multiple entities are separated by the newline character. Identifier of the organization model entity associated with the event.

entityId

TIBCO ActiveMatrix BPM - BPM Developers Guide

296

| Chapter 12
Attribute

Working with Events

Description/Notes Type of the organization model entity associated with the event. This must be one of the following values: ORGANIZATION ORGANIZATIONAL_UNIT GROUP POSITION PRIVILEGE CAPABILITY RESOURCE LOCATION ORGANIZATION_TYPE ORGANIZATIONAL_UNIT_TYPE POSITION_TYPE LOCATION_TYPE ORGUNIT_RELATIONSHIP_TYPE POSITION_HELD ORGUNIT_RELATIONSHIP ORGUNIT_FEATURE POSITION_FEATURE PARAMETER_DESCRIPTOR

entityType

hostAddress hostName id ldapResourceId managedObjectId

Address of the host on which the event occurred. Name of the host on which the event occurred. Primary key of the event. Unique identifier of the primary LDAP container resource associated with the event. Valid values for this attribute depend on the value of the messageCategory attribute - see Message Categories and Attribute Contents on page 307.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 297

Attribute managedObjectName

Description/Notes Valid values for this attribute depend on the value of the messageCategory attribute - see Message Categories and Attribute Contents on page 307. Valid values for this attribute depend on the value of the messageCategory attribute - see Message Categories and Attribute Contents on page 307. Valid values for this attribute depend on the value of the messageCategory attribute - see Message Categories and Attribute Contents on page 307. Description of the event. Identifies the entity which was being operated on causing this event to be produced. See Message Categories and Attribute Contents on page 307. Identifier of the event. For example:
messageId='BX_INSTANCE_PROCESS*'

managedObjectType

managedObjectVersion

message messageCategory

messageId

moduleName nodeName parentActivityInstanceId parentContextId

Process package name of the deployed process associated with the event. Name of the node on which the event occurred. Identifier of the parent activity associated with the event. The parentContextID is used with the correlationID and contextID to determine the series of events that have occurred. The parentContextID is set to a new value each time an internal (to a component) service call is made, and is set to the context ID of the calling service, thus identifying the parent of this service call.

parentObjectId

Valid values for this attribute depend on the value of the messageCategory attribute - see Message Categories and Attribute Contents on page 307. Identifier of the parent process associated with the event. Unique identifier of the security principal associated with the event.

parentProcessInstanceId principalId

TIBCO ActiveMatrix BPM - BPM Developers Guide

298

| Chapter 12
Attribute

Working with Events

Description/Notes Name of the security principal associated with the event. Priority of the event. This must be one of the following: LOW MEDIUM HIGH

principalName priority

priorStepId processPriority pushDestination pushDestinationTarget resourceId resourceName severity

Identifier of the previous activity (to the one associated with the event). Priority of the process instance associated with the event. XML document representing the push destination associated with the event. Target of a push destination. For example, a business attribute or email address. Identifier of the resource associated with the event. Name of the resource associated with the event. Severity of the event. This must be one of the following: TRACE DEBUG INFO SERVICE AUDIT WARN ERROR FATAL

subprocessInstanceId subprocessName subprocessVersion

Identifier of the sub-process associated with the event. Name of the sub-process associated with the event. Version of the sub-process associated with the event.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 299

Attribute systemActionComponentId systemActionId workItemScheduleEnd workItemScheduleStart

Description/Notes Identifier of the component that requested a system action check. (Typically this will be BRM.) Unique identifier of the requested system action. Scheduled end date of the work item associated with the event. Scheduled start date of the work item associated with the event.

PROCESS_METRICS Option Attributes

A query that uses the PROCESS_METRICS option operates against the ec_stats Event Collector database table, which stores hourly measures about process templates. The following table describes the attributes that you can include in a filter expression in a query that uses the PROCESS_METRICS option. Attribute id moduleName moduleVersion pi_avg_time pi_cancelled pi_completed pi_failed pi_started pi_suspended pi_total pi_total_time Description/Notes Unique identifier (in milliseconds) of the hour. Module name. Module version. Average time taken (in milliseconds) by completed process instances during this hour. Total number of process instances that were cancelled during this hour. Total number of process instances that were completed during this hour. Total number of process instances that failed during this hour. Total number of process instances that were started during this hour. Total number of process instances that were suspended during this hour. Total number of process instances that existed during this hour. Total time taken (in milliseconds) by completed process instances during this hour.

TIBCO ActiveMatrix BPM - BPM Developers Guide

300

| Chapter 12
Attribute ref

Working with Events

Description/Notes Unique identifier of the process template. It includes the process template name, module name, and module version. This is stored in the ec_proc_template table. Name of the process template. Timestamp (in date format) of the hour. Average time (in milliseconds) during this hour that a work item was being actioned. A work item is defined as being actioned between its firstOpenTime and its completionTime. Total time (in milliseconds) during this hour that work items were being actioned. A work item is defined as being actioned between its firstOpenTime and its completionTime. Average time (in milliseconds) during this hour that a work item was active. A work item is defined as being active between its firstOfferTime and its completionTime, disregarding any intermediate states. Total time (in milliseconds) during this hour that work items were active. A work item is defined as being active between its firstOfferTime and its completionTime, disregarding any intermediate states. Total number of work items that were allocated or opened during this hour. Total number of work items that were cancelled during this hour. Total number of work items that were completed during this hour. Total number of work items that were opened during this hour. Total number of work items that were offered during this hour. Total number of work items that were pended during this hour. Total number of work items that were suspended during this hour. Total number of work items that existed during this hour. Average time (in milliseconds) during this hour that a work item was waiting. A work item is defined as waiting between its firstOfferTime and its firstOpenTime.

templateName timestamp wi_action_avg

wi_action_dur

wi_active_avg

wi_active_dur

wi_allocated wi_cancelled wi_completed wi_opened wi_offered wi_pended wi_suspended wi_total wi_wait_avg

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 301

Attribute wi_wait_dur

Description/Notes Total time (in milliseconds) during this hour that work items were waiting. A work item is defined as waiting between its firstOfferTime and its firstOpenTime. Average time (in milliseconds) during this hour that a work item was being worked on. A work item is defined as being worked on between its first and last (form submission) activities. Total time (in milliseconds) during this hour that work items were being worked on. A work item is defined as being worked on between its first and last (form submission) activities.

wi_work_time_avg

wi_work_time_dur

PROCESS_STATS Option Attributes

A query that uses the PROCESS_STATS option operates against the ec_pe_status Event Collector database table, which stores measures about process instances. The following table describes the attributes that you can include in a filter expression in a query that uses the PROCESS_STATS option. Attribute endTime moduleName priority processTemplateId Description/Notes Completion time of this process instance. Module name related to the parent process template. Priority of this process instance. Unique identifier of the process template. It includes the process template name, module name, and module version. This is stored in the ec_proc_template table. Name of the parent process template. Unique identifier of this process instance. Start time of this process instance. Status of this process instance. Timestamp of the last status change of this process instance. Total time taken (in milliseconds) by this process instance between its startTime and endTime.

processTemplateName ref startTime status statusChanged timeTaken

TIBCO ActiveMatrix BPM - BPM Developers Guide

302

| Chapter 12
Attribute userGuid userId version

Working with Events

Description/Notes Guid of the resource associated with this process instance. Resource associated with this process instance. Version number of the parent process template.

WORKITEM_STATS Option Attributes

A query that uses the WORKITEM_STATS option operates against the ec_wi_status Event Collector database table, which stores measures about work items. The following table describes the attributes that you can include in a filter expression in a query that uses the WORKITEM_STATS option. Attribute actionDuration activeDuration Description/Notes Total duration (in milliseconds) that this work item was being actioned that is, the time between its firstOpenTime and its completionTime. Total duration (in milliseconds) that this work item was active - that is, the time between its firstOfferTime and its completionTime, disregarding any intermediate states. Instance identifier of the activity from which the work item was derived. This value is unique even if the activity is executed multiple times - for example, as part of a loop. Name of the activity from which the work item was derived. Completion time of this work item. Resource completing this work item. GUID of the resource completing this work item. First time that this work item was offered or allocated. First time that this work item was opened. Last time that this work item was opened. The comma-separated list of the organizational entity GUIDs to which this work item was offered.

activityInstanceId

activityName completionTime completingUserId completingUserGuid firstOfferTime firstOpenTime lastOpenTime orgEntGuids

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 303

Attribute orgEntNames orgEntTypes orgEntVers processInstance processTemplate processTemplateId ref scheduleEnd scheduleStart statusChanged userGuid userId waitDuration wistatus workingTimeDuration

Description/Notes The comma-separated list of the organizational entity names to which this work item was offered. The comma-separated list of the organizational entity types to which this work item was offered. The comma-separated list of the organizational entity versions to which this work item was offered. Identifier of the parent process instance from which this work item was generated. Identifier (name) of the process template from which the parent process instance was generated. The reference to the process template, module name, and module version, referenced in the ec_proc_template table. Unique identifier of this work item. Scheduled end date/time (in UTC) for this work item. Scheduled start date/time (in UTC) for this work item. Time that the status of this work item was last changed. Guid of the resource associated with this work item. Resource associated with this work item. Total duration (in milliseconds) that this work item was waiting - that is, the time between its firstOfferTime and its firstOpenTime. Status of this work item. Total working time duration (in milliseconds) for this work item i.e. the cumulative time for between first and last (form submission) activities.

TIBCO ActiveMatrix BPM - BPM Developers Guide

304

| Chapter 12

Working with Events

REGISTERED_QUERIES Option Attributes

A query that uses the REGISTERED_QUERIES option operates against the ec_query Event Collector database table, which stores information about queries that have been registered with Event Collector. The following table describes the attributes that you can include in a filter expression in a query that uses the REGISTERED_QUERIES option. Attribute attributes correlate filter id ref sort target Description/Notes Required attributes to be fetched when executing this registered query. Boolean value defining whether correlation is required for this registered query. Filter string used by this registered query. Primary key of this registered query. Unique tag defined for this registered query. Attributes defining the sort criteria for this registered query. Target of this registered query, defining the database table against which the query executes - for example, AUDIT or REGISTERED_ATTRIBUTES.

REGISTERED_COMPONENTS Option Attributes

A query that uses the REGISTERED_COMPONENTS option operates against the ec_component Event Collector database table, which stores information about components that have been registered with Event Collector. The following table describes the attributes that you can include in a filter expression in a query that uses the REGISTERED_COMPONENTS option. Attribute componentClass componentName Description/Notes Component Logging Meta Data (CLMD) class file used by this component. SCA component name - for example, implementation.brm. This defaults to the ref value if it is an internal (non-SCA) component. componentType SCA component type - for example, TIBCO-IT-SPRING or TIBCO-IT-WEBAPP.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 305

Attribute description id parentId ref revision version

Description/Notes Description of this component. Primary key of this component. Identifier of the parent component. Unique identifier of this component. For example, BRM or DE. Deployed plugin revision number of this component. Deployed plugin version number of this component.

REGISTERED_ATTRIBUTES Option Attributes

A query that uses the REGISTERED_ATTRIBUTES option operates against the ec_attribute Event Collector database table, which stores information about attributes that have been registered with Event Collector. The following table describes the attributes that you can include in a filter expression in a query that uses the REGISTERED_ATTRIBUTES option. Attribute category componentId id ref type Description/Notes Category of this attribute. Unique identifier of the attributes parent component. Primary key of this attribute. Name of this attribute. Type of this attribute. This must be one of the following: INT LONG DOUBLE BOOLEAN STRING DATE

TIBCO ActiveMatrix BPM - BPM Developers Guide

306

| Chapter 12

Working with Events

USER_ACTIVITY Option Attributes

A query that uses the USER_ACTIVITY option operates against the ec_user_activity Event Collector database table, which stores information about user activity. The following table describes the attributes that you can include in a filter expression in a query that uses the USER_ACTIVITY option. Attribute actionDuration actionEnd actionStart activityInstanceId Description/Notes Total duration (in milliseconds) for this user activity. End date/time for this user activity. Start date/time for this user activity. Instance identifier of the activity from which the work item was derived. This value is unique, even if the activity is executed multiple times, for example, as part of a loop. Name of the activity from which the work item was derived. Unique identifier for this user activity. The comma-separated list of the organizational entity GUIDs to which this work item was offered. The comma-separated list of the organizational entity names to which this work item was offered. The comma-separated list of the organizational entity types to which this work item was offered. The comma-separated list of the organizational entity versions to which this work item was offered. Identifier of the parent process instance from which this work item was generated. Identifier (name) of the process template from which the parent process instance was generated. The reference to the process template, module name, and module version referenced in the ec_proc_template table. The work item associated with this user activity.

activityName id orgEntGuids orgEntNames orgEntTypes orgEntVers processInstance processTemplate processTemplateId ref

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 307

Attribute userAction userGuid userId wiStatus

Description/Notes The user action for this work item. GUID of the resource associated with this work item. Resource associated with this work item. Status of the work item.

Message Categories and Attribute Contents

When constructing a filter expression for a query against the ec_event table (where the query uses the AUDIT option), there are several attributes for which the possible valid values change depending on the value of the messageCategory attribute. The following sections list possible values of the messageCategory attribute and the attributes whose values are affected by this setting. For example: If messageCategory=PROCESS_INSTANCE, then managedObjectName must be the name of a process template. If messageCategory=ORGANIZATIONAL_ENTITY, then managedObjectName must be the name of an organization model entity.

CHANNEL Attribute Name managedObjectId managedObjectName managedObjectVersion parentObjectId Contents Channel ID Channel name Channel version Name of the Distributed Application Archive (DAA) that contains this channel.

TIBCO ActiveMatrix BPM - BPM Developers Guide

308

| Chapter 12

Working with Events

COMPONENT Attribute Name parentObjectId Contents Component name

LDAP_CONTAINER Attribute Name managedObjectId managedObjectName Contents LDAP container ID LDAP container name

LDAP_REQUEST Attribute Name managedObjectName Contents LDAP alias

ORG_MODEL Attribute Name managedObjectId managedObjectName managedObjectVersion Contents Organization model ID Organization model name Organization model version number (in format major.minor.micro). -1 defines the latest version of the organization model.

ORGANIZATIONAL_ENTITY Attribute Name managedObjectId managedObjectName Contents Organization model entity GUID Organization model entity name

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 309

Attribute Name managedObjectType

Contents Number indicating the type of the organization model entity. This must be one of the following: 1. ORGANIZATION 2. ORGANIZATIONAL_UNIT 3. GROUP 4. POSITION 5. PRIVILEGE 6. CAPABILITY 7. RESOURCE 8. LOCATION 9. ORGANIZATION_TYPE 10. ORGANIZATIONAL_UNIT_TYPE 11. POSITION_TYPE 12. LOCATION_TYPE 13. ORGUNIT_RELATIONSHIP_TYPE 14. POSITION_HELD 15. ORGUNIT_RELATIONSHIP 16. ORGUNIT_FEATURE 17. POSITION_FEATURE 18. PARAMETER_DESCRIPTOR

TIBCO ActiveMatrix BPM - BPM Developers Guide

310

| Chapter 12

Working with Events

PROCESS_INSTANCE Attribute Name managedObjectId managedObjectName managedObjectVersion Contents ID of the process instance Name of the process template from which this process instance is generated Version of the process template from which this process instance is generated, in the format major.minor.micro.qualifier Type of the design-time process activity (only for BX_INSTANCE_TASKS* events). For example: StartEvent, exclusiveGateway or serviceTask parentObjectId applicationActivityName ID of the design-time process template Name of the design-time process activity (only for BX_INSTANCE_TASKS* events). For example: StartEvent, gateway or DBTask applicationActivityModelId applicationActivityInstanceId parentApplicationActivityId ID of the design-time process activity (only for BX_INSTANCE_TASKS* events) Run-time ID of the task (only for BX_INSTANCE_TASKS* events) Run-time ID of the tasks parent task (only for BX_INSTANCE_TASKS* events)

managedObjectType

The following attributes are not used for process instance lifecycle events such as BX_INSTANCE_PROCESS_STARTED or BX_INSTANCE_PROCESS_SUSPENDED: managedObjectType applicationActivityName applicationActivityModelId applicationActivityInstanceId parentApplicationActivityId

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 311

PROCESS_TEMPLATE Attribute Name managedObjectId managedObjectName managedObjectVersion Contents ID of the design-time process template Name of the design-time process template Version of the design-time process template, in the format major.minor.micro.qualifier

RESOURCE Attribute Name managedObjectId managedObjectName Contents Resource ID Resource name

SCRIPT_TYPE Attribute Name managedObjectId managedObjectUrl Contents Script ID URL on registration failure

SECURITY Attribute Name managedObjectId managedObjectVersion Contents GUID of the organization model entity making the request Version number of the organization model in which the organization model entity resides. -1 means the latest organization model version.

TIBCO ActiveMatrix BPM - BPM Developers Guide

312

| Chapter 12

Working with Events

USER_SETTING Attribute Name managedObjectId Contents ID of the user setting

WORK_GROUP Attribute Name managedObjectId managedObjectName managedObjectType Contents ID of work group Name of work group Type of work group

WORK_ITEM Attribute Name managedObjectId managedObjectVersion Contents ID of the work item Version number of the work item. The work item version is updated each time the work item is changed. parentObjectId workTypeId workTypeDesc workGroupId workGroupType workModelId ID of the process instance from which the work item is generated UID of the work type associated with the work item Description of the work type associated with the work item ID of the work group to which the work item belongs (if applicable) Type of the work group to which the work item belongs (if applicable) UID of the work model associated with the work item (if applicable)

TIBCO ActiveMatrix BPM - BPM Developers Guide

Using Attributes in Query Filters 313

Attribute Name applicationId

Contents ID of the process template used to create the process instance from which the work item is generated Name of the process template used to create the process instance from which the work item is generated Runtime ID of the Task from which the work item was generated Name of the design-time process activity from which the work item was generated Name of the presentation channel associated with the work item ID of the presentation channel associated with the work item ID of the organization model entity associated with the work item Type of the organization model entity associated with the work item

applicationName

applicationActivityInstanceId applicationActivityName channelName channelType entityId entityType

WORK_MODEL Attribute Name managedObjectId managedObjectName managedObjectDesc Contents Work model ID Work model name Work model description

WORK_TYPE Attribute Name managedObjectId Contents Work type ID

TIBCO ActiveMatrix BPM - BPM Developers Guide

314

| Chapter 12

Working with Events

Attribute Name managedObjectDesc

Contents Work type description

TIBCO ActiveMatrix BPM - BPM Developers Guide

Example Queries 315

Example Queries
The following table shows and describes some example queries. Query
((messageCategory='PROCESS_INSTANCE') AND (managedObjectId='pvm:0a121')) ((messageCategory='PROCESS_INSTANCE') AND (managedObjectId=::ProcID))

Description Returns all events referring to process instance

pvm:0a121.

Returns all events referring to a process instance value that is defined by the ProcID late bound parameter literal. The executeGenericQueryRequest or executeRegisteredGenericQueryRequest message must include a value for ProcID as part of the QueryOptions element.

((messageCategory='WORK_ITEM') AND (parentObjectId='pvm:0a126')) ((messageCategory='PROCESS_INSTANCE') AND (managedObjectId='pvm:0a121') AND (messageId <> BX_INSTANCE_PROCESS_COMPLETED)) ((resourceName= Clint Hill) AND (messageCategory = WORK_ITEM)) (message = Start ??Service*)

Returns all events for work items generated by process instance pvm:0a126. Returns all events referring to process instance pvm:0a121 where the messageID is not
BX_INSTANCE_PROCESS_COMPLETED.0

Returns all events for work items associated with the resource (user) Clint Hill. Returns all events where the message attribute value is Start , followed by any two characters, followed by Service, followed by anything.

TIBCO ActiveMatrix BPM - BPM Developers Guide

316

| Chapter 12

Working with Events

Event Measures
The EventCollectorMeasuresService is one of the Event Collection Services provided by Process Manager. This API provides a means of accessing statistical data for both processes and work items. The EventCollectorMeasuresService provides the following web service operations (SOAP) / Service Connector methods (Java): requestProcessDurationMeasure - This operation returns both counts and time measures for a given process. For example, it returns the total number of work items generated by a given process, within the specified time period. It also returns time measures, such as the amount of time a given process was active during the specified time period. For more detailed information about this operation, see requestProcessDurationMeasure on page 322. requestProcessTemplateMeasure - This operation returns the number of process instances, for the given process template, whose state changed to each of the available states (Started, Completed, etc.), during the specified time period. For more detailed information about this operation, see requestProcessTemplateMeasure on page 325. requestWorkItemPerformanceForTemplate - This operation returns the number of work items, generated by the given process, whose state changed to each of the available states (Offered, Allocated, etc.), during the specified time period. For more detailed information about this operation, see requestWorkItemPerformanceForTemplate on page 326.

Event Measure Parameters

As noted in the bullet points above, each event measure operation returns a different type of measure. However, all of the event measure operations expect the same parameters in the request, as follows: Process Template IDs - One or more process templates must be identified, which causes either process instance or work item statistics for each of the process templates to be returned. Start and End Date - The total period of time encompassed by the statistical data returned (which is further broken down into periods, as specified by the granularity parametersee below).

TIBCO ActiveMatrix BPM - BPM Developers Guide

Event Measures 317

Granularity - The period of time (hour, day, week, etc.) for which each piece of statistical data is returned (for example, number of process instances whose state was changed to "Suspended" during a particular month). Consolidation - Allows you to specify whether statistical data should be returned for each specified process, or consolidated, or both individually and consolidated.

These parameters are described in more detail in the following subsections. Process Template IDs Each event measure operation request identifies one or more process templates, for which statistical data is to be returned. These are specified in the <id> / <processTemplateName> elements:
Request: ... <id> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <id> <processTemplateName>HelpDeskProcess</processTemplateName> </id> ...

Start and End Date The start and end dates specify the total period of time for which statistical data is being returned. This period is then further subdivided into smaller periods according to the granularity specified for the operation (see Granularity on page 318). The start and end dates are specified in the <duration> / <endDate> and <startDate> elements:
Request: ... <duration> <endDate>2011-08-30T00:00:00.000Z</endDate> <startDate>2011-08-27T00:00:00.000Z</startDate> ...

TIBCO ActiveMatrix BPM - BPM Developers Guide

318

| Chapter 12

Working with Events

Note that all statistical data is stored internally in one-hour blocks. Therefore, if the start and end dates specified in a request fall inside a one-hour block, they are always rounded to include the entire one-hour block, as follows: startDate is rounded down to the nearest hour boundary endDate is rounded up to the nearest hour boundary For example, if the following dates are specified:
<endDate>2011-08-25T08:23:55.829Z</endDate> <startDate>2011-08-25T10:45:12.000Z</startDate>

The operation response will include the measures (times or counts) stored in the one-hour blocks after the date/time is rounded. For example:

Granularity Granularity specifies the periods into which you want the larger time period, specified by the start and end dates, subdivided. The following are the granularity periods that can be specified: HOUR DAY WEEK MONTH YEAR

TIBCO ActiveMatrix BPM - BPM Developers Guide

Event Measures 319

Granularity is passed in requests in the <duration> / <granularity> element. For example:

Request: ... <duration> <endDate>2011-08-30T00:00:00.000Z</endDate> <startDate>2011-08-27T00:00:00.000Z</startDate> <granularity>DAY</granularity> </duration> ...

This example is specifying start and end dates that encompass three days, with a granularity of one day. This causes the response to include statistical data in three, one-day periods. For each granularity period, a <period> element is returned, which contains the event measures data (in the <entry> elements) for that particular time period:

Response: ... <measure xmlns=""> <index>0</index> <id xmlns:api="http://api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <period> <index>0</index> <duration> <startDate>2011-08-27T00:00:00.000Z</startDate> </duration> <entry> <index>0</index> <value>19</value> <type>STARTED</type> </entry> ... </period> ...

In this example, three <period> elements are returned, each contained the event measures data for one day.

TIBCO ActiveMatrix BPM - BPM Developers Guide

320

| Chapter 12

Working with Events

Also note that when the granularity period is specified as DAY, it means 24 hours, starting at the beginning of the hour block according to the start date (as described above), to the next day at the same time (that is, it is not from the beginning of the day to the end of the day). For example, if the startDate is 2011-08-27T07:00:00.000Z, a granularity of DAY means the granularity period is from 7:00 on Aug. 27 to 7:00 on Aug. 28. Consolidation Consolidation allows you to specify whether or not to consolidate the returned event measures data for each process template specified, as follows: NO_CONSOLIDATION - The event measures data for each specified process template is returned in a separate <measure> element. CONSOLIDATE - The event measures data for all specified process templates is consolidated in a single <measure> element. BOTH - The event measures data for each specified process template is returned in a separate <measure> element, plus it is also consolidated in a single <measure> element.

Note that this capability is most applicable when the request specifies multiple process templates. Consolidation is specified in the <options> / <consolidation> element. For example:
Request: ... <options> <consolidation>BOTH</consolidation> </options> ...

TIBCO ActiveMatrix BPM - BPM Developers Guide

Event Measures 321

The following example shows the response from an event measure operation where consolidation is specified as BOTH:
Response: ... <measure xmlns=""> <index>0</index> <id xmlns:api="http://api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <processTemplateName>CSCallbackProcess</processTemplateName> </id> ... </measure> <measure xmlns=""> <index>1</index> <id xmlns:api="http://api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <processTemplateName>HelpDeskProcess</processTemplateName> </id> ... </measure> ... <measure xmlns=""> <index>-1</index> <isConsolidatedMeasure>true</isConsolidatedMeasure> ... </measure> ...

The <measure> elements for the individual process templates contain an index, starting at 0, as well as the name of the process template for which the event measure data inside the <measure> element applies. The <measure> element that contains the consolidated event measure data always has an index of -1, as well as a <isConsolidatedMeasure> element with a value of "true".

TIBCO ActiveMatrix BPM - BPM Developers Guide

322

| Chapter 12

Working with Events

requestProcessDurationMeasure
This operation returns both count and time measures for: the process instances of the specified process templates, and the work items generated by the instances of the specified process templates.

Each count/time measure is returned inside of an <entry> element, inside of the <period> element that represents the granularity period (see Granularity on page 318). The following example shows that 15 instances of CSCallbackProcess were started during the first granularity period (index=0). Plus, the instances of CSCallbackProcess were active for a total of 2884367898 milliseconds during that same period.
Response: ... <measure xmlns=""> <index>0</index> <id xmlns:api="http://api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <period> <index>0</index> <duration> <startDate>2011-08-01T00:00:00.000Z</startDate> </duration> <entry> <index>0</index> <value>15</value> <type>PROCESS_TOTAL</type> </entry> <entry> <index>1</index> <value>2884367898</value> <type>PROCESS_TOTAL_TIME</type> </entry> ...

TIBCO ActiveMatrix BPM - BPM Developers Guide

Event Measures 323

The counts and times returned by the requestProcessDurationMeasure operation are defined in the following table: Type PROCESS_TOTAL Description Total number of instances of the process template started during the specified granularity period (note that this is a deltait is only the number that were started during the period). Total time (in milliseconds) that instances of the process template were active during the specified granularity period. Average time (in milliseconds) that instances of the process template were active during the specified granularity period. Total number of work items generated by the instances of the process template during the specified granularity period (note that this is a deltait is not the number that existed, but rather the number that were generated during the period). Total time (in milliseconds) that a work item generated by the process template was active during the specified granularity period. A work item is defined as being active between the time it first entered the OFFERED state, and the time it entered the COMPLETED state, disregarding any intermediate states. Average time (in milliseconds) that work items generated by the process template were active during the specified granularity period. A work item is defined as being active between the time it first entered the OFFERED state, and the time it entered the COMPLETED state, disregarding any intermediate states. Total time (in milliseconds) that work items generated by the process template were waiting during the specified granularity period. A work item is defined as waiting between the time it first entered the OFFERED state, and the time it first entered the OPENED state.
TIBCO ActiveMatrix BPM - BPM Developers Guide

PROCESS_TOTAL_TIME

PROCESS_AVERAGE_TIME

WORKITEM_TOTAL

WORKITEM_ACTIVE_TOTAL_TIME

WORKITEM_ACTIVE_AVERAGE_TIME

WORKITEM_WAIT_TOTAL_TIME

324

| Chapter 12
Type

Working with Events

Description Average time (in milliseconds) that a work item generated by the process template was waiting during the specified granularity period. A work item is defined as waiting between the time it first entered the OFFERED state, and the time it first entered the OPENED state. Total time (in milliseconds) that work items generated by the process template were being actioned during the specified granularity period. A work item is defined as being actioned between the time it first entered the OPENED state, and the time it entered the COMPLETED state (that is, when the user submitted the form). Average time (in milliseconds) that a work item generated by the process template during the specified granularity period. A work item is defined as being actioned between the time it first entered the OPENED state, and the time it entered the COMPLETED state (that is, when the user submitted the form). Total time (in milliseconds) that users spent processing work items generated by the process template during the specified granularity period. A work item is defined as being worked on between the accumulated time between when it entered the OPENED state, and the time it entered a PENDED, SUSPENDED, CANCELLED, or COMPLETED state. Average time (in milliseconds) that a work item generated by the process template was worked on by users during the specified granularity period. A work item is defined as being worked on between the accumulated time when it entered the OPENED state, and the time when it entered a PENDED, SUSPENDED, CANCELLED or COMPLETED state.

WORKITEM_WAIT_AVERAGE_TIME

WORKITEM_ACTION_TOTAL_TIME

WORKITEM_ACTION_AVERAGE_TIME

WORKITEM_WORKINGTIME_TOTAL_TIME

WORKITEM_WORKINGTIME_AVERAGE_TIME

For additional information, see requestProcessDurationMeasure on page 474.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Event Measures 325

requestProcessTemplateMeasure
This operation returns the number of process instances that changed to the following states, for the given process template, during the granularity period: STARTED COMPLETED SUSPENDED CANCELLED FAILED

Note that the counts returned by this operation are deltas, that is, it is the number that changed to each state during the period, not the number that were in that state during the period. Each state change count is returned inside of an <entry> element, inside of the <period> element that represents the granularity period (see Granularity on page 318). The following example response from a requestProcessTemplateMeasure operation shows that 15 instances of CSCallbackProcess were started, and 12 were completed, during the first granularity period (index=0):
Response: ... <measure xmlns=""> <index>0</index> <id xmlns:api="http://api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <period> <index>0</index> <duration> <startDate>2011-08-27T00:00:00.000Z</startDate> </duration> <entry> <index>0</index> <value>15</value> <type>STARTED</type> </entry> <entry> <index>1</index> <value>12</value> <type>COMPLETED</type> </entry> ...

TIBCO ActiveMatrix BPM - BPM Developers Guide

326

| Chapter 12

Working with Events

For additional information, see requestProcessTemplateMeasure on page 477.

requestWorkItemPerformanceForTemplate
This operation returns the number of work items that changed to the following states, for the given process template, during the granularity period: OFFERED ALLOCATED PENDED COMPLETED SUSPENDED CANCELLED

Note that the counts returned by this operation are deltas, that is, it is the number that changed to each state during the period, not the number that were in that state during the period. Each state change count is returned inside of an <entry> element, inside of the <period> element that represents the granularity period (see Granularity on page 318).

TIBCO ActiveMatrix BPM - BPM Developers Guide

Event Measures 327

The following example response from a requestWorkItemPerformanceForTemplate operation shows that 7 work items generated from instances of CSCallbackProcess were changed to an OFFERED state, and 5 were changed to an ALLOCATED state, during the first granularity period (index=0):
Response: ... <measure xmlns=""> <index>0</index> <id xsi:type="base:ProcessTemplateId" xmlns:api="http://api.ec.n2.tibco.com" xmlns:base="http://base.api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <period> <index>0</index> <duration> <startDate>2011-08-27T00:00:00.000Z</startDate> </duration> <entry> <index>0</index> <value>7</value> <type>OFFERED</type> </entry> <entry> <index>1</index> <value>5</value> <type>ALLOCATED</type> </entry> ...

For additional information, see requestWorkItemPerformanceForResource on page 484.

TIBCO ActiveMatrix BPM - BPM Developers Guide

328

| Chapter 12

Working with Events

TIBCO ActiveMatrix BPM - BPM Developers Guide

| 329
Chapter 13

TIBCO ActiveMatrix BPM Services

This chapter summarizes the public services provided by TIBCO ActiveMatrix BPM, and provides links to: detailed documentation on the operations provided by a particular service, and the equivalent methods provided by the Java Service Connector API. WSDL and XSD documentation for a particular service API or schema.

You can download a zip file containing the complete TIBCO ActiveMatrix BPM web service API. The file contains all the WSDL and XSD files described in this chapter. Alternatively, you can generate a WSDL for a particular service from TIBCO ActiveMatrix Administrator. See TIBCO ActiveMatrix BPM APIs and How to Obtain Them for more information.

Topics
Business Services, page 330 Business Resource Management Services, page 331 Calendar Services, page 333 Directory Services, page 334 Event Collection Services, page 336 Pageflow Services, page 338 Process Services, page 339 Work Presentation Services, page 340

TIBCO ActiveMatrix BPM - BPM Developers Guide

330

| Chapter 13

TIBCO ActiveMatrix BPM Services

Business Services
Business services are provided by the Work Manager logical node (by the Pageflow Engine (PFE) component).

Services
The Business services API provides the following public service. Service BusinessService Description Get information about and interact with deployed business service templates and business service instances

API Files
The following table shows the API files that provide Business services. File busserv.wsdl pfe-business-service.xsd pfe-common.xsd channeltype.xsd datamodel.xsd presentationmodel.xsd pfe-exception.xsd comexception.xsd Description Business services API Pageflow services - BusinessService schema Pageflow services - common schema Work Presentation services - channel type schema Common data model schema Work Presentation services - presentation model schema Pageflow services - exception schema Common exception schema Hyperlinks are provided to the WSDL and XSD documentation for a particular service API or schema. Any xsd files that do not have hyperlinks are included (directly or indirectly) in hyperlinked xsd files. For example, the XSD documentation for pfe-business-service.xsd also includes the documentation for pfe-common.xsd.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Business Resource Management Services 331

Business Resource Management Services

Business Resource Management services are provided by the Work Manager logical node (by the Business Resource Management (BRM) component).

Services
The Business Resource Management Services API provides the following public services. Service WorkItemManagementService WorkListService OrganisationalEntityConfigService Description Perform actions on work items. Get work item lists for organization model entities, and get/set sort/filter criteria for work item lists. Manage resource configuration attributes and get/set resource configuration attributes for individual resources.

API Files
The following table lists the API files that provide Business Resource Management services. File brm.wsdl brm.xsd Description Business Resource Management services API Business Resource Management services schema (WorkItemManagementService, WorkListService and OrganisationalEntityConfigService services) Business Resource Management services - data transfer object schema Business Resource Management services - work model schema Common data model schema Directory services - organization schema Business Resource Management services - script description schema Business Resource Management services - exception schema

brmdto.xsd brmworkmodel.xsd datamodel.xsd organisation.xsd scriptdescriptor.xsd brmexception.xsd

TIBCO ActiveMatrix BPM - BPM Developers Guide

332

| Chapter 13
File

TIBCO ActiveMatrix BPM Services

Description Directory services - exception schema Common exception schema Hyperlinks are provided to the WSDL and XSD documentation for a particular service API or schema. Any xsd files that do not have hyperlinks are included (directly or indirectly) in hyperlinked xsd files. For example, the XSD documentation for brm.xsd also includes the documentation for brmdto.xsd. The Business Resource Management Services API also includes a number of private services which are intended only for internal use by TIBCO ActiveMatrix BPM. These services, which should not be used by an external application, are marked in the API with the following annotation: **PRIVATE API - Reserved for internal use** The private services WorkGroupManagementService, WorkItemSchedulerService and WorkModelBrowserService are visible in TIBCO ActiveMatrix Administrator. Do not generate and use WSDLs for these services.

deexception.xsd comexception.xsd

TIBCO ActiveMatrix BPM - BPM Developers Guide

Calendar Services 333

Calendar Services
Calendar services are provided by the Process Manager logical node (by the Date and Calendar (DAC) component).

Services
The Calendar services API provides the following public services. Service CalendarService BusinessDeadlineService Description Get information about and configure working time for a given organizational entity. Calculate the business deadline based on a given organizational entity's calendar.

API Files
The following table shows the API files that provide Calendar services. File dac.wsdl dac-calendar-service.xsd dac-deadline-service.xsd dac-common.xsd dac-exception.xsd comexception.xsd Description Calendar services API Calendar services - CalendarService schema Calendar services - BusinessDeadlineService schema Calendar services - common object schema Calendar services - exception schema Common exception schema Hyperlinks are provided to the WSDL and XSD documentation for a particular service API or schema. Any xsd files that do not have hyperlinks are included (directly or indirectly) in hyperlinked xsd files. For example, the XSD documentation for dac-calendar-service.xsd also includes the documentation for dac-common.xsd.

TIBCO ActiveMatrix BPM - BPM Developers Guide

334

| Chapter 13

TIBCO ActiveMatrix BPM Services

Directory Services
Directory services are provided by the Work Manager logical node (by the Directory Engine (DE) component).

Services
The Directory services API provides the following public services. Service EntityResolverService LDAPService BrowseModelService MappingService ContainerService AttributeService SecurityService Description Get information about resources and their association with specific organization model entities. Get information about and from LDAP sources. Get information about or from the organization model. Manage mappings between organization model resources and LDAP entities. Manage LDAP containers. Manage resource attributes, including push destinations for work items. Manage user authentication and authorization. Note: See System Actions on page 768 for more information about how to specify system actions when using these operations. UserSettingsService ExporterService ResourceQueryService Manage user settings. Export and import defined LDAP containers, resources and push destinations Execute a Resource Query Language (RQL) query to find a set of resources that match specific criteria.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Directory Services 335

API Files
The following table shows the API files that provide Directory services. File de.wsdl de-attribute-service.xsd de-browse-service.xsd de-container-service.xsd de-exporter-service.xsd de-ldap-service.xsd de-mapping-service.xsd de-resolver-service.xsd de-resourcequery-service.xsd de-security-service.xsd de-usersettings-service.xsd de.xsd de-ldap.xsd organisation.xsd channeltype.xsd deexception.xsd comexception.xsd Description Directory services API Directory services - AttributeService schema Directory services - BrowseModelService schema Directory services - ContainerService schema Directory services - ExporterService schema Directory services - LDAPService schema Directory services - MappingService schema Directory services - EntityResolverService schema Directory services - ResourceQueryService schema Directory services - SecurityService schema Directory services - UserSettingsService schema Directory services schema (all services) Directory services - LDAP schema Directory services - organization schema Work Presentation services - channel type schema Directory services - exception schema Common exception schema Hyperlinks are provided to the WSDL and XSD documentation for a particular service API or schema. Any xsd files that do not have hyperlinks are included (directly or indirectly) in hyperlinked xsd files. For example, the XSD documentation for de-attribute-service.xsd also includes the documentation for de.xsd.

TIBCO ActiveMatrix BPM - BPM Developers Guide

336

| Chapter 13

TIBCO ActiveMatrix BPM Services

Event Collection Services

Event Collection services are provided by the Process Manager logical node (by the Event Collector (EC) component).

Services
The Event Collection services API provides the following public services. Service EventCollectorQueryService EventCollectorMeasuresService Description Get information from the Event Collector database tables about events, attributes and components. Get measures stored by Event Collector.

API Files
The following table shows the API files that provide Event Collection service. File ec.wsdl ec.xsd ec-basetypes.xsd ecexception.xsd comexception.xsd Description Event Collection services API Event Collection services schema (EventCollectorQueryService and EventCollectorMeasuresService services) Event Collection services - type schema Event Collection services - exception schema Common exception schema Hyperlinks are provided to the WSDL and XSD documentation for a particular service API or schema. Any xsd files that do not have hyperlinks are included (directly or indirectly) in hyperlinked xsd files. For example, the XSD documentation for ec.xsd also includes the documentation for ec-basetypes.xsd.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Event Collection Services 337

The Event Collection Services API also includes some private service operations which are intended only for internal use by TIBCO ActiveMatrix BPM. These service operations, which should not be used by an external application, are marked in the API with the following annotation: **PRIVATE API - Reserved for internal use**

TIBCO ActiveMatrix BPM - BPM Developers Guide

338

| Chapter 13

TIBCO ActiveMatrix BPM Services

Pageflow Services
Pageflow services are provided by the Work Manager logical node (by the Pageflow Engine (PFE) component).

Services
The Pageflow services API provides the following public service. Service PageFlowService Description Get information about and interact with deployed pageflows.

API Files
The following table shows the API files that provide Pageflow services. File pflow.wsdl pfe-pageflow-service.xsd pfe-common.xsd channeltype.xsd datamodel.xsd presentationmodel.xsd pfe-exception.xsd comexception.xsd Description Pageflow services API Pageflow services - PageFlowService schema Pageflow services - common schema Work Presentation services - channel type schema Common data model schema Work Presentation services - presentation model schema Pageflow services - exception schema Common exception schema Hyperlinks are provided to the WSDL and XSD documentation for a particular service API or schema. Any xsd files that do not have hyperlinks are included (directly or indirectly) in hyperlinked xsd files. For example, the XSD documentation for pfe-pageflow-service.xsd also includes the documentation for pfe-common.xsd.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Process Services 339

Process Services
Process services are provided by the Process Manager logical node (by the Process Manager (PM) component).

Services
The Process services API provides the following public service. Service ProcessManagerService Description Manage process templates and process instances.

API Files
The following table shows the API files that provide Process services. File processManagement.wsdl processManagement.xsd Description Process services API ProcessManagement service schema

The ProcesManagerService includes an operation, purgeProcessInstances, which is intended only for internal use by TIBCO ActiveMatrix BPM. This operation should not be used by an external application and is marked in the API with the following annotation: **PRIVATE API - Reserved for internal use** The ProcessManagement service appears as BxProcessManagementService in TIBCO ActiveMatrix Administrator.

TIBCO ActiveMatrix BPM - BPM Developers Guide

340

| Chapter 13

TIBCO ActiveMatrix BPM Services

Work Presentation Services

Work Presentation services are provided by the Work Manager logical node (by the Work Presentation (WP) component).

Services
The Work Presentation services API provides the following public service. Service WorkPresentationService Description Get work presentation details for and perform actions on work items.

API Files
The following table shows the API files that provide Work Presentation services. File wp.wsdl wp.xsd wp-basetypes.xsd wpModel.xsd channeltype.xsd presentationmodel.xsd datamodel.xsd bs-basetypes.xsd wpexception.xsd comexception.xsd Description Work Presentation services API Work Presentation services schema (WorkPresentationService and ChannelBusService services) Work Presentation services - basic types schema Work Presentation services - model schema Work Presentation services - channel type schema Work Presentation services - presentation model schema Common data model schema Work Presentation services - TIBCO Business Studio basic types schema Work Presentation services - exception schema Common exception schema

TIBCO ActiveMatrix BPM - BPM Developers Guide

Work Presentation Services 341

Hyperlinks are provided to the WSDL and XSD documentation for a particular service API or schema. Any xsd files that do not have hyperlinks are included (directly or indirectly) in hyperlinked xsd files. For example, the XSD documentation for wp.xsd also includes the documentation for wp-basetypes.xsd.

TIBCO ActiveMatrix BPM - BPM Developers Guide

342

| Chapter 13

TIBCO ActiveMatrix BPM Services

TIBCO ActiveMatrix BPM - BPM Developers Guide

AttributeService 343

Chapter 14

AttributeService

AttributeService is one of the Directory Services provided by Work Manager. Use AttributeService requests to manage resource attributes, including push destinations for work items.

Topics
listBusinessParameters, page 344 getBusinessParameters, page 347 setBusinessParameters, page 350 getPushDestinations, page 353 setPushDestinations, page 356

TIBCO ActiveMatrix BPM - BPM Developers Guide

344

| Chapter 14

AttributeService

listBusinessParameters
List all parameter descriptors that describe resource attributes in a specific version of the organization model: The request must specify the major version of the organization model for which parameter descriptors describing resource attributes should be listed. The response returns all the parameter descriptors (in the specified version of the organization model) that describe resource attributes.

See also: Mapping Resource Attributes to LDAP Attributes on page 118. Required System Action readParameters

TIBCO ActiveMatrix BPM - BPM Developers Guide

listBusinessParameters 345

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the listBusinessParameters element (from the AttributeService schema) None Returns a listBusinessParametersResponse element (from the AttributeService schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:att="http://attribute.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <att:listBusinessParameters model-version="-1"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listBusinessParametersResponse xmlns="http://attribute.api.de.n2.tibco.com"> <param-desc default-value="" description="" guid="_looEEMpSEd64gM7QE8RwxA" model-version="3" name="CellPhone" type="String" xmlns=""/> <param-desc default-value="" description="" guid="_n2CW0MpSEd64gM7QE8RwxA" model-version="3" name="ClearanceExpiration" type="DateTime" xmlns=""/> <param-desc default-value="" description="" guid="_qr04MMpSEd64gM7QE8RwxA" model-version="3" name="DeskPhone" type="String" xmlns=""/> <param-desc default-value="" description="" guid="_sfdZAMpSEd64gM7QE8RwxA" model-version="3" name="DeveloperLevel" type="Enum" xmlns=""> <enum-val>Advanced</enum-val> <enum-val>Intermediate</enum-val> <enum-val>Beginner</enum-val> </param-desc> . . . </listBusinessParametersResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

346

| Chapter 14

AttributeService

Service Connector API (Java Method)

Method Service listBusinessParameters (args) AttributeService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getBusinessParameters 347

getBusinessParameters
List resource attribute values for a specific organization model entity: The request must specify the details of the organization model entity for which resource attribute values should be returned. The response returns the resource attribute values currently held by the specified organization model entity.

See also: Mapping Resource Attributes to LDAP Attributes on page 118. Required System Action readParameters

TIBCO ActiveMatrix BPM - BPM Developers Guide

348

| Chapter 14

AttributeService

Web Service API (SOAP Operation)

Request Parameter notes Uses the getBusinessParameters element (from the AttributeService schema) Response Example entity-type: Must be LOCATION, ORGANIZATION, ORGANIZATIONAL_UNIT, POSITION, or RESOURCE. guid: Can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources.

Returns a getBusinessParametersResponse element (from the AttributeService schema) For a resource attribute whose value is held locally: Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:att="http://attribute.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <att:getBusinessParameters model-version="-1" entity-type="RESOURCE" guid="7AAB6AE7-CA2E-4211-BBF8-E081659526FE" /> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getBusinessParametersResponse entity-type="RESOURCE" guid="7AAB6AE7-CA2E-4211-BBF8-E081659526FE" model-version="3" xmlns="http://attribute.api.de.n2.tibco.com"> <parameter desc-guid="_looEEMpSEd64gM7QE8RwxA" local="true" name="CellPhone" type="String" xmlns=""> <value>509-555-2323</value> </parameter> <parameter desc-guid="_7seVwMpSEd64gM7QE8RwxA" ldap-alias="easyAs" ldap-attribute="mail" ldap-dn="ou=Clint Hill, ou=Swindon, ou=AllEmployees" local="false" name="EmailAddress" type="String" xmlns=""> <value>chill@easyasinsurance.com</value> </parameter> </getBusinessParametersResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getBusinessParameters 349

Service Connector API (Java Method)

Method Service getBusinessParameters (args) AttributeService

TIBCO ActiveMatrix BPM - BPM Developers Guide

350

| Chapter 14

AttributeService

setBusinessParameters
Set resource attribute values for a specific resource: The request must specify the organization model entity for whom resource attribute values are to be set, and the resource attribute values that are to be set. The response indicates whether the specified resource attribute values were successfully set for the specified organization model entity.

See also: Mapping Resource Attributes to LDAP Attributes on page 118. Required System Action writeParameters

TIBCO ActiveMatrix BPM - BPM Developers Guide

setBusinessParameters 351

Web Service API (SOAP Operation)

Request Parameter notes Uses the setBusinessParameters element (from the AttributeService schema) Response Example entity-type: Must be RESOURCE1. guid: Can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources. parameter.name: Can be obtained from listBusinessParameters. parameter.desc-guid: Can be obtained from listBusinessParameters. parameter.type: Can be obtained from listBusinessParameters.

Returns a setBusinessParametersResponse element (from the AttributeService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:att="http://attribute.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <att:setBusinessParameters model-version="-1" entity-type="RESOURCE" guid="7AAB6AE7-CA2E-4211-BBF8-E081659526FE" > <parameter name="CellPhone" desc-guid="_looEEMpSEd64gM7QE8RwxA" type="String" local="true" > <value>509-555-2323</value> </parameter> </att:setBusinessParameters> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <setBusinessParametersResponse xmlns="http://attribute.api.de.n2.tibco.com"> <successful xmlns="">true</successful> </setBusinessParametersResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

1. Attribute values for non-resource entities must be set via the organization model (using TIBCO Business Studio Organization Modeler).

TIBCO ActiveMatrix BPM - BPM Developers Guide

352

| Chapter 14

AttributeService

Service Connector API (Java Method)

Method Service setBusinessParameters (args) AttributeService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getPushDestinations 353

getPushDestinations
List currently defined push destinations for one or more organization model entities: The request must specify the organization model entities for whom push destinations should be retrieved. The response returns the currently defined push destinations for each specified organization model entity.

Required System Action readPushDestinations

TIBCO ActiveMatrix BPM - BPM Developers Guide

354

| Chapter 14

AttributeService

Web Service API (SOAP Operation)

Request Parameter notes Uses the getPushDestinations element (from the AttributeService schema) entity-type: Must be ORGANIZATIONAL_UNIT, POSITION, GROUP, or RESOURCE. guid: Organization unit, position, and group GUIDs can be obtained from listOrgModelOverview or openOrgModel. Resource GUIDs can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources.

Response

Returns a getPushDestinationsResponse element (from the AttributeService schema). If the push destination is obtained from a resource attribute (desc-guid was passed in the setPushDestinations operation), the value attribute in the response contains the value in the resource attribute.

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:att="http://attribute.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <att:getPushDestinations> <org-entity model-version="-1" entity-type="POSITION" guid="_6lTHwMpREd64gM7QE8RwxA" /> </att:getPushDestinations> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getPushDestinationsResponse xmlns="http://attribute.api.de.n2.tibco.com"> <org-entity entity-type="POSITION" guid="_6lTHwMpREd64gM7QE8RwxA" model-version="3" xmlns=""> <XmlPushDestination channel-id="EmailGIPush_USA" channel-type="EmailChannel" enabled="true" name="EmailGIPush_USA" xmlns="http://attribute.api.de.n2.tibco.com"> <value xmlns="">ITManager@megacorp.com</value> </XmlPushDestination> </org-entity> </getPushDestinationsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getPushDestinations 355

Service Connector API (Java Method)

Method Service getPushDestinations (args) AttributeService

TIBCO ActiveMatrix BPM - BPM Developers Guide

356

| Chapter 14

AttributeService

setPushDestinations
Set one or more push destinations for a specific organization model entity: The request must specify an organization model entity and one or more push destinations. The response indicates whether the specified push destinations were successfully set for the organization model entity.

Required System Action writePushDestinations

TIBCO ActiveMatrix BPM - BPM Developers Guide

setPushDestinations 357

Web Service API (SOAP Operation)

Request Parameter notes Uses the setPushDestinations element (from the AttributeService schema) entity-type: Must be ORGANIZATIONAL_UNIT, POSITION, GROUP, or RESOURCE. guid: Organization unit, position, and group GUIDs can be obtained from listOrgModelOverview or openOrgModel. Resource GUIDs can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources. qualifier: Not used in this request. name: Not needed in the request. Returned in the response. It is set to the same value as channel-id. channel-type: An enumerated value associated with that channel type, for example, EmailChannel, MobileChannel, and openspaceChannel. For more information, see Identifying the Client Channel in a Service Call on page 236. channel-id: Uniquely identifies the presentation channel to use when pushing work items. The channel ID is defined when a presentation channel is defined in TIBCO Business Studio. For more information, see the TIBCO Business Studio documentation, as well as Identifying the Client Channel in a Service Call on page 236 and "Configuring the Email Presentation Channel" in the TIBCO ActiveMatrix BPM - BPM Administration guide. enabled: Allows you to enable/disable the push destination without removing the push destination definition. desc-guid: (Optional) Identifies a resource attribute from which the push destination will be obtained at the time a work item is pushed. Can be obtained from getBusinessParameters. value: Contains the push destination (for example, for an email push destination, this would be an email address). If both this attribute and desc-guid are passed in the request, the value in desc-guid is used.

Response

Returns a setPushDestinationsResponse element (from the AttributeService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

358

| Chapter 14
Example

AttributeService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:att="http://attribute.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <att:setPushDestinations model-version="-1" entity-type="POSITION" guid="_6lTHwMpREd64gM7QE8RwxA"> <att:XmlPushDestination channel-type="EmailChannel" channel-id="EmailGIPush_DefaultChannel" enabled="true"> <value>jMiller@megacorp.com</value> </att:XmlPushDestination> </att:setPushDestinations> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <setPushDestinationsResponse xmlns="http://attribute.api.de.n2.tibco.com"> <successful xmlns="">true</successful> </setPushDestinationsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service setPushDestinations (args) AttributeService

TIBCO ActiveMatrix BPM - BPM Developers Guide

BrowseModelService 359

Chapter 15

BrowseModelService

BrowseModelService is one of the Directory Services provided by Work Manager. Use BrowseModelService requests to get information about or from the organization model.

Topics
listModelVersions, page 360 openOrgModel, page 362 browseModelNode, page 365 listOrgModelOverview, page 367 listCapabilities, page 370 listPrivileges, page 372 getCapabilities, page 374 getPrivileges, page 376 listOrganizations, page 378

TIBCO ActiveMatrix BPM - BPM Developers Guide

360

| Chapter 15

BrowseModelService

listModelVersions
List all major versions (including the deployment artefacts the make up each major version) of the organization model: The request takes no parameters. The response returns a list of all major versions of the organization model.

Required System Action browseModel

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the listModelVersions element (from the BrowseModelService schema) The <dummy> element is a placeholderits value is not referenced. Returns a listModelVersionsResponse element (from the BrowseModelService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

listModelVersions 361

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:listModelVersions> <dummy>false</dummy> </brow:listModelVersions> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listModelVersionsResponse xmlns="http://browse.api.de.n2.tibco.com"> <versions model-version="0" xmlns=""> <deployment deployed="2011-06-28T20:06:40.193Z" micro="0" minor="1" name="sys_org_model" qualifier=""/> </versions> <versions model-version="1" xmlns=""> <deployment deployed="2011-06-29T14:29:58.120Z" micro="0" minor="0" name="OrganizationModel" qualifier="201106290731"/> <deployment deployed="2011-06-29T15:30:30.220Z" micro="0" minor="0" name="OrganizationModel" qualifier="201106290831"/> </versions> <versions model-version="2" xmlns=""> <deployment deployed="2011-07-12T17:05:21.467Z" micro="0" minor="1" name="OrganizationModel" qualifier="201107121007"/> </versions> <versions model-version="3" xmlns=""> <deployment deployed="2011-06-28T20:25:32.017Z" micro="1" minor="5" name="AcmeOrganizationModel" qualifier="201105061158"/> </versions> </listModelVersionsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

major="0"

major="1"

major="1"

major="2"

major="3"

Service Connector API (Java Method))

Method Service listModelVersions (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

362

| Chapter 15

BrowseModelService

openOrgModel
Open a major version of the organization model: The request can specify the major version of the organization model that is to be opened. The response returns details of the root node(s) of the organization model tree. (The caller can then use repeated browseModelNode calls to iterate through the organization modelfor additional information, see Navigating Large Organizations on page 110.) Note that this operation only includes those organizations (and sub-elements) to which the calling user has access (because of organization relationships). For more information, see Organization Relationships on page 123. Required System Action browseModel

TIBCO ActiveMatrix BPM - BPM Developers Guide

openOrgModel 363

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the openOrgModel element (from the BrowseModelService schema) model-version: Use -1 (or omit the parameter) to specify the latest version of the organization model. Use listModelVersions to get a list of all major versions.

Returns a openOrgModelResponse element (from the BrowseModelService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:openOrgModel model-version="2"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <openOrgModelResponse model-version="2" xmlns="http://browse.api.de.n2.tibco.com"> <root-node entity-type="ORGANIZATION" guid="_tf5fgSe3EeCoD7MklYZAuw" has-children="true" model-version="2" name="EasyAs" xmlns=""> <selection-mode method="ANY" plugin=""/> <child entity-type="ORGANIZATIONAL_UNIT" guid="_OAbNoCfHEeChutsy_vK9tg" has-children="true" model-version="2" name="ClaimsDepartment"> <selection-mode method="ANY" plugin=""/> </child> <child entity-type="ORGANIZATIONAL_UNIT" guid="_1HaTYCfLEeChutsy_vK9tg" has-children="true" model-version="2" name="TestDepartment"> <selection-mode method="ANY" plugin=""/> </child> </root-node> <root-node entity-type="GROUP" guid="_ZvVVsCfQEeChutsy_vK9tg" model-version="2" name="Managers" resource-count="0" xmlns=""> <selection-mode method="ANY" plugin=""/> </root-node> <root-node entity-type="GROUP" guid="_i1LeoCrrEeCEDr7D0P9b2w" model-version="2" name="CustomerServicesRepresentatives" resource-count="0" xmlns=""> <selection-mode method="ANY" plugin=""/> </root-node> </openOrgModelResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

364

| Chapter 15

BrowseModelService

Service Connector API (Java Method))

Method Service openOrgModel (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

browseModelNode 365

browseModelNode
Get details of a particular organization model entity and its children (for additional information about when this service operation would be used, see Navigating Large Organizations on page 110): The request must specify the organization model entity (node) for which details should be returned. The response returns details of the specified organization model entity and all of its immediate child entities. Note that this operation only includes those organizations (and sub-elements) to which the calling user has access (because of organization relationships). For more information, see Organization Relationships on page 123. Required System Action browseModel

Web Service API (SOAP Operation)

Request Parameter notes Uses the browseModelNode element (from the BrowseModelService schema) model-version: Use -1 (or omit the parameter) to specify the latest version of the organization model. Use listModelVersions to get a list of all major versions. entity-type and guid: Depending on the entity, the following operations can be used to obtain entity-type and GUID values: listOrgModelOverview, listOrganizations, listCapabilities, listPrivileges and lookupUser. Note that the browseModelNode element indicates that entity-type is a required parameter. However, you can omit entity-type and just identify the required organization model entity by its GUID. (This is because entity-type is defined within the XmlModelEntityId shared element. Its use is mandatory with other operations.) Response guid: Can be obtained with listOrgModelOverview, listOrganizations, listCapabilities, listPrivileges and lookupUser.

Returns a browseModelNodeResponse element (from the BrowseModelService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

366

| Chapter 15
Example

BrowseModelService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:browseModelNode model-version="-1" entity-type="ORGANIZATIONAL_UNIT" guid="_aT_UMCfLEeChutsy_vK9tg" qualifier=""/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <browseModelNodeResponse entity-type="ORGANIZATIONAL_UNIT" guid="_aT_UMCfLEeChutsy_vK9tg" has-children="true" model-version="2" name="HouseholdClaims" xmlns="http://browse.api.de.n2.tibco.com"> <selection-mode method="ANY" plugin="" xmlns=""/> <child entity-type="POSITION" guid="_aT_UMifLEeChutsy_vK9tg" ideal-number="10" model-version="2" name="CustomerServiceRepresentativeHousehold" resource-count="0" xmlns=""> <selection-mode method="ANY" plugin=""/> </child> <child entity-type="POSITION" guid="_aT_UMSfLEeChutsy_vK9tg" ideal-number="1" model-version="2" name="HouseholdClaimsManager" resource-count="0" xmlns=""> <selection-mode method="ANY" plugin=""/> </child> </browseModelNodeResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service browseModelNode (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

listOrgModelOverview 367

listOrgModelOverview
List details of every organization, organization unit, position, group and location defined in the organization model: The request can specify the major version of the organization model for which information should be returned. The response returns details of the organization, organization unit, position, group and location defined in the organization model. Note that this operation only includes those organizations (and sub-elements) to which the calling user has access (because of organization relationships). For more information, see Organization Relationships on page 123. Required System Action browseModel

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the listOrgModelOverview element (from the BrowseModelService schema) model-version: Use -1 (or omit the parameter) to specify the latest version of the organization model. Use listModelVersions to get a list of all major versions.

Returns a listOrgModelOverviewResponse element (from the BrowseModelService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

368

| Chapter 15
Example

BrowseModelService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:listOrgModelOverview model-version="2"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listOrgModelOverviewResponse xmlns="http://browse.api.de.n2.tibco.com"> <root-node entity-type="ORGANIZATION" guid="_tf5fgSe3EeCoD7MklYZAuw" model-version="2" name="EasyAs" xmlns=""> <selection-mode method="ANY" plugin=""/> <child entity-type="ORGANIZATIONAL_UNIT" guid="_OAbNoCfHEeChutsy_vK9tg" model-version="2" name="ClaimsDepartment"> <selection-mode method="ANY" plugin=""/> <child entity-type="ORGANIZATIONAL_UNIT" guid="_aT_UMCfLEeChutsy_vK9tg" model-version="2" name="HouseholdClaims"> <selection-mode method="ANY" plugin=""/> . . . <child entity-type="POSITION" guid="_2CRZICfLEeChutsy_vK9tg" ideal-number="1" model-version="2" name="TestManager" resource-count="0"> <selection-mode method="ANY" plugin=""/> </child> </child> </root-node> <root-node entity-type="GROUP" guid="_ZvVVsCfQEeChutsy_vK9tg" model-version="2" name="Managers" resource-count="0" xmlns=""> <selection-mode method="ANY" plugin=""/> </root-node> <root-node entity-type="GROUP" guid="_i1LeoCrrEeCEDr7D0P9b2w" model-version="2" name="CustomerServicesRepresentatives" resource-count="0" xmlns=""> <selection-mode method="ANY" plugin=""/> </root-node> </listOrgModelOverviewResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

listOrgModelOverview 369

Service Connector API (Java Method))

Method Service listOrgModelOverview (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

370

| Chapter 15

BrowseModelService

listCapabilities
List all the capabilities defined in the organizational model: The request must specify the major version of the organization model for which capabilities should be listed. The response returns details of all capabilities defined for the specified organization model version.

Required System Action browseModel

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the listCapabilities element (from the BrowseModelService schema) model-version: Use -1 (or omit the parameter) to specify the latest version of the organization model. Use listModelVersions to get a list of all major versions.

Returns a listCapabilitiesResponse element (from the BrowseModelService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

listCapabilities 371

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:listCapabilities model-version="2"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listCapabilitiesResponse xmlns="http://browse.api.de.n2.tibco.com"> <capability entity-type="CAPABILITY" guid="_FrCEcCfREeChutsy_vK9tg" model-version="2" name="Inhousemanagementtraining" xmlns=""/> <capability entity-type="CAPABILITY" guid="_JxFSkCrsEeCEDr7D0P9b2w" model-version="2" name="FrenchSpeaker" xmlns=""/> <capability entity-type="CAPABILITY" guid="_NlKBICrsEeCEDr7D0P9b2w" model-version="2" name="SignoffWork" xmlns=""/> </listCapabilitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method))

Method Service listCapabilities (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

372

| Chapter 15

BrowseModelService

listPrivileges
List all the privileges defined in the organizational model: The request must specify the major version of the organization model for which privileges should be listed. The response returns details of all privileges defined for the specified organization model version.

Required System Action browseModel

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the listPrivileges element (from the BrowseModelService schema) model-version: Use -1 (or omit the parameter) to specify the latest version of the organization model. Use listModelVersions to get a list of all major versions.

Returns a listPrivilegesResponse element (from the BrowseModelService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

listPrivileges 373

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:listPrivileges model-version="2"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listPrivilegesResponse xmlns="http://browse.api.de.n2.tibco.com"> <privilege entity-type="PRIVILEGE" guid="_g7EMECheEeC2gpNnCloTog" model-version="2" name="AuthorizeClaims" xmlns=""> <qualifier-desc default-value="" description="" guid="_3o1kgCheEeC2gpNnCloTog" model-version="2" type="Integer"/> </privilege> </listPrivilegesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method))

Method Service listPrivileges (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

374

| Chapter 15

BrowseModelService

getCapabilities
Get the capabilities associated with a specific organization model entity: The request must specify the organization model entity for which capabilities should be listed. The response returns details of all capabilities associated with the specified organization model entity.

Required System Action browseModel

Web Service API (SOAP Operation)

Request Parameter notes Uses the getCapabilities element (from the BrowseModelService schema) model-version: Use -1 (or omit the parameter) to specify the latest version of the organization model. Use listModelVersions to get a list of all major versions. entity-type and guid: Note that the getCapabilities element indicates that entity-type is a required parameter. However, you can omit entity-type and just identify the required organization model entity by its GUID. (This is because entity-type is defined within the XmlModelEntityId shared element. Its use is mandatory with other operations.) Pass the GUID for a group or position to get the capabilities that resources mapped to those groups or positions should possess (it is not enforced). Pass the GUID for a resource to get the capabilities possessed by the resource. You can obtain GUIDs for groups, positions, and resources using listOrgModelOverview, openOrgModel, and lookupUser. Response qualifier: Does not apply to this operation.

Returns a getCapabilitiesResponse element (from the BrowseModelService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

getCapabilities 375

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:getCapabilities model-version="-1" guid="D4E3C720-5500-4651-B105-6C60C613E226"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getCapabilitiesResponse xmlns="http://browse.api.de.n2.tibco.com"> <capability entity-type="CAPABILITY" guid="_BJKvUMpQEd64gM7QE8RwxA" model-version="3" name="Degree" xmlns=""> <qualifierSet value="MBA"/> </capability> <capability entity-type="CAPABILITY" guid="_ax1rQMpTEd64gM7QE8RwxA" model-version="3" name="ManagementTrainingLevel" xmlns=""> <qualifierSet value="Senior"/> </capability> <capability entity-type="CAPABILITY" guid="_xI4ikMpPEd64gM7QE8RwxA" model-version="3" name="CanTravel" xmlns=""/> </getCapabilitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method))

Method Service getCapabilities (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

376

| Chapter 15

BrowseModelService

getPrivileges
Get the privileges associated with a specific organization model entity: The request must specify the organization model entity for which privileges should be listed. The response returns details of all privileges associated with the specified organization model entity.

Required System Action browseModel

Web Service API (SOAP Operation)

Request Parameter notes Uses the getPrivileges element (from the BrowseModelService schema) model-version: Use -1 (or omit the parameter) to specify the latest version of the organization model. Use listModelVersions to get a list of all major versions. entity-type and guid: Note that the getPrivileges element indicates that entity-type is a required parameter. However, you can omit entity-type and just identify the required organization model entity by its GUID. (This is because entity-type is defined within the XmlModelEntityId shared element. Its use is mandatory with other operations.) Pass the GUID for an organization unit, position, or group to get the privileges assigned to those entitiesresources mapped to those entities inherit the assigned privileges. Pass the GUID for a resource to get the privileges possessed by the resource. You can obtain GUIDs for organization units, positions, groups, and resources using listOrgModelOverview, openOrgModel, and lookupUser. Response qualifier: Does not apply to this operation.

Returns a getPrivilegesResponse element (from the BrowseModelService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

getPrivileges 377

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:getPrivileges model-version="-1" guid="_v2ro8MpREd64gM7QE8RwxA" /> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getPrivilegesResponse xmlns="http://browse.api.de.n2.tibco.com"> <privilege entity-type="PRIVILEGE" guid="_CTAasF-JEd-rno5lLiXABg" model-version="3" name="SuperviseSalesManagers" xmlns=""/> <privilege entity-type="PRIVILEGE" guid="_80Y14F-IEd-rno5lLiXABg" model-version="3" name="SuperviseITManagers" xmlns=""/> <privilege entity-type="PRIVILEGE" guid="_HIl0IF-KEd-rno5lLiXABg" model-version="3" name="SuperviseVPs" xmlns=""/> <privilege entity-type="PRIVILEGE" guid="_M1FR8MpSEd64gM7QE8RwxA" model-version="3" name="SuperviseCSManagers" xmlns=""/> </getPrivilegesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method))

Method Service getPrivileges (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

378

| Chapter 15

BrowseModelService

listOrganizations
Get a list of all organizations that have been deployed: The request takes no parameters. The response returns a list of all organizations that have been deployed (that is, organization model entities with an entity-type of ORGANIZATION).

Required System Action browseModel

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the listOrganizations element (from the BrowseModelService schema) The <dummy> element is a placeholderits value is not referenced. Returns a listOrganizationsResponse element (from the BrowseModelService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

listOrganizations 379

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:brow="http://browse.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <brow:listOrganizations> <dummy>false</dummy> </brow:listOrganizations> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listOrganizationsResponse xmlns="http://browse.api.de.n2.tibco.com"> <Organizations entity-type="ORGANIZATION" guid="_iPYXscpPEd64gM7QE8RwxA" model-version="3" name="Acme" xmlns=""/> <Organizations entity-type="ORGANIZATION" guid="_5fLygDBSEd-x4cVy01Xlww" model-version="3" name="ReardenSteel" xmlns=""/> <Organizations entity-type="ORGANIZATION" guid="_-SS8MDBSEd-x4cVy01Xlww" model-version="3" name="TaggartTranscontinental" xmlns=""/> <Organizations entity-type="ORGANIZATION" guid="_jGi_kcxxEd-nOYM9N6WPrw" model-version="1" name="Organization1" xmlns=""/> <Organizations entity-type="ORGANIZATION" guid="_tf5fgSe3EeCoD7MklYZAuw" model-version="2" name="EasyAs" xmlns=""/> </listOrganizationsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method))

Method Service listOrganizations (args) BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

380

| Chapter 15

BrowseModelService

TIBCO ActiveMatrix BPM - BPM Developers Guide

BusinessDeadlineService 381

Chapter 16

BusinessDeadlineService

BusinessDeadlineService is one of the Calendar Services provided by Work Manager. Use BusinessDeadlineService requests to calculate the deadline for completing a specified task, based on a given calendar. Note that all times passed are taken to be time-zone-neutral: that is, the API assumes that all times are in UTC format.

Topics
calcBusinessDeadline, page 382

TIBCO ActiveMatrix BPM - BPM Developers Guide

382

| Chapter 16

BusinessDeadlineService

calcBusinessDeadline
Calculate the business deadline based on the working time for a given calendar. The request must specify the GUID of the calendar from which working day details are to be taken. This information about working time is used to calculate the deadline, along with the start and duration of the requested task. The calendarLookAhead property in the dac.properties file determines how far ahead in the calendar the calculation algorithm looks to take account of entries that would affect the duration of a task. See "Configuring TIBCO ActiveMatrix BPM Deadline and Calendar Properties" in the TIBCO ActiveMatrix BPM Administration guide for details of this property. The response returns the calculated end date based on the specified calendar's working time.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

calcBusinessDeadline 383

Web Service API (SOAP Operation)

Request Parameter notes Uses the calcBusinessDeadline element (from the BusinessDeadlineService schema) guid: the GUID of the calendar which supplies the working day information to be used. The only supported value is SYSTEM. See CalendarService for more information about setting up and updating working times on the calendar. start-date-time: the date and time when the task begins. duration: the duration of the task, expressed in standard XSD notation.

Response Example

Returns a calcBusinessDeadlineResponse element (from the BusinessDeadlineService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dead="http://deadline.api.dac.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <dead:calcBusinessDeadline guid="SYSTEM" start-date-time="2011-08-01T09:00:00" duration="P3DT4H"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <calcBusinessDeadlineResponse end-date-time="2011-08-13T12:00:00.000Z" xmlns="http://deadline.api.dac.n2.tibco.com"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service calcBusinessDeadline (args) BusinessDeadlineService

TIBCO ActiveMatrix BPM - BPM Developers Guide

384

| Chapter 16

BusinessDeadlineService

TIBCO ActiveMatrix BPM - BPM Developers Guide

BusinessService 385

Chapter 17

BusinessService

BusinessService is one of the Business Services provided by Work Manager. Use BusinessService operations to get information about and interact with deployed business services.

Topics
listCategories, page 386 queryCategories, page 389 listBusinessServices, page 391 queryBusinessServices, page 394 startBusinessService, page 396 updateBusinessService, page 399 injectBusinessServiceEvent, page 402 cancelBusinessService, page 407

TIBCO ActiveMatrix BPM - BPM Developers Guide

386

| Chapter 17

BusinessService

listCategories
List categories of all deployed business services. The request requests a list of the categories of all deployed business services. If you specify the filter channelId, the request requests a list of categories for all deployed business services for the specified channel. The response returns the detailed descriptions of the categories of the deployed business services. The parameter includeFormalParameters determines whether the categories of deployed business services that have formal parameters are listed or not. See Parameter notes for details.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

listCategories 387

Web Service API (SOAP Operation)

Request Parameter notes Uses the listCategories element (from the BusinessService schema) includeFormalParameters: determines if the response includes categories with formal parameters. By default, response lists the categories without formal parameters (false). When set to true, the response includes all the categories with formal parameters as well. channelId: when specified, only the deployed business services for the specified channel are listed. getTotalCount: total number of categories listed in the response. numberOfItems: maximum number of items (categories) that the response message can contain. startPosition: start position in the list of the first item on the response returned to the user. The list is zero-based. To start at the first item, specify 0.

Response Example

Returns a listCategoriesResponse element (from the BusinessService schema) Request:

<soapenv:Body> <bus:listCategories getTotalCount="true" numberOfItems="10" startPosition="0"> </bus:listCategories> </soapenv:Body>

Response:
<SOAP-ENV:Body> <listCategoriesResponse xmlns="http://business.api.busserv.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <totalItems xmlns="">2</totalItems> <Category name="WelcomeCustomer" xmlns=""> <ChildCategory name="WCProcessPackage"/> </Category> <Category name="WelcomeUsersImplementSolution" xmlns=""> <ChildCategory name="ProcessPackage"/> </Category> </listCategoriesResponse> </SOAP-ENV:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

388

| Chapter 17

BusinessService

Service Connector API (Java Method)

Method Service listCategories (args) BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryCategories 389

queryCategories
Query categories of all deployed business services. The request requests a list of all the deployed business services. Optionally, the request can specify a filter based on the Category and ChannelId. The response returns detailed descriptions of the categories of deployed business services.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

390

| Chapter 17

BusinessService

Web Service API (SOAP Operation)

Request Parameter notes Uses the queryCategories element (from the BusinessService schema) includeFormalParameters: determines if the response includes categories with formal parameters. By default, response lists the categories without formal parameters (false). When set to true, the response includes all the categories with formal parameters as well. If you are using wild cards to specify the filter based on category or channelId, note that the wildcard character * cannot be the only and/or the last character in the search string. For example, to search for all categories, the search string to be specified is **. To search for all categories under Category1, the search string to be specified is Category1/**.

Response Example

Returns a queryCategoriesResponse element (from the BusinessService schema) Request:

<soapenv:Body> <bus:queryCategories> <category>Category1/**</category> </bus:queryCategories> </soapenv:Body>

Response:
<SOAP-ENV:Body> <queryCategoriesResponse xmlns="http://business.api.busserv.n2.tibco.com"> <businessCategory name="Category1" xmlns=""> <ChildBusinessCategory name="SubCategory"> <BusinessServiceTemplate moduleName="/SanityProcesses/Sanity Tests/SanityTests.xpdl" processName="SanityTestsStartEvent" version="1.0.0.201107041448"/> </ChildBusinessCategory> </businessCategory> </queryCategoriesResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service queryCategories (args) BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

listBusinessServices 391

listBusinessServices
Lists all the deployed business services. The request requests a list of all the deployed business services. Optionally, the request can specify a filter based on the ChannelId. The response returns detailed descriptions of all the deployed business services. The parameter includeFormalParameters determines whether deployed business services that have formal parameters are listed or not. See Parameter notes for details. If the parameter includeFormalParameters is not specified, only the deployed business services that do not have formal parameters are listed.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

392

| Chapter 17

BusinessService

Web Service API (SOAP Operation)

Request Parameter notes Uses the listBusinessServices element (from the BusinessService schema) includeFormalParameters: determines if the response includes the business services with formal parameters. By default, the value is set to false and the response lists the business services without formal parameters. When set to true, the response includes the business services with formal parameters as well. getTotalCount: total number of business services listed in the response. numberOfItems: maximum number of items (business services) that the response message can contain. startPosition: start position in the list of the first item on the response returned to the user. The list is zero-based. To start at the first item, specify 0.

Response Example

Returns a listBusinessServicesResponse element (from the BusinessService schema) Request:

<soapenv:Body> <bus:listBusinessServices getTotalCount="true" numberOfItems="2" startPosition="0"> </bus:listBusinessServices> </soapenv:Body>

Response:
<SOAP-ENV:Body> <listBusinessServicesResponse xmlns="http://business.api.busserv.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <totalItems xmlns="">2</totalItems> <businessCategory name="Category1" xmlns=""> <ChildBusinessCategory name="SubCategory"> <BusinessServiceTemplate moduleName="/SanityProcesses/Sanity Tests/SanityTests.xpdl" processName="SanityTestsStartEvent" version="1.0.0.201107041448"/> </ChildBusinessCategory> </businessCategory> <businessCategory name="InjectBS" xmlns=""> <ChildBusinessCategory name="InjectBS"> <BusinessServiceTemplate moduleName="/InjectBS/Process Packages/InjectBS.xpdl" processName="ProcessPackageStartEvent" version="1.0.0.201107121100"/> </ChildBusinessCategory> </businessCategory> </listBusinessServicesResponse> </SOAP-ENV:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

listBusinessServices 393

Service Connector API (Java Method)

Method Service listBusinessServices (args) BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

394

| Chapter 17

BusinessService

queryBusinessServices
Queries all the deployed business services. The request requests a list of all the deployed business services for a specified category. Optionally, the request can specify a filter based on the channelId. The response returns detailed descriptions of all the deployed business services for the specified. If a filter is specified, the response contains the list of deployed business services that fulfil the order filter criteria.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryBusinessServices 395

Web Service API (SOAP Operation)

Request Parameter notes Uses the queryBusinessServices element (from the BusinessService schema) If you are using wildcards to specify the filter based on category or channelId, note that the wildcard character * cannot be the only and/or the last character in the search string. For example, to search for all categories, the search string to be specified is **. To search for all categories under Category1, the search string to be specified is Category1/**.

Response Example

Returns a queryBusinessServicesResponse element (from the BusinessService schema) Request:

<soapenv:Body> <bus:queryBusinessServices> <category>**</category> </bus:queryBusinessServices> </soapenv:Body>

Response:
<SOAP-ENV:Body> <queryBusinessServicesResponse xmlns="http://business.api.busserv.n2.tibco.com"> <businessServiceTemplate moduleName="/WelcomeCustomer/Process Packages/WCProcessPackage.xpdl" processName="WCRequestCall" version="1.0.0.201107201543" xmlns=""/> <businessServiceTemplate moduleName="/WelcomeUsersImplementSolution/Process Packages/ProcessPackage.xpdl" processName="RequestCall" version="1.0.0.201107281325" xmlns=""/> </queryBusinessServicesResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service queryBusinessServices (args) BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

396

| Chapter 17

BusinessService

startBusinessService
Starts an instance of a deployed business service. The request identifies the business service of which you want to start an instance. You can optionally specify the payload mode and provide the payload in the request message. The response returns the complete information about the started business service instance and the execution state is set to IN_PROGRESS.

Required System Action startBusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

startBusinessService 397

Web Service API (SOAP Operation)

Request Parameter notes Uses the startBusinessService element (from the BusinessService schema). Response Example businessServiceDefinition: can be obtained from listBusinessServices. It consists of the moduleName, processName, and version of the specified business service. formalParams: details of formal parameters used. You must obtain this information directly from the relevant project in TIBCO Business Studio. responseFeedType: specifies the feed type expected in the response. The value can be one of XML or JSON. cacheTimeout: specifies the time to wait for the specified business service to start.

Returns a startBusinessServiceResponse element (from the BusinessService schema) Request:

<soapenv:Body> <bus:startBusinessService> <businessServiceDefinition moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestCall" version="1.0.0.201108111516"/> </bus:startBusinessService> </soapenv:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

398

| Chapter 17

BusinessService

Response:
<SOAP-ENV:Body> <startBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestCall" version="1.0.0.201108111516"/> <processReference> <id>pvm:0a101o</id> <name>RequestCall</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g1o.3" activityModelId="_qTxqOlnREd-qRKl4nKSPqA" activityName="CollectData" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" moduleVersion="1.0.0.201108111516" processName="RequestCall"/> <payload payloadMode="XML"> <XmlPayload> <inouts array="false" name="UserName" optional="true" type="String"> <simpleSpec/> </inouts> <inouts array="false" name="PhoneNumber" optional="true" type="String"> <simpleSpec/> </inouts> </XmlPayload> </payload> </pageData> </pageResponse> </startBusinessServiceResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service startBusinessService (args) BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

updateBusinessService 399

updateBusinessService
Updates the specified business service instance. The request identifies the business service instance to be updated. You can optionally specify the payload mode and provide the payload in the request message. The response returns the complete information about the updated business service.

Required System Action startBusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

400

| Chapter 17

BusinessService

Web Service API (SOAP Operation)

Request Parameter notes Uses the updateBusinessService element (from the BusinessService schema) Response Example process reference id: ID returned when you start a business service. You can obtain the value from the response returned by startBusinessService. activityId: the activity ID returned when you start a business service. You can obtain the value from the response returned by startBusinessService. If your process has mandatory parameters, ensure that you provide valid values for all these parameters.

Returns a updateBusinessServiceResponse element (from the BusinessService schema) Request:

<soapenv:Body> <bus:updateBusinessService> <context> <processReference> <id>pvm:0a101s</id> </processReference> <activityReference activityId="pvm:001g1s.3"/> </context> <pageFields payloadMode="XML"> <XmlPayload> <inouts array="false" name="UserName" optional="true" type="String"> <simpleSpec> <value>TIB_USER</value> </simpleSpec> </inouts> <inouts array="false" name="PhoneNumber" optional="true" type="String"> <simpleSpec> <value>987654321</value> </simpleSpec> </inouts> </XmlPayload> </pageFields> <responsePayloadMode>XML</responsePayloadMode> </bus:updateBusinessService> </soapenv:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

updateBusinessService 401

Response:
<SOAP-ENV:Body> <updateBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="COMPLETED" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestCall" version="1.0.0.201108111516"/> <processReference> <id>pvm:0a101s</id> <name>RequestCall</name> </processReference> </context> <pageData> <payload payloadMode="XML"> <XmlPayload xmlns:bus="http://business.api.busserv.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <inouts array="false" name="UserName" optional="true" type="String"> <simpleSpec> <value>TIB_USER</value> </simpleSpec> </inouts> <inouts array="false" name="PhoneNumber" optional="true" type="String"> <simpleSpec> <value>987654321</value> </simpleSpec> </inouts> </XmlPayload> </payload> </pageData> </pageResponse> </updateBusinessServiceResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service updateBusinessService (args) BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

402

| Chapter 17

BusinessService

injectBusinessServiceEvent
Injects an event into a business service whose execution state is IN_PROGRESS. The request identifies the event to be injected into the given business service and specifies the formal parameter value(s) that is to be injected. The response returns complete information about the injected business service instance.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

injectBusinessServiceEvent 403

Web Service API (SOAP Operation)

Request Parameter notes Uses the injectBusinessServiceEvent element (from the BusinessService schema) eventDefinition: It consists of the moduleName, processName, eventName, and processInstanceId of the specified business service. You can obtain the values for these parameters from the response returned by startBusinessService or updateBusinessService operations. formalParams: values for the formal parameters that you want to inject.

Response

Returns a injectBusinessServiceEventResponse element (from the BusinessService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

404

| Chapter 17
Example

BusinessService

Request:
<soapenv:Body> <bus:injectBusinessServiceEvent> <eventDefinition moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" eventName="IntermediateEvent" processInstanceId="pvm:0a10a"/> <formalParams payloadMode="XML"> <XmlPayload> <inputs array="false" name="Parameter" optional="false" type="String"> <simpleSpec length="50"> <value>Tibco</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter2" optional="false" type="Integer Number"> <simpleSpec length="9"> <value>147</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter3" optional="false" type="Decimal Number"> <simpleSpec decimal="2" length="10"> <value>3.14</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter4" optional="false" type="Boolean"> <simpleSpec> <value>false</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter5" optional="false" type="Date"> <simpleSpec> <value>2012-02-29</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter6" optional="false" type="Time"> <simpleSpec> <value>09:30:10.5</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter7" optional="false" type="Date Time"> <simpleSpec> <value>2009-04-06%2002-05-30T09:30:10Z</value> </simpleSpec> </inputs> </XmlPayload> </formalParams> <responsePayloadMode>XML</responsePayloadMode> </bus:injectBusinessServiceEvent> </soapenv:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

injectBusinessServiceEvent 405

Response:
<SOAP-ENV:Body> <injectBusinessServiceEventResponse xmlns="http://business.api.busserv.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess" version="1.0.0.201108111140"/> <processReference> <id>pvm:0a10a</id> <name>EventHandlerProcess</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001ga.f" activityModelId="_tM7ysL0REeCCNPLAO2IuzQ" activityName="UserTask3" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" moduleVersion="1.0.0.201108111140" processName="EventHandlerProcess"/> <payload payloadMode="XML"> <XmlPayload> <inputs array="false" name="Parameter" optional="true" type="String"> <simpleSpec> <value>[Ljava.lang.String;@6092c80d</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter2" optional="true" type="Integer Number"> <simpleSpec> <value>[Ljava.lang.String;@740ee811</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter3" optional="true" type="Decimal Number"> <simpleSpec> <value>[Ljava.lang.String;@7ea5ef9d</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter4" optional="true" type="Boolean"> <simpleSpec> <value>[Ljava.lang.String;@40166d60</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter5" optional="true" type="Date"> <simpleSpec> <value>[Ljava.lang.String;@66da7f</value> </simpleSpec> </inputs> <!-- Response continued -->

TIBCO ActiveMatrix BPM - BPM Developers Guide

406

| Chapter 17

BusinessService

<!-- Continued --> <inputs array="false" name="Parameter6" optional="true" type="Time"> <simpleSpec> <value>[Ljava.lang.String;@448bff03</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter7" optional="true" type="Date Time"> <simpleSpec> <value>[Ljava.lang.String;@4313411d</value> </simpleSpec> </inputs> </XmlPayload> </payload> </pageData> </pageResponse> </injectBusinessServiceEventResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service injectBusinessServiceEvent (args) BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

cancelBusinessService 407

cancelBusinessService
Cancels a given business service instance. The request identifies the instance Id of the business service to be cancelled. The response returns the execution status - SUCCESS when the pageflow is cancelled successfully and a service fault if the execution fails.

Required System Action None.

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the cancelBusinessService element (from the BusinessService schema) processInstanceId: the process instance ID returned when you start a business service. You can obtain the value from the response returned by startBusinessService.

Returns a cancelBusinessServiceResponse element (from the BusinessService schema) Request:

<soapenv:Body> <bus:cancelBusinessService> <processInstanceId>pvm:0a101o</processInstanceId> </bus:cancelBusinessService> </soapenv:Body>

Response:
<SOAP-ENV:Body> <cancelBusinessServiceResponse xmlns="http://business.api.busserv.n2.tibco.com"> <status xmlns="">SUCCESS</status> </cancelBusinessServiceResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service cancelBusinessService (args) BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

408

| Chapter 17

BusinessService

TIBCO ActiveMatrix BPM - BPM Developers Guide

CalendarService 409

Chapter 18

CalendarService

CalendarService is one of the Calendar Services provided by Work Manager. Use CalendarService requests to get information about and configure working time. Note that: Only one calendar is supported. This is a system-wide calendar with a GUID of "SYSTEM". All start and end times passed are taken to be time-zone-neutral: that is, the API assumes that all times are in UTC format.

Topics
updateWorkingDays, page 410 addWorkingDayExceptions, page 414 updateWorkingDayExceptions, page 417 deleteWorkingDayExceptions, page 420 getCalendarEntries, page 422

TIBCO ActiveMatrix BPM - BPM Developers Guide

410

| Chapter 18

CalendarService

updateWorkingDays
Specify the working days for a particular calendar. The request must specify the GUID of the calendar for which working day details are to be modified and the new working day information. The working day information specified in the request completely replaces the existing working day information (for the specified calendar). The response returns a confirmation that the request was successful.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

updateWorkingDays 411

Web Service API (SOAP Operation)

Request Parameter notes Uses the updateWorkingDays element (from the CalendarService schema) guid: the GUID of the calendar for which the working day information is being specified. The only supported value is SYSTEM. day-of-week: Up to seven entries. Each is the name of one day of the week in abbreviated form: MO, TU, WE, TH, FR, SA, SU. time slot start and end: Up to five entries, giving the start and end times of a working period within the specified day. Morning and afternoon separated by a meal break, for example, would be two time slots. Specify times as hh:mm:ss. All times are taken as UTC.

Response

Returns an updateWorkingDaysResponse element (from the CalendarService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

412

| Chapter 18
Example

CalendarService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://calendar.api.dac.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <cal:updateWorkingDays guid="SYSTEM"> <!--0 to 7 repetitions:--> <working-day day-of-week="MO"> <!--0 to 5 repetitions:--> <time-slot start="09:00:00" end="13:00:00"/> <time-slot start="14:00:00" end="17:30:00"/> </working-day> <working-day day-of-week="TU"> <time-slot start="09:00:00" end="13:00:00"/> <time-slot start="14:00:00" end="17:30:00"/> </working-day> <working-day day-of-week="WE"> <time-slot start="09:00:00" end="13:00:00"/> <time-slot start="14:00:00" end="17:30:00"/> </working-day> <working-day day-of-week="TH"> <time-slot start="09:00:00" end="13:00:00"/> <time-slot start="14:00:00" end="17:30:00"/> </working-day> <working-day day-of-week="FR"> <time-slot start="09:00:00" end="13:00:00"/> </working-day> <working-day day-of-week="SA"> <time-slot start="09:00:00" end="13:00:00"/> </working-day> </cal:updateWorkingDays> </soapenv:Body> </soapenv:Envelope> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <updateWorkingDaysResponse xmlns="http://calendar.api.dac.n2.tibco.com">OK</updateWorkingDaysResp onse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

updateWorkingDays 413

Service Connector API (Java Method)

Method Service updateWorkingDays (args) CalendarService

TIBCO ActiveMatrix BPM - BPM Developers Guide

414

| Chapter 18

CalendarService

addWorkingDayExceptions
Add working day exceptions for a given calendar. The request must specify the GUID of the calendar for which working day exception details are to be created, and the new working day exception information. The response returns a list of GUIDs, one for each newly created working day exception. You can use these IDs to identify the exceptions in future updateWorkingDayExceptions and deleteWorkingDayExceptions operations.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

addWorkingDayExceptions 415

Web Service API (SOAP Operation)

Request Parameter notes Uses the addWorkingDayExceptions element (from the CalendarService schema) guid: the ID of the calendar for which exception information is being entered. The only supported value is SYSTEM. add-exceptions: a list of the exceptions being added. Each one includes: description: a string giving a free-text description of the exception, such as "Annual leave" or "Public holiday". all-day: (optional) whether the exception takes up the whole of normal working hours on the day (or days) specified. Defaults to "false". This is given for information only, and is not validated against the start and end times given. start and end: dates and times for the start or end of the exception. All times are taken as UTC. free-busy: whether the exception is available working time (FREE) or is time unavailable for working (BUSY). The only supported value is BUSY. Response Example Returns an addWorkingDayExceptionsResponse element (from the CalendarService schema). This contains a list of IDs of the exceptions that have been added. Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://calendar.api.dac.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <cal:addWorkingDayExceptions guid="SYSTEM"> <!--1 or more repetitions:--> <add-exceptions description="Public Holiday" all-day="true" start="2011-12-26T00:00:00" end="2011-12-26T23:59:59" free-busy="BUSY"/> </cal:addWorkingDayExceptions> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <addWorkingDayExceptionsResponse xmlns="http://calendar.api.dac.n2.tibco.com"> <add-exceptions xmlns="">A25D05C7-E656-400C-A84F-F8DF41FE73DF</add-exceptions> </addWorkingDayExceptionsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

416

| Chapter 18

CalendarService

Service Connector API (Java Method)

Method Service addWorkingDayExceptions (args) CalendarService

TIBCO ActiveMatrix BPM - BPM Developers Guide

updateWorkingDayExceptions 417

updateWorkingDayExceptions
Update working day exceptions for a given calendar. The request must specify: the GUID of the calendar for which working day exception details are to be modified the GUIDs of the exceptions to be updated, and the information being updated for each one. The response returns a confirmation that the request was successful.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

418

| Chapter 18

CalendarService

Web Service API (SOAP Operation)

Request Parameter notes Uses the updateWorkingDayExceptions element (from the CalendarService schema) guid: the ID of the calendar for which the exception information is being updated. The only supported value is SYSTEM. update-exceptions: one or more exceptions to be updated. In each case the guid of the exception is mandatory. You can obtain this from the response to the addWorkingDayExceptions operation that created the exception. Other informationdescription, all-day, start, end, and free-busyis optional. You need specify only the information that is changing for each exception. See addWorkingDayExceptions for details of these parameters. Response Example Returns an updateWorkingDayExceptionsResponse element (from the CalendarService schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://calendar.api.dac.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <cal:updateWorkingDayExceptions guid="SYSTEM"> <!--1 or more repetitions:--> <update-exceptions guid="A25D05C7-E656-400C-A84F-F8DF41FE73DF" all-day="false" start="2011-12-26T12:00:00" end="2011-12-26T18:00:00"/> </cal:updateWorkingDayExceptions> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <updateWorkingDayExceptionsResponse xmlns="http://calendar.api.dac.n2.tibco.com">OK</updateWorkingDayExcep tionsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method updateWorkingDayExceptions (args)

TIBCO ActiveMatrix BPM - BPM Developers Guide

updateWorkingDayExceptions 419

Service

CalendarService

TIBCO ActiveMatrix BPM - BPM Developers Guide

420

| Chapter 18

CalendarService

deleteWorkingDayExceptions
Delete working day exceptions for a given calendar. The request must specify the GUID of the calendar for which working day exception details are to be removed and the GUIDs identifying those exceptions. The response returns a confirmation that the request was successful.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

deleteWorkingDayExceptions 421

Web Service API (SOAP Operation)

Request Parameter notes Uses the deleteWorkingDayExceptions element (from the CalendarService schema) guid: the ID of the calendar from which the exception is being deleted. The only supported value is SYSTEM. delete-exceptions: a list of IDs of the exceptions to be deleted. You can obtain these IDs from the response to the addWorkingDayExceptions operation that created the exception.

Response Example

Returns a deleteWorkingDayExceptionsResponse element (from the CalendarService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://calendar.api.dac.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <cal:deleteWorkingDayExceptions guid="SYSTEM"> <!--1 or more repetitions:--> <delete-exceptions>A25D05C7-E656-400C-A84F-F8DF41FE73DF</delete-except ions> </cal:deleteWorkingDayExceptions> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <deleteWorkingDayExceptionsResponse xmlns="http://calendar.api.dac.n2.tibco.com">OK</deleteWorkingDayExcep tionsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service deleteWorkingDayExceptions (args) CalendarService

TIBCO ActiveMatrix BPM - BPM Developers Guide

422

| Chapter 18

CalendarService

getCalendarEntries
Get the working time for a given calendar. The request must specify the GUID of the calendar from which working time details are required, with an optional filter on the response to be provided. The response returns a complete description of working time for the specified calendar.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

getCalendarEntries 423

Web Service API (SOAP Operation)

Request Parameter notes Uses the getCalendarEntries element (from the CalendarService schema) guid: the ID of the calendar for which information is required. The only value supported is SYSTEM. start-date-time and end-date-time: start and end time filters for the information to be returned. All times are taken as UTC. This parameter is required if FREE_BUSY is specified in the required-detail filter. In other circumstances it is optional required-detail: (optional): a filter to enhance the detail of the information returned. Can be: WORKING_WEEK: Include working day details in the response. FREE_BUSY: Include working day exceptions in the response. The full properties of the exception, including its GUID and free-busy value, are returned. See addWorkingDayExceptions for these properties. Response Returns a getCalendarEntriesResponse element (from the CalendarService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

424

| Chapter 18
Example

CalendarService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://calendar.api.dac.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <cal:getCalendarEntries guid="SYSTEM" start-date-time="2011-08-01T09:00:00" end-date-time="2012-08-15T18:00:00"> <!--Zero or more repetitions:--> <required-detail>FREE_BUSY</required-detail> <required-detail>WORKING_WEEK</required-detail> </cal:getCalendarEntries> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getCalendarEntriesResponse daylight-savings="true" time-zone="Europe/London" xmlns="http://calendar.api.dac.n2.tibco.com"> <working-days day-of-week="MO" xmlns=""> <time-slot end="13:00:00.000Z" start="09:00:00.000Z"/> <time-slot end="17:30:00.000Z" start="14:00:00.000Z"/> </working-days> <working-days day-of-week="TU" xmlns=""> <time-slot end="13:00:00.000Z" start="09:00:00.000Z"/> <time-slot end="17:30:00.000Z" start="14:00:00.000Z"/> </working-days> <working-days day-of-week="WE" xmlns=""> <time-slot end="13:00:00.000Z" start="09:00:00.000Z"/> <time-slot end="17:30:00.000Z" start="14:00:00.000Z"/> </working-days> <working-days day-of-week="TH" xmlns=""> <time-slot end="13:00:00.000Z" start="09:00:00.000Z"/> <time-slot end="17:30:00.000Z" start="14:00:00.000Z"/> </working-days> <working-days day-of-week="FR" xmlns=""> <time-slot end="13:00:00.000Z" start="09:00:00.000Z"/> </working-days> <working-days day-of-week="SA" xmlns=""> <time-slot end="13:00:00.000Z" start="09:00:00.000Z"/> </working-days> <working-day-exceptions all-day="true" description="Public Holiday" end="2011-12-27T23:59:59.999Z" free-busy="BUSY" guid="927D8BEB-143B-48B9-8FFF-FEE1A6621D01" start="2011-12-26T00:00:00.000Z" xmlns=""/> </getCalendarEntriesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getCalendarEntries 425

Service Connector API (Java Method)

Method Service getCalendarEntries (args) CalendarService

TIBCO ActiveMatrix BPM - BPM Developers Guide

426

| Chapter 18

CalendarService

TIBCO ActiveMatrix BPM - BPM Developers Guide

ContainerService 427

Chapter 19

ContainerService

ContainerService is one of the Directory Services provided by Work Manager. Use ContainerService requests to manage LDAP containers.

Topics
listLDAPContainers, page 428 getLDAPContainerDetail, page 430 saveLDAPContainerDetail, page 432 deleteLDAPContainer, page 435

TIBCO ActiveMatrix BPM - BPM Developers Guide

428

| Chapter 19

ContainerService

listLDAPContainers
List details of all currently configured LDAP containers to which the caller has access. (Access can be restricted if the caller was created in an LDAP container that has a relationship set up with an organizationfor more information, see Organization Relationships on page 123.) The request takes no parameters. The response returns details of configured LDAP containers.

Required System Action resourceAdmin and/or LDAPAdmin1

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the listLDAPContainers element (from the ContainerService schema) No parameters are required for this request. (The empty element is a placeholderits value is not referenced.) Returns a listLDAPContainersResponse element (from the ContainerService schema)

1. This operation can be called by users possessing either the resourceAdmin or LDAPAdmin system action. The LDAPAdmin system action gives the user additional access to organizations that are restricted due to organization relationships. For more information, see Overriding Organization Relationships on page 124.
TIBCO ActiveMatrix BPM - BPM Developers Guide

listLDAPContainers 429

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://container.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <con:listLDAPContainers> <empty>0</empty> </con:listLDAPContainers> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listLDAPContainersResponse xmlns="http://container.api.de.n2.tibco.com"> <ldap-container active="true" description="" entity-count="8" id="1" last-accessed="2011-07-15T20:52:04.377Z" name="easyAs" xmlns=""> <primary-ldap display-name-attributes="ou" guid="0FFC620C-31FC-4687-94A8-08E9F7F07D89" id="1" ldap-alias="easyAs" ldap-search-string="(objectClass=organizationalPerson)"/> </ldap-container> <ldap-container active="true" id="51" name="local" xmlns=""> <primary-ldap base-dn="OU=employees" display-name-attributes="displayname" guid="6F4B63DF-FD44-4605-B709-40B4E5EFF7C3" id="51" ldap-alias="local" ldap-search-string="(objectClass=person)"/> </ldap-container> . . . </listLDAPContainersResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service listLDAPContainers (args) ContainerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

430

| Chapter 19

ContainerService

getLDAPContainerDetail
List details of a specific LDAP container: The request must specify the unique ID of the LDAP container for which details should be listed. The response returns details of the specified LDAP container.

Required System Action LDAPAdmin

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getLDAPContainerDetail element (from the ContainerService schema) container-id: Can be obtained listLDAPContainers.

Returns a getLDAPContainerDetailResponse element (from the ContainerService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://container.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <con:getLDAPContainerDetail container-id="1"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getLDAPContainerDetailResponse active="true" description="" entity-count="8" id="1" last-accessed="2011-07-15T20:52:04.377Z" name="easyAs" xmlns="http://container.api.de.n2.tibco.com"> <primary-ldap display-name-attributes="ou" guid="0FFC620C-31FC-4687-94A8-08E9F7F07D89" id="1" ldap-alias="easyAs" ldap-search-string="(objectClass=organizationalPerson)" xmlns=""/> </getLDAPContainerDetailResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getLDAPContainerDetail 431

Service Connector API (Java Method)

Method Service getLDAPContainerDetail (args) ContainerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

432

| Chapter 19

ContainerService

saveLDAPContainerDetail
Create a new LDAP container or update the details for an existing LDAP container: The request must specify the details of the LDAP container to be created or updated. The response returns the unique ID of the newly-created or updated LDAP container.

Required System Action LDAPAdmin

Web Service API (SOAP Operation)

Request Uses the saveLDAPContainerDetail element (from the ContainerService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

saveLDAPContainerDetail 433

Parameter notes

id: Passed when updating an existing container. Can be obtained from listLDAPContainers. name: Passed when creating a new container. Must be unique among the LDAP containers. entity-count: Only returned in the response. last-accessed: Only returned in the response. primary-ldap.id, secondary-ldap.id: This is only needed when mapping resource attributes to LDAP attributes. The value passed in this attribute (which can be any arbitrary value) can then be included in attribute-mapping.ldap-resource-id to identify which LDAP source the LDAP attribute is to come from. For more information, see Mapping Resource Attributes to LDAP Attributes on page 118. primary-ldap.guid, secondary-ldap.guid: This is needed only when updating an existing container. Can be obtained from getLDAPContainerDetail. primary-ldap.ldap-alias, secondary-ldap.ldap-alias: Can be obtained from listLDAPSources. An LDAP Container can contain only one reference to any LDAP Alias. That is, no two LDAP Sources within the same LDAP Container can share the same LDAP Alias. primary-ldap.ldap-search-string, secondary-ldap.ldap-search-string: Identifies the LDAP entries to be considered as candidates for resourcesthis is required in every request. For example: "(objectclass=person)"). For information about valid search strings, see Using LDAP Filters on page 113. LDAP attributes and their values can be obtained from listLDAPAttributeNames and listLDAPAttributes. primary-ldap.display-name-attribute: [This attribute is only applicable to the primary LDAP.] The attributes in this parameter determine the name by which the user must log into the application. LDAP attributes and their values can be obtained from listLDAPAttributeNames and listLDAPAttributes. This can consist of multiple, space-separated attributes (for example "givenname sn"). secondary-ldap.container-mapping: Describes how a secondary LDAP source is mapped to the primary LDAP source. LDAP attributes and their values can be obtained from listLDAPAttributeNames and listLDAPAttributes For more information, see Defining Secondary LDAP Sources in an LDAP Container on page 115. attribute-mapping: Used to map organization model resource attributes to LDAP attributes. The ldap-resource-id value identifies the LDAP sourceit is obtained from the primary-ldap.id or secondary-ldap.id attributes. The business-attribute-id value can be obtained from listBusinessParameters. The ldap-attribute value can be obtained from listLDAPAttributeNames and listLDAPAttributes. For more information, see Mapping Resource Attributes to LDAP Attributes on page 118. administered-organization: Used to set up organization relationships. The guid attribute can be obtained from listOrgModelOverview. The name attribute is not used in this request. For more information, see Organization Relationships on page 123.
TIBCO ActiveMatrix BPM - BPM Developers Guide

434

| Chapter 19
Response Example

ContainerService

Returns a saveLDAPContainerDetailResponse element (from the ContainerService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://container.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <con:saveLDAPContainerDetail name="My New Container"> <primary-ldap ldap-alias="deLdap2" ldap-search-string="(objectClass=person)" display-name-attributes="displayname" /> </con:saveLDAPContainerDetail> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <saveLDAPContainerDetailResponse container-id="60" xmlns="http://container.api.de.n2.tibco.com"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service saveLDAPContainerDetail (args) ContainerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

deleteLDAPContainer 435

deleteLDAPContainer
Deletes the LDAP container specified in the request: The request must specify the unique ID of the LDAP container that is to be deleted. The response indicates whether or not the LDAP container was successfully deleted.

Required System Action deleteLDAPAdmin

Web Service API (SOAP Operation)

Request Parameter notes Uses the deleteLDAPContainer element (from the ContainerService schema) container-id: Can be obtained listLDAPContainers. delete-resources: Allows you to delete the resources at the same time as the container. (Resources can also be deleted with the deleteResource operation.) If resources are not deleted prior to, or at the same time as, deleting the container, their mappings are still valid, and they can still log into the system and receive work items in their work list. You can get a list of resources whose container has been deleted without also deleting the resources in the container by using the listContainerResources operation and passing 0 (zero) in the container-id parameter (it also returns administrator users, which are users created by the system that you cannot delete).

Response

Returns a deleteLDAPContainerResponse element (from the ContainerService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

436

| Chapter 19
Example

ContainerService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://container.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <con:deleteLDAPContainer container-id="70" delete-resources="false"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <deleteLDAPContainerResponse successful="true" xmlns="http://container.api.de.n2.tibco.com"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service deleteLDAPContainer (args) ContainerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

EntityResolverService 437

Chapter 20

EntityResolverService

EntityResolverService is one of the Directory Services provided by Work Manager. Use EntityResolverService requests to get information about resources and their association with specific organization model entities.

Topics
getResourceDetail, page 438 listAssociatedResources, page 441 lookupUser, page 443

TIBCO ActiveMatrix BPM - BPM Developers Guide

438

| Chapter 20

EntityResolverService

getResourceDetail
Get detailed information about one or more resources: The request must specify the resource(s) for which details are required. The response returns detailed descriptions of the requested resource(s). This information includes the groups, positions, capabilities, privileges and attributes associated with each resource.

Required System Action resolveResource

Web Service API (SOAP Operation)

Request Parameter notes Uses the getResourceDetail element (from the EntityResolverService schema) Response entity-type: Must be specified as RESOURCE. guid: Can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources. qualifer: Not used in this operation.

Returns a getResourceDetailResponse element (from the EntityResolverService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

getResourceDetail 439

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:res="http://resolver.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <res:getResourceDetail> <!--1 or more repetitions:--> <resource model-version="-1" entity-type="RESOURCE" guid="0C87F2ED-0BF8-482F-BAFB-84E51C5AA624" /> </res:getResourceDetail> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getResourceDetailResponse xmlns="http://resolver.api.de.n2.tibco.com"> <resource guid="0C87F2ED-0BF8-482F-BAFB-84E51C5AA624" name="Tony Pulis" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="easyAs" ldap-alias="easyAs" ldap-dn="OU=Tony Pulis, OU=London, OU=AllEmployees, O=easyAsInsurance"/> <group endDate="2011-07-26T06:59:59.000Z" entity-type="GROUP" guid="_o6QGsALvEeCHF4vrCq9WPw" model-version="3" name="AdminResourceManagement" startDate="2011-07-22T07:00:00.000Z"/> <privilege endDate="2011-07-26T06:59:59.000Z" entity-type="PRIVILEGE" guid="_UNb_kMpSEd64gM7QE8RwxA" model-version="3" name="ResourceManager" startDate="2011-07-22T07:00:00.000Z"> <origin entity-type="GROUP" guid="_o6QGsALvEeCHF4vrCq9WPw" model-version="3" name="AdminResourceManagement"/> </privilege> <privilege endDate="2011-07-26T06:59:59.000Z" entity-type="PRIVILEGE" guid="_I8YiEMpSEd64gM7QE8RwxA" model-version="3" name="BaseUser" startDate="2011-07-22T07:00:00.000Z"> <origin entity-type="GROUP" guid="_ISlQ8ALvEeCHF4vrCq9WPw" model-version="3" name="Admin"/> </privilege> </resource> </getResourceDetailResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

440

| Chapter 20

EntityResolverService

Service Connector API (Java Method)

Method Service getResourceDetail (args) EntityResolverService

TIBCO ActiveMatrix BPM - BPM Developers Guide

listAssociatedResources 441

listAssociatedResources
List the resources associated with one or more organization model entities. The request must specify the organization model entities for which the associated resources are required. The response returns the details of the resources associated with the specified organization model entities.

This operation considers an "associated" entity as one in which the resource is a member, or the resource possesses the entity (in the case of privileges and capabilities). Note that the association is hierarchical: If the entity specified is a group, the result also includes resources associated with sub-groups. If the entity specified is an organization unit, the result also includes resources associated with positions in that organization unit. If the entity specified is a privilege, the result includes resources that have inherited that privilege because of their membership in groups and positions. If the entity specified is a capability, the result includes resources that hold that capability directly. It does not take into consideration the capabilities of groups and positions to which the resource is a member. Required System Action resolveResource

TIBCO ActiveMatrix BPM - BPM Developers Guide

442

| Chapter 20

EntityResolverService

Web Service API (SOAP Operation)

Request Parameter notes Uses the listAssociatedResources element (from the EntityResolverService schema) entity-guid: Organization unit, position, and group GUIDs can be obtained from listOrgModelOverview. Privilege GUIDs can be obtained from getPrivileges, getUserPrivileges, or listPrivileges. Capability GUIDs can be obtained from getCapabilities or listCapabilities.

Response

Returns a listAssociatedResourcesResponse element (from the EntityResolverService schema). If multiple organizational entities are specified, and a resource is associated with more than one of those entities, that resource is only listed once in the response.

Example

Request:
<soapenv:Body> <res:listAssociatedResources> <entity-guid>_ntQXEDMeEeCrFvFvgjfN_w</entity-guid> </res:listAssociatedResources> </soapenv:Body>

Response:
<SOAP-ENV:Body> <listAssociatedResourcesResponse xmlns="http://resolver.api.de.n2.tibco.com"> <resource guid="tibco-admin" name="tibco-admin" resource-type="HUMAN" xmlns=""> <LdapReference ldap-alias="system" ldap-dn="UID=admin, OU=system"/> </resource> <resource guid="ED72300B-F2FA-4E60-90D4-F829FB8DEA9D" name="Liam Lawrence" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="OU=Liam Lawrence, OU=London, OU=AllEmployees, O=easyAsInsurance"/> </resource> </listAssociatedResourcesResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method listAssociatedResources (args) listAssociatedResources (args) Service EntityResolverService [signature 1] [signature 2]

TIBCO ActiveMatrix BPM - BPM Developers Guide

lookupUser 443

lookupUser
List the resources that match a specified login name or LDAP DN. The request must specify the name and/or LDAP DN on which to search, and whether to return details of those users. The response returns the number of users found that match the given criteria and, optionally, lists the details of those users.

Required System Action resolveResource

TIBCO ActiveMatrix BPM - BPM Developers Guide

444

| Chapter 20

EntityResolverService

Web Service API (SOAP Operation)

Request Parameter notes Uses the lookupUser element (from the EntityResolverService schema) Response Example name: Either pass the resources name in this attribute, or an LDAP dn value in the ldap-dn attribute to search for a resource. Wildcards cannot be used. ldap-alias: If searching by providing the LDAP dn, you can also pass this to limit the search to a specific LDAP. Can be obtained from listLDAPContainers. ldap-dn: The LDAP dn (distinguished name) to search against. Can be obtained from listLDAPEntities or listContainerResources.

Returns a lookupUserResponse element (from the EntityResolverService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:res="http://resolver.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <res:lookupUser ldap-alias="easyAs" ldap-dn="ou=Tony Pulis,ou=London,ou=AllEmployees,o=easyAsInsurance" get-detail="true"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <lookupUserResponse user-count="1" xmlns="http://resolver.api.de.n2.tibco.com"> <detail alias="easyAs" dn="OU=Tony Pulis, OU=London, OU=AllEmployees, O=easyAsInsurance" entity-type="RESOURCE" guid="0C87F2ED-0BF8-482F-BAFB-84E51C5AA624" model-version="-1" name="Tony Pulis" resource-type="HUMAN" xmlns=""> <groups>_ISlQ8ALvEeCHF4vrCq9WPw</groups> <groups>_o6QGsALvEeCHF4vrCq9WPw</groups> </detail> </lookupUserResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service lookupUser (args) EntityResolverService

TIBCO ActiveMatrix BPM - BPM Developers Guide

EventCollectorQueryService 445

Chapter 21

EventCollectorQueryService

EventCollectorQueryService is one of the Event Collection Services provided by Process Manager. Use EventCollectorQueryService requests to get information from the Event Collector database tables about events, attributes and components.

Topics
executeGenericQuery, page 446 executeRegisteredGenericQuery, page 450 getAllAttributes, page 454 getAttributes, page 457 getComponents, page 460 isQueryRegistered, page 463 registerQuery, page 465 unRegisterQuery, page 468 lookupQueryByTag, page 470

TIBCO ActiveMatrix BPM - BPM Developers Guide

446

| Chapter 21

EventCollectorQueryService

executeGenericQuery
Execute the specified query against the Event Collector database tables. (If a query needs to be executed multiple times, better performance will be experienced by registering the query with registerQuery, then using the executeRegisteredGenericQuery operation.) The request must specify the details of the query that is to be executed, along with any options for the query. The response returns details of the events that match the specified query, along with summary information about the executed query.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

executeGenericQuery 447

Web Service API (SOAP Operation)

Request Parameter notes Uses the executeGenericQueryRequest element (from the EventCollectorQueryService schema) Query.filter: For information about valid filter query syntax, see Defining Query Filter Strings. Query.requiredAttribute: Can be obtained from getAllAttributes or getAttributes. Query.sortOrder.attribute: Can be obtained from getAllAttributes or getAttributes. Query.target: For a list of the valid targets, including information about which Event Collector database tables each target value queries, see Using Attributes in Query Filters on page 293.

Response

Returns a executeGenericQueryResponse element (from the EventCollectorQueryService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

448

| Chapter 21
Example

EventCollectorQueryService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com" xmlns:base="http://base.api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:executeGenericQueryRequest> <base:Query> <correlate>false</correlate> <filter>((messageCategory='WORK_ITEM') AND (parentObjectId='pvm:0a121'))</filter> <requireAllAttributes>true</requireAllAttributes> <target>AUDIT</target> </base:Query> <base:QueryOptions> </base:QueryOptions> </api:executeGenericQueryRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <executeGenericQueryResponse xmlns="http://api.ec.n2.tibco.com"> <GenericResult xmlns="http://base.api.ec.n2.tibco.com"> <endPosition xmlns="">11</endPosition> <startPosition xmlns="">0</startPosition> <totalItems xmlns="">11</totalItems> <resultEntry xmlns=""> <id>65</id> <ref>BRM_WORKITEM_SCHEDULED</ref> <attribute xsi:type="base:StringEntryAttribute" xmlns:base="http://base.api.ec.n2.tibco.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <attributeId>27</attributeId> <attributeName>hostAddress</attributeName> <type>STRING</type> <value>10.97.8.153</value> </attribute> . . . </GenericResult> </executeGenericQueryResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

executeGenericQuery 449

Service Connector API (Java Method)

Method Service executeGenericQuery (args) EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

450

| Chapter 21

EventCollectorQueryService

executeRegisteredGenericQuery
Execute a query that has been previously registered using the registerQuery operation. The request must specify the previously registered query that is to be executed, along with any options to be used on this particular execution of the query. The response returns details of the events that match the specified query, along with summary information about the executed query.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

executeRegisteredGenericQuery 451

Web Service API (SOAP Operation)

Request Parameter notes Uses the executeRegisteredGenericQueryRequest element (from the EventCollectorQueryService schema) QueryIdentifier.guid, QueryIdentifier.tag: Either the GUID or the tag can be used to identify the query, which was previously registered with the registerQuery operationboth are returned by registerQuery. Note, however, passing the GUID makes a more efficient query. You can also determine the GUID using the lookupQueryByTag operation.

Response

Returns a executeRegisteredGenericQueryResponse element (from the EventCollectorQueryService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

452

| Chapter 21
Example

EventCollectorQueryService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com" xmlns:base="http://base.api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:executeRegisteredGenericQueryRequest> <base:QueryIdentifier> <tag>EventTag123</tag> </base:QueryIdentifier> <base:QueryOptions> <numberOfItems>-1</numberOfItems> <populateAttributeNames>true</populateAttributeNames> </base:QueryOptions> </api:executeRegisteredGenericQueryRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <executeRegisteredGenericQueryResponse xmlns="http://api.ec.n2.tibco.com"> <GenericResult xmlns="http://base.api.ec.n2.tibco.com"> <endPosition xmlns="">11</endPosition> <startPosition xmlns="">0</startPosition> <totalItems xmlns="">11</totalItems> <resultEntry xmlns=""> <id>65</id> <ref>BRM_WORKITEM_SCHEDULED</ref> <attribute xsi:type="base:StringEntryAttribute" xmlns:base="http://base.api.ec.n2.tibco.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <attributeId>27</attributeId> <attributeName>hostAddress</attributeName> <type>STRING</type> <value>10.97.8.153</value> </attribute> . . . </resultEntry> </GenericResult> </executeRegisteredGenericQueryResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

executeRegisteredGenericQuery 453

Service Connector API (Java Method)

Method Service executeRegisteredGenericQuery (args) EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

454

| Chapter 21

EventCollectorQueryService

getAllAttributes
List all attributes registered in the Event Collector database tables. The request has no parameters. The response returns the details of all attributes registered in the Event Collector database tables.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

getAllAttributes 455

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getAllAttributesRequest element (from the EventCollectorQueryService schema) This request has no parameters. Returns a getAllAttributesResponse element (from the EventCollectorQueryService schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getAllAttributesRequest/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getAllAttributesResponse xmlns="http://api.ec.n2.tibco.com"> <AttributeDefinition xmlns="http://base.api.ec.n2.tibco.com"> <category xmlns="">message</category> <componentId xmlns="">1</componentId> <id xmlns="">1</id> <isPrimary xmlns="">true</isPrimary> <name xmlns="">messageId</name> <type xmlns="">STRING</type> </AttributeDefinition> <AttributeDefinition xmlns="http://base.api.ec.n2.tibco.com"> <category xmlns="">environment</category> <componentId xmlns="">1</componentId> <id xmlns="">2</id> <isPrimary xmlns="">false</isPrimary> <name xmlns="">environmentName</name> <type xmlns="">STRING</type> </AttributeDefinition> . . . </getAllAttributesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

456

| Chapter 21

EventCollectorQueryService

Service Connector API (Java Method)

Method Service getAllAttributes (args) EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getAttributes 457

getAttributes
List all attributes in the Event Collector database tables that are registered for a specific component. The request must specify the identifier of the component for which attributes should be listed. The response returns the details of all attributes registered in the Event Collector database for the specified component.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

458

| Chapter 21

EventCollectorQueryService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getAttributesRequest element (from the EventCollectorQueryService schema) componentId: Can be obtained from lookupQueryByTag.

Returns a getAttributesResponse element (from the EventCollectorQueryService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getAttributesRequest> <componentId>1</componentId> </api:getAttributesRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getAttributesResponse xmlns="http://api.ec.n2.tibco.com"> <AttributeDefinition xmlns="http://base.api.ec.n2.tibco.com"> <category xmlns="">message</category> <componentId xmlns="">1</componentId> <id xmlns="">1</id> <isPrimary xmlns="">true</isPrimary> <name xmlns="">messageId</name> <type xmlns="">STRING</type> </AttributeDefinition> <AttributeDefinition xmlns="http://base.api.ec.n2.tibco.com"> <category xmlns="">environment</category> <componentId xmlns="">1</componentId> <id xmlns="">2</id> <isPrimary xmlns="">false</isPrimary> <name xmlns="">environmentName</name> <type xmlns="">STRING</type> </AttributeDefinition> . . . </getAttributesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getAttributes 459

Service Connector API (Java Method)

Method Service getAttributes (args) EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

460

| Chapter 21

EventCollectorQueryService

getComponents
List the components that are registered on the system. The request has no parameters. The response returns the details of each component that is registered on the system.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

getComponents 461

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getComponentsRequest element (from the EventCollectorQueryService schema) This request has no parameters. Returns a getComponentsResponse element (from the EventCollectorQueryService schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getComponentsRequest/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getComponentsResponse xmlns="http://api.ec.n2.tibco.com"> <Component xmlns="http://base.api.ec.n2.tibco.com"> <componentClass xmlns="">com.tibco.n2.logging.metadata.n2lf.N2LFMetaData</componentCla ss> <componentName xmlns="">N2LF</componentName> <description xmlns="">N2 Logging Framework</description> <id xmlns="">1</id> <implementationType xmlns="">N2LF-INTERNAL</implementationType> <name xmlns="">N2LF</name> <parentId xmlns="">-1</parentId> <revision xsi:nil="true" xmlns="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <version xmlns="">1.1</version> </Component> . . . </getComponentsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

462

| Chapter 21

EventCollectorQueryService

Service Connector API (Java Method)

Method Service getComponents (args) EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

isQueryRegistered 463

isQueryRegistered
Test whether a query is registered with Event Collector. (This can be useful for determining whether a frequently used query tag is already present on the system.) The request must specify the query that is to be tested. The response returns whether the query is registered with Event Collector.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

464

| Chapter 21

EventCollectorQueryService

Web Service API (SOAP Operation)

Request Parameter notes Uses the isQueryRegisteredRequest element (from the EventCollectorQueryService schema) QueryIdentifier.guid, QueryIdentifier.tag: Either the GUID or the tag can be used to identify the query, which was previously registered with the registerQuery operationboth are returned by registerQuery. You can also determine the GUID using the lookupQueryByTag operation.

Response Example

Returns a isQueryRegisteredResponse element (from the EventCollectorQueryService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com" xmlns:base="http://base.api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:isQueryRegisteredRequest> <base:QueryIdentifier> <tag>EventTag123</tag> </base:QueryIdentifier> </api:isQueryRegisteredRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <isQueryRegisteredResponse xmlns="http://api.ec.n2.tibco.com"> <result xmlns="">true</result> </isQueryRegisteredResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service isQueryRegistered (args) EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

registerQuery 465

registerQuery
Register a query with Event Collector, so that it can be subsequently executed using the executeRegisteredGenericQuery operation. The request must specify the query to be registered and a tag with which to identify it. The response returns the GUID and tag for the newly registered query.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

466

| Chapter 21

EventCollectorQueryService

Web Service API (SOAP Operation)

Request Parameter notes Uses the registerQueryRequest element (from the EventCollectorQueryService schema) tag: Must be unique among registered queries on the system. Query.filter: For information about valid filter query syntax, see Defining Query Filter Strings. Query.requiredAttribute: Can be obtained from getAllAttributes or getAttributes. Query.sortOrder.attribute: Can be obtained from getAllAttributes or getAttributes. Query.target: For a list of the valid targets, including information about which Event Collector database tables each target value queries, see Using Attributes in Query Filters on page 293.

Response

Returns a registerQueryResponse element (from the EventCollectorQueryService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

registerQuery 467

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com" xmlns:base="http://base.api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:registerQueryRequest> <tag>EventTag123</tag> <base:Query> <correlate>false</correlate> <filter>((messageCategory='WORK_ITEM') AND (parentObjectId='pvm:0a121'))</filter> <requireAllAttributes>true</requireAllAttributes> </base:Query> </api:registerQueryRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <registerQueryResponse xmlns="http://api.ec.n2.tibco.com"> <QueryIdentifier xmlns="http://base.api.ec.n2.tibco.com"> <guid xmlns="">2</guid> <tag xmlns="">EventTag123</tag> </QueryIdentifier> </registerQueryResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service registerQuery (args) EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

468

| Chapter 21

EventCollectorQueryService

unRegisterQuery
Unregister a previously registered query. The request must specify the query that is to be unregistered (using either a GUID or tag). The response has no parameters.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

unRegisterQuery 469

Web Service API (SOAP Operation)

Request Parameter notes Uses the unRegisterQueryRequest element (from the EventCollectorQueryService schema) QueryIdentifier.guid, QueryIdentifier.tag: Either the GUID or the tag can be used to identify the query, which was previously registered with the registerQuery operationboth are returned by registerQuery. You can also determine the GUID using the lookupQueryByTag operation.

Response Example

Returns a unRegisterQueryResponse element (from the EventCollectorQueryService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com" xmlns:base="http://base.api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:unRegisterQueryRequest> <base:QueryIdentifier> <tag>EventTag123</tag> </base:QueryIdentifier> </api:unRegisterQueryRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <unRegisterQueryResponse xmlns="http://api.ec.n2.tibco.com"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service unRegisterQuery (args) EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

470

| Chapter 21

EventCollectorQueryService

lookupQueryByTag
List the details for a particular query (identified by its tag). This operation can be used to obtain the GUID for a registered query. The executeRegisteredGenericQuery operation executes faster if the query is identified using its GUID rather than its tag. The request must specify the tag to be used to look up the query. The response returns the details of the specified query, including its identifier.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

lookupQueryByTag 471

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the lookupQueryByTagRequest element (from the EventCollectorQueryService schema) tag: Name that was given to the query when it was registered with the registerQuery operation.

Returns a lookupQueryByTagResponse element (from the EventCollectorQueryService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:lookupQueryByTagRequest> <tag>EventTag123</tag> </api:lookupQueryByTagRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <lookupQueryByTagResponse xmlns="http://api.ec.n2.tibco.com"> <QueryInfo xmlns="http://base.api.ec.n2.tibco.com"> <query xmlns=""> <correlate>false</correlate> <filter>((messageCategory='WORK_ITEM') AND (parentObjectId='pvm:0a121'))</filter> <requireAllAttributes>true</requireAllAttributes> </query> <identifier xmlns=""> <guid>2</guid> <tag>EventTag123</tag> </identifier> </QueryInfo> </lookupQueryByTagResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method lookupQueryByTag (args)

TIBCO ActiveMatrix BPM - BPM Developers Guide

472

| Chapter 21
Service

EventCollectorQueryService

EventCollectorQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

EventCollectorMeasuresService 473

Chapter 22

EventCollectorMeasuresService

EventCollectorMeasuresService is one of the Event Collection Services provided by Process Manager. Use EventCollectorMeasuresService requests to get measures information stored by the Event Collector database tables about process templates or work items.

Topics
requestProcessDurationMeasure, page 474 requestProcessTemplateMeasure, page 477 requestWorkItemPerformanceForTemplate, page 480 requestWorkItemPerformanceForResource, page 484

TIBCO ActiveMatrix BPM - BPM Developers Guide

474

| Chapter 22

EventCollectorMeasuresService

requestProcessDurationMeasure
Request a process duration measure from the Event Collector database tables: The request must specify the process template name(s) for which a process duration measure is to be returned, start and end dates, the duration to be measured, and whether data consolidation is required. The response returns the requested measure(s).

Required System Action None

Web Service API (SOAP Operation)

Request Parameter notes Uses the requestProcessDurationMeasureRequest element (from the EventCollectorMeasuresService schema) id.moduleName, id.processTemplateName, and id.processTemplateVersion: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt. duration.endDate, duration.startDate: Required dates for the measure. advancedOption: For internal use only.

Response

Returns a requestProcessDurationMeasureResponse element (from the EventCollectorMeasuresService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

requestProcessDurationMeasure 475

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:requestProcessDurationMeasureRequest> <id> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <duration> <endDate>2011-08-05T00:00:00.000Z</endDate> <startDate>2011-07-01T00:00:00.000Z</startDate> <granularity>YEAR</granularity> </duration> <options> <consolidation>BOTH</consolidation> </options> </api:requestProcessDurationMeasureRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <requestProcessDurationMeasureResponse xmlns="http://api.ec.n2.tibco.com"> <measure xmlns=""> <index>0</index> <id xmlns:api="http://api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <period> <index>0</index> <duration> <startDate>2011-07-01T00:00:00.000Z</startDate> </duration> <entry> <index>0</index> <value>7</value> <type>PROCESS_TOTAL</type> </entry> . . . </period> </measure> </requestProcessDurationMeasureResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

476

| Chapter 22

EventCollectorMeasuresService

Service Connector API (Java Method)

Method Service requestProcessDurationMeasure (args) EventCollectorMeasuresService

TIBCO ActiveMatrix BPM - BPM Developers Guide

requestProcessTemplateMeasure 477

requestProcessTemplateMeasure
Request a process template measure from the Event Collector database tables: The request must specify the process template name(s) for which a process template measure is to be returned, start and end dates, the duration to be measured, and whether data consolidation is required. The response returns the requested measure(s).

Required System Action None

Web Service API (SOAP Operation)

Request Parameter notes Uses the requestProcessTemplateMeasureRequest element (from the EventCollectorMeasuresService schema) id.moduleName, id.processTemplateName, and id.processTemplateVersion: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt. duration.endDate, duration.startDate: Required dates for the measure. advancedOption: For internal use only.

Response

Returns a requestProcessTemplateMeasureResponse element (from the EventCollectorMeasuresService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

478

| Chapter 22
Example

EventCollectorMeasuresService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:requestProcessTemplateMeasureRequest> <!--1 or more repetitions:--> <id> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <duration> <endDate>2011-08-05T00:00:00.000Z</endDate> <startDate>2011-07-01T00:00:00.000Z</startDate> <granularity>YEAR</granularity> </duration> <options> <consolidation>BOTH</consolidation> </options> </api:requestProcessTemplateMeasureRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <requestProcessTemplateMeasureResponse xmlns="http://api.ec.n2.tibco.com"> <measure xmlns=""> <index>0</index> <id xmlns:api="http://api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <period> <index>0</index> <duration> <startDate>2011-07-01T00:00:00.000Z</startDate> </duration> <entry> <index>0</index> <value>7</value> <type>STARTED</type> </entry> . . . </period> </measure> </requestProcessTemplateMeasureResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

requestProcessTemplateMeasure 479

Service Connector API (Java Method)

Method Service requestProcessTemplateMeasure (args) EventCollectorMeasuresService

TIBCO ActiveMatrix BPM - BPM Developers Guide

480

| Chapter 22

EventCollectorMeasuresService

requestWorkItemPerformanceForTemplate
Request a work item performance measure for a process template from the Event Collector database tables: The request must specify the process template name(s) for which a work item performance measure is to be returned, start and end dates, the duration to be measured, and whether data consolidation is required. The response returns the requested measure(s).

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

requestWorkItemPerformanceForTemplate 481

Web Service API (SOAP Operation)

Request Parameter notes Uses the requestWorkItemPerformanceForTemplateRequest element (from the EventCollectorMeasuresService schema) id.moduleName, id.processTemplateName, and id.processTemplateVersion: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt. duration.endDate, duration.startDate: Required dates for the measure. advancedOption: For internal use only.

Response

Returns a requestWorkItemPerformanceForTemplateResponse element (from the EventCollectorMeasuresService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

482

| Chapter 22
Example

EventCollectorMeasuresService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ec.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:requestWorkItemPerformanceForTemplateRequest> <id> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <duration> <endDate>2011-08-05T00:00:00.000Z</endDate> <startDate>2011-07-01T00:00:00.000Z</startDate> <granularity>YEAR</granularity> </duration> <options> <consolidation>BOTH</consolidation> </options> </api:requestWorkItemPerformanceForTemplateRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <requestWorkItemPerformanceForTemplateResponse xmlns="http://api.ec.n2.tibco.com"> <measure xmlns=""> <index>0</index> <id xsi:type="base:ProcessTemplateId" xmlns:api="http://api.ec.n2.tibco.com" xmlns:base="http://base.api.ec.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <processTemplateName>CSCallbackProcess</processTemplateName> </id> <period> <index>0</index> <duration> <startDate>2011-07-01T00:00:00.000Z</startDate> </duration> <entry> <index>0</index> <value>4</value> <type>OFFERED</type> </entry> . . . </period> </measure> </requestWorkItemPerformanceForTemplateResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

requestWorkItemPerformanceForTemplate 483

Service Connector API (Java Method)

Method Service requestWorkItemPerformanceForTemplate (args) EventCollectorMeasuresService

TIBCO ActiveMatrix BPM - BPM Developers Guide

484

| Chapter 22

EventCollectorMeasuresService

requestWorkItemPerformanceForResource
Request a work item performance measure for a resource from the Event Collector database tables: The request must specify the resource name(s) for which a work item performance measure is to be returned, start and end dates, the duration to be measured, and whether data consolidation is required. The response returns the requested measure(s).

This operation is not currently supported.

TIBCO ActiveMatrix BPM - BPM Developers Guide

ExporterService 485

Chapter 23

ExporterService

ExporterService is one of the Directory Services provided by Work Manager. Use ExporterService requests to export and import defined LDAP containers, resource mappings and push destinations.

Topics
exportResources, page 486 importResources, page 490

TIBCO ActiveMatrix BPM - BPM Developers Guide

486

| Chapter 23

ExporterService

exportResources
Export defined LDAP containers, resource mappings and push destinations, either for backup or for subsequent import to other environments: The request must specify the elements that are to be exported from this server. The response returns an export object containing the details of all the exported elements.

Required System Action exportLDAPAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

exportResources 487

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the exportResourcesRequest element (from the ExporterService schema) None

Returns a exportResourcesResponse element (from the ExporterService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

488

| Chapter 23
Example

ExporterService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:exp="http://exporter.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <exp:exportResourcesRequest export-ldap-containers="true" export-resources="true" export-push-destinations="true"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <exportResourcesResponse xmlns="http://exporter.api.de.n2.tibco.com"> <container active="true" description="" entity-count="8" id="1" last-accessed="2011-08-01T16:16:59.490Z" name="easyAs" xmlns=""> <primary-ldap display-name-attributes="ou" guid="0FFC620C-31FC-4687-94A8-08E9F7F07D89" id="1" ldap-alias="easyAs" ldap-search-string="(objectClass=organizationalPerson)"/> </container> <resource id="tibco-admin" ldapalias="system" ldapdn="UID=admin, OU=system" name="tibco-admin" resourceType="HUMAN" xmlns=""> <resourceGroup groupId="CF931D25A207BF4C4458FF923692F350"/> <resourceGroup groupId="CD4888DFE350794FE9185524F409A6F0"/> <resourceGroup groupId="Undelivered"/> <resourceGroup groupId="BBC750FBBDD594EDD04E42CAC1C731E7"/> <resourceGroup groupId="CF8999291E375FA9B249009F98C457A8"/> </resource> <resource id="B15F1CE0-4B28-4F48-BC7C-42C171A9AF48" ldapalias="easyAs" ldapcontainer="easyAs" ldapdn="OU=Liam Lawrence, OU=London, OU=AllEmployees, O=easyAsInsurance" name="Liam Lawrence" resourceType="HUMAN" xmlns=""> <positionHeld positionId="_2ieLgMpREd64gM7QE8RwxA"/> </resource> . . . <resource id="D4E3C720-5500-4651-B105-6C60C613E226" ldapalias="easyAs" ldapcontainer="easyAs" ldapdn="OU=Leon Court, OU=Paris, OU=AllEmployees, O=easyAsInsurance" name="Leon Court" resourceType="HUMAN" xmlns=""> <positionHeld positionId="_2ieLgMpREd64gM7QE8RwxA"/> </resource> </exportResourcesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

exportResources 489

Service Connector API (Java Method)

Method Service exportResources (args) ExporterService

TIBCO ActiveMatrix BPM - BPM Developers Guide

490

| Chapter 23

ExporterService

importResources
Import a previously exported object containing details of the exported LDAP containers, resource mappings and push destinations: The request must specify the previously exported data object that is to be imported to this server. The response returns a success result if the supplied data has been successfully imported.

Required System Action importLDAPAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

importResources 491

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the importResourcesRequest element (from the ExporterService schema) Use the output from the exportResources operation as the input to this operation.

Returns a importResourcesResponse element (from the ExporterService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

492

| Chapter 23
Example

ExporterService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:exp="http://exporter.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <exp:importResourcesRequest> <container active="true" description="" entity-count="8" id="1" last-accessed="2011-08-01T16:16:59.490Z" name="easyAs" xmlns=""> <primary-ldap display-name-attributes="ou" guid="0FFC620C-31FC-4687-94A8-08E9F7F07D89" id="1" ldap-alias="easyAs" ldap-search-string="(objectClass=organizationalPerson)"/> </container> <resource id="tibco-admin" ldapalias="system" ldapdn="UID=admin, OU=system" name="tibco-admin" resourceType="HUMAN" xmlns=""> <resourceGroup groupId="CF931D25A207BF4C4458FF923692F350"/> <resourceGroup groupId="CD4888DFE350794FE9185524F409A6F0"/> <resourceGroup groupId="Undelivered"/> <resourceGroup groupId="BBC750FBBDD594EDD04E42CAC1C731E7"/> <resourceGroup groupId="CF8999291E375FA9B249009F98C457A8"/> </resource> <resource id="B15F1CE0-4B28-4F48-BC7C-42C171A9AF48" ldapalias="easyAs" ldapcontainer="easyAs" ldapdn="OU=Liam Lawrence, OU=London, OU=AllEmployees, O=easyAsInsurance" name="Liam Lawrence" resourceType="HUMAN" xmlns=""> <positionHeld positionId="_2ieLgMpREd64gM7QE8RwxA"/> </resource> . . . <resource id="D4E3C720-5500-4651-B105-6C60C613E226" ldapalias="easyAs" ldapcontainer="easyAs" ldapdn="OU=Leon Court, OU=Paris, OU=AllEmployees, O=easyAsInsurance" name="Leon Court" resourceType="HUMAN" xmlns=""> <positionHeld positionId="_2ieLgMpREd64gM7QE8RwxA"/> </resource> </exp:importResourcesRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <importResourcesResponse xmlns="http://exporter.api.de.n2.tibco.com">true</importResourcesRespo nse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

importResources 493

Service Connector API (Java Method)

Method Service importResources (args) ExporterService

TIBCO ActiveMatrix BPM - BPM Developers Guide

494

| Chapter 23

ExporterService

TIBCO ActiveMatrix BPM - BPM Developers Guide

LDAPService 495

Chapter 24

LDAPService

LDAPService is one of the Directory Services provided by Work Manager. Use LDAPService operations to get information about and from LDAP sources.

Topics
listLDAPSources, page 496 listLDAPEntities, page 498 listLDAPAttributes, page 501 listLDAPAttributeNames, page 504 listContainerResources, page 508

TIBCO ActiveMatrix BPM - BPM Developers Guide

496

| Chapter 24

LDAPService

listLDAPSources
List all LDAP sources currently available to the BPM runtime. The request takes no parameters. The response returns the LDAP aliases of all currently available LDAP sources.

You must use TIBCO ActiveMatrix Administrator to create LDAP sources.

Required System Action LDAPAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

listLDAPSources 497

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the listLDAPSources element (from the LDAPService schema) This request takes no parameters. (The empty element is a placeholderits value is not referenced.) Returns a listLDAPSourcesResponse element (from the LDAPService schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listLDAPSources> <empty>0</empty> </ldap:listLDAPSources> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listLDAPSourcesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> <LdapSource ldap-alias="system" xmlns=""/> <LdapSource ldap-alias="easyAs" xmlns=""/> </listLDAPSourcesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service listLDAPSources (args) LDAPService

TIBCO ActiveMatrix BPM - BPM Developers Guide

498

| Chapter 24

LDAPService

listLDAPEntities
List the LDAP resources in a particular LDAP container. This operation can return resources that already exist (that is, they have been "created" with either the getResourceGuid or mapEntities operation), as well as those that are potential resources (resources that are available in an LDAP source, but have not been created yet). Note that the listContainerResources operation can also be used to get resources that already exist. The request must specify the LDAP container whose resources should be listed. The response returns detailed descriptions of all LDAP resources available in the specified LDAP container. Note that this operation returns an empty response if the calling user does not have access to an organization to which a LDAP container is associated (because of organization relationships). For more information, see Organization Relationships on page 123. Required System Actions resourceAdmin and/or LDAPAdmin1

1. This operation can be called by users possessing either the resourceAdmin or LDAPAdmin system action. The LDAPAdmin system action gives the user additional access to organizations that are restricted due to organization relationships. For more information, see Overriding Organization Relationships on page 124.
TIBCO ActiveMatrix BPM - BPM Developers Guide

listLDAPEntities 499

Web Service API (SOAP Operation)

Request Parameter notes Uses the listLDAPEntities element (from the LDAPService schema) model-version: Note that resources are not versioned, therefore, the model version does not affect the resources returned. However, it can affect the resource details (entities, such as positions, groups, privileges, etc.), as they are versioned and may not appear in all organization model versions. Use -1 to specify the latest version. You can get the available versions from listModelVersions. container-id: Can be obtained from listLDAPContainers. existing-only: Can be set to: true: to only return details of LDAP resources that exist (that is, resources that have been created with either the getResourceGuid or mapEntities operation those resources have a GUID (resources that do not exist yet do not have a GUID). false: to return details of all the LDAP resources defined in the LDAP container, both those that exist as well as potential resources. For these resources, only an LdapReference is returned instead of a GUID. Response Example Returns a listLDAPEntitiesResponse element (from the LDAPService schema). Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listLDAPEntities model-version="-1" container-id="1" existing-only="false"/> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

500

| Chapter 24

LDAPService

Response: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listLDAPEntitiesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> <LdapResource name="Richard Cresswell" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="ou=Richard Cresswell,ou=London,ou=AllEmployees,o=easyAsInsurance"/> </LdapResource> <LdapResource name="John Eustace" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="ou=John Eustace,ou=Swindon,ou=AllEmployees,o=easyAsInsurance"/> </LdapResource> <LdapResource guid="A618D111-4121-417F-86DC-519A2151FAE8" name="Steve Simonsen" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="ou=Steve Simonsen,ou=London,ou=AllEmployees,o=easyAsInsurance"/> </LdapResource> <LdapResource guid="ED72300B-F2FA-4E60-90D4-F829FB8DEA9D" name="Liam Lawrence" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="ou=Liam Lawrence,ou=London,ou=AllEmployees,o=easyAsInsurance"/> </LdapResource> </listLDAPEntitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service listLDAPEntities (args) LDAPService

TIBCO ActiveMatrix BPM - BPM Developers Guide

listLDAPAttributes 501

listLDAPAttributes
List the data values stored in one or more LDAP attributes for a particular LDAP entity: The request must specify the LDAP resource and, optionally, LDAP attributes for which data values should be returned. The response returns the data values stored for the requested LDAP attributes.

Required System Action LDAPAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

502

| Chapter 24

LDAPService

Web Service API (SOAP Operation)

Request Parameter notes Uses the listLDAPAttributes element (from the LDAPService schema) alias: Can be obtained from listLDAPSources. dn: Can be obtained from listContainerResources or listLDAPEntities (in the ldap-dn attribute of the LdapReference element). req-attributes.name is optional. If it is omitted, the response will contain all attributes defined for the specified LDAP entity. If it is included, the response will include only those attributes specified. If a specified attribute is not found, a null value is returned. Can be obtained from listLDAPAttributeNames. req-attributes.value: Not used in the request. Contains the value of the specified attributes in the response.

Response Example

Returns a listLDAPAttributesResponse element (from the LDAPService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listLDAPAttributes alias="easyAs" dn="ou=Steve Simonsen,ou=London,ou=AllEmployees"> <req-attributes name="employeenumber"> </req-attributes> </ldap:listLDAPAttributes> </soapenv:Body> </soapenv:Envelope>

Response:
SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listLDAPAttributesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> <req-attributes ldap-alias="easyAs" ldap-attribute="employeenumber" ldap-dn="ou=Steve Simonsen,ou=London,ou=AllEmployees" name="employeenumber" xmlns=""> <value>1323</value> </req-attributes> </listLDAPAttributesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

listLDAPAttributes 503

Service Connector API (Java Method)

Method Service listLDAPAttributes (args) LDAPService

TIBCO ActiveMatrix BPM - BPM Developers Guide

504

| Chapter 24

LDAPService

listLDAPAttributeNames
List all LDAP attribute names that exist in a particular LDAP source and that have data: The request must specify the LDAP source from which attribute data should be returned. The response returns a list of LDAP attribute names that exist in the specified LDAP source, and (optionally) a list of sample entries.

Required System Action LDAPAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

listLDAPAttributeNames 505

Web Service API (SOAP Operation)

Request Parameter notes Uses the listLDAPAttributeNames element (from the LDAPService schema) alias: Can be obtained from listLDAPSources. filter: Must be specified. See Using LDAP Filters for details of LDAP filter expressions usage. (This can be a string such as "(cn=*)", which returns all entries with a valid cn attribute.) sample-data-number: Defaults to 0 (zero), which causes only attribute name to be returned, with no sample data. If sample data is requested, the returned data returned for each attribute is random.

Response Example

Returns a listLDAPAttributeNamesResponse element (from the LDAPService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listLDAPAttributeNames alias="easyAs" filter="(employeenumber=12*)" sample-data-number="1"/> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

506

| Chapter 24

LDAPService

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listLDAPAttributeNamesResponse entity-count="3" xmlns="http://ldapservice.api.de.n2.tibco.com"> <Names xmlns=""> <AttributeName>mail</AttributeName> <AttributeName>sn</AttributeName> <AttributeName>ou</AttributeName> <AttributeName>manager</AttributeName> <AttributeName>employeetype</AttributeName> <AttributeName>userpassword</AttributeName> <AttributeName>employeenumber</AttributeName> <AttributeName>cn</AttributeName> </Names> <LdapEntry xmlns=""> <LdapAttribute name="mail"> <value>chill@easyasinsurance.com</value> </LdapAttribute> <LdapAttribute name="sn"> <value>Hill</value> </LdapAttribute> <LdapAttribute name="ou"> <value>Clint Hill</value> </LdapAttribute> <LdapAttribute name="manager"> <value>ou=John Eustace,ou=Swindon,ou=AllEmployees,o=easyAsInsurance</value> </LdapAttribute> <LdapAttribute name="employeetype"> <value>Permanent</value> </LdapAttribute> <LdapAttribute name="userpassword"> <value>dGliY28xMjM=</value> </LdapAttribute> <LdapAttribute name="employeenumber"> <value>1201</value> </LdapAttribute> <LdapAttribute name="cn"> <value>Mr Clint Hill</value> </LdapAttribute> </LdapAttribute> </LdapEntry> </listLDAPAttributeNamesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

listLDAPAttributeNames 507

Service Connector API (Java Method)

Method Service listLDAPAttributeNames (args) LDAPService

TIBCO ActiveMatrix BPM - BPM Developers Guide

508

| Chapter 24

LDAPService

listContainerResources
List the organization model resources in a particular LDAP container. Note that this operation returns only resources that already exist (that is, they have been "created" with either the getResourceGuid or mapEntities operation). To get resources that already exist, as well as those that are potential resources (those that are available in an LDAP source, but have not been created yet), use the listLDAPEntities operation. The request must specify the LDAP container for which resources should be listed. The response returns a list of the organization model resources in the specified LDAP container. Note that this operation returns an empty response if the calling user does not have access to an organization to which a LDAP container is associated (because of organization relationships). For more information, see Organization Relationships on page 123. Required System Action resourceAdmin and/or LDAPAdmin1

1. This operation can be called by users possessing either the resourceAdmin or LDAPAdmin system action. The LDAPAdmin system action gives the user additional access to organizations that are restricted due to organization relationships. For more information, see Overriding Organization Relationships on page 124.
TIBCO ActiveMatrix BPM - BPM Developers Guide

listContainerResources 509

Web Service API (SOAP Operation)

Request Parameter notes Uses the listContainerResources element (from the LDAPService schema) model-version: Note that resources are not versioned, therefore, the model version does not effect the resources returned. However, it can effect the resource details (entities, such as positions, groups, privileges, etc.), as they are versioned and may not appear in all organization model versions. Use -1 to specify the latest version. You can get the available versions from listModelVersions. container-id: Can be obtained from listLDAPContainers. You can also pass a 0 (zero) in container-id to get a list of administrator users (those created by the system that you cannot delete), as well as resources that had been created in an LDAP container that was subsequently deleted without first deleting the resources that were in the container. If you specify a container that does not exist, the response contains no resources; it does not cause an exception. Response Returns a listContainerResourcesResponse element (from the LDAPService schema).

TIBCO ActiveMatrix BPM - BPM Developers Guide

510

| Chapter 24
Example

LDAPService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ldap="http://ldapservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <ldap:listContainerResources model-version="-1" container-id="1"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listContainerResourcesResponse xmlns="http://ldapservice.api.de.n2.tibco.com"> <LdapResource guid="99E75521-E091-4AC6-A8AE-7561BF1ABCB5" name="Clint Hill" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="OU=Clint Hill, OU=Swindon, OU=AllEmployees, O=easyAsInsurance"/> </LdapResource> <LdapResource guid="D2E3C35F-7213-42FE-8877-86EA03F96880" name="Tony Pulis" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="EasyAs" ldap-alias="easyAs" ldap-dn="OU=Tony Pulis, OU=London, OU=AllEmployees, O=easyAsInsurance"/> </LdapResource> </listContainerResourcesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service listContainerResources (args) LDAPService

TIBCO ActiveMatrix BPM - BPM Developers Guide

MappingService 511

Chapter 25

MappingService

MappingService is one of the Directory Services provided by Work Manager. Use MappingService requests to manage mappings between organization model resources and LDAP entities.

Topics
listMappedEntities, page 512 mapEntities, page 515 getResourceGuid, page 518 deleteResource, page 521 updateCapabilityAssignments, page 523

TIBCO ActiveMatrix BPM - BPM Developers Guide

512

| Chapter 25

MappingService

listMappedEntities
List the resources that are currently mapped to the specified group or position: The request must specify the organization model entity (group or position) for which mapped resources are to be returned, as well as the GUID for the group or position. The response returns the details of each resource that is mapped to the specified group or position.

Required System Action resourceAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

listMappedEntities 513

Web Service API (SOAP Operation)

Request Parameter notes Uses the listMappedEntities element (from the MappingService schema) Response entity-type: Must be either GROUP or POSITION, as those are the only entities to which resources can be mapped. guid: Can be obtained from listOrgModelOverview. qualifier: Not used in this operation.

Returns a listMappedEntitiesResponse element (from the MappingService schema) If there are no resources currently mapped to the specified group or position, the response is an empty document.

TIBCO ActiveMatrix BPM - BPM Developers Guide

514

| Chapter 25
Example

MappingService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:map="http://mapping.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <map:listMappedEntities> <parent-entity model-version="-1" entity-type="GROUP" guid="_Jb8oYMpREd64gM7QE8RwxA" /> </map:listMappedEntities> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listMappedEntitiesResponse xmlns="http://mapping.api.de.n2.tibco.com"> <resource guid="B15F1CE0-4B28-4F48-BC7C-42C171A9AF48" name="Liam Lawrence" resource-type="HUMAN" xmlns=""> <LdapReference container-id="1" container-name="easyAs" ldap-alias="easyAs" ldap-dn="OU=Liam Lawrence, OU=London, OU=AllEmployees, O=easyAsInsurance"/> <group entity-type="GROUP" guid="_Jb8oYMpREd64gM7QE8RwxA" model-version="3" name="Employees"/> <group entity-type="GROUP" guid="_mHwlMMpUEd64gM7QE8RwxA" model-version="3" name="Consultants"/> <privilege entity-type="PRIVILEGE" guid="_I8YiEMpSEd64gM7QE8RwxA" model-version="3" name="BaseUser"> <origin entity-type="GROUP" guid="_Jb8oYMpREd64gM7QE8RwxA" model-version="3" name="Employees"/> </privilege> . . . </listMappedEntitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service listMappedEntities (args) MappingService

TIBCO ActiveMatrix BPM - BPM Developers Guide

mapEntities 515

mapEntities
Map resources to, or remove resources from, one or more positions or groups: The request must specify the target positions or groups and the resources that are to be mapped to, or removed from, those positions or groups. You can map already existing resources by passing their GUID. You can map and create a resource at the same time by passing an LdapReference from which the resource can be derived. The response returns the resources that were mapped to or removed from the specified positions or groups.

See also: Mapping Users on page 92. Required System Action createResourceAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

516

| Chapter 25

MappingService

Web Service API (SOAP Operation)

Request Parameter notes Uses the mapEntities element (from the MappingService schema) target.entity-type: Must be either GROUP or POSITION, as those are the only entities to which resources can be mapped. target.guid: Can be obtained from listOrgModelOverview. target.qualifier: Not used in this operation.

Use the create element when adding resources to groups or positions create.resource-type: Must be HUMAN when mapping users to groups or positions. create.guid: Pass a GUID when adding existing resources to groups/positions. Can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources. create.name: The name assigned to the newly created resource. Used only when creating a new resource by passing in an LdapReference. create.startDate, endDate: For an example of usage, see Example 2Mapping a Resource that Does Not Currently Exist on page 101. create.invalid, invalidReason: Are not passed in the request; they are returned in the response if there is a conflict with an existing resource. create.LdapReference: Pass this parameter if you are creating and mapping a resource at the same time. Can be obtained from listLDAPEntities.

Use the remove element when removing resources from groups or positions. remove.entity-type: Must be RESOURCE. remove.guid: Can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources. remove.qualifier: Not used in this operation.

Note that you can adjust already specified start and end dates by including both the remove and the create elements for the same resource, along with the startDate and endDate attributes with the new dates. Response Returns a mapEntitiesResponse element (from the MappingService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

mapEntities 517

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:map="http://mapping.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <map:mapEntities> <entityMapping> <target model-version="-1" entity-type="GROUP" guid="_xa5ewOtZEd-mNLRdDlu5kA" /> <create resource-type="HUMAN" guid="F270973F-E79D-49B7-A5E6-44D1BC4446AD" > </create> </entityMapping> </map:mapEntities> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <mapEntitiesResponse xmlns="http://mapping.api.de.n2.tibco.com"> <result modified="1" xmlns=""> <resource guid="F270973F-E79D-49B7-A5E6-44D1BC4446AD" name="John Eustace" resource-type="HUMAN" xmlns:map="http://mapping.api.de.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"></resource> </result> </mapEntitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service mapEntities (args) MappingService

TIBCO ActiveMatrix BPM - BPM Developers Guide

518

| Chapter 25

MappingService

getResourceGuid
Create a resource (including assigning a GUID to the resource) without mapping the resource to a group or position. This allows the created resource to log into a BPM application, but not receive work items. (This operation will also return an existing resources name if a resource GUID is passed in, but thats not its primary purpose.). The request must specify the details of the organization model resource (and/or its underlying LDAP entries) that is to be found or created. The response returns the details of the requested organization model resource (whether found or created).

See also: Creating Resources on page 93. Required System Action createResourceAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

getResourceGuid 519

Web Service API (SOAP Operation)

Request Parameter notes Uses the getResourceGuid element (from the MappingService schema) resource-type: Must be HUMAN. guid: If a GUID of an existing resource is passed in this attribute, the resources name is returned. Can be obtained from listContainerResources. You would normally not pass this; instead you will pass an LdapReference, which identifies the resource to create. name: The name given to the newly created resource. This is the name the resource must use to log in. startDate, endDate: Not used in this operation. invalid, invalidReason: Are not passed in the request; they are returned in the response if there is a conflict with an existing resource. LdapReference: Pass this parameter if you are creating and mapping a resource at the same time. Can be obtained from listLDAPEntities.

Response

Returns a getResourceGuidResponse element (from the MappingService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

520

| Chapter 25
Example

MappingService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:map="http://mapping.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <map:getResourceGuid> <target resource-type="HUMAN" name="Steve Simonsen" > <LdapReference container-id="1" container-name="easyAs" ldap-alias="easyAs" ldap-dn="ou=Steve Simonsen,ou=London,ou=AllEmployees,o=easyAsInsurance"/> </target> </map:getResourceGuid> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getResourceGuidResponse xmlns="http://mapping.api.de.n2.tibco.com"> <entity guid="3B2CE289-66F0-4539-B9BA-D0C302FD2B31" name="Steve Simonsen" resource-type="HUMAN" xmlns="" xmlns:map="http://mapping.api.de.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <LdapReference container-id="1" container-name="easyAs" ldap-alias="easyAs" ldap-dn="ou=Steve Simonsen,ou=London,ou=AllEmployees,o=easyAsInsurance"/> </entity> </getResourceGuidResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service getResourceGuid (args) MappingService

TIBCO ActiveMatrix BPM - BPM Developers Guide

deleteResource 521

deleteResource
Delete an organization model resource and its associated organization mappings (if any): The request must specify the GUID of the organization model resource to be deleted. The response returns a value indicating whether the specified organization model resource and its organizational associations have been successfully deleted.

Required System Action deleteResourceAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

522

| Chapter 25

MappingService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the deleteResource element (from the MappingService schema) resource-guid: Can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources.

Returns a deleteResourceResponse element (from the MappingService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:map="http://mapping.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <map:deleteResource resource-guid="C4A8178F-2E88-4187-9C5A-AA3F7673E0F3"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <deleteResourceResponse xmlns="http://mapping.api.de.n2.tibco.com"> <successful xmlns="">true</successful> </deleteResourceResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service deleteResource (args) MappingService

TIBCO ActiveMatrix BPM - BPM Developers Guide

updateCapabilityAssignments 523

updateCapabilityAssignments
Assign capabilities to, or remove capabilities from, one or more organization model resources: The request must specify the capabilities and the organization model resource to be updated, and whether the capability is to be assigned to, or removed from, the resource. The response returns a value indicating whether the specified organization model resources and capabilities have been successfully modified.

Required System Action resourceAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

524

| Chapter 25

MappingService

Web Service API (SOAP Operation)

Request Parameter notes Uses the updateCapabilityAssignments element (from the MappingService schema) Response Example remove: Defaults to FALSE, which assigns the capability. capability-guid: Can be obtained from getCapabilities or listCapabilities. qualifier: Used to add or remove a capability with a specific qualifier value. resource-guid: Can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources.

Returns a updateCapabilityAssignmentsResponse element (from the MappingService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:map="http://mapping.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <map:updateCapabilityAssignments> <assignment model-version="-1" remove="false" capability-guid="_LlK0IMpQEd64gM7QE8RwxA" qualifier="Spanish" resource-guid="6767C0A5-F6EF-437F-9E83-0A42496F2647"> </assignment> </map:updateCapabilityAssignments> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <updateCapabilityAssignmentsResponse xmlns="http://mapping.api.de.n2.tibco.com"> <successful xmlns="">true</successful> </updateCapabilityAssignmentsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service updateCapabilityAssignments (args) MappingService

TIBCO ActiveMatrix BPM - BPM Developers Guide

OrganisationalEntityConfigService 525

Chapter 26

OrganisationalEntityConfigService

OrganisationalEntityConfigService is one of the Business Resource Management Services provided by Work Manager. Use OrganisationalEntityConfigService requests to manage resource configuration attributes and to get or set them for individual resources.

Topics
getOrgEntityConfigAttributes, page 526 setOrgEntityConfigAttributes, page 528 getOrgEntityConfigAttributesAvailable, page 530 deleteOrgEntityConfigAttributes, page 534

TIBCO ActiveMatrix BPM - BPM Developers Guide

526

| Chapter 26

OrganisationalEntityConfigService

getOrgEntityConfigAttributes
Get the configuration attribute information currently defined for a resource: The request must specify the resource for whom configuration attribute information is required. The response returns the configuration attribute information currently defined for this resource.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

getOrgEntityConfigAttributes 527

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getOrgEntityConfigAttributes element (from the OrganisationalEntityConfigService schema) resource: the GUID of the resource whose configuration attribute information is required. A resources GUID can be obtained from a previous lookupUser operation.

Returns a getOrgEntityConfigAttributesResponse element (from the OrganisationalEntityConfigService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getOrgEntityConfigAttributes> <resource>931F96FA-EC57-43B5-AA61-613784B1BD10</resource> </api:getOrgEntityConfigAttributes> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getOrgEntityConfigAttributesResponse xmlns="http://api.brm.n2.tibco.com"> <orgEntityConfigAttribute xmlns=""> <attributeName>WorkItemAutoOpen</attributeName> <attributeValue>true</attributeValue> <readOnly>false</readOnly> </orgEntityConfigAttribute> </getOrgEntityConfigAttributesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service getOrgEntityConfigAttributes (args) OrganisationalEntityConfigService

TIBCO ActiveMatrix BPM - BPM Developers Guide

528

| Chapter 26

OrganisationalEntityConfigService

setOrgEntityConfigAttributes
Set one or more configuration attributes for a resource: The request must specify the configuration attribute information that should be set and the resource for whom it is to be set. The response returns whether the request succeeded or failed.

Required System Action The autoOpenNextWorkItem system action is required to set the WorkItemAutoOpen attribute.

TIBCO ActiveMatrix BPM - BPM Developers Guide

setOrgEntityConfigAttributes 529

Web Service API (SOAP Operation)

Request Parameter notes Uses the setOrgEntityConfigAttributes element (from the OrganisationalEntityConfigService schema) Response Example resource: the GUID of the resource whose configuration attributes are being set. A resources GUID can be obtained from a previous lookupUser operation. orgEntityConfigAttributeSet: contains an attributeName and an attributeValue for each configuration attribute being set.

Returns a setOrgEntityConfigAttributesResponse element (from the OrganisationalEntityConfigService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:setOrgEntityConfigAttributes resource="931F96FA-EC57-43B5-AA61-613784B1BD10"> <orgEntityConfigAttributeSet> <attributeName>WorkItemAutoOpen</attributeName> <attributeValue>true</attributeValue> </orgEntityConfigAttributeSet> </api:setOrgEntityConfigAttributes> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <setOrgEntityConfigAttributesResponse xmlns="http://api.brm.n2.tibco.com"> <success xmlns="">true</success> </setOrgEntityConfigAttributesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service setOrgEntityConfigAttributes (args) OrganisationalEntityConfigService

TIBCO ActiveMatrix BPM - BPM Developers Guide

530

| Chapter 26

OrganisationalEntityConfigService

getOrgEntityConfigAttributesAvailable
Get a list of available configuration attributes that can be applied to an organization model entity: The request must specify how many configuration attributes to return. The response returns a list of the specified number of configuration attributes. Returns the attributeName for each attribute, and whether or not it is read-only.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

getOrgEntityConfigAttributesAvailable 531

Web Service API (SOAP Operation)

Request Parameter notes Uses the getOrgEntityConfigAttributesAvailable element (from the OrganisationalEntityConfigService schema) Response startAt: the position in the list of available configuration attributes from which to start the page of results. numToReturn: the number of configuration attributes to include in the response.

Returns a getOrgEntityConfigAttributesAvailableResponse element (from the OrganisationalEntityConfigService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

532

| Chapter 26
Example

OrganisationalEntityConfigService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getOrgEntityConfigAttributesAvailable> <startAt>0</startAt> <numToReturn>10</numToReturn> </api:getOrgEntityConfigAttributesAvailable> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getOrgEntityConfigAttributesAvailableResponse xmlns="http://api.brm.n2.tibco.com"> <orgEntityConfigAttributesAvailable xmlns=""> <attributeName>MaxOpenWorkItemCount</attributeName> <readOnly>false</readOnly> </orgEntityConfigAttributesAvailable> <orgEntityConfigAttributesAvailable xmlns=""> <attributeName>WorkItemFilterCriteriaAPI</attributeName> <readOnly>true</readOnly> </orgEntityConfigAttributesAvailable> <orgEntityConfigAttributesAvailable xmlns=""> <attributeName>WorkItemOrderCriteriaAPI</attributeName> <readOnly>true</readOnly> </orgEntityConfigAttributesAvailable> <orgEntityConfigAttributesAvailable xmlns=""> <attributeName>WorkItemOrderCriteriaPARSED</attributeName> <readOnly>true</readOnly> </orgEntityConfigAttributesAvailable> <orgEntityConfigAttributesAvailable xmlns=""> <attributeName>WorkItemOrderCriteriaHQLPARSED </attributeName> <readOnly>true</readOnly> </orgEntityConfigAttributesAvailable> <orgEntityConfigAttributesAvailable xmlns=""> <attributeName>WorkItemAutoOpen</attributeName> <readOnly>false</readOnly> </orgEntityConfigAttributesAvailable> </getOrgEntityConfigAttributesAvailableResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getOrgEntityConfigAttributesAvailable 533

Service Connector API (Java Method)

Method Service getorgEntityConfigAttributesAvailable (args) OrganisationalEntityConfigService

TIBCO ActiveMatrix BPM - BPM Developers Guide

534

| Chapter 26

OrganisationalEntityConfigService

deleteOrgEntityConfigAttributes
Delete one or more configuration attributes for a resource: The request must specify the configuration attributes that should be deleted and the resource from whom they are to be deleted. The response returns whether the request succeeded or failed.

Required System Action The autoOpenNextWorkItem system action is required to delete the WorkItemAutoOpen attribute.

TIBCO ActiveMatrix BPM - BPM Developers Guide

deleteOrgEntityConfigAttributes 535

Web Service API (SOAP Operation)

Request Parameter notes Uses the deleteOrgEntityConfigAttributes element (from the OrganisationalEntityConfigService schema) resource: the GUID of the resource whose configuration attributes are to be deleted. A resources GUID can be obtained from a previous lookupUser operation. attributename: one or more names of the configuration attributes to be deleted.

Response Example

Returns a deleteOrgEntityConfigAttributesResponse element (from the OrganisationalEntityConfigService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:deleteOrgEntityConfigAttributes resource="931F96FA-EC57-43B5-AA61-613784B1BD10"> <attributeName>WorkItemAutoOpen</attributeName> </api:deleteOrgEntityConfigAttributes> </soapenv:Body> </soapenv:Envelope>

Response:
SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <deleteOrgEntityConfigAttributesResponse xmlns="http://api.brm.n2.tibco.com"> <success xmlns="">true</success> </deleteOrgEntityConfigAttributesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service deleteOrgEntityConfigAttributes (args) OrganisationalEntityConfigService

TIBCO ActiveMatrix BPM - BPM Developers Guide

536

| Chapter 26

OrganisationalEntityConfigService

TIBCO ActiveMatrix BPM - BPM Developers Guide

PageFlowService 537

Chapter 27

PageFlowService

PageFlowService is one of the Pageflow Services provided by Work Managers PageFlow Engine. Use the PageFlowService operations to get information about and interact with deployed PageFlows.

Topics
listPageFlows, page 538 startPageFlow, page 541 updatePageFlow, page 544 injectPageFlowEvent, page 548 cancelPageFlow, page 551

TIBCO ActiveMatrix BPM - BPM Developers Guide

538

| Chapter 27

PageFlowService

listPageFlows
List all deployed pageflows. The request requests a list of all deployed pageflows. The response returns the detailed descriptions of the deployed pageflows. The parameter includeFormalParameters determines whether pageflows that have formal parameters are listed or not. See Parameter notes for details. If the parameter includeFormalParameters is not specified, only the pageflows that do not have formal parameters are listed.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

listPageFlows 539

Web Service API (SOAP Operation)

Request Parameter notes Uses the listPageFlows element (from the PageFlowService schema). includeFormalParameters: determines if the response includes pageflows with formal parameters. By default, the value is set to false and the response lists the pageflows without formal parameters. When set to true, the response includes the pageflows with formal parameters as well. getTotalCount: total number of pageflows listed in the response. numberOfItems: maximum number of items (pageflows) that the response message can contain. startPosition: start position in the list of the first item on the response returned to the user. The list is zero-based. To start at the first item, specify 0.

Response Example

Returns a listPageFlowsResponse element (from the PageFlowService schema). Request:

<soapenv:Body> <pag:listPageFlows startPosition="0" numberOfItems="10" getTotalCount="true"> <includeFormalParameters>true</includeFormalParameters> </pag:listPageFlows> </soapenv:Body>

Response:
<SOAP-ENV:Body> <listPageFlowsResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <totalItems xmlns="">3</totalItems> <pageFlowTemplate hasFormalParameters="true" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" processName="RequestAdditionalDataPageflow" version="1.0.0.201108111516" xmlns=""/> <pageFlowTemplate hasFormalParameters="false" moduleName="/APH_WelcomeUsersImplementSolution/Process Packages/aph_test.xpdl" processName="GetName" version="1.0.0.201108111305" xmlns=""/> <pageFlowTemplate hasFormalParameters="true" moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" processName="ProcessPackageProcess" version="1.0.0.201108161050" xmlns=""/> </listPageFlowsResponse> </SOAP-ENV:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

540

| Chapter 27

PageFlowService

Service Connector API (Java Method)

Method Service listPageFlows (args) PageFlowService

TIBCO ActiveMatrix BPM - BPM Developers Guide

startPageFlow 541

startPageFlow
Starts an instance of a deployed pageflow. The request identifies the pageflow of which you want to start an instance. The response returns the complete information about the started pageflow instance.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

542

| Chapter 27

PageFlowService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the startPageFlow element (from the PageFlowService schema). None Returns a startPageFlowResponse element (from the PageFlowService schema). Request:
<soapenv:Body> <pag:startPageFlow> <pageFlowDefinition moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" processName="ProcessPackageProcess" version="1.0.0.201108161050"/> <formalParams payloadMode="XML"> <XmlPayload> <inputs name="Names" type="Text" optional="true" array="false"> <simpleSpec length="50"> <value>TIBCO</value> </simpleSpec> </inputs> </XmlPayload> </formalParams> <responsePayloadMode>XML</responsePayloadMode> </pag:startPageFlow> </soapenv:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

startPageFlow 543

Response:
<SOAP-ENV:Body> <startPageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" processName="ProcessPackageProcess" version="1.0.0.201108161050"/> <processReference> <id>pvm:0a101f</id> <name>ProcessPackageProcess</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g1f.5" activityModelId="_VK4SIKh8EeCt2PSB39ZXYA" activityName="UserTasks" moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" moduleVersion="1.0.0.201108161050" processName="ProcessPackageProcess"/> <payload payloadMode="XML"> <XmlPayload/> </payload> </pageData> </pageResponse> </startPageFlowResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service startPageFlow (args) PageFlowService

TIBCO ActiveMatrix BPM - BPM Developers Guide

544

| Chapter 27

PageFlowService

updatePageFlow
Updates a specified pageflow instance. The request identifies the pageflow instance to be updated. You can optionally specify the payload mode and provide the payload in the request message. The response returns the complete information of the updated pageflow instance including the execution state of the pageflow.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

updatePageFlow 545

Web Service API (SOAP Operation)

Request Parameter notes Response Uses the updatePageFlow element (from the PageFlowService schema). None Returns a updatePageFlowResponse element (from the PageFlowService schema).

TIBCO ActiveMatrix BPM - BPM Developers Guide

546

| Chapter 27
Example

PageFlowService

Request:
<soapenv:Body> <pag:updatePageFlow> <context> <processReference> <id>pvm:0a10q</id> </processReference> <activityReference activityId="pvm:001gq.5"/> </context> <pageFields feedFormat="NO_FORMAT" feedMode="XML"> <XMLObjectModel> <inputs array="false" name="Names" optional="true" type="Complex"> <simpleSpec/> </inputs> </XMLObjectModel> </pageFields> <responseFeedType> <feedTypes feedFormat="NO_FORMAT" feedMode="XML"/> </responseFeedType> </pag:updatePageFlow> </soapenv:Body>

Response:
<SOAP-ENV:Body> <updatePageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <pageResponse executionState="COMPLETED" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/Inject/Process Packages_Inject/ProcessPackage.xpdl" processName="ProcessPackageProcess" version="1.0.0.201108021509"/> <processReference> <id>pvm:0a10q</id> <name>ProcessPackageProcess</name> </processReference> </context> <pageData> <responseFeed> <XMLObjectModel xmlns:pag="http://pageflow.api.pfe.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <inputs array="false" name="Names" optional="true" type="Complex"> <simpleSpec/> </inputs> </XMLObjectModel> </responseFeed> </pageData> </pageResponse> </updatePageFlowResponse> </SOAP-ENV:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

updatePageFlow 547

Service Connector API (Java Method)

Method Service updatePageFlow (args) PageFlowService

TIBCO ActiveMatrix BPM - BPM Developers Guide

548

| Chapter 27

PageFlowService

injectPageFlowEvent
Injects an event into an in-progress pageflow. The request identifies the pageflow event to be injected. The response returns the information about the injected pageflow event.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

injectPageFlowEvent 549

Web Service API (SOAP Operation)

Request Parameter notes Uses the injectPageFlowEvent element (from the PageFlowService schema). eventDefinition: It consists of the moduleName, processName, eventName, and processInstanceId of the specified pageflow. You can obtain the values for these parameters from the response returned by startPageFlow or updatePageFlow operations.

formalParams: values for the formal parameters that you want to inject. Response Example Returns a injectPageFlowResponse element (from the PageFlowService schema). Request:
<soapenv:Body> <pag:injectPageFlowEvent> <eventDefinition moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess2" eventName="IntermediateEvent" processInstanceId="pvm:0a101u"/> <formalParams payloadMode="XML"> <XmlPayload> <inputs array="false" name="Parameter" optional="false" type="String"> <simpleSpec length="50"> <!--Zero or more repetitions:--> <value>TIBX</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter2" optional="false" type="Integer Number"> <simpleSpec length="9"> <!--Zero or more repetitions:--> <value>147</value> </simpleSpec> </inputs> </XmlPayload> </formalParams> </pag:injectPageFlowEvent> </soapenv:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

550

| Chapter 27

PageFlowService

Response:
<SOAP-ENV:Body> <injectPageFlowEventResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <pageResponse executionState="IN_PROGRESS" xmlns=""> <context> <pageFlowTemplate hasFormalParameters="false" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" processName="EventHandlerProcess2" version="1.0.0.201108161235"/> <processReference> <id>pvm:0a101u</id> <name>EventHandlerProcess2</name> </processReference> </context> <pageData> <pageReference activityId="pvm:001g1u.9" activityModelId="_eMANL720EeC61dgFHyHHpQ" activityName="UserTask3" moduleName="/EventHandler/Process Packages/EventHandler.xpdl" moduleVersion="1.0.0.201108161235" processName="EventHandlerProcess2"/> <payload payloadMode="XML"> <XmlPayload> <inputs array="false" name="Parameter" optional="true" type="String"> <simpleSpec> <value>[Ljava.lang.String;@2818fe57</value> </simpleSpec> </inputs> <inputs array="false" name="Parameter2" optional="true" type="Integer Number"> <simpleSpec> <value>[Ljava.lang.String;@e21652</value> </simpleSpec> </inputs> <inouts array="false" name="Field" optional="true" type="String"> <simpleSpec/> </inouts> </XmlPayload> </payload> </pageData> </pageResponse> </injectPageFlowEventResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service injectPageFlowEvent (args) PageFlowService

TIBCO ActiveMatrix BPM - BPM Developers Guide

cancelPageFlow 551

cancelPageFlow
Cancels a given pageflow instance. The request identifies the pageflow process instance to be cancelled. The response returns the execution status - SUCCESS when the pageflow is cancelled successfully and a service fault if the execution fails.

Required System Action None.

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the cancelPageFlow element (from the PageFlowService schema). processInstanceId: the process reference ID returned when you start a pageflow. You can obtain the value from the response returned by startPageFlow or updatePageFlow.

Returns a cancelPageFlowResponse element (from the PageFlowService schema). Request:

<soapenv:Body> <pag:cancelPageFlow> <processInstanceId>pvm:0a101e</processInstanceId> </pag:cancelPageFlow> </soapenv:Body>

Response:
<SOAP-ENV:Body> <cancelPageFlowResponse xmlns="http://pageflow.api.pfe.n2.tibco.com"> <status xmlns="">SUCCESS</status> </cancelPageFlowResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service cancelPageFlow (args) PageFlowService

TIBCO ActiveMatrix BPM - BPM Developers Guide

552

| Chapter 27

PageFlowService

TIBCO ActiveMatrix BPM - BPM Developers Guide

ProcessManagerService 553

Chapter 28

ProcessManagerService

ProcessManagerService is one of the Process Services provided by Process Manager. Use ProcessManagerService operations to manage process templates and process instances.

Topics
cancelProcessInstance, page 555 cancelProcessInstances, page 557 createProcessInstance, page 559 getActivityInstanceStatus, page 562 getParameterValue, page 564 getProcessInstanceStatus, page 566 getProcessInstanceSummary, page 568 getStarterOperationInfo, page 571 listProcessInstanceAttributes, page 574 listSetofProcessInstanceAttributes, page 578 listProcessInstances, page 581 listProcessTemplateAttributes, page 584 listProcessTemplates, page 588 listStarterOperations, page 592 queryDone, page 595 queryFirstPage, page 597 queryLastPage, page 601 queryNextPage, page 604 queryPreviousPage, page 608
TIBCO ActiveMatrix BPM - BPM Developers Guide

554

| Chapter 28

ProcessManagerService

queryProcessInstanceCount, page 612 queryProcessInstances, page 614 queryProcessInstancesAlt, page 617 queryProcessTemplateCount, page 620 queryProcessTemplates, page 622 queryProcessTemplatesAlt, page 626 resumeProcessInstance, page 629 resumeProcessInstances, page 631 setDeadlineExpiration, page 633 setPriority, page 635 suspendProcessInstance, page 637 suspendProcessInstances, page 639 getMigrationPoints, page 641 setMigrationRules, page 644 unsetMigrationRules, page 646 clearMigrationRules, page 648 isSetMigrationRule, page 650 listMigrationRules, page 652

TIBCO ActiveMatrix BPM - BPM Developers Guide

cancelProcessInstance 555

cancelProcessInstance
Cancel a specific process instance. The request must specify the unique ID of the process instance that is to be cancelled. The response indicates whether or not the process instance has been successfully cancelled.

Required System Action cancelProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

556

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the processID element (from the ProcessManagement schema) processID: Can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt.

Returns a success element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:processID>pvm:0a126</proc:processID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service cancelProcessInstance (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

cancelProcessInstances 557

cancelProcessInstances
Cancel all process instances for one or more process templates. The request must specify the process templates for which instances are to be cancelled. The response returns a count of the number of process instances that have been cancelled.

Required System Action cancelProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

558

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the qualifiedProcessName element (from the ProcessManagement schema) moduleName, processName, and version can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt.

Returns an itemCount element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName></proc:moduleName> <proc:processName>CSCallbackProcess</proc:processName> <proc:version></proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:itemCount xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">2</proc:itemCount> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service cancelProcessInstances (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

createProcessInstance 559

createProcessInstance
Create a process instance using a starter operation. The request must specify the starter operation and its associated parameter values that should be used to create the process instance. The response returns the unique ID of the newly created process instance.

Required System Action startprocess

TIBCO ActiveMatrix BPM - BPM Developers Guide

560

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Uses the createProcessInstanceInput element (from the ProcessManagement schema) processQName: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt. operationName: This is the "starter operation" name, which must be a start event with a trigger type of "None". Can be obtained from listStarterOperations. parameterMap: The names of the "start parameters" (also known as "formal parameters") can be obtained from getStarterOperationInfo. These are used to pass data into the process instance being started.

Response Example

Returns a processID element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:createProcessInstanceInput> <proc:processQName> <proc:moduleName>/AccountCheck/Process Packages/ProcessPackage.xpdl</proc:moduleName> <proc:processName>AccountCheck</proc:processName> <proc:version>1.0.0.201107121120</proc:version> </proc:processQName> <proc:operationName>StartEvent</proc:operationName> <proc:parameterMap> <!--Zero or more repetitions:--> <proc:parameter> <proc:name>CustomerID</proc:name> <proc:value>992251</proc:value> </proc:parameter> </proc:parameterMap> </proc:createProcessInstanceInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:processID xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">pvm:0a1213</proc:processID> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

createProcessInstance 561

Java Method
Method Service createProcessInstance (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

562

| Chapter 28

ProcessManagerService

getActivityInstanceStatus
Get the status of an activity for a particular process instance. The request must specify the activity and process instance for which the status should be returned. The response returns status information for the specified activity. This includes the activityID, which is used when setting a deadline time on an activitysee setDeadlineExpiration.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

getActivityInstanceStatus 563

SOAP Operation
Request Parameter notes Response Example Uses the getActivityInstanceStatusInput element (from the ProcessManagement schema) processID: Can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt.

Returns an activityInstanceStatus element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:getActivityInstanceStatusInput> <proc:processID>pvm:0a1216</proc:processID> <proc:activityName>EmbeddedSubProcess</proc:activityName> </proc:getActivityInstanceStatusInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <activityInstanceStatus xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <activityID>pvm:001ib0</activityID> <activityName>EmbeddedSubProcess</activityName> <activityState>waiting.state</activityState> <startTime>2011-07-13T08:51:35.250-07:00</startTime> <completionTime xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <deadlineExpirationTime>2011-07-13T09:51:35.862-07:00</deadlineExpirat ionTime> </activityInstanceStatus> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service getActivityInstanceStatus (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

564

| Chapter 28

ProcessManagerService

getParameterValue
Get the value of a specific parameter (also referred to as "custom attributes") for a particular process instance. The request must specify the parameter and the process instance for which the value should be returned. The response returns the value of the specified parameter.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

getParameterValue 565

SOAP Operation
Request Parameter notes Uses the getParameterValueInput element (from the ProcessManagement schema) Response Example processID: Can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt. parameterName: Can be obtained from listProcessInstanceAttributes.

Returns a getParameterValueOutput element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:getParameterValueInput> <proc:processID>pvm:0a127</proc:processID> <proc:parameterName>ContactPhone</proc:parameterName> </proc:getParameterValueInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getParameterValueOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <parameterValue>509-555-1234</parameterValue> </getParameterValueOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service getParameterValue (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

566

| Chapter 28

ProcessManagerService

getProcessInstanceStatus
Get the status of a particular process instance. The request must specify the ID of the process instance for which status information should be listed. The response returns the status of the specified process instance.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

getProcessInstanceStatus 567

SOAP Operation
Request Parameter notes Response Example Uses the processID element (from the ProcessManagement schema) processID: Can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt.

Returns a getProcessInstanceStatusOutput element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:processID>pvm:0a127</proc:processID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getProcessInstanceStatusOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processQName> <moduleName/> <processName>SalesCallbackProcess</processName> <version/> </processQName> <id>pvm:0a127</id> <state>ACTIVE</state> <startTime>2011-06-28T15:19:38.317-07:00</startTime> <waitingWorkCount>1</waitingWorkCount> <parentProcessID/> </getProcessInstanceStatusOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service getProcessInstanceStatus (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

568

| Chapter 28

ProcessManagerService

getProcessInstanceSummary
Get a full summary report on a specific process instance (this operation is most useful for debugging). The request must specify the ID of the process instance for which summary information should be listed. The response returns (in a formatted string) all information relevant to the specified process instance, including a snapshot of all process variables' values.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

getProcessInstanceSummary 569

SOAP Operation
Request Parameter notes Response Example Uses the processID element (from the ProcessManagement schema) processID: Can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt.

Returns a processInstanceSummary element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:processID>pvm:0a127</proc:processID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <processInstanceSummary xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <summary>Summary for pvm:0a127 Process SalesCallbackProcess, version 1.0.0.201105061158, ACTIVE, active.state Root Task [{TASK}bpelProcessActivity], waiting.state - _BX_flow [{TASK}bpelFlowActivity], waiting.state - Start [{TASK}bpelScopeActivity], done.state - _BX_sequence [{TASK}bpelSequenceActivity], done.state - _BX_receive [{TASK}bpelReceiveActivity], done.state - _BX_assign [{TASK}bpelAssignActivity], done.state - EndEvent [{TASK}bpelEmptyActivity], starting.state - ReturnCall [{TASK}bpelExtensionActivity], waiting.state - Start to ReturnCall [{LINK}bpelLink], from=Start, to=ReturnCall, true.state - ReturnCall to EndEvent [{LINK}bpelLink], from=ReturnCall, to=EndEvent, unset.state</summary> </processInstanceSummary> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method getProcessInstanceSummary (args)

TIBCO ActiveMatrix BPM - BPM Developers Guide

570

| Chapter 28
Service

ProcessManagerService

ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getStarterOperationInfo 571

getStarterOperationInfo
List the parameter details for a particular starter operation. (Starter operations refer to start events of processes. To be able to directly start an instance of a process template, the start event of the process must have a trigger type of "None" (as opposed to a trigger type of "Message", which requires that the process be started by a business service).) The request must specify the starter operation for which parameter details should be listed. The response returns the details of the of the specified starter operation's parameters.

Required System Action queryProcessTemplate

TIBCO ActiveMatrix BPM - BPM Developers Guide

572

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Uses the starterOperation element (from the ProcessManagement schema) Response Example processQName: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt. operationName: Can be obtained from listStarterOperations.

Returns a operationInfo element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:starterOperation> <proc:processQName> <proc:moduleName>/AccountCheck/Process Packages/ProcessPackage.xpdl</proc:moduleName> <proc:processName>AccountCheck</proc:processName> <proc:version>1.0.0.201107121120</proc:version> </proc:processQName> <proc:operation>StartEvent</proc:operation> </proc:starterOperation> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <operationInfo xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <operationName>StartEvent</operationName> <parameters> <templateAttribute> <name>CustomerID</name> <type>java.lang.String</type> </templateAttribute> </parameters> </operationInfo> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getStarterOperationInfo 573

Java Method
Method Service getStarterOperationInfo (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

574

| Chapter 28

ProcessManagerService

listProcessInstanceAttributes
List process instance attributes for one or more process templates (these attributes can be used in process instance queriessee queryProcessInstances and queryProcessInstancesAlt). The request must specify the criteria to be used to identify the process templates for which process instance attributes are to be listed. The response returns details of the process instance attributes associated with the process template specified in the request.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

listProcessInstanceAttributes 575

SOAP Operation
Request Parameter notes Response Uses the listProcessInstanceAttributesInput element (from the ProcessManagement schema) processQName: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt.

Returns a instanceAttributes element (from the ProcessManagement schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

576

| Chapter 28
Example

ProcessManagerService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:listProcessInstanceAttributesInput> <proc:processQName> <proc:moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</proc:moduleName> <proc:processName>WelcomeUsers</proc:processName> <proc:version>1.0.0.201106290831</proc:version> </proc:processQName> <proc:attributeType>FILTERABLE</proc:attributeType> </proc:listProcessInstanceAttributesInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <instanceAttributes xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <instanceAttribute> <name>INSTANCE.WAITING_WORK_COUNT</name> <type>integer</type> <processQName> <moduleName/> <processName/> <version/> </processQName> <viewtype>123</viewtype> </instanceAttribute> <instanceAttribute> <name>INSTANCE.VERSION</name> <type>string</type> <processQName> <moduleName/> <processName/> <version/> </processQName> <viewtype>123</viewtype> </instanceAttribute> . . . </instanceAttributes> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

listProcessInstanceAttributes 577

Java Method
Method Service listProcessInstanceAttributes (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

578

| Chapter 28

ProcessManagerService

listSetofProcessInstanceAttributes
List process instance attributes for a set of process templates (these attributes can be used in process instance queriessee queryProcessInstances and queryProcessInstancesAlt). The request must specify the process templates for which process instance attributes are to be listed. The response returns details of both the system-defined and user-defined attributes in the specified process instance(s).

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

listSetofProcessInstanceAttributes 579

SOAP Operation
Request Parameter notes Response Example Uses the listSetofProcessInstanceAttributesInput element (from the ProcessManagement schema) qualifiedProcessNames: Consists of one or more qualifiedProcessName elements, which can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt.

Returns a instanceAttributes element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:listSetofProcessInstanceAttributesInput> <proc:qualifiedProcessNames> <!--1 or more repetitions:--> <proc:qualifiedProcessName> <proc:moduleName>/HelpDesk/Process Packages/HelpDesk.xpdl</proc:moduleName> <proc:processName>InternalHelpDesk</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> <proc:qualifiedProcessName> <proc:moduleName>/SalesCallback/Process Packages/SalesCallback.xpdl</proc:moduleName> <proc:processName>SalesCallbackProcess</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> </proc:qualifiedProcessNames> <proc:attributeType>DISPLAYABLE</proc:attributeType> </proc:listSetofProcessInstanceAttributesInput> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

580

| Chapter 28

ProcessManagerService

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <instanceAttributes xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <instanceAttribute> <name>INSTANCE.PRIORITY</name> <type>short</type> <processQName> <moduleName/> <processName/> <version/> </processQName> <viewtype>123</viewtype> </instanceAttribute> <instanceAttribute> <name>ContactName</name> <type>string</type> <processQName> <moduleName>/SalesCallback/Process Packages/SalesCallback.xpdl</moduleName> <processName>SalesCallbackProcess</processName> <version>1.0.0.201105061158</version> </processQName> <viewtype>123</viewtype> </instanceAttribute> . . . <instanceAttribute> <name>MODULE.NAME</name> <type>string</type> <processQName> <moduleName/> <processName/> <version/> </processQName> <viewtype>123</viewtype> </instanceAttribute> </instanceAttributes> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service listSetofProcessInstanceAttributes (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

listProcessInstances 581

listProcessInstances
List process instances for one or more process templates. This is a convenience operation: queryProcessInstances can return the same information, but requires more input. The request must specify the process templates for which process instances are to be listed. The response returns the process instances that exist for the specified process template.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

582

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the qualifiedProcessName element (from the ProcessManagement schema) moduleName, processName, and version: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt.

Returns a processInstances element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</proc:moduleName> <proc:processName>WelcomeUsers</proc:processName> <proc:version>1.0.0.201106290731</proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <processInstances xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processInstance> <processQName> <moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</moduleName> <processName>WelcomeUsers</processName> <version>1.0.0.201106290731</version> </processQName> <id>pvm:0a12e</id> <state>ACTIVE</state> <startTime>2011-06-29T07:33:04.377-07:00</startTime> <completionTime xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <waitingWorkCount>1</waitingWorkCount> <parentProcessID/> </processInstance> </processInstances> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

listProcessInstances 583

Java Method
Method Service listProcessInstances (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

584

| Chapter 28

ProcessManagerService

listProcessTemplateAttributes
List process template attributes. These attributes, which are pre-defined variables and are the same for all process templates, can be used in queries for process templatessee queryProcessTemplates and queryProcessTemplatesAlt The request must specify any filter criteria to be used, to list only filterable, sortable or displayable attributes. The response returns only system-defined attributes (as name/type pairs) that match the specified filter.

Required System Action queryProcessTemplate

TIBCO ActiveMatrix BPM - BPM Developers Guide

listProcessTemplateAttributes 585

SOAP Operation
Request Parameter notes Response Uses the listProcessTemplateAttributesInput element (from the ProcessManagement schema) attributeType: FILTERABLE, SORTABLE, or DISPLAYABLE; or leave empty for all attribute types.

Returns a templateAttributes element (from the ProcessManagement schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

586

| Chapter 28
Example

ProcessManagerService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:listProcessTemplateAttributesInput> <proc:attributeType>FILTERABLE</proc:attributeType> </proc:listProcessTemplateAttributesInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <templateAttributes xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <templateAttribute> <name>DEFINITION.PRIORITY</name> <type>short</type> </templateAttribute> <templateAttribute> <name>DEFINITION.DESCRIPTION</name> <type>string</type> </templateAttribute> <templateAttribute> <name>DEFINITION.VERSION</name> <type>string</type> </templateAttribute> <templateAttribute> <name>DEFINITION.NAME</name> <type>string</type> </templateAttribute> <templateAttribute> <name>MODULE.NAME</name> <type>string</type> </templateAttribute> <templateAttribute> <name>DEFINITION.CREATION_DATE</name> <type>dateTime</type> </templateAttribute> </templateAttributes> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method listProcessTemplateAttributes (args)

TIBCO ActiveMatrix BPM - BPM Developers Guide

listProcessTemplateAttributes 587

Service

ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

588

| Chapter 28

ProcessManagerService

listProcessTemplates
List process templates that match the input criteria. This is a convenience operation: queryProcessTemplates can return the same information, but requires more input. The request must specify the search criteria for which matching process templates should be listed. The response returns the process templates that match the specified criteria.

Required System Action queryProcessTemplate

TIBCO ActiveMatrix BPM - BPM Developers Guide

listProcessTemplates 589

SOAP Operation
Request Parameter notes Response Uses the qualifiedProcessName element (from the ProcessManagement schema) None Returns a basicProcessTemplates element (from the ProcessManagement schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

590

| Chapter 28
Example

ProcessManagerService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName>/Acme-SubProcs/Process Packages/AcmeSubProcs.xpdl</proc:moduleName> <proc:processName></proc:processName> <proc:version></proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <basicProcessTemplates xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <basicProcessTemplate> <processQName> <moduleName>/Acme-SubProcs/Process Packages/AcmeSubProcs.xpdl</moduleName> <processName>Sub1</processName> <version>1.1.0.201105061158</version> </processQName> <description>*** Generated by TIBCO Business Studio.</description> </basicProcessTemplate> <basicProcessTemplate> <processQName> <moduleName>/Acme-SubProcs/Process Packages/AcmeSubProcs.xpdl</moduleName> <processName>Main</processName> <version>1.1.0.201105061158</version> </processQName> <description>*** Generated by TIBCO Business Studio.</description> </basicProcessTemplate> </basicProcessTemplates> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method listProcessTemplates (args)

TIBCO ActiveMatrix BPM - BPM Developers Guide

listProcessTemplates 591

Service

ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

592

| Chapter 28

ProcessManagerService

listStarterOperations
List available starter operations for one or more process templates (see also: createProcessInstance). (Starter operations refer to start events of processes. To be able to directly start an instance of a process template, the start event of the process must have a trigger type of "None" (as opposed to a trigger type of "Message", which requires that the process be started by a business service).) The request must specify the process templates for which starter operations are to be listed. The response returns all starter operations defined for the specified process templates.

Required System Action queryProcessTemplate

TIBCO ActiveMatrix BPM - BPM Developers Guide

listStarterOperations 593

SOAP Operation
Request Parameter notes Response Example Uses the qualifiedProcessName element (from the ProcessManagement schema) moduleName, processName, and version: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt.

Returns a starterOperations element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName>/HelpDesk/Process Packages/HelpDesk.xpdl</proc:moduleName> <proc:processName>InternalHelpDesk</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <starterOperations xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <starterOperation> <processQName> <moduleName>/HelpDesk/Process Packages/HelpDesk.xpdl</moduleName> <processName>InternalHelpDesk</processName> <version>1.0.0.201105061158</version> </processQName> <operation>StartEvent</operation> </starterOperation> </starterOperations> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method listStarterOperations (args)

TIBCO ActiveMatrix BPM - BPM Developers Guide

594

| Chapter 28
Service

ProcessManagerService

ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryDone 595

queryDone
Release all resources associated with a particular paged result set. An application must call this operation whenever it has finished with a particular paged result set. The request must specify the paging ID of the result set which is no longer required. The response indicates whether or not the resources associated with the specified result set have been successfully released.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

596

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Uses the pagingID element (from the ProcessManagement schema) pagingID: This is obtained when a query is paged by submitting -1 or a number greater than 0 for the PageSize parameter when calling the following operations: queryProcessInstances, queryProcessInstancesAlt, queryProcessTemplates, and queryProcessTemplatesAlt.

Response Example

Returns a success element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:pagingID>1304896907</proc:pagingID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service queryDone (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryFirstPage 597

queryFirstPage
List the first page of data from the result set of a particular query operation. The request must specify the paging ID of the result set for which the first page of data should be listed. The response returns a page of data, which will be a list of either process templates or process instances, depending on the originating call.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

598

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Uses the pagingID element (from the ProcessManagement schema) pagingID: This is obtained when a query is paged by submitting -1 or a number greater than 0 for the PageSize parameter when calling the following operations: queryProcessInstances, queryProcessInstancesAlt, queryProcessTemplates, and queryProcessTemplatesAlt.

Response

Returns a page element (from the ProcessManagement schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryFirstPage 599

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:pagingID>1304896907</proc:pagingID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <page xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processInstances> <processInstance> <processQName> <processName>SalesCallbackProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>TestNoneStarter</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>InternalHelpDesk</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>parallelProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>InternalHelpDesk</processName> </processQName> </processInstance> </processInstances> </page> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

600

| Chapter 28

ProcessManagerService

Java Method
Method Service queryFirstPage (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryLastPage 601

queryLastPage
List the last page of data from the result set of a particular query operation. The request must specify the paging ID of the result set for which the last page of data should be listed. The response returns a page of data, which will be a list of either process templates or process instances, depending on the originating call.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

602

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Uses the pagingID element (from the ProcessManagement schema) pagingID: This is obtained when a query is paged by submitting -1 or a number greater than 0 for the PageSize parameter when calling the following operations: queryProcessInstances, queryProcessInstancesAlt, queryProcessTemplates, and queryProcessTemplatesAlt.

Response Example

Returns a page element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:pagingID>1304896907</proc:pagingID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <page xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processInstances> <processInstance> <processQName> <processName>parallelProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>parallelProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>WithdrawProcess</processName> </processQName> </processInstance> </processInstances> </page> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryLastPage 603

Java Method
Method Service queryLastPage (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

604

| Chapter 28

ProcessManagerService

queryNextPage
List the next page of data from the result set of a particular query operation. The request must specify the paging ID of the result set for which the next page of data should be listed. The response returns a page of data, which will be a list of either process templates or process instances, depending on the originating call.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryNextPage 605

SOAP Operation
Request Parameter notes Uses the pagingID element (from the ProcessManagement schema) pagingID: This is obtained when a query is paged by submitting -1 or a number greater than 0 for the PageSize parameter when calling the following operations: queryProcessInstances, queryProcessInstancesAlt, queryProcessTemplates, and queryProcessTemplatesAlt.

Response

Returns a page element (from the ProcessManagement schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

606

| Chapter 28
Example

ProcessManagerService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:pagingID>1304896907</proc:pagingID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <page xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processInstances> <processInstance> <processQName> <processName>WelcomeUsers</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>HelpDeskProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>SalesCallbackProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>WithdrawProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>InternalHelpDesk</processName> </processQName> </processInstance> </processInstances> </page> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryNextPage 607

Java Method
Method Service queryNextPage (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

608

| Chapter 28

ProcessManagerService

queryPreviousPage
List the previous page of data from the result set of a particular query operation. The request must specify the paging ID of the result set for which the previous page of data should be listed. The response returns a page of data, which will be a list of either process templates or process instances, depending on the originating call.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryPreviousPage 609

SOAP Operation
Request Parameter notes Uses the pagingID element (from the ProcessManagement schema) pagingID: This is obtained when a query is paged by submitting -1 or a number greater than 0 for the PageSize parameter when calling the following operations: queryProcessInstances, queryProcessInstancesAlt, queryProcessTemplates, and queryProcessTemplatesAlt.

Response

Returns a page element (from the ProcessManagement schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

610

| Chapter 28
Example

ProcessManagerService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:pagingID>1304896907</proc:pagingID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <page xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processInstances> <processInstance> <processQName> <processName>SalesCallbackProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>TestNoneStarter</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>InternalHelpDesk</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>parallelProcess</processName> </processQName> </processInstance> <processInstance> <processQName> <processName>InternalHelpDesk</processName> </processQName> </processInstance> </processInstances> </page> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryPreviousPage 611

Java Method
Method Service queryPreviousPage (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

612

| Chapter 28

ProcessManagerService

queryProcessInstanceCount
Count the number of process instances that match certain criteria. The request must specify a SQL query that defines the search criteria. The response returns the number of process instances that match the specified criteria.

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryProcessInstanceCount 613

SOAP Operation
Request Parameter notes Response Example Uses the queryString element (from the ProcessManagement schema) queryString: For information about valid query strings, see Sorting and Filtering Lists of Process Templates and Instances on page 151.

Returns a itemCount element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:queryString>INSTANCE.PRIORITY = 200</proc:queryString> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:itemCount xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">7</proc:itemCount> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service queryProcessInstanceCount (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

614

| Chapter 28

ProcessManagerService

queryProcessInstances
Query information about process instances that match specified criteria. The request must specify a SQL query that defines the search criteria. The response returns information from process instances according to the specified criteria, either as a complete list or as the first page of a paged list (in which case a paging ID is also returned).

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryProcessInstances 615

SOAP Operation
Request Parameter notes Uses the queryProcessInstancesInput element (from the ProcessManagement schema) query: For information about valid SQL syntax, see Sorting and Filtering Lists of Process Templates and Instances on page 151. attributeMap: If a user-defined attribute is used in the SELECT statement of a paginated query, that attribute and its type should be included in the attributeMap, otherwise a database query must be made to get the type of the user-defined attribute, making the request less efficient (see the example below). pageSize: If you specify a paged result (pageSize = -1 or a number greater than 0), use the queryFirstPage, queryLastPage, queryNextPage, and queryPreviousPage operations to navigate the paged list, and queryDone to clear resources when you are finished with the paged list. (Note that the result limit for non-paginated queries (pageSize=0) is 500.)

Response Example

Returns a queryProcessInstancesOutput element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:queryProcessInstancesInput> <proc:query>SELECT ContactName FROM process WHERE INSTANCE.STATUS = 'ACTIVE'</proc:query> <proc:pageSize>10</proc:pageSize> <proc:attributeMap> <!--Zero or more repetitions:--> <proc:templateAttribute> <proc:name>ContactName</proc:name> <proc:type>string</proc:type> </proc:templateAttribute> </proc:attributeMap> </proc:queryProcessInstancesInput> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

616

| Chapter 28

ProcessManagerService

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryProcessInstancesOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processInstances> <processInstance> <customAttributes> <customAttribute> <name>ContactName</name> <value>Ira Olson</value> </customAttribute> </customAttributes> </processInstance> <processInstance> <customAttributes> <customAttribute> <name>ContactName</name> <value>Walter Burfiend</value> </customAttribute> </customAttributes> </processInstance> </processInstances> <pagingID>-1859988354</pagingID> </queryProcessInstancesOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service queryProcessInstances (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryProcessInstancesAlt 617

queryProcessInstancesAlt
Query information about process instances that match specified criteria. This is a variation of queryProcessInstances, in which the query string is divided into its constituent parts. The request must specify an SQL query that defines the search criteria The response returns information from process instances according to the specified criteria, either as a complete list or as the first page of a paged list (in which case a paging ID is also returned).

Required System Action queryProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

618

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Uses the queryProcessInstancesAltInput element (from the ProcessManagement schema) select, where, orderBy: For information about valid SQL syntax, see Sorting and Filtering Lists of Process Templates and Instances on page 151. attributeMap: If a user-defined attribute is used in the select parameter of a paginated query, that attribute and its type should be incudes in the attributeMap, otherwise a database query must be made to get the type of the user-defined attribute, making the request less efficient (see the example below). pageSize: If you specify a paged result (pageSize = -1 or a number greater than 0), use the queryFirstPage, queryLastPage, queryNextPage, and queryPreviousPage operations to navigate the paged list, and queryDone to clear resources when you are finished with the paged list. (Note that the result limit for non-paginated queries (pageSize=0) is 500.)

Response Example

Returns a queryProcessInstancesOutput element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:queryProcessInstancesAltInput> <proc:select>INSTANCE.NAME,INSTANCE.ID,Issue</proc:select> <proc:where>INSTANCE.STATUS = 'SUSPENDED'</proc:where> <proc:orderBy>INSTANCE.START_DATE</proc:orderBy> <proc:pageSize>10</proc:pageSize> <proc:attributeMap> <!--Zero or more repetitions:--> <proc:templateAttribute> <proc:name>Issue</proc:name> <proc:type>string</proc:type> </proc:templateAttribute> </proc:attributeMap> </proc:queryProcessInstancesAltInput> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryProcessInstancesAlt 619

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryProcessInstancesOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processInstances> <processInstance> <processQName> <processName>InternalHelpDesk</processName> </processQName> <id>pvm:0a12u</id> <customAttributes> <customAttribute> <name>Issue</name> <value>Forgot password</value> </customAttribute> </customAttributes> </processInstance> </processInstances> <pagingID>-94865740</pagingID> </queryProcessInstancesOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service queryProcessInstancesAlt (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

620

| Chapter 28

ProcessManagerService

queryProcessTemplateCount
Count the number of process templates that match certain criteria. The request must specify an SQL query that defines the search criteria. The response returns the number of process templates that match the specified criteria.

Required System Action queryProcessTemplate

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryProcessTemplateCount 621

SOAP Operation
Request Parameter notes Response Example Uses the queryString element (from the ProcessManagement schema) queryString: For information about valid query strings, see Sorting and Filtering Lists of Process Templates and Instances on page 151.

Returns a itemCount element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:queryString>DEFINITION.NAME='WelcomeUsers'</proc:queryString> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:itemCount xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">2</proc:itemCount> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service queryProcessTemplateCount (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

622

| Chapter 28

ProcessManagerService

queryProcessTemplates
Query information about process templates that match specified criteria. The request must specify an SQL query that defines the search criteria. The response returns information from process templates according to the specified criteria, either as a complete list or as the first page of a paged list (in which case a paging ID is also returned).

Also see queryProcessTemplatesAlt for an alternative method of querying process templates. Required System Action queryProcessTemplate

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryProcessTemplates 623

SOAP Operation
Request Parameter notes Uses the queryProcessTemplatesInput element (from the ProcessManagement schema) query: For information about valid SQL syntax, see Sorting and Filtering Lists of Process Templates and Instances on page 151. pageSize: If you specify a paged result (pageSize = -1 or a number greater than 0), use the queryFirstPage, queryLastPage, queryNextPage, and queryPreviousPage operations to navigate the paged list, and queryDone to clear resources when you are finished with the paged list. (Note that the result limit for non-paginated queries (pageSize=0) is 500.)

Response

Returns a queryProcessTemplatesOutput element (from the ProcessManagement schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

624

| Chapter 28
Example

ProcessManagerService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:queryProcessTemplatesInput> <proc:query>SELECT * FROM process WHERE DEFINITION.NAME='WelcomeUsers' ORDER BY DEFINITION.VERSION</proc:query> <proc:pageSize>0</proc:pageSize> </proc:queryProcessTemplatesInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryProcessTemplatesOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processTemplates> <processTemplate> <basicTemplate> <processQName> <moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</moduleName> <processName>WelcomeUsers</processName> <version>1.0.0.201106290731</version> </processQName> <description/> </basicTemplate> <priority>NORMAL</priority> <creationTime>2011-06-29T07:29:58.943-07:00</creationTime> </processTemplate> <processTemplate> <basicTemplate> <processQName> <moduleName>/WelcomeUsersDesignSolution/Process Packages/ProcessPackage.xpdl</moduleName> <processName>WelcomeUsers</processName> <version>1.0.0.201106290831</version> </processQName> <description/> </basicTemplate> <priority>NORMAL</priority> <creationTime>2011-06-29T08:30:30.543-07:00</creationTime> </processTemplate> </processTemplates> <pagingID>0</pagingID> </queryProcessTemplatesOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryProcessTemplates 625

Java Method
Method Service queryProcessTemplates (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

626

| Chapter 28

ProcessManagerService

queryProcessTemplatesAlt
List process templates that match certain criteria. (This is a variation of queryProcessTemplates in which the query string is divided into its constituent parts.) The request must specify an SQL query that defines the search criteria. The response returns the process templates that match the specified criteria, either as a complete list or as the first page of a paged list (in which case a paging ID is also returned).

Required System Action queryProcessTemplate

TIBCO ActiveMatrix BPM - BPM Developers Guide

queryProcessTemplatesAlt 627

SOAP Operation
Request Parameter notes Uses the queryProcessTemplatesAltInput element (from the ProcessManagement schema) select, where, orderBy: For information about valid SQL syntax, see Sorting and Filtering Lists of Process Templates and Instances on page 151. pageSize: If you specify a paged result (pageSize = -1 or a number greater than 0), use the queryFirstPage, queryLastPage, queryNextPage, and queryPreviousPage operations to navigate the paged list, and queryDone to clear resources when you are finished with the paged list. (Note that the result limit for non-paginated queries (pageSize=0) is 500.)

Response

Returns a queryProcessTemplatesOutput element (from the ProcessManagement schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

628

| Chapter 28
Example

ProcessManagerService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:queryProcessTemplatesAltInput> <proc:select>DEFINITION.CREATION_DATE</proc:select> <proc:where>DEFINITION.NAME='WelcomeUsers'</proc:where> <proc:orderBy></proc:orderBy> <proc:pageSize>0</proc:pageSize> </proc:queryProcessTemplatesAltInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <queryProcessTemplatesOutput xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <processTemplates> <processTemplate> <creationTime>2011-06-29T07:29:58.943-07:00</creationTime> </processTemplate> <processTemplate> <creationTime>2011-06-29T08:30:30.543-07:00</creationTime> </processTemplate> </processTemplates> <pagingID>0</pagingID> </queryProcessTemplatesOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service queryProcessTemplatesAlt (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

resumeProcessInstance 629

resumeProcessInstance
Resume a previously suspended process instance. See also: suspendProcessInstance and suspendProcessInstances. The request must specify the unique ID of the process instance that is to be resumed. The response indicates whether or not the process instance has been successfully resumed.

Required System Action resumeProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

630

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the processID element (from the ProcessManagement schema) processID: Can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt.

Returns a success element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:processID>pvm:0a12g</proc:processID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service resumeProcessInstance (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

resumeProcessInstances 631

resumeProcessInstances
Resume all process instances for one or more process templates. See also: suspendProcessInstance and suspendProcessInstances. The request must specify the process templates for which instances are to be resumed. The response returns a count of the number of process instances that have been resumed.

Required System Action resumeProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

632

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the qualifiedProcessName element (from the ProcessManagement schema) moduleName, processName, version: These parameters can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt.

Returns a itemCount element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName></proc:moduleName> <proc:processName>SalesCallbackProcess</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:itemCount xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">2</proc:itemCount> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service resumeProcessInstances (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

setDeadlineExpiration 633

setDeadlineExpiration
Change the deadline value for an activity. The request must specify the activity ID for which the deadline value is to be changed. The response indicates whether or not the specified deadline has been successfully set.

An active deadline must be in use (that is, it cannot be expired) on an activity (using an intermediate timer event) to be able to set the expiration time with this operation. Required System Action setDeadlineExpiration

TIBCO ActiveMatrix BPM - BPM Developers Guide

634

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Uses the setDeadlineExpirationInput element (from the ProcessManagement schema) activityID: Can be obtained from getActivityInstanceStatus. expirationTime: The current deadline date/time value for an activity can be obtained from getActivityInstanceStatus.

Response Example

Returns a success element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:setDeadlineExpirationInput> <proc:activityID>pvm:001ic0</proc:activityID> <proc:expirationTime>2011-07-14T16:30:00.000-07:00</proc:expirationTim e> </proc:setDeadlineExpirationInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service setDeadlineExpiration (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

setPriority 635

setPriority
Change the scheduling priority for execution of a process instance. The request must specify the process instance for which the priority is to be set, as well as the new priority level. The response indicates whether or not the specified deadline has been successfully set.

Required System Action setPriority

TIBCO ActiveMatrix BPM - BPM Developers Guide

636

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the setPriorityInput element (from the ProcessManagement schema) processID: Can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt.

Returns a success element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:setPriorityInput> <proc:processID>pvm:0a12i</proc:processID> <proc:priority>400</proc:priority> </proc:setPriorityInput> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service setPriority (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

suspendProcessInstance 637

suspendProcessInstance
Suspend a process instance from being scheduled for execution. See also: resumeProcessInstance and resumeProcessInstances. The request must specify the unique ID of the process instance that is to be suspended. The response indicates whether or not the specified deadline has been successfully set.

Required System Action suspendProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

638

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the processID element (from the ProcessManagement schema) processID: Can be obtained from listProcessInstances, queryProcessInstances, and queryProcessInstancesAlt.

Returns a success element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:processID>pvm:0a12g</proc:processID> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service suspendProcessInstance (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

suspendProcessInstances 639

suspendProcessInstances
Suspend all process instances for one or more process templates from being scheduled for execution. See also: resumeProcessInstance and resumeProcessInstances. The request must specify the process templates for which instances are to be suspended. The response returns a count of the number of process instances that have been suspended.

Required System Action suspendProcessInstance

TIBCO ActiveMatrix BPM - BPM Developers Guide

640

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the qualifiedProcessName element (from the ProcessManagement schema) moduleName, processName, version: These parameters can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt.

Returns a itemCount element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName></proc:moduleName> <proc:processName>SalesCallbackProcess</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:itemCount xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">2</proc:itemCount> </SOAP-ENV:Body> </SOAP-ENV:Envelope

Java Method
Method Service suspendProcessInstances (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getMigrationPoints 641

getMigrationPoints
List the permissible process instance migration points for one or more process templates. (Migration points are the points in the process from which a process instance can be migrated to a different version.) For information about process migration, see Migrating a Process Instance to a Different Version on page 161. The request must specify the process templates for which process instance migration points are to be listed. The response returns the valid process instance migration points for the specified process templates.

Required System Action handleProcessMigration

TIBCO ActiveMatrix BPM - BPM Developers Guide

642

| Chapter 28

ProcessManagerService

SOAP Operation
Request Parameter notes Response Example Uses the qualifiedProcessName element (from the ProcessManagement schema) moduleName, processName, version: These parameters can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt.

Returns a migrationPoints element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName>/HelpDesk/Process Packages/HelpDesk.xpdl</proc:moduleName> <proc:processName>InternalHelpDesk</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <migrationPoints xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <module name="/HelpDesk/Process Packages/HelpDesk.xpdl" version="1.0.0.201105061158"> <process name="InternalHelpDesk"> <task name="EnterIssue"/> <task name="Complete"/> <task name="EnterResolution"/> <task name="EndEvent"/> </process> </module> </migrationPoints> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method getMigrationPoints (args)

TIBCO ActiveMatrix BPM - BPM Developers Guide

getMigrationPoints 643

Service

ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

644

| Chapter 28

ProcessManagerService

setMigrationRules
Set one or more process instance migration rules. (Each migration rule consists of a unique set of module name, module version from which to migrate, process template name, task name from which to migrate, and module version to which to migrate.) For information about process migration, see Migrating a Process Instance to a Different Version on page 161. The request must specify the process instance migration rules that are to be set. The response returns whether the specified process instance migration rules have been successfully set.

Required System Action handleProcessMigration

TIBCO ActiveMatrix BPM - BPM Developers Guide

setMigrationRules 645

SOAP Operation
Request Parameter notes Uses the migrationRules element (from the ProcessManagement schema) The module, process template, and version information can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt. The task being used as the migration point can be obtained from getMigrationPoints. Response Example Returns a success element (from the ProcessManagement schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:migrationRules> <!--Zero or more repetitions:--> <proc:module name="/HelpDesk/Process Packages/HelpDesk.xpdl" version="1.0.0.201105061158"> <!--Zero or more repetitions:--> <proc:process name="InternalHelpDesk"> <!--Zero or more repetitions:--> <proc:migrate fromTask="EnterIssue" toVersion="1.0.0.201107140929" description="Added history check"/> </proc:process> </proc:module> </proc:migrationRules> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service setMigrationRules (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

646

| Chapter 28

ProcessManagerService

unsetMigrationRules
Unset one or more currently set process instance migration rules. For information about process migration, see Migrating a Process Instance to a Different Version on page 161. The request must specify the process instance migration rules that are to be unset. The response returns whether the specified process instance migration rules have been successfully unset.

Required System Action handleProcessMigration

TIBCO ActiveMatrix BPM - BPM Developers Guide

unsetMigrationRules 647

SOAP Operation
Request Parameter notes Response Example Uses the migrationRules element (from the ProcessManagement schema) The process instances that have migration rules set can be obtained using the listMigrationRules operation. Returns a success element (from the ProcessManagement schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:migrationRules> <!--Zero or more repetitions:--> <proc:module name="/HelpDesk/Process Packages/HelpDesk.xpdl" version="1.0.0.201105061158"> <!--Zero or more repetitions:--> <proc:process name="InternalHelpDesk"> <!--Zero or more repetitions:--> <proc:migrate fromTask="EnterIssue" toVersion="1.0.0.201107140929" description="Added history check"/> </proc:process> </proc:module> </proc:migrationRules> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service unsetMigrationRules (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

648

| Chapter 28

ProcessManagerService

clearMigrationRules
Clear all currently set process instance migration rules for one or more process templates. For information about process migration, see Migrating a Process Instance to a Different Version on page 161. The request must specify the process templates for which process instance migration rules are to be cleared. The response returns whether all process instance migration rules have been successfully unset for the specified process templates.

Required System Action handleProcessMigration

TIBCO ActiveMatrix BPM - BPM Developers Guide

clearMigrationRules 649

SOAP Operation
Request Parameter notes Response Example Uses the qualifiedProcessName element (from the ProcessManagement schema) The process instances that have migration rules set can be obtained using the listMigrationRules operation. Returns a success element (from the ProcessManagement schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName>/HelpDesk/Process Packages/HelpDesk.xpdl</proc:moduleName> <proc:processName>InternalHelpDesk</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:success xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">OK</proc:success> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service clearMigrationRules (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

650

| Chapter 28

ProcessManagerService

isSetMigrationRule
Test whether any process instance migration rules are set for a particular qualified task name. For information about process migration, see Migrating a Process Instance to a Different Version on page 161. The request must specify the qualified task name that is to be tested. (The qualified task name includes the task name and its parent process template, module and template/module version). The response returns whether any process instance migration rules are currently set for the specified qualified task name.

Required System Action handleProcessMigration

TIBCO ActiveMatrix BPM - BPM Developers Guide

isSetMigrationRule 651

SOAP Operation
Request Parameter notes Response Example Uses the qualifiedTaskName element (from the ProcessManagement schema) The module, process template, and version information can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt. Returns a isSet element (from the ProcessManagement schema) Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedTaskName> <proc:moduleName>/HelpDesk/Process Packages/HelpDesk.xpdl</proc:moduleName> <proc:processName>InternalHelpDesk</proc:processName> <proc:version>1.0.0.201105061158</proc:version> <proc:taskName>EnterIssue</proc:taskName> </proc:qualifiedTaskName> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <proc:isSet xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType ">true</proc:isSet> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Java Method
Method Service isSetMigrationRule (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

652

| Chapter 28

ProcessManagerService

listMigrationRules
List the process instance migration rules that are set for one or more process templates. For information about process migration, see Migrating a Process Instance to a Different Version on page 161. The request must specify the process templates for which process instance migration rules are to be listed. The response returns the process instance migration rules that are set for the specified process templates.

Required System Action handleProcessMigration

TIBCO ActiveMatrix BPM - BPM Developers Guide

listMigrationRules 653

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the qualifiedProcessName element (from the ProcessManagement schema) moduleName, processName, and version: Can be obtained from listProcessTemplates, queryProcessTemplates, and queryProcessTemplatesAlt.

Returns a migrationRuleList element (from the ProcessManagement schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.tibco.com/bx/2009/management/processManagerType "> <soapenv:Header/> <soapenv:Body> <proc:qualifiedProcessName> <proc:moduleName>/HelpDesk/Process Packages/HelpDesk.xpdl</proc:moduleName> <proc:processName>InternalHelpDesk</proc:processName> <proc:version>1.0.0.201105061158</proc:version> </proc:qualifiedProcessName> </soapenv:Body> </soapenv:Envelope>

Response:
The response when migration rules are not set: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <migrationRuleList xmlns="http://www.tibco.com/bx/2009/management/processManagerType"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope> The response when migration rules are set: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <migrationRuleList xmlns="http://www.tibco.com/bx/2009/management/processManagerType"> <module name="/HelpDesk/Process Packages/HelpDesk.xpdl" version="1.0.0.201105061158"> <process name="InternalHelpDesk"> <migrate creationTime="2011-07-14T09:38:50.773-07:00" description="Added history check" fromTask="EnterIssue" toVersion="1.0.0.201107140929"/> </process> </module> </migrationRuleList> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

654

| Chapter 28

ProcessManagerService

Service Connector API (Java Method)

Method Service listMigrationRules (args) ProcessManagerService

TIBCO ActiveMatrix BPM - BPM Developers Guide

ResourceQueryService 655

Chapter 29

ResourceQueryService

ResourceQueryService is one of the Directory Services provided by Work Manager. Use ResourceQueryService requests to execute a Resource Query Language (RQL) query to find a set of resources that match specific criteria.

Topics
executeQuery, page 656

TIBCO ActiveMatrix BPM - BPM Developers Guide

656

| Chapter 29

ResourceQueryService

executeQuery
Execute a Resource Query Language (RQL) query to find a set of resources that match specific criteria: The request must specify the query to be executed. The response returns the unique IDs of resources matching the supplied criteria.

TIBCO ActiveMatrix BPM - BPM Developers Guide

executeQuery 657

Web Service API (SOAP Operation)

Request Parameter notes Uses the executeQuery element (from the ResourceQueryService schema) model-version: Used to restrict the organization model entities (organization units, positions, groups, etc.) that are considered in the evaluation of the query. Can be obtained from listModelVersions. singleRandomResult: Pass "true" to get one resource, chosen at random from the query result. Defaults to "false". query: Must conform to Resource Query Language (RQL) syntax rules. See Appendix D - Resource Query Language of the TIBCO Business Studio BPM Implementation guide.

Response Example

Returns an executeQueryResponse element (from the ResourceQueryService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:res="http://resourcequery.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <res:executeQuery model-version="-1" singleRandomResult="false"> <query>organization(name="EasyAs")</query> </res:executeQuery> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <executeQueryResponse xmlns="http://resourcequery.api.de.n2.tibco.com"> <resource guid="846D100C-77C8-42DE-BD01-C23D214D2BB4" name="Liam Lawrence" push-enabled="false" xmlns=""/> <resource guid="3D9296E1-B1F8-4A09-A219-0285D43B3498" name="Tony Pulis" push-enabled="false" xmlns=""/> <resource guid="931F96FA-EC57-43B5-AA61-613784B1BD10" name="Leon Court" push-enabled="false" xmlns=""/> <resource guid="9DDA518C-3323-4656-B730-9C186E4ADC01" name="John Eustace" push-enabled="false" xmlns=""/> <resource guid="6C7C4DED-A214-4D00-839A-0DAA33FF64A4" name="Steve Simonsen" push-enabled="false" xmlns=""/> </executeQueryResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

658

| Chapter 29

ResourceQueryService

Service Connector API (Java Method)

Method Service executeQuery (args) ResourceQueryService

TIBCO ActiveMatrix BPM - BPM Developers Guide

SecurityService 659

Chapter 30

SecurityService

SecurityService is one of the Directory Services provided by Work Manager. Use SecurityService requests to manage user authorization.

Topics
authenticateUser, page 660 getUserPrivileges, page 661 isActionAuthorised, page 664 listActionAuthorisedEntities, page 667 listAuthorisedOrgs, page 669

TIBCO ActiveMatrix BPM - BPM Developers Guide

660

| Chapter 30

SecurityService

authenticateUser
This operation has been deprecated and should no longer be used. It is only available for backward compatibility, and may be removed in a future release.

TIBCO ActiveMatrix BPM - BPM Developers Guide

getUserPrivileges 661

getUserPrivileges
List the privileges currently assigned to a specific user: The request must specify the unique ID of the user whose privileges should be listed. The response returns the privileges currently assigned to the specified user.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

662

| Chapter 30

SecurityService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getUserPrivileges element (from the SecurityService schema) user-guid: Can be obtained from lookupUser, listMappedEntities, listContainerResources, or listAssociatedResources.

Returns a getUserPrivilegesResponse element (from the SecurityService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="http://security.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <sec:getUserPrivileges user-guid="7AAB6AE7-CA2E-4211-BBF8-E081659526FE"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getUserPrivilegesResponse user-guid="7AAB6AE7-CA2E-4211-BBF8-E081659526FE" xmlns="http://security.api.de.n2.tibco.com"> <Privilege entity-type="PRIVILEGE" guid="_AzyDoF-JEd-rno5lLiXABg" name="SuperviseSalesReps" xmlns=""/> <Privilege entity-type="PRIVILEGE" guid="_J8v90F-KEd-rno5lLiXABg" name="SuperviseReception" xmlns=""/> <Privilege entity-type="PRIVILEGE" guid="_-QxUUF-IEd-rno5lLiXABg" name="SuperviseITReps" xmlns=""/> <Privilege entity-type="PRIVILEGE" guid="_80Y14F-IEd-rno5lLiXABg" name="SuperviseITManagers" xmlns=""/> <Privilege entity-type="PRIVILEGE" guid="_HIl0IF-KEd-rno5lLiXABg" name="SuperviseVPs" xmlns=""/> <Privilege entity-type="PRIVILEGE" guid="_I8YiEMpSEd64gM7QE8RwxA" name="BaseUser" xmlns=""/> <Privilege entity-type="PRIVILEGE" guid="_CTAasF-JEd-rno5lLiXABg" name="SuperviseSalesManagers" xmlns=""/> <Privilege entity-type="PRIVILEGE" guid="_M1FR8MpSEd64gM7QE8RwxA" name="SuperviseCSManagers" xmlns=""/> <Privilege entity-type="PRIVILEGE" guid="_PQMpgMpSEd64gM7QE8RwxA" name="SuperviseCSReps" xmlns=""/> </getUserPrivilegesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getUserPrivileges 663

Service Connector API (Java Method)

Method Service getUserPrivileges (args) SecurityService

TIBCO ActiveMatrix BPM - BPM Developers Guide

664

| Chapter 30

SecurityService

isActionAuthorised
Test whether the caller (as identified by the SOAP security header) is authorized to perform one or more system actions, either globally or within the scope of a particular organization model entity: The request must specify the system actions to be tested for authorization and, optionally, an organization model entity that defines the scope of the test. The response returns a list of the requested system actions, defining for each its scope and whether the user is authorized to perform the system action.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

isActionAuthorised 665

Web Service API (SOAP Operation)

Request Parameter notes Uses the isActionAuthorised element (from the SecurityService schema) Response scope: If scope is not specified, authorization is tested against the organization model, rather than a scoped entity. scope.entity-type: For information about organizational entity scope, see Scope of System Actions on page 773. scope.guid: Can be obtained from listOrgModelOverview or listMappedEntities. action: For a list of the available components and system actions, see System Actions on page 768.

Returns a isActionAuthorisedResponse element (from the SecurityService schema). Note that if multiple system actions are passed in the request, a results of: true means that the caller is authorized to perform all of the specified actions. false means that the caller is authorized to perform some, or none, of the specified actions.

TIBCO ActiveMatrix BPM - BPM Developers Guide

666

| Chapter 30
Example

SecurityService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="http://security.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <sec:isActionAuthorised fault-on-unauthorised="false"> <scope model-version="-1" entity-type="POSITION" guid="_9y7hYMpREd64gM7QE8RwxA" /> --> <action component="BRM" name="viewWorkList"/> </sec:isActionAuthorised> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <isActionAuthorisedResponse overall="true" xmlns="http://security.api.de.n2.tibco.com"> <scope entity-type="POSITION" guid="_9y7hYMpREd64gM7QE8RwxA" model-version="-1" xmlns="" xmlns:sec="http://security.api.de.n2.tibco.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"/> <action authorised="true" component="BRM" name="viewWorkList" xmlns=""/> </isActionAuthorisedResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service isActionAuthorised (args) SecurityService

TIBCO ActiveMatrix BPM - BPM Developers Guide

listActionAuthorisedEntities 667

listActionAuthorisedEntities
List the organization model entities on which the caller (as determined by the SOAP security header) is authorized to perform a specific system action. The request must specify the system action for which the caller's authorizations should be listed. The response returns a list of the guids of organization model entities on which the user is authorized to perform the request.

Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

668

| Chapter 30

SecurityService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the listActionAuthorisedEntitiesRequest element (from the SecurityService schema) component / name: For a list of the available components and system actions, see System Actions on page 768.

Returns a listActionAuthorisedEntitiesResponse element (from the SecurityService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="http://security.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <sec:listActionAuthorisedEntities component="BRM" name="pendWorkItem"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listActionAuthorisedEntitiesResponse xmlns="http://security.api.de.n2.tibco.com"> <guid xmlns="">_aT_UMifLEeChutsy_vK9tg</guid> <guid xmlns="">_fE8zxSfJEeChutsy_vK9tg</guid> <guid xmlns="">_i1LeoCrrEeCEDr7D0P9b2w</guid> <guid xmlns="">_QIgJwHT9EeC85dHJry9Pug</guid> <guid xmlns="">_CWsngMpSEd64gM7QE8RwxA</guid> <guid xmlns="">_HF-LkHT4EeC85dHJry9Pug</guid> <guid xmlns="">_lcnV0CfIEeChutsy_vK9tg</guid> <guid xmlns="">_P0fAkDBTEd-x4cVy01Xlww</guid> . . . </listActionAuthorisedEntitiesResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service listActionAuthorisedEntities (args) SecurityService

TIBCO ActiveMatrix BPM - BPM Developers Guide

listAuthorisedOrgs 669

listAuthorisedOrgs
List the organizations on which the caller (as determined by the SOAP security header) is authorized to perform a specific system action: The request must specify the system action for which the caller's authorizations should be listed. The response returns the unique IDs of organizations on which the user is authorized to perform the requested system action.

Note that in addition to testing the named system action, this operation limits the organizations to those to which the calling user has access (because of organization relationships). For more information, see Organization Relationships on page 123. Required System Action None

TIBCO ActiveMatrix BPM - BPM Developers Guide

670

| Chapter 30

SecurityService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the listAuthorisedOrgs element (from the SecurityService schema) component / name: For a list of the available components and system actions, see System Actions on page 768.

Returns a listAuthorisedOrgsResponse element (from the SecurityService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="http://security.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <sec:listAuthorisedOrgs component="BRM" name="pendWorkItem"/> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listAuthorisedOrgsResponse all-organizations="true" xmlns="http://security.api.de.n2.tibco.com"> <guid xmlns="">_5fLygDBSEd-x4cVy01Xlww</guid> <guid xmlns="">_iPYXscpPEd64gM7QE8RwxA</guid> <guid xmlns="">_tf5fgSe3EeCoD7MklYZAuw</guid> <guid xmlns="">_jGi_kcxxEd-nOYM9N6WPrw</guid> <guid xmlns="">_-SS8MDBSEd-x4cVy01Xlww</guid> </listAuthorisedOrgsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service listAuthorisedOrgs (args) SecurityService

TIBCO ActiveMatrix BPM - BPM Developers Guide

UserSettingsService 671

Chapter 31

UserSettingsService

UserSettingsService is one of the Directory Services provided by Work Manager. Use UserSettingsService requests to manage user settings.

Topics
saveUserSettings, page 672 getUserSettings, page 675 deleteUserSettings, page 677 listUserSettingIds, page 679

TIBCO ActiveMatrix BPM - BPM Developers Guide

672

| Chapter 31

UserSettingsService

saveUserSettings
Save one or more user settings (name/value pairs) for a specific storageKey and settingID: The request must specify the user settings (name/value pairs) to be stored and the associated storageKey and settingID. The response returns an empty document if the user settings were successfully stored.

User settings allow the BPM application to store any name/value pairs on the server for later retrieval (using the getUserSettings operation). Required System Action userAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

saveUserSettings 673

Web Service API (SOAP Operation)

Request Parameter notes Uses the saveUserSettingsRequest element (from the UserSettingsService schema) storageKey: Any arbitrary value. Can also be a resource identifier if storage is resource-specific. But it can be any value identifying the data the application needs to persist on the server. settingId: Any arbitrary value (with one exceptionsee below). Identifies the specific setting stored that relates to the value passed in storageKey. For each storageKey, there can be many settingIds. Note that the TIBCO Workspace application reserves settingIds that begin with "workspace". settingProperties.Name: Identifies the value stored. settingProperties.Value: The value being stored on the server for later retrieval.

Response Example

Returns a saveUserSettingsRsponse element (from the UserSettingsService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:user="http://usersettingsservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <user:saveUserSettingsRequest> <settings storageKey="configStore" settingId="viewSettings"> <settingProperties Name="listSize" Value="20" xmlns=""/> <settingProperties Name="caption" Value="Description" xmlns=""/> <settingProperties Name="winSize" Value="600,400" xmlns=""/> <settingProperties Name="layout" Value="tabbed" xmlns=""/> </settings> </user:saveUserSettingsRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <saveUserSettingsResponse xmlns="http://usersettingsservice.api.de.n2.tibco.com"> <empty xmlns="">0</empty> </saveUserSettingsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

674

| Chapter 31

UserSettingsService

Service Connector API (Java Method)

Method Service saveUserSettings (args) UserSettingsService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getUserSettings 675

getUserSettings
List the user settings (name/value pairs) currently defined for a specific storageKey and settingID: The request must specify the storageKey and settingID for which user settings should be listed. The response returns the user settings (name/value pairs) currently defined for the specified specific storageKey and settingID.

Required System Action userAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

676

| Chapter 31

UserSettingsService

Web Service API (SOAP Operation)

Request Parameter notes Uses the getUserSettingsRequest element (from the UserSettingsService schema) Response Example storageKey: Identifies the key used to persist data on the server. Must be created using the storageKey attribute in the saveUserSettings operation. settingId: Identifies the specific setting for the value in storageKey. Must be created using the settingId attribute in the saveUserSettings operation.

Returns a getUserSettingsRsponse element (from the UserSettingsService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:user="http://usersettingsservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <user:getUserSettingsRequest> <storageKey>configStore</storageKey> <settingId>viewSettings</settingId> </user:getUserSettingsRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getUserSettingsResponse xmlns="http://usersettingsservice.api.de.n2.tibco.com"> <settingProperties Name="listSize" Value="20" xmlns=""/> <settingProperties Name="caption" Value="Description" xmlns=""/> <settingProperties Name="winSize" Value="600,400" xmlns=""/> <settingProperties Name="layout" Value="tabbed" xmlns=""/> </getUserSettingsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service getUserSettings (args) UserSettingsService

TIBCO ActiveMatrix BPM - BPM Developers Guide

deleteUserSettings 677

deleteUserSettings
Delete all user settings (name/value pairs) currently defined for a specific storageKey: The request must specify the storageKey for which user settings should be deleted. The response returns an empty document if the user settings were successfully deleted.

Required System Action userAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

678

| Chapter 31

UserSettingsService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the deleteUserSettingsRequest element (from the UserSettingsService schema) storageKey: Identifies the key used to persist data on the server. Must be created using the storageKey attribute in the saveUserSettings operation.

Returns a deleteUserSettingsRsponse element (from the UserSettingsService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:user="http://usersettingsservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <user:deleteUserSettingsRequest> <storageKey>configStore</storageKey> </user:deleteUserSettingsRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <deleteUserSettingsResponse xmlns="http://usersettingsservice.api.de.n2.tibco.com"> <empty xmlns="">0</empty> </deleteUserSettingsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service deleteUserSettings (args) UserSettingsService

TIBCO ActiveMatrix BPM - BPM Developers Guide

listUserSettingIds 679

listUserSettingIds
List all user settingIDs currently defined for a specific storageKey: The request must specify the storageKey for which user settingIDs should be listed. The response returns the user settingIDs currently defined for the specified storageKey.

Required System Action userAdmin

TIBCO ActiveMatrix BPM - BPM Developers Guide

680

| Chapter 31

UserSettingsService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the listUserSettingsIdsRequest element (from the UserSettingsService schema) storageKey: Identifies the key used to persist data on the server. Must be created using the storageKey attribute in the saveUserSettings operation.

Returns a listUserSettingsIdsResponse element (from the UserSettingsService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:user="http://usersettingsservice.api.de.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <user:listUserSettingIdsRequest> <storageKey>configStore</storageKey> </user:listUserSettingIdsRequest> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <listUserSettingIdsResponse xmlns="http://usersettingsservice.api.de.n2.tibco.com"> <settingId xmlns="">viewSettings</settingId> <settingId xmlns="">workFlow</settingId> </listUserSettingIdsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service listUserSettingIds (args) UserSettingsService

TIBCO ActiveMatrix BPM - BPM Developers Guide

WorkItemManagementService 681

Chapter 32

WorkItemManagementService

WorkItemManagementService is one of the Business Resource Management Services provided by Work Manager. Use WorkItemManagementService requests to perform actions on work items.

Topics
getWorkItemHeader, page 682 openWorkItem, page 685 closeWorkItem, page 688 allocateWorkItem, page 692 allocateAndOpenWorkItem, page 695 allocateAndOpenNextWorkItem, page 699 unallocateWorkItem, page 703 completeWorkItem, page 706 skipWorkItem, page 710 reallocateWorkItem, page 712 reallocateWorkItemData, page 715 getOfferSet, page 719 saveOpenWorkItem, page 721 pendWorkItem, page 725

TIBCO ActiveMatrix BPM - BPM Developers Guide

682

| Chapter 32

WorkItemManagementService

getWorkItemHeader
Get the header information for a specific work item: Identifies the work item for which header information is required. The response returns the work item header information.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

getWorkItemHeader 683

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getWorkItemheader element (from the WorkItemManagementService schema) workItemID: ID of the work item for which information is required. version: (Optional) If it is omitted, the latest version is used.

Returns a getWorkItemHeaderResponse element (from the WorkItemManagementService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getWorkItemHeader> <workItemID id="10" version="0"/> </api:getWorkItemHeader> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getWorkItemHeaderResponse xmlns="http://api.brm.n2.tibco.com"> <workItemHeader distributionStrategy="OFFER" priority="50" xmlns=""> <name>ServicingMgr</name> <description>ServicingMgr</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i1m</activityID> <activityName>ServicingMgr</activityName> <appInstance>pvm:0a124</appInstance> <appName>AMXSupervisor</appName> <appID>_fQ0ZAHClEeCF3qXLa8gNUw</appID> <appInstanceDescription>SrvCall</appInstanceDescription> </itemContext> </workItemHeader> </getWorkItemHeaderResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

684

| Chapter 32

WorkItemManagementService

Service Connector API (Java Method)

Method Service getWorkItemHeader (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

openWorkItem 685

openWorkItem
Open a work item (to get the associated input and output data). Note that there is an openWorkItem operation in two services: WorkItemManagementService (the one described here) - Use this one if the user task was designed to not open a form nor start a pageflow. This would typically be used only in special use-case client applications. WorkPresentationService - Use this one if the user task was designed to either open a form or start a pageflow, which is typical for most client applications (see openWorkItem). The request must specify the work item that should be opened. The response returns the work item body of the opened work item. This operation can only be used if the work item is in a state from which it can be opened. See Work Item State Transitions, page 195. This operation can only be used if the work item is assigned to the user with whose credentials the operation is being invoked.

Required System Action Requires openOtherResourcesItems in order to open a work item currently allocated to another userfor example, when a manager is opening an item in a supervised work list (see Creating and Managing Supervised Work List Views on page 180 for information on supervised work lists). Otherwise, none.

TIBCO ActiveMatrix BPM - BPM Developers Guide

686

| Chapter 32

WorkItemManagementService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the openWorkItem element (from the WorkItemManagementService schema) workItemID: ID of the work item for which information to be opened. version: (Optional). If it is omitted, the latest version is used.

Returns an openWorkItemResponse element (from the WorkItemManagementService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:openWorkItem> <workItemID id="24" version="0"/> </api:openWorkItem> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

openWorkItem 687

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <openWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItemBody xmlns=""> <dataModel> <inouts array="false" name="Lname" type="String"> <simpleSpec> <value>Fur</value> </simpleSpec> </inouts> <inouts array="false" name="Address1st" type="String"> <simpleSpec> <value>666 Hades Gate</value> </simpleSpec> </inouts> <inouts array="false" name="Gender" type="String"> <simpleSpec> <value>F</value> </simpleSpec> </inouts> <inouts array="false" name="PostCode" type="String"> <simpleSpec> <value>HA6 666</value> </simpleSpec> </inouts> <inouts array="false" name="Fname" type="String"> <simpleSpec> <value>Lucy</value> </simpleSpec> </inouts> </dataModel> </workItemBody> </openWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service openWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

688

| Chapter 32

WorkItemManagementService

closeWorkItem
Close a work item (and update the associated input and output data). Note that there is a closeWorkItem operation in two services: WorkItemManagementService (the one described here) - Use this one if the user task did not open a form when the work item was opened. This would be used only in special use-case client applications. Note that one special use-case for using the closeWorkItem operation in WorkItemManagementService is to set the work item state to PendHidden so that it does not appear in the work list for a specified period of time. For more information, see Accessing Hidden Work Items on page 218. WorkPresentationService - Use this one to close a form that was opened when the work item was opened with the openWorkItem operation. This is typically called in response to a user clicking the Close button on a work item form. The request must specify the work item that should be closed. The response returns the ID of the closed work item. This operation puts the work item into a PendHidden state if a hidden period is specified, or into a Pended state if not. This operation can only be used if the work item is in a state from which it can be closed. See Work Item State Transitions, page 195. This operation can only be used if the work item is assigned to the user with whose credentials the operation is being invoked.

Required System Action Requires closeOtherResourcesItems in order to close a work item currently allocated to another userfor example, when a manager is closing an item in a supervised work list (see Creating and Managing Supervised Work List Views on page 180 for information on supervised work lists). Otherwise, none.

TIBCO ActiveMatrix BPM - BPM Developers Guide

closeWorkItem 689

Web Service API (SOAP Operation)

Request Parameter notes Uses the closeWorkItem element (from the WorkItemManagementService schema) workItemID: ID of the work item to be closed. version: (Optional). If it is omitted, the latest version is used. workItemPayload: the complete body of the work item: data to be written to the work item as part of the Close action. If complexSpec business data is passed into this operation, see Valid Format for ComplexSpec Business Data on page 216 for information about the valid format. hiddenPeriod: information about how long the work item is to be hidden. Either a duration for which it is to be hidden, or the date and time when it is to become visible. A hiddenPeriod of 0 cancels any current hiddenPeriod. See Accessing Hidden Work Items on page 218 for more details.

Response

Returns a closeWorkItemResponse element (from the WorkItemManagementService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

690

| Chapter 32
Example

WorkItemManagementService

Request:
<soapenv:Header/> <soapenv:Body> <api:closeWorkItem> <workItemID id="23"/> <workItemPayload> <dataModel> <!--Zero or more repetitions:--> <inputs name="?" type="?" optional="?" array="?"> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <simpleSpec length="?" decimal="?"> <!--Zero or more repetitions:--> <value>?</value> </simpleSpec> <!--Optional:--> <complexSpec className="?"> <!--Zero or more repetitions:--> <value>?</value> </complexSpec> </inputs> <!--Zero or more repetitions:--> <outputs name="?" type="?" optional="?" array="?"> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <simpleSpec length="?" decimal="?"> <!--Zero or more repetitions:--> <value>?</value> </simpleSpec> <!--Optional:--> <complexSpec className="?"> <!--Zero or more repetitions:--> <value>?</value> </complexSpec> </outputs> <!--Zero or more repetitions:--> <inouts name="?" type="?" optional="?" array="?"> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <simpleSpec length="?" decimal="?"> <!--Zero or more repetitions:--> <value>?</value> </simpleSpec> <!--Optional:--> <complexSpec className="?"> <!--Zero or more repetitions:--> <value>?</value> </complexSpec> </inouts> </dataModel> </workItemPayload> <hiddenPeriod>

TIBCO ActiveMatrix BPM - BPM Developers Guide

closeWorkItem 691

<!--You have a CHOICE of the next 2 items at this level--> <hiddenDuration years="0" months="0" weeks="0" days="2" hours="0" minutes="0"/> </hiddenPeriod> </api:closeWorkItem> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <closeWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItemID id="23" version="4" xmlns=""/> </closeWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service closeWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

692

| Chapter 32

WorkItemManagementService

allocateWorkItem
Allocate a work item to a single resource: The request must specify the work item that should be allocated and the resource to whom it is to be allocated. The response returns details of the allocated work item. This operation can only be used if the work item is in a state from which it can be allocated. See Work Item State Transitions, page 195.

Required System Action workItemAllocation

TIBCO ActiveMatrix BPM - BPM Developers Guide

allocateWorkItem 693

Web Service API (SOAP Operation)

Request Parameter notes Uses the allocateWorkItem element (from the WorkItemManagementService schema) Response workItemID: ID of the work item to be allocated. version: (Optional) If it is omitted, the latest version is used. resource: the GUID of the resource to whom the work item is to be allocated. A resources GUID can be obtained from a previous lookupUser operation.

Returns an allocateWorkItemResponse element (from the WorkItemManagementService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

694

| Chapter 32
Example

WorkItemManagementService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:allocateWorkItem> <workItemID id="22"/> <resource>ED72300B-F2FA-4E60-90D4-F829FB8DEA9D</resource> </api:allocateWorkItem> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <allocateWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItem xmlns=""> <id id="22" version="1"/> <header distributionStrategy="OFFER" priority="50"> <name>ServicingMgr</name> <description>ServicingMgr</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i3a</activityID> <activityName>ServicingMgr</activityName> <appInstance>pvm:0a128</appInstance> <appName>AMXSupervisor</appName> <appID>_fQ0ZAHClEeCF3qXLa8gNUw</appID> <appInstanceDescription>Oho</appInstanceDescription> </itemContext> </header> <state>ALLOCATED</state> <visible>true</visible> </workItem> </allocateWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service allocateWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

allocateAndOpenWorkItem 695

allocateAndOpenWorkItem
Allocate a work item to a single resource and immediately open the work item (to get the associated input and output data): The request must specify the work item that should be allocated and the name of the resource to whom it is to be allocated. The response returns full details of the allocated work item. This operation can only be used if the work item is in a state from which it can be allocated and opened. See Work Item State Transitions, page 195.

Required System Action workItemAllocation

TIBCO ActiveMatrix BPM - BPM Developers Guide

696

| Chapter 32

WorkItemManagementService

Web Service API (SOAP Operation)

Request Parameter notes Uses the allocateAndOpenWorkItem element (from the WorkItemManagementService schema) Response workItemID: ID of the work item to be allocated. version: (Optional) If it is omitted, the latest version is used. resource: the GUID of the resource to whom the work item is to be allocated. A resources GUID can be obtained from a previous lookupUser operation.

Returns an allocateAndOpenWorkItemResponse element (from the WorkItemManagementService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

allocateAndOpenWorkItem 697

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:allocateAndOpenWorkItem> <workItemID id="22" version="2"/> <resource>ED72300B-F2FA-4E60-90D4-F829FB8DEA9D</resource> </api:allocateAndOpenWorkItem> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <allocateAndOpenWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItem xmlns=""> <id id="22" version="3"/> <header distributionStrategy="OFFER" priority="50"> <name>ServicingMgr</name> <description>ServicingMgr</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i3a</activityID> <activityName>ServicingMgr</activityName> <appInstance>pvm:0a128</appInstance> <appName>AMXSupervisor</appName> <appID>_fQ0ZAHClEeCF3qXLa8gNUw</appID> <appInstanceDescription>Oho</appInstanceDescription> </itemContext> </header> <body> <dataModel> <inputs array="false" name="param2" type="String"> <simpleSpec> <value>identity3</value> </simpleSpec> </dataModel> </body> <workType version="1.0.0.201106141602" workTypeDescription="ServicingMgr" workTypeID="WT__QnN14HCmEeCF3qXLa8gNUw"/> <state>OPENED</state> <visible>true</visible> </workItem> </allocateAndOpenWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

698

| Chapter 32

WorkItemManagementService

Service Connector API (Java Method)

Method Service allocateAndOpenWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

allocateAndOpenNextWorkItem 699

allocateAndOpenNextWorkItem
Allocate the next available work item for a specified resource to that resource and immediately open the work item (to get the associated input and output data): The operation fails if there is no next item in the resources work list. The request must specify the required resource. The response returns full details of the allocated work item. This operation can only be used if the work item is in a state from which it can be allocated and opened. See Work Item State Transitions, page 195.

Required System Action workItemAllocation

TIBCO ActiveMatrix BPM - BPM Developers Guide

700

| Chapter 32

WorkItemManagementService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the allocateAndOpenNextWorkItem element (from the WorkItemManagementService schema) resource: the GUID of the resource to whom the work item is to be allocated. A resources GUID can be obtained from a previous lookupUser operation.

Returns an allocateAndOpenNextWorkItemResponse element (from the WorkItemManagementService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:allocateAndOpenNextWorkItem> <resource>ED72300B-F2FA-4E60-90D4-F829FB8DEA9D</resource> </api:allocateAndOpenNextWorkItem> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

allocateAndOpenNextWorkItem 701

Response:
SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <allocateAndOpenNextWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItem xmlns=""> <id id="35" version="1"/> <header distributionStrategy="OFFER" priority="50"> <name>ServicingMgr</name> <description>ServicingMgr</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i71</activityID> <activityName>ServicingMgr</activityName> <appInstance>pvm:0a12j</appInstance> <appName>AMXSupervisor</appName> <appID>_fQ0ZAHClEeCF3qXLa8gNUw</appID> <appInstanceDescription>ryt6</appInstanceDescription> </itemContext> </header> <body> <dataModel> <inputs array="false" name="param2" type="String"> <simpleSpec> <value>ryt6</value> </simpleSpec> </inputs> <inouts array="false" name="txtField1" type="String"> <simpleSpec> <value>r6y</value> </simpleSpec> </inouts> </dataModel> </body> <workType version="1.0.0.201106141602" workTypeDescription="ServicingMgr" workTypeID="WT__QnN14HCmEeCF3qXLa8gNUw"/> <state>OPENED</state> <visible>true</visible> </workItem> </allocateAndOpenNextWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

702

| Chapter 32

WorkItemManagementService

Service Connector API (Java Method)

Method Service allocateAndOpenNextWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

unallocateWorkItem 703

unallocateWorkItem
Reoffer a currently allocated work item to the original offer set: The request must specify the work item that should be deallocated. The response returns full details of the deallocated work item. This operation can only be used if the work item is in a state from which it can be unallocated. See Work Item State Transitions, page 195.

Required System Action workItemAllocation

TIBCO ActiveMatrix BPM - BPM Developers Guide

704

| Chapter 32

WorkItemManagementService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the unallocateWorkItem element (from the WorkItemManagementService schema) workItemID: ID of the work item to be unallocated. version: (Optional) If it is omitted, the latest version is used.

Returns an unallocateWorkItemResponse element (from the WorkItemManagementService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:unallocateWorkItem> <workItemID id="22" version="1"/> </api:unallocateWorkItem> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <unallocateWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItem xmlns=""> <id id="22" version="2"/> <header distributionStrategy="OFFER" priority="50"> <name>ServicingMgr</name> <description>ServicingMgr</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i3a</activityID> <activityName>ServicingMgr</activityName> <appInstance>pvm:0a128</appInstance> <appName>AMXSupervisor</appName> <appID>_fQ0ZAHClEeCF3qXLa8gNUw</appID> <appInstanceDescription>Oho</appInstanceDescription> </itemContext> </header> <state>OFFERED</state> <visible>true</visible> </workItem> </unallocateWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

unallocateWorkItem 705

Service Connector API (Java Method)

Method Service unallocateWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

706

| Chapter 32

WorkItemManagementService

completeWorkItem
Complete a work item (and update the associated input and output data): The request must specify the work item that should be completed. The response indicates whether or not the operation succeeded.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

completeWorkItem 707

Web Service API (SOAP Operation)

Request Parameter notes Uses the completeWorkItem element (from the WorkItemManagementService schema) workItemID: ID of the work item to be completed. version: (Optional) If it is omitted, the latest version is used. workItemPayload: the complete body of the work item: data to be written to the work item as part of the Complete action. If complexSpec business data is passed into this operation, see Valid Format for ComplexSpec Business Data on page 216 for information about the valid format. getNextPiledItem: An optional Boolean field. If work items are piled, a value of true will automatically open the next work item. For information on piled work items, see the TIBCO Business Studio Process Modeling User's Guide.

Response

Returns a completeWorkItemResponse element (from the WorkItemManagementService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

708

| Chapter 32
Example

WorkItemManagementService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:completeWorkItem> <workItemID id="4" version="0"/> <workItemPayload> <dataModel> <!--Zero or more repetitions:--> <inputs name="PhoneNum" type="string" optional="?" array="false"> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <simpleSpec length="?" decimal="?"> <!--Zero or more repetitions:--> <value>555-14951</value> </simpleSpec> </inputs> <inputs name="Name" type="string" optional="?" array="false"> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <simpleSpec length="?" decimal="?"> <!--Zero or more repetitions:--> <value>Francois Premier</value> </simpleSpec> <!--Optional:--> <complexSpec className="?"> <!--Zero or more repetitions:--> <value>?</value> </complexSpec> </inputs> <!--Zero or more repetitions:--> <outputs ........ ........ </outputs> <!--Zero or more repetitions:--> <inouts ........ ........ </inouts> </dataModel> </workItemPayload> <!--Optional:--> <getNextPiledItem>false</getNextPiledItem> </api:completeWorkItem> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

completeWorkItem 709

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <completeWorkItemResponse xmlns="http://api.brm.n2.tibco.com"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service completeWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

710

| Chapter 32

WorkItemManagementService

skipWorkItem
Skip a work item. This means that no action is carried out on the work item. The request must specify the work item that should be skipped. The response identifies whether the request succeeded or failed. This operation can only be carried out on work items that have default values for all required output and in/out data fields, or have values set already for such fields.

Required System Action skipWorkItem

TIBCO ActiveMatrix BPM - BPM Developers Guide

skipWorkItem 711

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the skipWorkItem element (from the WorkItemManagementService schema) workItemID: ID of the work item to be completed. version: (Optional) If it is omitted, the latest version is used.

Returns a skipWorkItemResponse element (from the WorkItemManagementService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:skipWorkItem> <workItemID id="2" version="1"/> </api:skipWorkItem> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <skipWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <success xmlns="">true</success> </skipWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service skipWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

712

| Chapter 32

WorkItemManagementService

reallocateWorkItem
Reallocate a work item with no new data to a different resource: The request must specify the work item that should be reallocated and the resource to whom it is to be reallocated. The response returns details of the reallocated work item. Note that the users to whom a work item can be reallocated is restricted by the system action held by the caller see below. Also, to reallocate a work item to the original offer set, the work item can have a state of Offered, Allocated, or Pended; to reallocate a work item to the "the world", the work item can have a state of Allocated or Pended. If there is new data to be written to the work item, use reallocateWorkItemData instead.

Required System Actions reallocateToOfferSet - This system action allows you to reallocate work items to only the users in the original offer set. reallocateWorkItemToWorld - This system action allows you to reallocate work items to any user in the organization model.

TIBCO ActiveMatrix BPM - BPM Developers Guide

reallocateWorkItem 713

Web Service API (SOAP Operation)

Request Parameter notes Uses the reallocateWorkItem element (from the WorkItemManagementService schema) workItemID: ID of the work item to be reallocated. version: (Optional) If it is omitted, the latest version is used. resource: the GUID of the resource to whom the work item is to be reallocated. A resources GUID can be obtained from a previous lookupUser operation The setting of revertData determines whether existing data is kept ("false") or whether it is discarded and the work item returned to its initial state when scheduled ("true").

Response

Returns a reallocateWorkItemResponse element (from the WorkItemManagementService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

714

| Chapter 32
Example

WorkItemManagementService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:reallocateWorkItem> <workItemID id="51" version=""/> <resource>3D9296E1-B1F8-4A09-A219-0285D43B3498</resource> <revertData>false</revertData> </api:reallocateWorkItem> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <reallocateWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItem xmlns=""> <id id="51" version="2"/> <header distributionStrategy="OFFER" priority="50"> <name>DisplayMessage</name> <description>Display Message</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i11</activityID> <activityName>DisplayMessage</activityName> <appInstance>pvm:0a124</appInstance> <appName>WelcomeUsers</appName> <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID> </itemContext> </header> <state>ALLOCATED</state> <visible>true</visible> </workItem> </reallocateWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service reallocateWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

reallocateWorkItemData 715

reallocateWorkItemData
Reallocate a work item to a different resource and update the work item with new data: The request must specify the work item and the data that should be reallocated, and the resource to whom it is to be reallocated. The response returns details of the reallocated work item. Note that the users to whom a work item can be reallocated is restricted by the system action held by the caller see below. Also, to reallocate a work item to the original offer set, the work item can have a state of Offered, Allocated, or Pended; to reallocate a work item to the "the world", the work item can have a state of Allocated or Pended. If the work item has no new data associated with it use reallocateWorkItem instead.

Required System Actions reallocateToOfferSet - This system action allows you to reallocate work items to only the users in the original offer set. reallocateWorkItemToWorld - This system action allows you to reallocate work items to any user in the organization model.

TIBCO ActiveMatrix BPM - BPM Developers Guide

716

| Chapter 32

WorkItemManagementService

Web Service API (SOAP Operation)

Request Parameter notes Uses the reallocateWorkItemData element (from the WorkItemManagementService schema) workItemID: ID of the work item to be reallocated. version: (Optional) If it is omitted, the latest version is used. resource: the GUID of the resource to whom the work item is to be reallocated. A resources GUID can be obtained from a previous lookupUser operation workItemPayload: the complete body of the work item, containing the new data to be written to the work item as part of this action. If complexSpec business data is passed into this operation, see Valid Format for ComplexSpec Business Data on page 216 for information about the valid format. Response Returns a reallocateWorkItemDataResponse element (from the WorkItemManagementService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

reallocateWorkItemData 717

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:reallocateWorkItemData> <workItemID id="3" version="12"/> <resource>846D100C-77C8-42DE-BD01-C23D214D2BB4</resource> <workItemPayload> <dataModel> <inputs name="Message" type="String" optional="?" array="false"> <simpleSpec length="?" decimal="?"> <value>Please call An Lushan at 01799887256.</value> </simpleSpec> <complexSpec className="?"> <value>?</value> </complexSpec> </inputs> <outputs name="?" type="?" optional="?" array="?"> <simpleSpec length="?" decimal="?"> <value>?</value> </simpleSpec> <complexSpec className="?"> <value>?</value> </complexSpec> </outputs> <inouts name="?" type="?" optional="?" array="?"> <simpleSpec length="?" decimal="?"> <value>?</value> </simpleSpec> <complexSpec className="?"> <!--Zero or more repetitions:--> <value>?</value> </complexSpec> </inouts> </dataModel> </workItemPayload> </api:reallocateWorkItemData> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

718

| Chapter 32

WorkItemManagementService

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <reallocateWorkItemDataResponse xmlns="http://api.brm.n2.tibco.com"> <workItem xmlns=""> <id id="3" version="16"/> <header distributionStrategy="OFFER" priority="50"> <name>DisplayMessage</name> <description>Display Message</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001io</activityID> <activityName>DisplayMessage</activityName> <appInstance>pvm:0a123</appInstance> <appName>WelcomeUsers</appName> <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID> </itemContext> </header> <state>ALLOCATED</state> <visible>true</visible> </workItem> </reallocateWorkItemDataResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service reallocateWorkItemData (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getOfferSet 719

getOfferSet
Get the offer set for a work item (The offer set is the set of organization model entities to whom a work item is to be offered.): The request must specify the work item for which the offer set is required. The response returns the IDs of the organization model entities that comprise the offer set for this work item.

Required system action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

720

| Chapter 32

WorkItemManagementService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getOfferSet element (from the WorkItemManagementService schema) workItemID: ID of the work item for which information is required. version: (Optional) If it is omitted, the latest version is used.

Returns a getOfferSetResponse element (from the WorkItemManagementService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getOfferSet> <workItemID id="3"/> </api:getOfferSet> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getOfferSetResponse xmlns="http://api.brm.n2.tibco.com"> <entityGuid xmlns="">_5i1V0CfLEeChutsy_vK9tg</entityGuid> </getOfferSetResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service getOfferSet (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

saveOpenWorkItem 721

saveOpenWorkItem
Save a work item (and update the associated input and output data): The request must specify the work item that should be saved, and the data that should be updated as part of the save. The response returns the ID of the saved work item.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

722

| Chapter 32

WorkItemManagementService

Web Service API (SOAP Operation)

Request Parameter notes Uses the saveOpenWorkItem element (from the WorkItemManagementService schema) workItemID: ID of the work item for which information is required. version: (Optional) If it is omitted, the latest version is used. workItemPayload: the complete body of the work item. This contains the data to be saved. If complexSpec business data is passed into this operation, see Valid Format for ComplexSpec Business Data on page 216 for information about the valid format. Response Returns a saveOpenWorkItemResponse element (from the WorkItemManagementService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

saveOpenWorkItem 723

Example

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:saveOpenWorkItem> <workItemID id="54"/> <workItemPayload> <dataModel> <inputs name="Message" type="String" optional="?" array="false"> <simpleSpec length="?" decimal="?"> <value>Please call William Tanner at 555-1066.</value> </simpleSpec> <complexSpec className="?"> <value>?</value> </complexSpec> </inputs> <outputs name="?" type="?" optional="?" array="?"> <simpleSpec length="?" decimal="?"> <!--Zero or more repetitions:--> <value>?</value> </simpleSpec> <complexSpec className="?"> <value>?</value> </complexSpec> </outputs> <inouts name="?" type="?" optional="?" array="?"> <simpleSpec length="?" decimal="?"> <value>?</value> </simpleSpec> <complexSpec className="?"> <value>?</value> </complexSpec> </inouts> </dataModel> </workItemPayload> </api:saveOpenWorkItem> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <saveOpenWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItemID id="54" version="3" xmlns=""/> </saveOpenWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

724

| Chapter 32

WorkItemManagementService

Service Connector API (Java Method)

Method Service saveOpenWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

pendWorkItem 725

pendWorkItem
To pend a work item: The request must specify the work item that should be pended. The response returns the ID of the pended work item. A pendWorkItem operation that specifies a hiddenPeriod of 0 cancels a hiddenPeriod set by a previous pendWorkItem operation on the same work item. See Accessing Hidden Work Items, page 218.

Required System Action pendWorkItem

TIBCO ActiveMatrix BPM - BPM Developers Guide

726

| Chapter 32

WorkItemManagementService

Web Service API (SOAP Operation)

Request Parameter notes Uses the pendWorkItem element (from the WorkItemManagementService schema) workItemID: ID of the work item for which information is required. version: (Optional) If it is omitted, the latest version is used. hiddenPeriod: information about how long the work item is to be hidden. Either a duration for which it is to be hidden, or the date and time when it is to become visible. A hiddenPeriod of 0 cancels any current hiddenPeriod. See Accessing Hidden Work Items on page 218 for more details.

Response Example

Returns a pendWorkItemResponse element (from the WorkItemManagementService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:pendWorkItem> <workItemID id="3" version=""/> <hiddenPeriod> <hiddenDuration years="0" months="0" weeks="0" days="0" hours="0" minutes="5"/> <visibleDate>2011-07-23T14:25:10</visibleDate> </hiddenPeriod> </api:pendWorkItem> </soapenv:Body> </soapenv:Envelope>

Response:
SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <pendWorkItemResponse xmlns="http://api.brm.n2.tibco.com"> <workItemID id="3" version="11" xmlns=""/> </pendWorkItemResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service pendWorkItem (args) WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

pendWorkItem 727

TIBCO ActiveMatrix BPM - BPM Developers Guide

728

| Chapter 32

WorkItemManagementService

TIBCO ActiveMatrix BPM - BPM Developers Guide

WorkListService 729

Chapter 33

WorkListService

WorkListService is one of the Business Resource Management Services provided by Work Manager. Use WorkListService requests to get work item lists for organization model entities, and to get or to set sort/filter criteria for work item lists.

Topics
getWorkListItems, page 730 getAllocatedWorkListItems, page 734 previewWorkItemFromList, page 738 getWorkItemOrderFilter, page 741 getResourceOrderFilterCriteria, page 743 setResourceOrderFilterCriteria, page 745

TIBCO ActiveMatrix BPM - BPM Developers Guide

730

| Chapter 33

WorkListService

getWorkListItems
:Get a work list for an organization model entity: The request must specify the organization model entity requiring a work item list, the number of work items to retrieve and (for a resource) any work list sort/filter criteria. The response returns the work list for the specified organization model entity. (The work list contains full details of the requested number of work items.)

Required System Action viewWorkList

TIBCO ActiveMatrix BPM - BPM Developers Guide

getWorkListItems 731

Web Service API (SOAP Operation)

Request Parameter notes Uses the getWorkListItems element (from the WorkListService schema) entityID: the GUID of the organizational entity whose work list you want to retrieve. startPosition: the position in the work list from which to start the page of results. The list is zero-based. To start at the first item, specify 0. numberOfItems: the number of items from the work list to include. getTotalCount: (Optional) whether to include a count of the total number of work items in the list. This defaults to true. The count is returned in the totalItems value in the response. You should set getTotalCount to false unless you specifically need the total figure, because setting it to true is expensive in terms of database access time. Note that if you pass false in this attribute, and there is at least one item in the list, the totalItems value returned in the response is -1. However, if you pass false and there are no work items in the list, the totalItems value in the response is 0 (zero). orderFilterCriteria: (Optional) sort or filter criteria, or both, to determine how the work items are to be filtered and presented. See Sorting and Filtering Work Lists on page 169 for details of the syntax and content of these criteria.

Response Example

Returns a getWorkListItemsResponse element (from the WorkListService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getWorkListItems startPosition="0" numberOfItems="5" getTotalCount="true"> <entityID model-version="-1" entity-type="POSITION" guid="_5i1V0CfLEeChutsy_vK9tg" > </entityID> <orderFilterCriteria> <order>id ASC</order> <filter>state=OFFERED</filter> </orderFilterCriteria> </api:getWorkListItems> </soapenv:Body> </soapenv:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

732

| Chapter 33

WorkListService

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getWorkListItemsResponse xmlns="http://api.brm.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <endPosition xmlns="">2</endPosition> <totalItems xmlns="">3</totalItems> <workItems xmlns=""> <id id="2" version="0"/> <header distributionStrategy="OFFER" priority="50"> <name>DisplayMessage</name> <description>Display Message</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001if</activityID> <activityName>DisplayMessage</activityName> <appInstance>pvm:0a122</appInstance> <appName>WelcomeUsers</appName> <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID> </itemContext> </header> <state>OFFERED</state> <visible>true</visible> </workItems> <workItems xmlns=""> <id id="3" version="0"/> <header distributionStrategy="OFFER" priority="50"> <name>DisplayMessage</name> <description>Display Message</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001io</activityID> <activityName>DisplayMessage</activityName> <appInstance>pvm:0a123</appInstance> <appName>WelcomeUsers</appName> <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID> </itemContext> </header> <state>OFFERED</state> <visible>true</visible> </workItems> </getWorkListItemsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getWorkListItems 733

Service Connector API (Java Method)

Method Service getWorkListItems (args) WorkListService

TIBCO ActiveMatrix BPM - BPM Developers Guide

734

| Chapter 33

WorkListService

getAllocatedWorkListItems
:Get an allocated work list for an organization model entity: The request must specify the organization model entity requiring an allocated work item list, the number of work items to retrieve and (for a resource) any work list sort/filter criteria. The response returns the work list for the specified organization model entity. (The work list contains full details of the requested number of allocated work items.)

Required System Action viewWorkList

TIBCO ActiveMatrix BPM - BPM Developers Guide

getAllocatedWorkListItems 735

Web Service API (SOAP Operation)

Request Parameter notes Uses the getAllocatedWorkListItems element (from the WorkListService schema) entityID: the GUID of the organizational entity whose work list you want to retrieve. startPosition: the position in the work list from which to start the page of results. The list is zero-based. To start at the first item, specify 0. numberOfItems: the number of items from the work list to include. getTotalCount: (Optional) whether to include a count of the total number of work items in the list. This defaults to true. The count is returned in the totalItems value in the response. You should set getTotalCount to false unless you specifically need the total figure, because setting it to true is expensive in terms of database access time. Note that if you pass false in this attribute, and there is at least one item in the list, the totalItems value returned in the response is -1. However, if you pass false and there are no work items in the list, the totalItems value in the response is 0 (zero). orderFilterCriteria: (Optional) sort or filter criteria, or both, to determine how the work items are to be filtered and presented. See Sorting and Filtering Work Lists on page 169 for details of the syntax and content of these criteria.

Response

Returns a getWorkListItemsResponse element (from the WorkListService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

736

| Chapter 33
Example

WorkListService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getAllocatedWorkListItems startPosition="0" numberOfItems="2" getTotalCount="true"> <entityID model-version="-1" entity-type="POSITION" guid="_5i1V0CfLEeChutsy_vK9tg"> </entityID> <orderFilterCriteria> <order>id DESC</order> <filter></filter> </orderFilterCriteria> </api:getAllocatedWorkListItems> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getWorkListItemsResponse xmlns="http://api.brm.n2.tibco.com"> <startPosition xmlns="">0</startPosition> <endPosition xmlns="">0</endPosition> <totalItems xmlns="">1</totalItems> <workItems xmlns=""> <id id="51" version="3"/> <header distributionStrategy="OFFER" priority="50"> <name>DisplayMessage</name> <description>Display Message</description> <flags> <scheduleStatus>DURING</scheduleStatus> </flags> <itemContext> <activityID>pvm:001i11</activityID> <activityName>DisplayMessage</activityName> <appInstance>pvm:0a124</appInstance> <appName>WelcomeUsers</appName> <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID> </itemContext> </header> <state>OPENED</state> <visible>true</visible> </workItems> </getWorkListItemsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getAllocatedWorkListItems 737

Service Connector API (Java Method)

Method Service getAllocatedWorkListItems (args) WorkListService

TIBCO ActiveMatrix BPM - BPM Developers Guide

738

| Chapter 33

WorkListService

previewWorkItemFromList
Preview one or more work items (to get the associated input and output data without opening the work items): The request message identifies the organizational entity making the request, and the work item or items to be previewed. Optionally it can also limit the data returned to specified fieldnames. The response message contains the work item ID and version, and the details of any requested fields.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

previewWorkItemFromList 739

Web Service API (SOAP Operation)

Request Parameter notes Uses the previewWorkItemFromList element (from the WorkListService schema) entityID: the GUID of the organizational entity which is requesting the work list. If the entity is not in the list of resources for which the work item is offered, the resource will not be able to preview the work item. workItemID: the IDs of one or more work items to be previewed. All work items must be from the work list of the same organizational entity. requiredField: A fieldname to be included in the returned data. This filters the set of fields for which preview data is to be returned: If any fieldnames are specified, only those fields will be returned for each work item. If the requiredField parameter is omitted, all fields will be returned for each work item. (Note that if requiredField is included without a value, it will be interpreted as a request for a field with a blank name, and nothing will be returned.) Response Returns a previewWorkItemFromListResponse element (from the WorkListService schema).

TIBCO ActiveMatrix BPM - BPM Developers Guide

740

| Chapter 33
Example

WorkListService

Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:previewWorkItemFromList> <entityID model-version="-1" entity-type="RESOURCE" guid="2D6430DC-9A65-4F21-A3BE-798AA192E468"> <qualifierSet value="?"/> </entityID> <workItemID id="19"/> <requiredField>UserName</requiredField> </api:previewWorkItemFromList> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <previewWorkItemFromListResponse xmlns="http://api.brm.n2.tibco.com"> <workItemPreview id="19" version="3" xmlns=""> <FieldPreview array="false" name="UserName" type="String"> <simpleSpec> <value>Loki Aesir</value> </simpleSpec> </FieldPreview> </workItemPreview> </previewWorkItemFromListResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service previewWorkItemFromList (args) WorkListService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getWorkItemOrderFilter 741

getWorkItemOrderFilter
Get the fields defined by BRM that can be used to define sort/filter criteria for a work item list: The request specifies the number of fields to return. The response returns details of the BRM-defined fields that can be used to define sort and/or filter criteria for a work item list.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

742

| Chapter 33

WorkListService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getWorkItemOrderFilter element (from the WorkListService schema) limitColumnsthe number of fields about which information should be returned. A value of 0 gets information about all fields.

Returns a getWorkItemOrderFilterResponse element (from the WorkListService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getWorkItemOrderFilter> <limitColumns>3</limitColumns> </api:getWorkItemOrderFilter> </soapenv:Body> </soapenv:Envelope> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getWorkItemOrderFilterResponse xmlns="http://api.brm.n2.tibco.com"> <columnData capability="BOTH_ORDER_FILTER" description="The integer value that denotes the ID of the work item." id="1" name="id" type="COL_NUMERIC" xmlns=""/> <columnData capability="FILTER" description="The name of the work item." id="2" name="name" type="COL_STRING" xmlns=""/> <columnData capability="FILTER" description="The description of the work item." id="3" name="description" type="COL_STRING" xmlns=""/> </getWorkItemOrderFilterResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service getWorkItemOrderFilter (args) WorkListService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getResourceOrderFilterCriteria 743

getResourceOrderFilterCriteria
Get (previously defined) sort/filter criteria for work item lists for a resource: The request must specify the resource for whom work list sort/filter criteria is required. The response returns the work list sort/filter criteria for the specified resource.

Required System Action setResourceOrderFilterCriteria

TIBCO ActiveMatrix BPM - BPM Developers Guide

744

| Chapter 33

WorkListService

Web Service API (SOAP Operation)

Request Parameter notes Response Example Uses the getResourceOrderFilterCriteria element (from the WorkListService schema) resourceID: the GUID of the resource for whose work list you want to retrieve sort and filter criteria..

Returns a getResourceOrderFilterCriteriaResponse element (from the WorkListService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:getResourceOrderFilterCriteria> <resourceID>846D100C-77C8-42DE-BD01-C23D214D2BB4</resourceID> </api:getResourceOrderFilterCriteria> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <getResourceOrderFilterCriteriaResponse xmlns="http://api.brm.n2.tibco.com"> <orderFilterCriteria xmlns=""> <order>startDate DESC</order> <filter>[2011-05-23,2012-07-23]</filter> </orderFilterCriteria> </getResourceOrderFilterCriteriaResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service getResourceOrderFilterCriteria (args) WorkListService

TIBCO ActiveMatrix BPM - BPM Developers Guide

setResourceOrderFilterCriteria 745

setResourceOrderFilterCriteria
Set sort/filter criteria for work item lists for a resource: The request must specify the sort/filter criteria to set and identify the resource for whom they should be set. The response returns whether the request succeeded or failed.

Required System Action setResourceOrderFilterCriteria

TIBCO ActiveMatrix BPM - BPM Developers Guide

746

| Chapter 33

WorkListService

Web Service API (SOAP Operation)

Request Parameter notes Uses the setResourceOrderFilterCriteria element (from the WorkListService schema) Response Example resourceID: the GUID of the resource for whose work list you want to set sort and filter criteria. orderFilterCriteria: the sort and filter criteria to set. See Sorting and Filtering Work Lists on page 169 for details of the syntax and content of these criteria.

Returns a setResourceOrderFilterCriteriaResponse element (from the WorkListService schema) Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com"> <soapenv:Header/> <soapenv:Body> <api:setResourceOrderFilterCriteria resourceID="846D100C-77C8-42DE-BD01-C23D214D2BB4"> <orderFilterCriteria> <!--Optional:--> <order>startDate DESC</order> <!--Optional:--> <filter>[2011-05-23,2012-07-23]</filter> </orderFilterCriteria> </api:setResourceOrderFilterCriteria> </soapenv:Body> </soapenv:Envelope>

Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <setResourceOrderFilterCriteriaResponse xmlns="http://api.brm.n2.tibco.com"> <success xmlns="">true</success> </setResourceOrderFilterCriteriaResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Service Connector API (Java Method)

Method Service setResourceOrderFilterCriteria (args) (args) WorkListService

TIBCO ActiveMatrix BPM - BPM Developers Guide

WorkPresentationService 747

Chapter 34

WorkPresentationService

WorkPresentationService is one of the Work Presentation Services provided by Work Manager. Use WorkPresentationService requests to perform various operations on work items.

Topics
openWorkItem, page 748 cancelWorkItem, page 751 closeWorkItem, page 753 completeWorkItem, page 756 openNextWorkItem, page 759 getBusinessServiceDetailsByModule, page 763

TIBCO ActiveMatrix BPM - BPM Developers Guide

748

| Chapter 34

WorkPresentationService

openWorkItem
Retrieves the associated input and output data and opens the work item form. Note that there is an openWorkItem operation in two services: WorkPresentationService (the one described here) - Use this one if the user task was designed to either open a form or start a pageflow, which is typical for most client applications. WorkItemManagementService - Use this one if the user task was designed to not open a form nor start a pageflow. This would typically be used only in special use-case client applicationssee openWorkItem. The request must specify the resource ID and the work item ID that is to be opened. The response returns the complete details of the work item that is opened, as well as the pageflow details if the user task was designed to start a pageflow.

For additional information, see Introduction to Work Items on page 190. Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

openWorkItem 749

Web Service API (SOAP Operation)

Request Parameter notes Uses the baseWorkRequest element (from the WorkPresentationService schema) resourceId: The GUID of the resource for whom the work item is to be opened. channelID: ID of the channel to use. If it is omitted, the default channel for the specified channelType is used. See "Configuring the GI Presentation Channel" in TIBCO ActiveMatrix BPM - BPM Administration for defining the default. workItemID: ID of the work item for which information to be opened. version: (Optional). If it is omitted, the latest version is used. openNextPiled: This parameter is not applicable to openWorkItem, cancelWorkItem, or closeWorkItem. The boolean value specified is used only when calling completeWorkItem.

Response

Returns a workResponse element (from the WorkPresentationService schema)

TIBCO ActiveMatrix BPM - BPM Developers Guide

750

| Chapter 34
Example

WorkPresentationService

Request:
<soapenv:Body> <api:baseWorkRequest action="?"> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <channelId>?</channelId> <channelType>GIChannel</channelType> <responsePayloadMode>XML</responsePayloadMode> <workItem id="37" version="0">?</workItem> <workTypeDetail uid="WT__81TKQFlFEd-5Ae672m_IWw" version="0" openNextPiled="true"/> </api:baseWorkRequest> </soapenv:Body>

Response:
<SOAP-ENV:Body> <workResponse xmlns="http://api.wp.n2.tibco.com"> <payloadModel payloadMode="XML" xmlns=""> <XmlPayload> <inputs array="false" name="Message" type="String"> <simpleSpec> <value>Please call TIB_USER at 987654321.</value> </simpleSpec> </inputs> </XmlPayload> </payloadModel> <workTypeDetail pilingLimit="0" typePiled="false" uid="WT__81TKQFlFEd-5Ae672m_IWw" version="1.0.0.201108111516" xmlns=""/> <presentation activityName="DisplayMessage" formIdenitifier="1.0.0.201108111516/GIGWTPull_DefaultChannel/.default/ ProcessPackage/WelcomeUsers/DisplayMessage/DisplayMessage.gwt.json" type="GI_FORM" version="1.0.0.201108111516" xmlns=""/> <workItem id="37" version="1" xmlns=""/> </workResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service openWorkItem (args) WorkPresentationService

TIBCO ActiveMatrix BPM - BPM Developers Guide

cancelWorkItem 751

cancelWorkItem
Cancels the specified work item. Any changes made to the data will be lost when you cancel a work item. The request must specify the work item and the resource ID for the work item that is to be cancelled. Optionally, you can also specify the work type details for the work item. The response returns the execution status of the operation.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

752

| Chapter 34

WorkPresentationService

Web Service API (SOAP Operation)

Request Parameter notes Uses the baseWorkRequest element (from the WorkPresentationService schema) channelID: ID of the channel to use. If it is omitted, the default channel for the specified channelType is used. See "Configuring the GI Presentation Channel" in TIBCO ActiveMatrix BPM - BPM Administration for defining the default. workItemId: ID of the work item for which information to be opened. version: (Optional). If it is omitted, the latest version is used. openNextPiled: This parameter is not applicable to openWorkItem, cancelWorkItem, or closeWorkItem. The boolean value specified is used only when calling completeWorkItem.

Response Example

Returns a workResponse element (from the WorkPresentationService schema) Request:

<soapenv:Body> <api:workRequest action="?"> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <channelId>?</channelId> <channelType>GIChannel</channelType> <responsePayloadMode>XML</responsePayloadMode> <workItem id="37" version="1">?</workItem> <workTypeDetail uid="WT__81TKQFlFEd-5Ae672m_IWw" version="1" openNextPiled="true"/> <payloadDetails payloadMode="XML"> <XmlPayload> </XmlPayload> </payloadDetails> </api:workRequest> </soapenv:Body>

Response:
<SOAP-ENV:Body> <workResponse isSuccessful="true" xmlns="http://api.wp.n2.tibco.com"/> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service cancelWorkItem (args) WorkPresentationService

TIBCO ActiveMatrix BPM - BPM Developers Guide

closeWorkItem 753

closeWorkItem
Closes a work item form and updates the associated data with any changes the user has made while it was open. Note that there is a closeWorkItem operation in two services: WorkPresentationService (the one described here) - Use the operation in this service to close a form that was opened when the work item was opened with the openWorkItem operation. This is typically called in response to a user clicking the Close button on a work item form. WorkItemManagementService - Use this one only if the user task did not open a form when the work item was opened. This would typically be used only in special use-case client applicationssee closeWorkItem. Note that one special use-case for using the closeWorkItem operation in WorkItemManagementService is to set the work item state to PendHidden so that it does not appear in the work list for a specified period of time. For more information, see Accessing Hidden Work Items on page 218. The request must specify the details of the work item to be closed, the payload, and whether the next piled work item must be opened after the current one is closed. The response returns the execution status, the payload received in the request message, the work type details, presentation details and pageflow details. This operation puts the work item into a Pended state. (If you wish to update the work item to a PendHidden state, you must use the closeWorkItem operation provided by the WorkItemManagementService.)

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

754

| Chapter 34

WorkPresentationService

Web Service API (SOAP Operation)

Request Parameter notes Uses the workRequest element (from the WorkPresentationService schema) channelId: ID of the channel to use. If it is omitted, the default channel for the specified channelType is used. See "Configuring the GI Presentation Channel" in TIBCO ActiveMatrix BPM - BPM Administration for defining the default. workItemID: ID of the work item to be closed. version: (Optional). If it is omitted, the latest version is used. payloadDetails: the complete body of the work item: data to be written to the work item as part of the Close action. If complexSpec business data is passed into this operation, see Valid Format for ComplexSpec Business Data on page 216 for information about the valid format. openNextPiled: This parameter is not applicable to openWorkItem, cancelWorkItem, or closeWorkItem. The boolean value specified is used only when calling completeWorkItem.

Response Example

Returns a workResponse element (from the WorkPresentationService schema) Request:

<soapenv:Body> <api:workRequest action="?"> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <channelId>?</channelId> <channelType>GIChannel</channelType> <responsePayloadMode>XML</responsePayloadMode> <workItem id="38" version="1">?</workItem> <workTypeDetail uid="WT__UZikcDjhEeCeRNBOZebDZA" version="1.0.0.201108111516" openNextPiled="true"/> <payloadDetails payloadMode="XML"> <XmlPayload> <inputs array="false" name="UserName" type="String"> <simpleSpec> <value>TIB_USER</value> </simpleSpec> </inputs> </XmlPayload> </payloadDetails> </api:workRequest> </soapenv:Body>

Response:
<SOAP-ENV:Body> <workResponse isSuccessful="true" xmlns="http://api.wp.n2.tibco.com"/> </SOAP-ENV:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

closeWorkItem 755

Service Connector API (Java Method)

Method Service closeWorkItem (args) WorkPresentationService

TIBCO ActiveMatrix BPM - BPM Developers Guide

756

| Chapter 34

WorkPresentationService

completeWorkItem
Use this operation when work on a work item or pageflow has completed. Input and output data associated with the work item is saved to the database. The work item must be Opened, and its state is changed to Completed. Note that there is a completeWorkItem operation in two services: WorkPresentationService (the one described here) - Use this one if a form was opened when the work item was opened with the openWorkItem operation. This is typically called in response to a user clicking the Submit button on a work item form. WorkItemManagementService - Use this one if the user task was designed to not open a form nor start a pageflow. This would typically be used only in special use-case client applicationssee completeWorkItem. The request must specify the work item to be completed and also provide the payload. The response returns the execution status, the payload received in the request message, the work type details, presentation details and pageflow details (if any). If the work item is part of a chained group, the response returns the next work item in the group. If the work item is piled, the response returns the next piled work item.

If the work item is part of a chained group and is also piled, then the chained group takes precedence. Once all the chained work items are executed, the next piled work item is executed. This operation puts the work item into a Completed state. Once completed, no further operations can be performed on the work item.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

completeWorkItem 757

Web Service API (SOAP Operation)

Request Parameter notes Uses the workRequest element (from the WorkPresentationService schema) channelID: ID of the channel to use. If it is omitted, the default channel for the specified channelType is used. See "Configuring the GI Presentation Channel" in TIBCO ActiveMatrix BPM - BPM Administration for defining the default. openNextPiled: An optional Boolean field. If work items are piled, a value of true will automatically open the next work item. For information on piled work items, see the TIBCO Business Studio Process Modeling User's Guide. payloadDetails: If complexSpec business data is passed into this operation, see Valid Format for ComplexSpec Business Data on page 216 for information about the valid format.

Response Example

Returns a workResponse element (from the WorkPresentationService schema) Request:

<soapenv:Body> <api:workRequest action="?"> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <channelId>?</channelId> <channelType>GIChannel</channelType> <responsePayloadMode>XML</responsePayloadMode> <workItem id="37" version="3"/> <workTypeDetail uid="WT__81TKQFlFEd-5Ae672m_IWw" version="1.0.0.201108111516" openNextPiled="true"/> <payloadDetails payloadMode="XML"> <XmlPayload> <inputs array="false" name="Message" type="String"> <simpleSpec> <value>Please call TIB_USER at 987654321.</value> </simpleSpec> </inputs> </XmlPayload> </payloadDetails> </api:workRequest> </soapenv:Body>

Response:
<SOAP-ENV:Body> <workResponse isSuccessful="true" xmlns="http://api.wp.n2.tibco.com"/> </SOAP-ENV:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

758

| Chapter 34

WorkPresentationService

Service Connector API (Java Method)

Method Service completeWorkItem (args) WorkPresentationService

TIBCO ActiveMatrix BPM - BPM Developers Guide

openNextWorkItem 759

openNextWorkItem
Opens the next work item in the work queue. The request must specify the resource ID, channel ID, channel type, and mode in which the payload must be returned. The response returns the execution status, the payload of the work item that is opened, the work type details, presentation details and pageflow details.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

760

| Chapter 34

WorkPresentationService

Web Service API (SOAP Operation)

Request Parameter notes Uses the baseRequest element (from the WorkPresentationService schema) resourceId: The GUID of the resource for whom the next work item from the work queue is to be opened. channelID: ID of the channel to use. If it is omitted, the default channel for the specified channelType is used. See "Configuring the GI Presentation Channel" in TIBCO ActiveMatrix BPM - BPM Administration for defining the default. responsePayloadMode: mode in which the response payload must be returned. The payload mode can be either XML or JSON.

Response Example

Returns a workResponse element (from the WorkPresentationService schema) Request:

<soapenv:Body> <api:baseRequest action="?"> <resourceId>2D6430DC-9A65-4F21-A3BE-798AA192E468</resourceId> <channelId>?</channelId> <channelType>GIChannel</channelType> <responsePayloadMode>JSON</responsePayloadMode> </api:baseRequest> </soapenv:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

openNextWorkItem 761

Response:
<SOAP-ENV:Body> <workResponse xmlns="http://api.wp.n2.tibco.com"> <payloadModel payloadMode="JSON" xmlns=""> <serializedPayload>{items:[{"$param":"UserName","$value":["TIB_USER"], "type":"String","mode":"IN"}]}</serializedPayload> </payloadModel> <workTypeDetail pilingLimit="0" typePiled="false" uid="WT__UZikcDjhEeCeRNBOZebDZA" version="1.0.0.201108111516" xmlns=""> <dataModel> <inputs array="false" name="UserName" optional="false" type="String"> <simpleSpec decimal="0" length="50"/> </inputs> </dataModel> </workTypeDetail> <presentation formIdenitifier="http://localhost:8080/bpm/" type="GI_FORM" xmlns=""/> <workItem id="38" version="7" xmlns=""/> <pageFlowDetail id="_ziwiYDjlEeCeRNBOZebDZA" moduleName="/PageflowSolution/Process Packages/ProcessPackage.xpdl" moduleVersion="1.0.0.201108111516" name="RequestAdditionalDataPageflow" url="PageflowSolution/.bpm/.processOut/pageflow/ProcessPackage.xpdl/Re questAdditionalDataPageflow.bpel" xmlns=""> <page-activity id="__Hoo4DjnEeCeRNBOZebDZA" name="Gettheusersemailaddress" xmlns="http://service.archive.wp.n2.tibco.com"> <page-reference guid="" name="Gettheusersemailaddress.gwt.json" version="1.0.0.201108111516"> <relative-path>1.0.0.201108111516/GIGWTPull_DefaultChannel/ProcessPack age/RequestAdditionalDataPageflow/Gettheusersemailaddress</relative-pa th> <base-path>http://localhost:8080/bpm</base-path> </page-reference> </page-activity> <page-activity id="_1mUqsDjnEeCeRNBOZebDZA" name="Gettheuserscellphonenumber" xmlns="http://service.archive.wp.n2.tibco.com"> <page-reference guid="" name="Gettheuserscellphonenumber.gwt.json" version="1.0.0.201108111516"> <relative-path>1.0.0.201108111516/GIGWTPull_DefaultChannel/.default/Pr ocessPackage/RequestAdditionalDataPageflow/Gettheuserscellphonenumber< /relative-path> <base-path>http://localhost:8080/bpm</base-path> </page-reference> </page-activity> <!-- Continued -->

TIBCO ActiveMatrix BPM - BPM Developers Guide

762

| Chapter 34

WorkPresentationService

<!-- Continued --> <page-activity id="_yMhV8DjqEeCeRNBOZebDZA" name="Asktheuserforasecurityquestion" xmlns="http://service.archive.wp.n2.tibco.com"> <page-reference guid="" name="Asktheuserforasecurityquestion.gwt.json" version="1.0.0.201108111516"> <relative-path>1.0.0.201108111516/GIGWTPull_DefaultChannel/.default/Pr ocessPackage/RequestAdditionalDataPageflow/Asktheuserforasecurityquest ion</relative-path> <base-path>http://localhost:8080/bpm</base-path> </page-reference> </page-activity> </pageFlowDetail> </workResponse> </SOAP-ENV:Body>

Service Connector API (Java Method)

Method Service openNextWorkItem (args) WorkPresentationService

TIBCO ActiveMatrix BPM - BPM Developers Guide

getBusinessServiceDetailsByModule 763

getBusinessServiceDetailsByModule
Retrieves all the information about the business service as requested by a module. The request must specify the module name and version, and the process name for the business service whose details are to be retrieved. The response returns details about the business service for the specified module.

Required System Action None.

TIBCO ActiveMatrix BPM - BPM Developers Guide

764

| Chapter 34

WorkPresentationService

Web Service API (SOAP Operation)

Request Parameter notes Uses the businessServiceDetailsRequest element (from the WorkPresentationService schema) Response Example moduleName: module name of the business service whose details are being requested. processName: the business service process name whose details are being requested. moduleVersion: module version of the business service whose details are being requested. The values of these parameters can be obtained from the response of the startBusinessService or updateBusinessService operations.

Returns an businessServiceDetailsResponse element (from the WorkPresentationServices schema) Request:

<soapenv:Body> <api:businessServiceDetailsRequest> <moduleName>/SanityProcesses/Sanity Tests/SanityTests.xpdl</moduleName> <processName>SanityTestsStartEvent</processName> <!--Optional:--> <moduleVersion>1.0.0.201108021442</moduleVersion> </api:businessServiceDetailsRequest> </soapenv:Body>

Response:
<SOAP-ENV:Body> <businessServiceDetailsResponse id="_PY_jILHTEd-8rbpgFImPHQ" moduleName="/SanityProcesses/Sanity Tests/SanityTests.xpdl" moduleVersion="1.0.0.201108021442" name="SanityTestsStartEvent" url="SanityProcesses/.bpm/.processOut/pageflow/SanityTests.xpdl/Sanity TestsStartEvent.bpel" xmlns="http://api.wp.n2.tibco.com"> <page-activity id="_Ptjd4rHTEd-8rbpgFImPHQ" name="UserTask" xmlns="http://service.archive.wp.n2.tibco.com"> <page-reference guid="" name="UserTask.gwt.json" version="1.0.0.201108021442"> <relative-path>1.0.0.201108021442/openspaceGWTPull_DefaultChannel/.def ault/SanityTests/SanityTestsStartEvent/UserTask</relative-path> <base-path>http://localhost:8080/bpm</base-path> </page-reference> </page-activity> </businessServiceDetailsResponse> </SOAP-ENV:Body>

TIBCO ActiveMatrix BPM - BPM Developers Guide

getBusinessServiceDetailsByModule 765

Service Connector API (Java Method)

Method Service getBusinessServiceDetailsByModule (args) WorkPresentationService

TIBCO ActiveMatrix BPM - BPM Developers Guide

766

| Chapter 34

WorkPresentationService

TIBCO ActiveMatrix BPM - BPM Developers Guide

System Actions Reference 767

Appendix A

System Actions Reference

This appendix contains reference information that you may need when using the TIBCO ActiveMatrix BPM API and system actions.

Topics
System Actions, page 768

TIBCO ActiveMatrix BPM - BPM Developers Guide

768

| Appendix A

System Actions Reference

System Actions
Table 4 lists the names, parent components and default value of all defined system actions. In the table: Name is the name of the system action. Required to execute lists the web service operations (and Service Connector methods, which use the same names) that require the system action. Component identifies the BPM component that owns this system action: BRM - Business Resource Management DE - Directory Engine EC - Event Collector PE - Process Manager WSB - Workspace Default value is the system-wide default value applied to this system action: Allowed - The system action can be performed by any user without authorization. Denied - The system action cannot be performed by any user unless they have the correct authorization. Both the component and the system action name must be specified when using certain Directory Services API SecurityService operations (for example, listActionAuthorisedEntities and listAuthorisedOrgs). Table 4 System action names and components System action applicationConfiguration autoOpenNextWorkItem Required to execute Not currently used setOrgEntityConfigAttributes deleteOrgEntityConfigAttributes1 Component WSB BRM Default value Denied Allowed

TIBCO ActiveMatrix BPM - BPM Developers Guide

System Actions 769

Table 4 System action names and components System action browseModel Required to execute listModelVersions openOrgModel browseModelNode listOrgModelOverview listCapabilities listPrivileges getCapabilities getPrivileges listOrganizations cancelProcessInstance cancelProcessInstances Not currently used by any public API closeWorkItem2 mapEntities getResourceGuid deleteLDAPContainer deleteResource exportResources getMigrationPoints setMigrationRules unsetMigrationRules clearMigrationRules isSetMigrationRule listMigrationRules importResources Component DE Default value Allowed

cancelProcessInstance cancelWorkItem closeOtherResourcesItems createResourceAdmin deleteLDAPAdmin deleteResourceAdmin exportLDAPAdmin handleProcessMigration

PE BRM BRM DE DE DE DE PE

Denied Allowed Denied Denied Denied Denied Denied Denied

importLDAPAdmin

DE

Denied

TIBCO ActiveMatrix BPM - BPM Developers Guide

770

| Appendix A

System Actions Reference

Table 4 System action names and components System action LDAPAdmin3 Required to execute listLDAPSources, listLDAPEntities, listLDAPAttributes, listLDAPAttributeNames, listContainerResources listLDAPContainers getLDAPContainerDetail saveLDAPContainerDetail Not currently used openWorkItem4 Not currently used n/a pendWorkItem n/a6 getActivityInstanceStatus getParameterValue getActivityInstanceStatus getProcessInstanceStatus getProcessInstanceSummary listProcessInstanceAttributes listSetofProcessInstanceAttributes listProcessInstances queryDone queryFirstPage queryLastPage queryNextPage queryPreviousPage queryProcessInstanceCount queryProcessInstances queryProcessInstancesAlt Component DE Default value Denied

listProcessTemplateAuditTrail openOtherResourcesItems openWorkItemAuditTrail organizationAdmin5 pendWorkItem purgeProcessInstances queryProcessInstance

EC BRM EC DE BRM PE PE

Allowed Denied Allowed Denied Allowed Denied Allowed

TIBCO ActiveMatrix BPM - BPM Developers Guide

System Actions 771

Table 4 System action names and components System action queryProcessTemplate Required to execute listProcessTemplateAttributes listProcessTemplates queryProcessTemplateCount queryProcessTemplates queryProcessTemplatesAlt listStarterOperations getStarterOperationInfo listBusinessParameters getBusinessParameters getPushDestinations reallocateWorkItem7 reallocateWorkItemData reallocateWorkItem4 reallocateWorkItemData getResourceDetail listAssociatedResources lookupUser listLDAPEntities listContainerResources listLDAPContainers getResourceDetail listAssociatedResources lookupUser listMappedEntities updateCapabilityAssignments resumeProcessInstance resumeProcessInstances Not currently used by any public API setDeadlineExpiration setPriority Component PE Default value Allowed

readParameters readPushDestinations reallocateToOfferSet reallocateWorkItemToWorld resolveResource

DE DE BRM BRM DE

Allowed Allowed Denied Denied Allowed

resourceAdmin

DE

Denied

resumeProcessInstance scheduleWorkItem setDeadlineExpiration setPriority

PE BRM PE PE

Denied Allowed Denied Denied

TIBCO ActiveMatrix BPM - BPM Developers Guide

772

| Appendix A

System Actions Reference

Table 4 System action names and components System action setResourceOrderFilterCriteria8 showProcessInstanceAuditTrail skipWorkItem startBusinessService startprocess suspendProcessInstance suspendWorkItem userAdmin9 Required to execute getResourceOrderFilterCriteria setResourceOrderFilterCriteria Not currently used skipWorkItem startBusinessService createProcessInstance suspendProcessInstance suspendProcessInstances Not currently used by any public API saveUserSettings getUserSettings deleteUserSettings listUserSettingIds getWorkListItems getAllocatedWorkListItems allocateWorkItem allocateAndOpenWorkItem allocateAndOpenNextWorkItem unallocateWorkItem setBusinessParameters setPushDestinations Component BRM EC BRM WSB PE PE BRM DE Default value Denied Allowed Denied Allowed Allowed Denied Allowed Allowed

viewWorkList workItemAllocation

BRM BRM

Denied Denied

writeParameters writePushDestinations

DE DE

Allowed Denied

1. This system action is required only if you are using these operations to set or to delete the WorkItemAutoOpen attribute. 2. This system action is required only when closing a work item allocated to another user. 3. For certain ContainerService and LDAPService operations, this system action gives the caller access to all organizations, regardless the organization relationships that are set up. For more information, see Overriding Organization Relationships on page 124. 4. This system action is required only when opening a work item allocated to another user.

TIBCO ActiveMatrix BPM - BPM Developers Guide

System Actions 773

5. This system action is not required to execute any web service operations. It is used to override organization relationships when calling BrowseModelService operations. Users possessing this system action can see all organizations when calling BrowseModelService operations that return organization elements, regardless the organization relationships that are set up. For more information, see Overriding Organization Relationships on page 124. 6. Completed process instances are automatically purged from the system. 7. The reallocateWorkItem and reallocateWorkItemData operations allow you to reallocate work items to users in the original offer set if you have the reallocateToOfferSet system action, or to any user in the organization model if you have the reallocateWorkItemToWorld system action. 8. Only the setResourceOrderFilterCriteria system action at the organization model level is used; the scoped setResourceOrderFilterCriteria system action (i.e., the one at the group, organization unit, and position level) is not currently used. 9. Note that the userAdmin system action appears as "User Settings" in TIBCO Business Studio, rather than "User Admin". When passed in web service operations or Service Connector method calls, pass "userAdmin".

Scope of System Actions

When system actions are configured in the organization model using TIBCO Business Studio, they can be configured at two levels: Organization model level - Most system actions are configured at this level. They control access to most functions in the application, based on privileges held by the logged-in user. For more information, see System Actions at the Organization Model Level on page 773. Group, organization unit, or position level - There are also a number of system actions that are scoped, that is, they can be set on specific groups, organization units, or positions. The scoped system actions are specifically used to control access to, and functions from, supervised work lists. Supervised work lists are lists containing work items that were sent to another resource, or directly to a group or position. For more information, see System Actions at the Group, Organization Unit, and Position Level on page 774. System Actions at the Organization Model Level System actions at this level control access to most functions in the application, based on privileges held by the logged-in user.

TIBCO ActiveMatrix BPM - BPM Developers Guide

774

| Appendix A

System Actions Reference

System actions at the organization model level are defined in TIBCO Business Studio by selecting the organization model, then associating a privilege to the appropriate system action. In the following example of system actions configured at the organization model level, users that have the "Acct Super" privilege can cancel work items.

At the organization model level, some system actions are granted to all users by default (those that contain "Available to all users" in the Value column), and some are denied by default (those that have an empty Value column). If a privilege has been assigned to a system action (such as the Cancel Work Item system action), it overrides the default; that is, once a privilege is assigned to a system action, only users that have that privilege can perform the associated function (such as cancelling work items). System Actions at the Group, Organization Unit, and Position Level To be able to view work items in, and perform some functions on, a work list containing work items that were sent to another resource, or directly to a group or position, you must have the appropriate scoped system actions, that is, system actions configured on an individual group, organization unit, or position.

TIBCO ActiveMatrix BPM - BPM Developers Guide

System Actions 775

System actions at the group, organization unit, and position level are defined in TIBCO Business Studio by selecting the group, organization unit, or position, then associating a privilege with the appropriate scoped system action:

Note that although there are seven scoped system actions available in TIBCO Business Studio, only the following ones are used at this time: BRM.viewWorkList - Controls access to supervised work lists: To view a supervised work list for an organizational entity, you must possess the privilege assigned to the system action, BRM.viewWorkList, on the group, organization unit, or position. To view a supervised work list for an individual resource, you must possess the privilege assigned to the system action, BRM.viewWorkList, on a specific position to which the resource has been mapped This is further explained in Viewing Supervised Work Lists on page 776. BRM.closeOtherResourcesItems - Controls whether you can cancel a work item in a supervised work list. BRM.reallocateToOfferSet - Controls whether you can allocate a work item, in a supervised work list, to a specific person in the original offer set. By default this system action is available at the organization model level. You can also define this system action as scoped at position level. You can use the scoped system action with the allocateAndOpenNextWorkItem operation, for example. BRM.reallocateWorkItemToWorld - By default this system action is available at the organization model level; use it at that level to also control access to the allocate to "world" function (see allocateWorkItem) from a supervised work list.

TIBCO ActiveMatrix BPM - BPM Developers Guide

776

| Appendix A

System Actions Reference

You can also define this system action as scoped at position level. You can use the scoped system action with the allocateAndOpenNextWorkItem operation, for example. The scoped system actions available in TIBCO Business Studio that are not currently used in the application are: BRM.setResourceOrderFilterCriteria BRM.openOtherResourcesItems (You cannot open another resources work items from a supervised work list.) BRM.workItemAllocation (This system action is available at the organization model level; use that one to also control access to the allocate work items function (see allocateWorkItem) on a supervised work list.)

Viewing Supervised Work Lists The primary use of the scoped system actions are for controlling the ability to view supervised work lists. A few of the other system actions available at the organizational entity-level control access to functions from a supervised work list. This section describes what is necessary to set up system actions to be able to view a supervised work list. When a supervised work list is requested with the getWorkListItems operation, you can request that it contain either: Work items sent to an organizational entity - This type of supervised work list only contains work items that were sent directly to the specified organizational entity. To be able to get this type of supervised work list: A privilege must be assigned to the BRM.viewWorkList system action for the group, organization unit, or position for which you want to supervise, and you must possess the privilege (and possible qualifier) assigned to the scoped BRM.viewWorkList system action for the organizational entity you want to supervise (you gain the privilege by being mapped to a group or position that gives you that privilege).

TIBCO ActiveMatrix BPM - BPM Developers Guide

System Actions 777

In the following example, the Claims Handling organization units scoped "View Work List" system action has a privilege assigned:

In this example, a logged-in user who possesses the "Manage Work" privilege, can view a supervised work list for the Claims Handling organization unit. Note - The checking for needed system actions is hierarchicalfor more information, see System Action Hierarchy on page 778. Work items for an individual resource - This type of supervised work list contains all of the work items that are currently in that resources work list. To be able to view this type of supervised work list: A privilege must be assigned to the BRM.viewWorkList system action for a specific position to which the desired resource is mapped, you must possess the privilege (and possible qualifier) assigned to the scoped BRM.viewWorkList system action for the position (you gain the privilege by being mapped to a group or position that gives you that privilege).

TIBCO ActiveMatrix BPM - BPM Developers Guide

778

| Appendix A

System Actions Reference

In the following example, a privilege has been assigned to the "View Work List" (BRM.viewWorkList) scoped system action on the Claims Handler position:

This allows a user who has the "Manage Work" privilege, with a qualifier of "Claims", to get a supervised work list for a user who has been mapped to the Claims Handler position. Note - The checking for needed system actions is hierarchicalfor more information, see System Action Hierarchy on page 778. System Action Hierarchy The checking of system actions is hierarchical. If different privileges are assigned to the same system action (e.g., BRM.viewWorkList) at different levels in the organization model, each level is checked when determining whether a user has the necessary privilege to be able to perform a particular system action. If the lowest level has no required privileges assigned, the parent entity is checked, and so on up the organization model hierarchy to the system-wide, organization model-level value.

TIBCO ActiveMatrix BPM - BPM Developers Guide

System Actions 779

For example, in the following diagram the "View work list" system action has been associated with three different privileges, "X", "Y" and "Z", at three different levelsthe organization model, organization unit A, and position 2.

This means that a user who holds privilege "X", "Y" or "Z" can view a supervised work list: for either Position 2 or Organization Unit A, or for individual resources that have been mapped to Position 2.

If a user wants to view the work list of a user who holds Position 1, they must hold privilege "X" or "Y". This is because no privilege has been associated with Position 1, so any privileges associated with the parent entity are used instead. If privilege "Y" had not been associated with Organization Unit A, the user would instead need privilege "X", defined in the parent Organization Model. As well as assigning different privileges at different levels, as shown above, qualifiers on the same privilege can be used to refine how access to a particular system action is controlled. (When comparing a required privilege to a held privilege, if either side is not qualified the comparison is positive. If both sides are qualified, the qualifications must match for the comparison to be positive.) For more information about system actions, see the BPM Concepts guide.

TIBCO ActiveMatrix BPM - BPM Developers Guide

780

| Appendix A

System Actions Reference

TIBCO ActiveMatrix BPM - BPM Developers Guide

TIBCO Forms Reference 781

Appendix B

TIBCO Forms Reference

This appendix contains reference information that you may need when using TIBCO forms with custom client applications.

Topics
Integrating TIBCO Forms with Custom Client Applications, page 782

TIBCO ActiveMatrix BPM - BPM Developers Guide

782

| Appendix B

TIBCO Forms Reference

Integrating TIBCO Forms with Custom Client Applications

TIBCO forms are a part of TIBCO ActiveMatrix BPM projects which are deployed to the BPM runtime. Forms are typically accessed by one of the pre-defined client applications shipped with TIBCO ActiveMatrix BPM: Openspace or Workspace. Alternatively, users can develop their own custom web client applications and embed TIBCO forms within them. The key top-level components that are involved in making TIBCO forms accessible from custom client applications are as follows: BPM Resources component - This is a component provided by the BPM runtime. This component fulfills two functions: First, it provides access to the Forms Runtime Adapter. This is a JavaScript API that client applications can load in the browser and use to render forms in their applications. See Injecting the Forms Runtime Adapter in the Browser to know about loading the forms runtime adapter. Second, this component provides access to the form resources of BPM applications deployed by the user. Each form that is deployed makes use of a number of resources including: the form definition, CSS, resource bundles for localization, and JavaScript files that provide form actions as well as implementations of Business Object Model objects referenced by the form. BPM public web service API - BPM exposes its functionality through comprehensive work management and process management APIs, which are exposed as web services. The main services that are used in the form applications are: WorkPresentationService, PageFlowService, and BusinessService. A client application can access the web services using either the BPM public web service API or the Java Service Connector API. Client Application - The client application is typically a web application that bundles together the non-Form UI resources that are used by the application, and a controller servlet that acts as the conduit between the browser and the BPM public web service API.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Integrating TIBCO Forms with Custom Client Applications 783

Injecting the Forms Runtime Adapter in the Browser

The Forms Runtime Adapter is hosted by the BPM runtime. To use this, you first need to load the Forms Runtime Adapter file in the page. This is typically done via a <script> tag in the <head> section of the HTML document.
<script src=http://<host-name>:<port>/bpmresources/formsclient /formsclient.nocache.js/>

See Rendering a TIBCO Business Studio Form for more information. Once the JavaScript API loading is complete, it notifies the client application by invoking a function called onTIBCOFormRunnerLoad. The client application can define this function on the page and get notified about the availability of com.tibco.forms.client.FormRunner. For example:
function onTIBCOFormRunnerLoad() { // Forms Runtime Adapter is now available for use on the page. // com.tibco.forms.client.FormRunner.loadForm() can be accessed from now on // to load the form. }

Typical flow of events

The following figure illustrates of the typical flow of events when a user opens a work item from the work list displayed in the browser of the custom client application:

TIBCO ActiveMatrix BPM - BPM Developers Guide

784

| Appendix B

TIBCO Forms Reference

Browser-based application Browser BPM Resources Client application Work presentation Services

Work list is displayed 1 User opens a work item 2 Client invokes Forms Runtime Adapter to render the form openWork Item [formUrl, formData] WorkPresentation Service

Form is displayed

User clicks Submit button 4 -or-

Forms Runtime Adapter submits the form data and notifies the client of the Submit action

completeWork Item

WorkPresentation Service

User clicks Close button 4 -orUser clicks Cancel button 4

Forms Runtime Adapter submits the form data and notifies the client of the Close action

-or-

closeWorkItem -or-

WorkPresentation Service

Forms Runtime Adapter submits the form data and notifies the client of the Cancel action 5

cancelWork Item

WorkPresentation Service

[success]

TIBCO ActiveMatrix BPM - BPM Developers Guide

Integrating TIBCO Forms with Custom Client Applications 785

The details of the events are as follows: 1. To open a work item, the client application invokes the BPM WorkPresentationService via a Java service connector. The openWorkItem() operation is used to open the work item. 2. In response to the openWorkItem() request, the formUrl and formData are returned to the client application. The client application decides the locale for rendering the form and provides the identifier of the DOM node under which the form will be rendered. The channelId is the identifier of the presentation channel to which the client application is bound, e.g. GIGWTPull_DefaultChannel or openspaceGWTPull_DefaultChannel. See Binding the Client Application to a Channel for more information. The client application invokes the FormRunner.loadForm() method, which accepts the above values along with two arguments - onSuccess and onError. See com.tibco.forms.client.FormRunner for details of the FormRunner.loadForm() method.

TIBCO ActiveMatrix BPM - BPM Developers Guide

786

| Appendix B

TIBCO Forms Reference

The following code snippet shows how the form is loaded using the FormRunner.loadForm() method.
var formURL; // Form URL obtained from the work item. var formData; // The initial form data obtained from the work item. var bomJSPath; // BOM JavaScript root path obtained from the workitem. var locale = "en_US"; // locale to use var parentId; // Identifier of a node to which the form is added. var submitHandler = function(actionName, form) { var formData = form.getSerializedParameters(); // submit the work item form.destroy(); }; var closeHandler = function(actionName, form) { // close the work item form.destroy(); }; var cancelHandler = function(actionName, form) { // cancel the work item form.destroy(); }; var onSuccess = function(form) { form.setActionHandler(com.tibco.forms.client.Form .ACTION_SUBMIT, submitHandler); form.setActionHandler(com.tibco.forms.client.Form .ACTION_CLOSE, closeHandler); form.setActionHandler(com.tibco.forms.client.Form .ACTION_CANCEL, cancelHandler); }; var onError = function(e) { alert("An error occurred while loading the form: "+ e); }; com.tibco.forms.client.FormRunner.loadForm(formURL, formData, bomJSPath, locale, parentId, onSuccess, onError, JSONP);

TIBCO ActiveMatrix BPM - BPM Developers Guide

Integrating TIBCO Forms with Custom Client Applications 787

It is not recommended to use the method on the page event, as the com.tibco.forms.client.FormRunner class might not be fully loaded and the API methods being used might not be available. To avoid these errors, the client application can define the onTIBCOFormRunnerLoad function on the page and can be notified about the availability of com.tibco.forms.client.FormRunner. See Injecting the Forms Runtime Adapter in the Browser for further details.
com.tibco.forms.client.FormRunner.loadForm() onLoad

3. The form is displayed in the browser. The FormRunner.loadForm() method is asynchronous, so any post-processing that is done on the loaded form object happens within the onSuccess callback handler. In the above code snippet, three action handlers are set that take care of the submit, close, and cancel operations that are provided on most forms. 4. When the form is submitted, the submitHandler handles the submit action. In response to form submission, form.getSerializedParameters() method retrieves the formData. See com.tibco.forms.client.Form for details of the form.getSerializedParameters() method. This method returns a JSON (JavaScript Object Notation) serialization of the data within the form. 5. After successful submission of the form, the client application invokes completeWorkItem() to pass the form data back to the BPM WorkPresentationService. This operation is used to update the work item.

Forms Runtime Adapter

The Forms Runtime Adapter defines the following three classes: 1. com.tibco.forms.client.FormRunner 2. com.tibco.forms.client.Form 3. com.tibco.forms.client.LoadStat This section provides the details of fields and methods supported by these classes. com.tibco.forms.client.FormRunner The com.tibco.forms.client.FormRunner class provides static utility methods for instantiating the Form class in the custom client application. The following two methods are supported:
1. loadForm() 2. loadFormWithRemoteData()

These methods have the same set of input parameters but they differ in the way the initial data are passed. Both the methods are void.
TIBCO ActiveMatrix BPM - BPM Developers Guide

788

| Appendix B

TIBCO Forms Reference

In loadForm(), the initial data are passed directly as a JSON (JavaScript Object Notation) string. In loadFormWithRemoteData(), a URL of the initial JSON data is passed using the initDataURL parameter. The FormRunner retrieves the data from the specified URL.

The details of these methods are as follows:

TIBCO ActiveMatrix BPM - BPM Developers Guide

Integrating TIBCO Forms with Custom Client Applications 789

Table 5 com.tibco.forms.client.FormRunner Class Method

loadForm( String url, String initialData, String bomJSPath, String locale, String parentNodeId, Function onSuccess, Function onError, Boolean JSONP)

Description Loads the form at the specified URL. The parameter details are as follows:
url

- Specifies the URL to the form JSON representation, e.g. "http://10.97.110.17:8080/bpmresources/1.0.0.2011072914

35/openspaceGWTPull_DefaultChannel/FindAddress/GetAddre ss/Getuserdetails/Getuserdetails.gwt.json"

initialData

- Specifies the JSON representation of the initial data that are provided to the form.

bomJSPath - Specifies the root folder path used for loading the BOM JavaScript files used by the form, e.g. "http://10.97.110.17:8080/bpmresources/1.0.0.2011072914 35" locale - Specifies the locale to be used in the form runtime with format <lc>[_<CC>] where [] denotes optionality, e.g. "en_US". The locale needs to be represented such that <lc> is a valid two-character lowercase ISO-639 language code and if present the optional <CC> is a valid two-character uppercase ISO-3166 country code. Both '_' and '-' are supported as delimiters. parentNodeId

- Specifies the DOM identifier of the node to which the form is added. The value cannot be null.

onSuccess - A function that is called once the form is successfully initialized. The Form object is passed into this function. This function can be used to add custom callback handlers that implement lifecycle events such as submit, close, and cancel. onError

- A function that is called if any errors are encountered in initializing the form. The function will receive any exception that was encountered during the initialization.

JSONP - Informs the Forms Runtime Adapter to use JSON with Padding (JSONP) when loading JSON resources. The default value is false. When the custom client and Forms Runtime Adapter are hosted on different servers, set the JSONP parameter as true. In this scenario, there are SOP (Single Origin Policy) issues while loading JSON resources. By using the JSONP technique, the JSON response is wrapped to a call to a function by the server and send to the client. A JSON resource can then be loaded using a script tag to avoid any SOP violations.

TIBCO ActiveMatrix BPM - BPM Developers Guide

790

| Appendix B
Method

TIBCO Forms Reference

Description Loads the form at the specified URL. The parameter details are as follows:
url

loadFormWithRemoteDat a(String url, String initDataURL, String bomJSPath, String locale, String parentNodeId, Function onSuccess, Function onError, Boolean JSONP)

- Specifies the URL to the form JSON representation, e.g. "http://10.97.110.17:8080/bpmresources/1.0.0.2011072914

35/openspaceGWTPull_DefaultChannel/FindAddress/GetAddre ss/Getuserdetails/Getuserdetails.gwt.json".

initDataURL

- Specifies the URL to the form initial data.

bomJSPath - Specifies the root folder path used for loading the BOM JavaScript files used by the form, e.g. "http://10.97.110.17:8080/bpmresources/1.0.0.2011072914 35" locale - Specifies the locale to be used in the form runtime with format <lc>[_<CC>] where [] denotes optionality, e.g. "en_US". The locale need to be represented such that <lc> is a valid two-character lowercase ISO-639 language code and if present the optional <CC> is a valid two-character uppercase ISO-3166 country code. Both '_' and '-' are supported as delimiters. parentNodeId

- Specifies the DOM identifier of the node to which the form should be added. The value cannot be null.

onSuccess - A function that is called once the form is successfully initialized. The Form object is passed into this function. This can be used to add custom callback handlers that implement lifecycle events such as submit, close, and cancel. onError

- A function that is called if any errors are encountered in initializing the form. The function will receive any exception that was encountered during the initialization.

JSONP - Informs the Forms Runtime Adapter to use JSON with Padding (JSONP) when loading JSON resources. The default value is false. When the custom client and Forms Runtime Adapter are hosted on different servers, set the JSONP parameter as true. In this scenario, there are SOP (Single Origin Policy) issues while loading JSON resources. By using the JSONP technique, the JSON response is wrapped to a call to a function by the server and send to the client. A JSON resource can then be loaded using a script tag to avoid any SOP violations.

TIBCO ActiveMatrix BPM - BPM Developers Guide

Integrating TIBCO Forms with Custom Client Applications 791

For the list of language codes and country codes required for specifying the locale parameter, visit the following web sites: List of language codes http://www.loc.gov/standards/iso639-2/langhome.html List of country codeshttp://www.iso.org/iso/country_codes/iso_3166_code_lists.htm com.tibco.forms.client.Form The com.tibco.forms.client.Form class provides access to the runtime form object. This object enables you to access panes and controls within the form, register handlers for form actions, and access data to be submitted back to the server. The com.tibco.forms.client.Form class has six fields which are used for setting action handlers. It also implements six methods. The details of the fields and methods are as follows: Table 6 com.tibco.forms.client.Form Class - Field Details Field
ACTION_APPLY ACTION_CANCEL ACTION_CLOSE ACTION_RESET ACTION_SUBMIT ACTION_VALIDATE

Data Type String String String String String String

Description Identifies the "apply" action. Identifies the "cancel" action. Identifies the "close" action. Identifies the "reset" action. Identifies the "submit" action. Identifies the "validate" action.

Table 7 com.tibco.forms.client.Form Class - Method Details Method

destroy()

Return Value Void

Description Removes the form from its container and also releases its resources. This can be called by the client application to close the form.

TIBCO ActiveMatrix BPM - BPM Developers Guide

792

| Appendix B
Method

TIBCO Forms Reference

Return Value LoadStat

Description Returns an array of LoadStat objects. Each statistic represents the measurement of a particular phase of the form load. This can be used by applications to report this information in the user interface or otherwise log the information. To enable collecting load statistics at runtime, the URL used by the client application to load the form should contain the parameter tibco_instr with a value true. Otherwise getLoadStats() method would return an empty array. To use getLoadStats() method, the client application needs to subscribe to PageBus event 'com.tibco.forms.form.loaded'. See com.tibco.forms.client.LoadStat for more details.

getLoadStats()

getLocale()

String String

Returns the string representation of the locale being used to render the form. Returns a JSON representation of the data being managed by the form. This is typically called from a submit handler in order to send the final results back to the server.

getSerializedParameters ()

TIBCO ActiveMatrix BPM - BPM Developers Guide

Integrating TIBCO Forms with Custom Client Applications 793

Method
setActionHandler( String actionName, Function handler)

Return Value Void

Description Adds a handler to the form that is invoked when the specified action is invoked in the form. Note that any handler already registered for this action will be replaced by this handler. The parameter details are as follows:
actionName - Used to specify the name of the action (e.g. ACTION_CLOSE). If the action is ACTION_SUBMIT, then all the validations in the form will be invoked prior to invoking the callback handlers. If any of the validations fail, then the callback handler will not be invoked. handler - This is the function that is invoked for the specified actionName. The form may have only one handler for each action. If this method is called more than once for the same actionName, the handler set previously will be replaced. Passing in null for this parameter will remove the handler for this particular action. The method signature of the handler function has two arguments: a string for the actionName and the form object.

setLocale(String locale)

Void

Sets the string representation of the locale currently being used to render the form, e.g. "en" or "en_US".

com.tibco.forms.client.LoadStat The com.tibco.forms.client.LoadStat class helps you to measure the load-time performance of the form. Each statistic has three fields: a description, a start time, and an end time. The times are measured in milliseconds from when the form load began. To use com.tibco.forms.client.LoadStat, the form loading has to be complete, including data loading and invocation of form open rules. The TIBCO PageBus event 'com.tibco.forms.form.loaded' is published when the form loading is complete. The client application needs to subscribe to this event in order to be notified that the form loading is complete and then use the getLoadStats() method.

TIBCO ActiveMatrix BPM - BPM Developers Guide

794

| Appendix B

TIBCO Forms Reference

For example:
var callback = function(subject, form) { var stat = form.getLoadStats(); for (var i=0; i<stat.length; i++) { alert(stat[i].label+" |End Time : " + stat[i].endTime+" | Begin Time : " + stat[i].startTime); } } PageBus.subscribe('com.tibco.forms.form.loaded', null,callback);

The details of the fields are as follows: Table 8 com.tibco.forms.client.LoadStat Class - Field Details Field
label

Data Type String Number

Description Describes what is being measured by this particular loadstat. The time, in milliseconds, when this particular measurement phase began. This time is relative to the instant when the form load began. The time, in milliseconds, when this particular measurement phase ended. This time is relative to the instant when the form load began.

startTime

endTime

Number

TIBCO ActiveMatrix BPM - BPM Developers Guide