Business Process Management API Development

 

This section provides an overview of application development using the business process management (BPM) API. It includes the following topics:

• Introduction

• WebLogic Integration Process Engine

• BPM API

• BPM Application Development Tasks

• BPM API Examples

 

---

Introduction

To support business process management (BPM), WebLogic Integration provides the following components:

• Process engine—BPM server

• WebLogic Integration Studio—Design client

• Worklist—Run-time management client

These components make up the basic BPM framework for designing, executing, and monitoring business processes, and administering related data with WebLogic Integration.

In addition to using these design and run-time management clients, you can create custom clients to manage your business processes, and/or enhance the existing set of user interface features using the BPM application programming interface (API).

This document describes how to use the BPM API to create custom configuration, design, run-time management, and monitoring clients. For more information about the API, see the BEA WebLogic Integration Javadoc.

Note: For an overview of the business process model, and details about using the Studio client interface to administer, design, and monitor business processes, see Using the WebLogic Integration Studio.

For details about using the Worklist client interface to execute business processes, see Using the WebLogic Integration Worklist.

 

---

WebLogic Integration Process Engine

The following figure illustrates the BPM processing model.

Figure 1-1 BPM Processing Model

 

Note: For a complete description of the BPM processing model, see Using the WebLogic Integration Studio.

Note that the BPM processing model depends on the WebLogic Integration process engine, which serves as the controller for run-time instances, managing their execution and monitoring their progress.

In the previous figure, the left column lists the methods through which you can start (or instantiate) a business process or interact with an existing business process: in response to an XML event, as a time-based event, through a manual call, through a call from another business process, or through a plug-in interface.

The right column lists the entities that can be integrated into a business process: JMS application, EJB component, Java class, or another application.

The database store, shown at the bottom of the figure, stores templates, template definitions, and run-time instances. You can create templates and template definitions, and monitor run-time instances using the Studio or a custom design client.

WebLogic Server Infrastructure

The WebLogic Integration process engine runs on BEA WebLogic Server and takes advantage of the Java 2 Platform, Enterprise Edition (J2EE) services listed in the following table. For more information about WebLogic Server services, see Introduction to BEA WebLogic Server, in the BEA WebLogic Server document set, available at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs61/intro/index.html

Table 1-1 WebLogic Server Services Used by BPM

Service	Description
Enterprise JavaBean (EJB)	Provides lifecycle management and services such as caching, persistence, and transaction management. The process engine consists of a combination of session and entity EJBs. For more information, see Process Engine Component Architecture. In addition, message-driven beans are used for providing asynchronous messaging services.
Security Realm	Supports security interfaces including principals, groups, ACLs, and permissions. The process engine builds on the WebLogic Server security realm. Roles defined in the Studio map to WebLogic Server security groups, and users, to WebLogic Server users.
Web server	Supports Web browsers and other custom design and run-time management clients that use HTTP, servlets, and JSPs.
Java Naming and Directory Service (JNDI)	Supports directory service functionality.
Java Database Connectivity (JDBC)	Supports Java database connectivity and persistence. The process engine uses JDBC for persisting data.
Messaging	Implements the Java Message Service (JMS), including the transmission of XML content. The process engine uses JMS for communicating worklist, time, and event notifications, and error and audit messages. For more information, see Establishing JMS Connections.
Clustering	Supports scalability and high-availability by grouping multiple servers together in a way that is transparent to application developers and end users. The process engine takes advantage of clustering. To ensure data integrity and idempotence, you specify a unique transaction ID, as described in the context of the applicable methods later in this document.
Time Services	Builds on the services provided by WebLogic Server to support timed events and other timer-based activities.

 

Process Engine Component Architecture

The WebLogic Integration process engine consists of the following components:

• Twelve session EJBs

• Eleven entity EJBs

• Two startup classes: TimeProcessor and WLPIInit

• Four message-driven beans: EventQueue, InitListener, TimeListener, and TopicRouter

The architecture of the process engine, including client and JMS interactions, is illustrated in the following figure.

Figure 1-2 Process Engine Component Architecture

 

Note the following in the previous figure:

• The process engine manages the design, administration, and execution of a business process.

