Package fuego.papi

Provides access to business processes deployed on ALBPM Process Execution Engines.

See:
Description

Interface Summary

ActivityView	ActivityView contains and handle instances located in the given activity.
ApplicationsView	This View handle information related to Applications (Global Activities). It keeps a list of the applications that the participant can execute. It has a default presentation.
ArgumentSet	Represents an ArgumentSet defined in the process.
ArgumentSet.Argument	Represents an argument of an ArgumentSet
Attachment	Represents an Attachment associated with an instance.
AttachmentInterface	Represents an Attachment associated with an instance. This class is for internal use only.
AttachmentsView	This View handle information related to Attachments. It keeps a list of attachments locked by this participant. It has a default presentation.
BookmarkView	A View to keep the Instances that are bookmarked.
Consult	Consult is a consultation- a Note sent to another Participant to ask a question about a process instance.
ConsultationsView	View that handle the information of the instances that have at least one consultation.
EditableActivityView	ActivityView that can be edited.
EditableApplicationsView	ApplicationsView that can be edited.
EditableAttachmentsView	AttachmentsView that can be edited.
EditableBookmarkView	This is a BookmarkView that can be edited.
EditableConsultationsView	ConsultationsView that can be edited.
EditableFolderView	This is a Folder View that can be modified, if it is needed a read-only Folder View use FolderView instead.
EditableHistoryView	HistoryView that can be edited.
EditableInstancesView	InstancesView that can be edited.
EditablePresentation
EditableView	This View can be modified, if it is needed a read-only View use View instead.
Execution	Allows advanced users to customize invocations on client-side components.
Filter	Filter is used to define a subset of instances returned from a View or set of Processes.
FilterAttribute	Represents a single condition in a Filter.
FolderView	To group a list of Views.
GlobalExecution	Allows advanced users to customize invocations of Global Activities on client-side components.
HistoryView	View that handle the information of the instances where the participant made some operation.
InstancesView	This View handle information related to Instances.
Invocation	Represents a mandatory client-side invocation.
MDObject	Contains the basic information of any metadata object. The metadata is all information about a process deployed, included Process, Activity and Task.
Note	Represents a Note associated with an instance.
NoteInterface	Interface for a subset of methods in the Note class. This class is for internal use only.
Presentation	Used to define the columns displayed in a View.
PresentationColumnFormat	PresentationColumnFormat defines the programming interface for formatting locale-sensitive presentation column values into Strings.
Process	Contains the metadata of a particular Process.
ProcessDiagram	This interface represents the diagram of a given process.
ProcessDiagramPath	Event for rendering process diagram
ProcessService.Factory
ProcessServiceNESession	ProcessServiceNESession contains methods for creating views and presentations, and for getting activities, attachments, instances, notes, and processes.
ProcessServiceSession	ProcessServiceSession contains methods to store presentation and views, to add attachments and notes, and to process activities and instances.
Task	Tasks correspond to Main Tasks and Optional Tasks in Studio.
TaskArgument	Represents an argument of an activity task.
TaskExecution	This interface allows a PAPI client to customize invocations over a task in interactive activities on client-side components. This interface is intended for advanced usage of PAPI.
View	Handles different kinds of information using presentations. There are three different kinds of views, depending on the information to be presented: views for instances, views for applications, and views for attachments.

Class Summary

Activity	Activity in a Process.
Arguments	Represents the arguments for an ArgumentSet for an Activity.
AttachmentOperationException	This exception can be thronw by any method who performs any operation over an Attachment.
BatchOperationException	Thrown when not all requested objects were retrieved or the executed operation was not performed correctly over every object.
ColumnFormat	ColumnFormat is the format of the presentation column.
CommunicationException	Thrown when any PAPI method can not communicate with the Directory.
ConnectedClientInfo
EngineException	Thrown when PAPI can not connect with the ALBPM Engine.
EngineRuntimeException	No RuntimeException thrown while executing an engine operation should "travel" to PAPI.
EventType	Enumeration of type of events over an instance.
InstanceEvent	Contains the information of a process-instance event.
InstanceId	Contains information about an instance, including process Id, instance identification number and thread identification number.
InstanceInfo	Contains information about Process instances.
InstanceItemState	Enumeration of Instance Item State (Task). Contains all valid status values for a process instance item.
InstanceStamp	This class keeps the minimal information about the Process Instance needed in the engine side in order to perform any operation over an instance. It is needed when an operation over an instance has to be done through PAPI.
OperationException	Superclass of all Exceptions in the fuego.papi and fuego.papi.exception packages.
OperationRuntimeException	Superclass of PAPI Runtime Exceptions.
Ordering	Ordering is a list of Ordering.Entry, which contains the information to sort the result of a Filter.
Participant	Contains Participant metadata and methods to get permissions and roles.
Participant.RoleAssignment	Contains Participant role assignment metadata.
ParticipantException	Superclass of Participant Exceptions.
ParticipantsForActivities	Used to match group of Paticipants with Activities.
Presentation.Column	Column contains every attribute for a column, the main idea is to get and keep all the neccesary info, like size and id, etc.
Presentation.DefaultPresentationColumnFormat	The default PresentationColumnFormat.
Priority	Enumeration of instance priorities.
ProcessInstanceState	Enumerates the different process instance's status.
ProcessNotAvailableException	Thrown when a Process is not available.
ProcessOperationException	Superclass of Process Exceptions.
ProcessService	Main class in Process API (PAPI) framework. This service provides the connection with the ALBPM Engine.
PropertyOperationException	A property is associated with a participant in the directory service.
SearchScope	Restricts the set of instances returned in a Filter by specifying the process instance status (StatusScope) and participant roles (ParticipantScope).
Status	Deprecated. use ProcessInstanceState and InstanceItemState instead
VarDefinition	VarDefinition contains all information related to a process variable.
ViewOperationException	Superclass of View Exceptions.

Package fuego.papi Description

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.4.2.)
  • {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:

• Order Provisioning Sample
• Filters Sample
• Audit Trail Sample

Each one of these samples contain:

• Sample Project
• PAPI Java Source Code