Introduction to BPM Plug-In Development

Note: WebLogic Integration supports a plug-in framework that is available for extending BPM functionality. This plug-in framework should only be used for extending the native functionality of the BPM. This plug-in framework should not be used to integrate the BPM with external applications or systems; for this either use EJBs (called from the BPM as business operations) or Application Integration (AI) adapters.

This section provides an introduction to business process management (BPM) plug-ins and their development. It includes the following topics:

• What Is a Plug-In?

• How BPM Supports Plug-In Development

• How BPM Discovers a Deployed Plug-In

• BPM Plug-In Development Tasks

• BPM Plug-In Sample

 

---

What Is a Plug-In?

A plug-in consists of a set of run-time loadable Java classes that extends the business process management (BPM) features and functionality of WebLogic Integration.

Using plug-ins, you can modify the design or run-time behavior of the following BPM workflow components:

• Start, Event, and Done nodes

• Task actions

• Properties of workflow templates and template definitions

• Functions

• Message types

• Variable types

For example, you may want to trigger the execution of a business process by sending an e-mail message or other nonXML event, rather than by using any of the standard Start node trigger methods available to you with the WebLogic Integration Studio. You can accomplish this by designing a plug-in that extends the behavior of the Start node to include support for this new nonXML trigger.

The following figure provides an example of a plug-in that modifies the design and run-time behavior of a Start node. It illustrates the plug-in-defined areas of the Start Properties dialog box.

Figure 1-1 Plug-In Example: Start Node

 

In this example:

• The Start Properties dialog box lists the Start Order event as a potential trigger on the Event pull-down menu, and displays the event information defined by the plug-in in the center of the dialog box when the event is selected. This behavior shows how the design of the Start node has been customized.

• At run-time, the Start Order event may trigger the workflow to start. This functionality shows how the run-time behavior of the Start node has been customized.

Note: For more information about the Start node plug-in illustrated in the previous figure, see BPM Plug-In Sample.

 

---

How BPM Supports Plug-In Development

In addition to the standard framework for designing, executing, and monitoring business processes, WebLogic Integration supports a plug-in framework for BPM functionality, enabling you to create plug-ins that customize the existing software, and achieve powerful and seamless integration with other products and technologies.

The following figure illustrates the BPM plug-in framework within the overall BPM architecture.

Figure 1-2 BPM Plug-In Framework

 

Note the following in this figure:

• BEA WebLogic Server manages the deployment of the BPM and plug-in EJBs.

  To make the plug-in available to BPM users, you simply deploy the plug-in as a session EJB on WebLogic Server. No additional installation is required on the WebLogic Integration process engine or BPM client.

  The plug-in must be deployed as part of the WLI application by editing the config.xml file. For more information about deploying a plug-in, see Deploying the Plug-In.

• The BPM Plug-in Manager stores plug-in configuration information in the WebLogic Integration database.

• An external application interacts with the process engine via an XML event or nonXML event. NonXML events are supported via the plug-in framework.

• The Event Processor manages both XML and nonXML events. For more information about plug-in event handling, see Processing Plug-In Events.

• The main components of the plug-in framework include:

  • Plug-in Manager, which supports the management of plug-ins

  • Plug-in API, which supports the design and development of plug-ins

The following sections describe these two components.

For additional information about the role of the process engine, see "WebLogic Integration Process Engine" in Business Process Management API Development in Programming BPM Client Applications.

Plug-In Manager

The Plug-in Manager is a dedicated part of the WebLogic Integration process engine that supports the configuration, design, and run-time management of plug-ins, as shown in the following figure.

Figure 1-3 Plug-In Manager

 

The Plug-in Manager oversees the loaded plug-ins and their interactions with the WebLogic Integration process engine and BPM clients, and routes all plug-in related requests.

For example, a subset of the configuration and design responsibilities of the Plug-in Manager includes:

• Supporting the import and export of workflows containing plug-in-specific content.

• Managing the simultaneous loading of multiple plug-ins.

• Enabling the BPM expression evaluator to interpret incoming plug-in data in any format, using common expression grammar.

• Enforcing the dependencies between templates and template definitions, and plug-ins, and handling cases in which the prerequisite plug-ins are not available.

• Enforcing strict type checking during the definition of a business operation that uses plug-in-defined variable types.

• Providing a generic message-handling facility that enables workflows to respond to an unlimited variety of message-handling data formats and sources.

For example, a subset of the run-time responsibilities of the Plug-in Manager includes:

• Enabling the plug-in to store and retrieve plug-in-specific workflow instance data.

• Preventing the instantiation of a workflow when a required plug-in is not loaded.

• Supports custom license checking during initialization.

When designing plug-ins, you access the management features of the Plug-in Manager using the following session EJBs:

• com.bea.wlpi.server.plugin.PluginManager

• com.bea.wlpi.server.plugin.PluginManagerCfg

These EJBs are part of the plug-in API described in the next section.

Plug-In API