• The Admin and Worklist session EJBs are the primary interfaces for design and run-time management clients, respectively.

• The WorkflowProcessor session EJB provides the main interface to the process engine. (It is not part of the BPM API.)

• The Audit session EJB manages the audit, trace, and error messages.

• The EventQueue message-driven bean manages XML events.

• The TopicRouter message-driven bean is supported for backward compatibility with pre-2.0 releases of the BEA WebLogic Process Integrator product: it reroutes all messages sent to the wlpiEvent JMS topic, which is not supported by the process engine (as of BEA WebLogic Process Integrator Release 2.0), to the EventQueue message-driven bean.

• The TimeProcessor startup class and TimeListener message-driven bean manage timed events.

• The WLPIInit startup class and InitListener message-driven bean initialize the process engine.

• A number of Entity EJBs (BusinessOperation, EventKey, Template, and TemplateDefinition) maintain two implementations for performance purposes: a read-write implementation used during configuration and design, and a read-only implementation used during run time.

The following sections describe the process engine components in more detail.

Session EJBs

Session EJBs provide application services to clients upon request. The BPM session EJBs provide the primary interface to the process engine.

The following table summarizes the functions of the BPM session EJBs, which are accessible to client applications via the BPM API (except where noted). It also indicates whether each EJB is stateful or stateless.

Table 1-2 Session EJBs

Session EJB	Description	EJB Type
com.bea.wlpi.server.admin.Admin	Provides the primary interface for design clients, including Studio and custom design clients.	Stateful
com.bea.wlpi.server.audit.Audit	Sends audit and error output to WebLogic JMS.	Stateless
com.bea.wlpi.server.catalog.EJBCatalog	Catalogs EJBs deployed on WebLogic Server.	Stateful
com.bea.wlpi.server.idgenerator.IDGenerator1	Generates unique IDs for various WLPI system object classes. (For internal use only.)	Stateless
com.bea.wlpi.server.notify.Notifier1	Supports JMS queue and publishing services. (For internal use only.)	Stateless
com.bea.wlpi.server.permission.Permission	Supports getting and setting user and role permissions.	Stateless
com.bea.wlpi.server.plugin.PluginManager	Provides run-time management of plug-ins during workflow execution. For more information about programming BPM plug-ins, see Programming BPM Plug-Ins for WebLogic Integration.	Stateless
com.bea.wlpi.server.plugin.PluginManagerCfg	Provides configuration- and design-time support and management of plug-ins. For more information about programming BPM plug-ins, see Programming BPM Plug-Ins for WebLogic Integration.	Stateless
com.bea.wlpi.server.serverproperties.ServerProperties	Supplies the BPM server properties.	Stateless
com.bea.wlpi.server.principal.WLPIPrincipal	Links the process engine to WebLogic Server security realms.	Stateless
com.bea.wlpi.server.workflowprocessor.WorkflowProcessor1	Provides the main interface to the process engine.	Stateful
com.bea.wlpi.server.worklist.Worklist	Provides the primary interface for run-time management clients, including Worklist and custom run-time management clients.	Stateful
com.bea.eci.repository.ejb.XMLRepository	Provides access to the XML repository database.	Stateless

1 Not available to the BPM API.

 

Stateful session EJBs are available to a client for the duration of a session, until the client releases the resource.

Stateless session EJBs, on the other hand, are a shared commodity. That is, a particular EJB can be accessed by multiple clients; there is no guarantee that the same EJB will be used by the process engine to handle multiple method calls to the EJB. Stateless session EJBs facilitate clustering, as subsequent method calls can be handled by different instances of an EJB on one or more servers.

For more information about the session EJBs available via the BPM API, see BPM API.

Entity EJBs

Entity EJBs represent data objects and include state information.

The BPM entity EJBs are not accessible directly through the BPM API; however, the com.bea.wlpi.common package provides classes for obtaining state information. For more information about the com.bea.wlpi.common package, see Client/Server Common Package.

The following table describes the BPM entity EJBs.

Table 1-3 Entity EJBs

