Provides access to business processes deployed on ALBPM Process Execution Engines.
Package Specification
What is PAPI ?
The ALBPM Process Application Programming Interface (PAPI) is the API provided and implemented by BEA Systems Inc. to interact with processes deployed to an existing and configured Process Execution Engine.
The accessed processes can be deployed on one or more ALBPM Process Execution Engines since PAPI internally will connect the configured Directory Service to find the Process Execution Engine in which the process has been deployed.
PAPI classes will let a developer implementing a program in Java to interact with business processes deployed in an ALBPM Process Execution Engine and perform operations like the ones listed below:
- Create a new instance in a process
- List instances the user is authorized for
- Abort instance
- Attach a file to an instance
- Audit an instance
- Edit instance�s attachment
- List deployed process activities
- Get latest version of process deployed
- List instance attachments
- Notify instance
- Run an instance�s task
- Select an instance
- Suspend an instance
PAPI is a 100 % Java API and can be invoked by any JVM supporting JVM version 1.4.2 or above.
When should we use PAPI ?
PAPI is primarily used by Java Applications that need interaction with business processes deployed in one or more ALBPM Process Execution Engines. PAPI cannot be used to connect to a Studio Process Execution Engine but to any of the Enterprise Process Execution Engines.
What other ALBPM applications or APIs use PAPI ?
PAPI is the public ALBPM's API to connect to business processes and as such, it is being used by other ALBPM components and APIs to interact with business processes on a Process Execution Engine.
Examples of these ALBPM Components and APIs follow:
- ALBPM WorkSpace Web Application: ALBPM WorkSpace uses PAPI extensively to interface with a number of ALBPM Process Execution Engines simultaneously.
The WorkSpace provides a user interface that allows business process participants to perform the execution of process steps requiring human participation allowing the rendering of forms and other UI components very easily.
- WAPI: WAPI is a Web based API implemented with Java Servlets that allows connectivity with a Process Execution Engine through the HTTP transport protocol.
The Servlets composing WAPI relay on PAPI to execute the requests on the appropiate business process deployed in an accessible Process Execution Engine.
WAPI is an extension to the set of servlets provided with the WorkSpace and are bundled and distributed with this Web Application. All the requests done through WAPI need to go through a configured WorkSpace instance.
This API is very useful when custom applications requires integration from HTML Forms or JSPs.
- PAPI-WS: ALBPM provides a Web Service API allowing a Web Service client programs to interact with a business process deployed on a Process Execution Engine. PAPI-WS internally uses PAPI to request the execution of
operations. PAPI-WS is exposed through the WorkSpace Web Application accepting SOAP request over HTTP or HTTP(S) (depending on how the WorkSpace Web Application has been deployed in the container hosting it).
PAPI Overview
The diagram below shows the interaction required for a Java Program to connect to an deployed business process in a Process Execution Engine.