The BPM API provides support for configuration, design, and run-time interactions between the process engine and a deployed plug-in.

The plug-in API consists of two session EJBs, a set of run-time management classes, and one package, as described in the following table.

Table 1-1 BPM Plug-In API Components  

Component	Description
com.bea.wlpi.server.plugin.PluginManager	Stateless session EJB providing run-time management of plug-ins during workflow execution: Provides meta-data about the deployed plug-ins Enables access to plug-in design and run-time components Handles event notifications to and from plug-ins
com.bea.wlpi.server.plugin.PluginManagerCfg	Stateless session EJB providing configuration and design management of plug-ins: Maintains plug-in configuration information Manages the plug-in framework cluster-wide state transitions Maintains a list of plug-ins that are registered for the system event notifications
com.bea.wlpi.server.plugin.*	Classes providing run-time management of plug-ins during workflow execution.
com.bea.wlpi.common.plugin	Package providing client and process engine functions, including value object classes. All members of this package are serializable to allow for exchanges between the client and process engine.

 

Note: For a complete description of the BPM API, see Programming BPM Client Applications or the BEA WebLogic Integration Javadoc.

 

---

How BPM Discovers a Deployed Plug-In

To make the plug-in available to BPM users, you simply package and deploy it as a session EJB on WebLogic Server.

If no additional installation is required on the process engine or BPM client, how does BPM discover a deployed plug-in and its implementation details? The plug-in is responsible for providing the functionality that enables BPM to:

• Detect the plug-in

• Manage lifecycle tasks and cache information about the plug-in

• Access the plug-in implementation to read, display, and save the plug-in within the design client

• Execute the plug-in at run time

Detecting the Plug-In

At startup, the process engine detects the plug-in via JNDI based on the plug-in's com.bea.wlpi.server.plugin.PluginHome home interface. All plug-in beans must use the PluginHome as their home interface.

For more information about the PluginHome interface, see Plug-In Home Interface.

Managing Lifecycle Tasks

Once the plug-in is detected, the Plug-in Manager performs the following tasks:

• Gets information about the plug-in, including configuration and dependency information, using the following methods:

  • getPluginInfo() - gets basic information about the plug-in

  • getPluginConfiguration() - gets default configuration information for the plug-in

    You can subsequently set the configuration information using the setConfiguration() method, as described in Managing Plug-Ins.

  • getDependencies() - gets dependencies for the plug-in

    The Plug-in Manager ensures that all dependencies are loaded before loading the plug-in.

• Loads or unloads plug-ins, using the load() or unload() methods, respectively, based on their configuration.

  The plug-in is available only after it is loaded. When the plug-in is loaded, the Plug-in Manager calls the getPluginCapabilitiesInfo() method to get detailed plug-in information, and the plug-in can register for notification messages, as described in Using Plug-In Notifications. At this time, all plug-in classes become visible to the BPM client.

• At shutdown, unloads and deinitializes all deployed plug-ins, using the unloadPlugin() method.

  The plug-in can be deinitialized only once during its lifecycle.

Each of the lifecycle methods listed in the previous list are remote interface methods that must be implemented by the plug-in bean. For more information, see Plug-In Remote Interface.

Accessing the Plug-In Implementation

The plug-in must implement the following classes for each component to define its functionality to the design client:

• Plug-in panel class to define the plug-in GUI component that is displayed in the design client. For more information, see Displaying the Plug-In GUI Component.

• Plug-in data interface to read and save plug-in data. For more information, see Reading and Saving Plug-In Data.

Because no additional installation is required on the BPM design client (for example, the Studio), the design client has no knowledge of the concrete classes that the plug-in defines. It is the responsibility of the plug-in to implement a public constructor that requires no arguments to support remote class loading on the design client.

Remote class loading on the design client proceeds as follows:

• The design client uses the value objects, obtained and cached by the Plug-in Manager at startup, to retrieve the plug-in Java class names based on the plug-in component name and ID.

• Subsequently, the class is loaded from the server by a custom class loader and instantiated by the design client using its no-argument constructor.

For example, in the figure Plug-In Example: Start Node, when a user selects the Start Order event as the Start node trigger, the Plug-in Manager loads the plug-in panel class, StartNodePanel, and it is instantiated by the Studio client using the no-argument constructor. The Studio client subsequently displays the plug-in GUI component in the Start Properties dialog box.

Executing the Plug-In at Run Time (Context Passing)

To define plug-in execution characteristics, you must implement a run-time interface for the plug-in component. At run time, the plug-in communicates with the process engine and client using a process called context passing: the Plug-in Manager obtains an instance of the plug-in component run-time interface and passes the context to it.

Each context interface provides restricted access to the Plug-in Manager, enabling the plug-in to execute and manage its own application logic, and introduce the plug-in instance data into the BPM run-time environment.

For more information about implementing the run-time interface, see Executing the Plug-In. For more information about implementing context interfaces, see Using Plug-In Run-Time Contexts.

 

---