Entity EJB	Description
com.bea.wlpi.server.businesscalendar.BusinessCalendar	Defines business-oriented time calculations.
com.bea.wlpi.server.businessoperation.BusinessOperation[RO,RW]	Defines user-defined EJB or Java class actions. Two implementations of this EJB are maintained for performances purposes: a read-write implementation used during configuration and design, and a read-only implementation used during run time.
com.bea.wlpi.server.eventkey.EventKey[RO,RW]	Defines event key expressions for filtering events. Two implementations of this EJB are maintained for performances purposes: a read-write implementation used during configuration and design, and a read-only implementation used during run time.
com.bea.wlpi.server.reroute.Reroute	Defines task rerouting for users at predetermined time intervals.
com.bea.wlpi.server.template.Template[RO,RW]	Provides design-time representation of a workflow template. Used at run time to create a running instance. Two implementations of this EJB are maintained for performances purposes: a read-write implementation used during configuration and design, and a read-only implementation used during run time.
com.bea.wlpi.server.template.TemplateDefinition[RO,RW]	Provides design-time representation of a workflow template definition. Used at run time to create a running instance. Two implementations of this EJB are maintained for performances purposes: a read-write implementation used during configuration and design, and a read-only implementation used during run time.
com.bea.wlpi.server.instance.WorkflowInstance	Provides run-time representation of a workflow instance.

 

Startup Classes

The following table describes the BPM startup classes.

Table 1-4 Startup Classes

Startup Class	Description
com.bea.wlpi.server.timeprocessor.TimeProcessor	Manages timed events (wlpiTimer). Used with the TimeListener message-driven bean.
com.bea.wlpi.server.wlpiinit.WLPIInit	Initializes the BPM framework. Used with the InitListener message-driven bean.

 

Message-Driven Beans

The following table describes the BPM message-driven beans.

Table 1-5 Message-Driven Beans

Message-Driven Bean	Description
com.bea.wlpi.EventQueue	JMS destination for event messages.
com.bea.wlpi.server.initlistener.InitListener	Initializes the BPM framework. Used with the WLPIInit startup class.
com.bea.wlpi.server.timelistener.TimeListener	Manages timed events (wlpiTimer). Used with the TimeProcessor startup class.
com.bea.wlpi.server.topicrouter.TopicRouter	Supported for backward compatibility with the process engine provided in the BEA WebLogic Process Integrator product before Release 2.0. Reroutes all messages sent to the wlpiEvent JMS topic (for which support was dropped in WebLogic Process Integrator Release 2.0) to the EventQueue message-driven bean, which handles messages for the newly-supported EventQueue queue. For more information about the JMS queues and topics, see Establishing JMS Connections. Note: Although you are not required to do so, you may update your code to use the eventQueue JMS queue (com.bea.wlpi.EventQueue) in place of the wlpiEvent JMS topic to expedite the transmission of messages.

 

 

---

BPM API

The business process management (BPM) API consists of nine EJBs (summarized in the table Session EJBs) and the following seven packages:

• com.bea.wlpi.client.common

• com.bea.wlpi.client.util

• com.bea.wlpi.common

• com.bea.wlpi.common.plugin

• com.bea.wlpi.common.security

• com.bea.wlpi.util

• com.bea.eci.repository.helper

The IDGenerator, Notifier, and WorkflowProcessor EJBs are not included in the BPM API.

The API components are described in detail in the following sections. For additional information, see the BEA WebLogic Integration Javadoc. For information about interfacing with the API session EJBs, see Connecting to the Process Engine.

Admin Session EJB

The com.bea.wlpi.server.admin.Admin session EJB is a stateful EJB that serves as the primary interface for design clients, including the Studio and custom design clients.

Using the public methods provided by the Admin EJB, you can:

• Define templates and template definitions, and associated business operations

• Create business calendars and event keys, and reroute tasks

• Control the stages in the lifecycle of a task (assign, mark done, and so on)

• Get class descriptors, tasks, variables, instances, and statistics reports

• Import and export template definitions and complete workflow packages

Audit Session EJB

The com.bea.wlpi.server.audit.Audit session EJB is a stateless EJB that encapsulates a WebLogic JMS topic (wlpiAudit) to which the process engine sends audit and error messages on behalf of clients. The Audit EJB also encapsulates access to the wlpiError topic, to which error messages are sent. Users define audit entries via task actions when designing workflow template definitions, as described in Using the WebLogic Integration Studio.