The diagram above shows all the APIs and systems that need to be connected in order to successfully connect to a business process deployed to a Process Execution Engine.
First of all, the Java Program will need to create a ProcessService object, that is necessary to get an instance of a ProcessServiceNESession or ProcessServiceSession.
When the session is created, PAPI internally uses FDI to authenticate the user as well as defining the permissions over which processes this individual has access depending on the roles assigned on the Organization maintained in the Directory Service.
Once the session has been successfully created, PAPI will start performing the requested operations over the appropiate process in one of the available Process Execution Engines. Once the session has been established, the developer can use any of the methods available in the
ProcessServiceSession class to perform all the operations needed to interact with business processes, views, etc.
PAPI Notifications
When a PAPI program is created, it requires the creation of a ProcessService object. When created, it will initialize and cache information from the FDI (information obtained when a session is created for a given participant) as well as maintaining a client side instance cache to minimize
the roundtrip with any of the available Process Execution Engines. Once this object has been created, it is necessary to keep this data up to date as modifications take place in the Organization and instances change state on the available Process Execution Engines.
To this extent, ALBPM can send notifications to a created and registered ProcessService object in a running Java Virtual Machine. These notifications can be classified as follow:
- Engine Notifications: These are notifications broadcasted by a Process Execution Engine to all ProcessService objects that required a connection with it.
The time interval for these notifications can be configured in the ALBPM Process Execution Engine Preferences by setting the appropiate value to the "Latency between notifications" parameter on the "Others" tab.
This parameter takes effect only when working with an Enterprise Standalone Process Execution Engine. The Enterprise Process Execution Engine deployed on a J2EE container uses a different notification mechanism based on JMS messages.
- FDI Notifications: Changes that are done to the Organization structure can also be obtained close to real time by an internal poller thread that checks if there have been changes on the Organization structure. Typical changes are reassignment of roles to participants.
The time interval between notifications are defined by using the PAPI method ProcessService.startUpdater.
- MPORTANT: Participant and Roles changes DO NOT take place while a participant is connected. For new role assignments to refresh, the participant will need to disconnect and connect back again. These bindings are defined at session connection time.
PAPI Environment Requirements
In order to successfully compile and execute a PAPI program, it is important to comply with the following minimal requirements and instructions provided below.
- Java Virtual Machine Requirements
Use a JVM 1.4.2 or greater, to successfully compile and execute a Java PAPI program.
- PAPI compilation Jars
When compiling a Java PAPI program you will need to include the following Java Jar files into the java compiler classpath. These Jar files are included with the ALBPM Enterprise distributions:
- fuegopapi-client.jar - (in the {ALBPM Home Directory}/client/papi/lib directory)
Compiling a Java PAPI Program
A PAPI Java Program can be compiled using a command line similar to the one shown below:
- C:\papi>{JVM 1.4.2 path}\bin\javac -classpath �{ALBPM Home Directory}client/papi/lib/fuegopapi-client.jar {Java Source filename}
- Running a Java PAPI Program
When running a Java PAPI program, you will need to include the following Java Jar files into the java classpath. These Jar files are:
- fuegopapi-client.jar - (in the {ALBPM Home Directory}/client/papi/lib directory)
- {JDBC Driver} (this is the JDBC Driver for the Directory Service Provider. Check the installation guide to select the appropiate JDBC Driver)
- jms.jar (for J2EE environment) - (in the {ALBPM Home Directory}/j2ee/common/lib directory)
- ejb-2.0.jar (for J2EE environment) - (in the {ALBPM Home Directory}/j2ee/common/lib directory)
In order to avoid unnecessary missing plugin warning messages, it is recommended the jars needed to execute a Java Client Program using PAPI are copied to a new folder or directory accessible by the Java Client Program.
This directory is relative to the location of the Java PAPI Program. In our example, we are assuming the location of the PAPI Java Program is c:\papi so this directory will then be: c:\papi\lib.
Based on the assumption above, the command line to run the Java PAPI Program should be:
- C:\papi>{JVM path}\bin\java �classpath ".;{Papi lib directory}\fuegopapi-client.jar;{Papi lib directory}\{JDBC Driver}" {Java Class filename} 'propertiesFile'
Here is how this Java program is invoked and what the arguments mean:
- {JVM path} - The JVM path (for example: e:\\j2sdk1.5.0.)
- {Papi lib directory} � The directory where the PAPI runtime jar files where copied over from the Fuego Enterprise Installation. In our example: c:\papi\lib.
- {JDBC Driver} - JDBC Driver for the Directory Service Provider (e.g. Oracle, Microsoft SQL Server, or DB2). If you are connecting to a Directory Service that is accessed via JNDI (e.g.: iPlanet, Microsoft Active Directory), there is no need to include a JDBC driver in the classpath.
- {Java Class filename} - You are running the command from the directory where the class you just created is located.
- propertiesFile: This is optional but recommended as a best practice. This is a file that is passed as the first argument of your PAPI program and one that can help you define environment specific properties for PAPI to connect successfully to the Directory Service such as:
- User.
- User Password
- Location of the directory.properties
A sample of a properties file follows:
fuego.directory.file=/development/directory.properties
fuego.directory.id=default
fuego.papi.cache.size=5000
test.user.id=user
test.user.password=password
PAPI Skeleton Code
The following is a sample PAPI Program that can be used as a model and skeleton for any kind of Program using the PAPI API to connect to business processes deployed in a Process Execution Engine.
import java.util.*;
import java.io.*;
import fuego.papi.*;
import fuego.papi.exception.*;
public class PapiTest
{
public static void main(String[] args)
{
try {
String propertiesFile = args[0];
// Load test properties from configuration file (including PAPI Properties)
Properties testProperties = new Properties();
testProperties.load(new FileInputStream(propertiesFile));
String userId = testProperties.getProperty("test.user.id");
String userPass = testProperties.getProperty("test.user.password");
String dirPropertiesFile = testProperties.getProperty("fuego.directory.file");
String dirId = testProperties.getProperty("fuego.directory.id");
String papiCacheSize = testProperties.getProperty("fuego.papi.cache.size");
// Create Properties object to create the session with the Directory Service.
Properties properties = new Properties();
properties.put(ProcessService.DIRECTORY_ID, dirId);
properties.put(ProcessService.DIRECTORY_PROPERTIES_FILE, dirPropertiesFile);
properties.put(ProcessService.INSTANCES_CACHE_SIZE, papiCacheSize);
properties.put(ProcessService.WORKING_FOLDER, "/tmp");
ProcessService service = ProcessService.create(properties);
// Creates a session with the provided user id and password.
ProcessServiceSession session = service.createSession(userID, userPass, "localhost");
// Perform any PAPI Operations through methods available in the ProcessServiceSession class.
...
session.close();
service.close();
}
catch (Exception e) {
e.printStackTrace();
}
}
PAPI Samples
The following is a list of FULL examples provided with the Enterprise distributions:
Each one of these samples contain:
- Sample Project
- PAPI Java Source Code