BPM Plug-In Development Tasks

To develop a BPM plug-in, you need to first create a session EJB that defines the required plug-in classes and interfaces, and then package and deploy the session EJB on WebLogic Server.

The following steps outline the BPM plug-in development tasks in more detail.

Note: In addition to accomplishing the steps outlined below, you should also review the plug-in development fundamentals described in Plug-In Development Fundamentals.

Step 1:

Identify design-time and run-time customization requirements.

Keep in mind that you can modify the design and run-time behavior of the following workflow components using plug-ins:

• Start, Event, and Done nodes

• Properties of the workflow templates and template definitions

• Task actions

• Functions

• Message types

• Variable types

The plug-in sample provides a set of plug-in classes that represent common plug-in scenarios. For more information, see BPM Plug-In Sample.

Step 2:

Define the plug-in session EJB:

1. Implement the javax.ejb.SessionBean interface methods, including:

   ejbActivate()
   ejbPassivate()
   ejbRemove()
   setSessionContext(SessionContext ctx)

2. Implement the com.bea.wlpi.server.plugin.PluginHome home interface ejbCreate() method.

   The home interface has been defined for you by the BPM plug-in framework via the com.bea.wlpi.server.plugin.PluginHome interface. The BPM home interface is described in detail in Plug-In Home Interface.

   Note: At this time, you can set up a custom plug-in icon for the Studio interface view when implementing the ejbCreate() method, as described in the table Home Interface Method.

3. Implement the com.bea.wlpi.server.plugin.Plugin remote interface methods.

   The remote interface has been defined for you by the BPM plug-in framework via the com.bea.wlpi.server.plugin.Plugin interface. The BPM remote interface is described in detail in Plug-In Remote Interface.

   Note: At this time, you must define the plug-in component value objects, and customize the action tree (if defining a plug-in action) when implementing the getPluginCapabilitiesInfo() method, as described in the table Remote Interface Plug-In Information Methods.

This step is described in detail in Defining the Plug-In Session EJB.

Step 3:

Define the plug-in component:

1. Implement the plug-in data interface to define the methods used for reading and saving the plug-in data.

2. Define the plug-in panel class to display the plug-in GUI component within the design client.

3. Define the plug-in run-time component class to define the run-time execution characteristics.

This step is described in detail in Defining Plug-In Components.

Step 4:

Set up notification management.

This step is described in detail in Using Plug-In Notifications.

Step 5:

Implement and register an event handler to process incoming plug-in events.

This step is described in detail in Processing Plug-In Events.

Step 6:

Manage the plug-in, customizing the plug-in configuration requirements, if desired.

This step is described in detail in Managing Plug-Ins.

Step 7:

Develop context-sensitive online help for the plug-in.

This step is described in detail in Defining Plug-In Online Help.

Step 8:

Package all plug-in Java classes in EJB JAR and WAR files, and deploy the plug-in.

This step is described in detail in Deploying the Plug-In.

 

---

BPM Plug-In Sample

The BPM plug-in sample provides a set of plug-in classes that represent common plug-in scenarios, and is provided with the software. The sample includes two workflow templates, Plug-in Order Processing and Plug-in Order Fulfillment, which are stored in the SAMPLES_HOME/integration/samples/bpm_api/plugin/sample_plug_in.jar file.

Note: The plug-in sample is loosely based on a generic Web-based sales order scenario that is described in detail in Introduction to WebLogic Integration and the Example Workflows in Learning to Use BPM with WebLogic Integration.

The following figure shows the plug-in sample workflow templates and identifies the plug-ins that have been added.

Figure 1-4 Plug-In Sample Workflow Templates

 

The previous example illustrates the following:

• The Plug-in Order Processing workflow template includes three plug-in components from the sample plug-in: a Start node that is triggered by a plug-in-defined event, a task action that simulates an inventory check, and an Event node that blocks until an order confirmation message is received.

• The Plug-in Order Fulfillment workflow template includes two plug-in components from the sample plug-in: a function that calculates the total price of an order and a task action that generates an event message to trigger the Confirm Order event.

Note: The Order Processing Trigger workflow template provided as part of the generic example (described in Learning to Use BPM with WebLogic Integration) is not used by the plug-in. Instead, the Plug-in Order Processing workflow template is triggered via a plug-in-defined XML event.

Excerpts from the plug-in sample are included throughout this document. For complete information about the BPM plug-in sample and its directory structure, and instructions for importing and running the sample, see BPM Plug-In Sample. For more information on the generic Web-based sales order scenario, see Learning to Use BPM with WebLogic Integration.

Note: In the previous figure, the following custom icon is shown in the upper-right corner of the Start and Event nodes to indicate that they contain customized plug-in properties.

Icons such as this are displayed when the Studio interface view is enabled. For information about how to enable the interface view, see Using the Studio Interface in Using the WebLogic Integration Studio.

To specify a custom plug-in icon when creating a remote plug-in object interface, see the create() method description in Plug-In Home Interface.