Each audit message consists of an XML document that conforms to the format defined in the Audit DTD. For more information about the Audit DTD format, see Audit DTD or the BEA WebLogic Integration Javadoc.

Audit information (Info) and error (Error) messages are sent to the WebLogic Server log file, using the subsystem name WLPI.

For more information about setting up a JMS connection to the wlipAudit and wlpiError JMS topics, see Establishing JMS Connections.

EJBCatalog Session EJB

The com.bea.wlpi.server.catalog.EJBCatalog session EJB is a stateful EJB that classifies the EJBs deployed on a particular server. The EJBCatalog session EJB scans the JNDI tree, collects the EJB metadata, and stores it in a catalog. The EJBCatalog is used by design clients to define business operations.

Using the public methods provided by the EJBCatalog EJB, you can:

• List the JNDI names of all EJBs deployed on the WebLogic Server

• List the EJB metadata describing the internals of all EJBs installed on the WebLogic Server

• Set the root context in the WebLogic JNDI tree in which cataloging is to begin

• Specify whether the catalog should be regenerated with each listing request

Permission Session EJB

The com.bea.wlpi.server.permission.Permission session EJB is a stateless EJB that enables you to get and set security permissions pertaining to both role and user actions.

PluginManager Session EJB

The com.bea.wlpi.server.plugin.PluginManager session EJB is a stateless EJB that provides run-time management of plug-ins during workflow execution.

For more information about programming plug-ins and the PluginManager EJB, see Programming BPM Plug-Ins for WebLogic Integration.

PluginManagerCfg Session EJB

The com.bea.wlpi.server.plugin.PluginManagerCfg session EJB is a stateless EJB that enables you to manage the implementation of user-defined plug-ins.

For more information about programming plug-ins and the PluginManagerCfg EJB, see Programming BPM Plug-Ins for WebLogic Integration.

ServerProperties Session EJB

The com.bea.wlpi.server.serverproperties.ServerProperties session EJB is a stateless EJB that enables clients to obtain information about the properties governing BPM.

Using the public methods provided by the ServerProperties EJB, you can get the following information:

• Software version, including the major and minor version numbers, build number, and product name

• Software properties

• Software version required to support the features defined in a template

WLPIPrincipal Session EJB

The com.bea.wlpi.server.principal.WLPIPrincipal session EJB is a stateless EJB that enables clients to interface with the WebLogic Server security realm and access BPM organizations, roles, users, and other security properties. BPM roles map to WebLogic Server security groups; BPM users, to WebLogic Server users.

Using the public methods provided by the WLPIPrincipal EJB, you can configure, manage, and obtain information about the organizations, roles, and users that ensure secure access to the system.

Note: Information about roles and users beyond the WebLogic Server-specific information that is stored in the WebLogic Server security realm, is maintained in the BPM database.

Worklist Session EJB

The com.bea.wlpi.server.worklist.Worklist session EJB is a stateful EJB serving as the primary interface for run-time management clients, including Worklist and custom run-time management clients. The Worklist EJB enables interaction with running instances.

Using the public methods provided by the Worklist EJB, you can:

• Get startable business processes

• Instantiate business processes

• Get tasks and task counts

• Control the stages in the lifecycle of a task being executed (assign, mark done, and so on)

• Respond to notifications

• Set task properties

• Invoke exception-handling methods

XMLRepository Session EJB

The com.bea.eci.repository.ejb.XMLRepository session EJB is a stateless EJB that provides access to the XML repository database.

Using the public methods provided by the XMLRepository EJB, you can:

• Manage XML repository folders

• Manage XML repository entities

• Get EJB environment variable values

Client Common Package

The com.bea.wlpi.client.common package provides common client-side classes used by a BPM client. This package includes classes for:

• Connecting to the process engine

• Facilitating client GUI layout and development, and generating dialog boxes

• Getting exception, task, and versioning information

• Managing resources

• Caching images and icons

• Filtering files by file extension

• Generating a unique transaction ID for use in a clustered environment

Client Utility Package

The com.bea.wlpi.client.util package provides two JMS utilities, JMSTest and JMSTestAddr, for testing the publish and subscribe features of a JMS topic.

Client/Server Common Package

The com.bea.wlpi.common package provides classes used by both the BPM client and the WebLogic Integration process engine. The package includes:

• Value objects for describing the following:

  • Organizations, users, and roles

  • Templates and template definitions

  • Tasks and task reroutings

  • Variables

  • Running instances and functions

  • Business calendars

  • Java classes

  • Event keys

  • Versioning information

• Descriptors for Java classes, EJBs, EJB invocations, and server-side Java class methods

• Mechanism for serializing long strings (strings that exceed 64KB when they are UTF-8 encoded) in pre-JDK 1.3 run-time environments

• Message interface for language-independent server messaging

Package members can be serialized to facilitate the exchange of information between the client and the server.

Plug-In Common Package

The com.bea.wlpi.common.plugin package provides common classes used to manage user-defined plug-ins.

For more information, see Programming BPM Plug-Ins for WebLogic Integration.

Security Common Package

The com.bea.wlpi.common.security package provides common classes used to define security permissions. The package includes:

• Value objects for describing role and user permissions

• Security permission types

Utility Package

The com.bea.wlpi.util package provides general BPM utilities, including a utility for generating message-driven beans.

XML Repository Helper Package

The com.bea.eci.repository.helper package provides common classes used to access the XML repository. The package includes:

• Value objects for describing the XML repository folder and entities

• Methods for creating and managing folders and subfolders

• Methods for creating and managing entities

 

---

BPM Application Development Tasks

The BPM API enables users to accomplish the application development tasks described in the following sections.

Configuration

The BPM API, via the Studio client or a custom configuration client, enables users to configure:

• Security realms (organizations, roles, and users)

• Business operations

• Event keys

• Business calendars

Part II of this document, Configuration, describes how to configure each of these types of entities using the BPM API. For more information about the API, see the BEA WebLogic Integration Javadoc.

Design

The BPM API, via the Studio client or a custom design client, enables users to perform the following types of design tasks:

• Create and manage workflow templates and template definitions

• Create and manage tasks and task reroutings

• Manage the XML repository database

• Import and export design data

Part III of this document, Design, describes how to perform each of these types of design-related tasks using the BPM API. For more information about the API, see the BEA WebLogic Integration Javadoc.

Run-Time Management

The BPM API, via the Worklist or a custom run-time management client, enables users to perform the following types of run-time management tasks:

• Manage the active organization

• Start business process instances

• Manage run-time tasks, including:

  • Get, assign, and execute tasks

  • Respond to client requests

  • Mark tasks as done or undone

  • Set task properties

  • Update variables

  • Invoke exception handlers

Part IV of this document, Run-Time Management, describes how to perform each of these types of run-time management tasks using the BPM API. For more information about the API, see the BEA WebLogic Integration Javadoc.

Monitoring

The BPM API, via the Studio or a custom monitoring client, enables users to perform the following types of monitoring tasks:

• Manage run-time instances

• Manage run-time variables

• Generate graphical reports based on workflow, tasks, user or role, and task status

• Generate statistical reports based on workflow, task, user or role, and date

Part V of this document, Monitoring, describes how to perform each of these types of monitoring tasks using the BPM API. For more information about the API, see the BEA WebLogic Integration Javadoc

Plug-In Development

The BPM API enables users to design and integrate custom plug-ins.

For more information, see Programming BPM Plug-Ins for WebLogic Integration.

 

---

BPM API Examples

The examples used throughout this document are excerpted from the BPM client examples provided with the software in the samples/bpm_api directory. The client examples include:

• Command-Line Administration Example

• Command-Line Studio Example

• Command-Line Worklist Example

• Command-Line SAX Parser Example

• JSP Worklist Example

The client examples are described in detail in the following sections.

Command-Line Administration Example

WebLogic Integration provides an example that demonstrates the basic administration tasks that you might support in a custom command-line client. These tasks include:

• Connecting to the process engine

• Managing organization, roles, and users: adding, deleting, and so on

• Managing the security realm: getting the name of a security realm class and determining whether or not the security realm is manageable

• Managing business operations: adding, deleting, and so on, and getting EJB and Java class descriptors

• Managing event keys: adding, deleting, and so on

• Managing business calendars: adding, deleting, and so on

• Managing deployed EJBs: listing names and descriptors of deployed EJBs, and enabling and/or disabling automatic regeneration

• Displaying server properties, including server version, template definition version supported, and system properties

The command-line administration example consists of one Java file, CLAdmin.java, located in the samples/bpm_api/commandline directory. For information about how to compile and run this example, see the Readme.txt file in this directory.

Some of the examples presented in Part I, API Development Fundamentals, and Part II, Configuration, are excerpted from the command-line administration example.

Command-Line Studio Example

WebLogic Integration provides an example that demonstrates basic design tasks that you might support in a custom command-line studio client, including:

• Managing templates: creating, deleting, and listing

• Managing task reroutings: adding, deleting, and listing

The command-line studio example consists of one Java file, CLStudio.java, located in the samples/bpm_api/commandline directory. For information about how to compile and run this example, see the Readme.txt file in this directory.

Some of the examples presented in Part III, Design, are excerpted from the command-line studio example.

Command-Line Worklist Example

WebLogic Integration provides an example that demonstrates the basic worklist management tasks that you might support in a custom command-line worklist client. These tasks include:

• Connecting to the process engine

• Managing organizations: listing all organizations, and listing and setting the current active organization

• Managing business processes: listing all startable business processes and starting a business process

• Managing tasks: listing and executing tasks, and getting task counts

The command-line worklist example consists of one Java file, CLWorklist.java, located in the samples/bpm_api/commandline directory. For information about how to compile and run this example, see the Readme.txt file in this directory.

Some of the examples presented in Part IV, Run-Time Management, are excerpted from the command-line worklist example.

Command-Line SAX Parser Example

WebLogic Integration provides an example that demonstrates how to use a SAX parser to parse client requests received from the BPM server. Specifically, this example illustrates how to:

• Use the Xerces SAX parser to parse client requests from the server

• Create and send a response to the server

The command-line SAX parser example consists of one Java file, CLSaxParser.java, located in the samples/bpm_api/commandline directory. For information about how to compile and run this example, see the Readme.txt file in this directory.

Some of the examples presented in Part IV, Run-Time Management, are excerpted from the command-line worklist example.

JSP Worklist Example

WebLogic Integration provides an example that demonstrates the basic run-time management tasks that you might support in a custom Java Server Page (JSP)-based worklist client. The main component of this example is the worklist.jsp file, which provides the main interfaces to the JSP worklist.

The following table lists the tasks that are demonstrated by the JSP client, and identifies example files to view for more information.

Table 1-6 JSP Worklist Example

Task	Related Example Files
Logging on and connecting to the process engine, and specifying a login, password, and URL. For more information about connecting to the process engine, see Connecting to the Process Engine.	logon.html, logon.jsp
Starting a workflow from the list of available workflow templates.	startworkflow.jsp
Getting tasks.	worklist.jsp
Executing tasks.	worklist.jsp
Parsing the response XML (responseParser). The responseParser implements a document handler with the SAX (Simple API for XML) parser, enabling the application to handle specific events as they occur within the XML document. For more information about parsing XML, see the XML.com Web site supported by O'Reilly & Associates, Inc. at the following URL: http://www.xml.com	ResponseParser.java
Responding when input is required to set variables (query.jsp) or acknowledge a message (message.jsp).	query.jsp, message.jsp
Reassigning a task to a different user or role.	reassign.jsp
Marking a task as done or undone.	worklist.jsp
Setting task properties to control the run-time characteristics of a running instance.	taskproperties.jsp
Logging out and disconnecting from the process engine. For more information about disconnecting, see Disconnecting from the Process Engine.	logoff.jsp

 

The following figure shows the main JSP interface, worklist.jsp.

Figure 1-3 Main Interface to the JSP Worklist

 

For information about this example, see the Readme.txt file in the following BPM directory: samples/bpm_api/jsp.

Some of the examples presented in Part IV, Run-Time Management, are excerpted from the JSP worklist example.