11.5    SAP BPM Application Programming Interface

In your projects, you might need to use or call the functionalities provided by SAP BPM from an external application. You can access the SAP BPM functionality from outside SAP BPM by using its API. A common scenario for using the SAP BPM API is when you want to use another UI technology that better fits your requirements to complete tasks generated by SAP BPM. Be aware that you can use any UI technology of your choice to consume the SAP BPM API, including Web Dynpro, EJB, Java Server Pages (JSP), SAPUI5, and so on.

The SAP BPM API is provided from within SAP PO, so you can’t directly consume it from an external application. To access it remotely, you’ll need to write an application that wraps the internal SAP BPM API functionality and exposes it as a REST or a web service (SOAP). There are some open-source projects available on SAP Code Exchange that provide a REST wrapper for the SAP BPM API.

Following are some of the functionalities that can be accessed by using the SAP BPM API:

• Starting an SAP BPM process
• Retrieving details of a process
• Retrieving details of a task
• Executing a task
• Assigning a task to a user
• Retrieving different statistics on the administrators of processes and tasks
• Retrieving a process flow diagram
• Retrieving reports

11.5.1    Prerequisite to Using the SAP BPM API

To start consuming the SAP BPM API functionality, the following conditions need to be satisfied:

• The SAP BPM process on which the API needs to be used must be deployed on the SAP PO server.
• The user to be used to connect to the SAP PO server (via the API) must have the necessary UME actions added to his profile to use the SAP BPM API. For instance, to start an SAP BPM process, you’ll need the role SAP_BPM_TRIGGER_EVENT assigned to the user’s profile.
• The UI technology chosen to call the SAP BPM API can be deployed in the SAP NetWeaver AS Java of the SAP PO server.

11.5.2    Implementation Aspects and Examples

The DC used to implement and call the SAP BPM API needs to have dependencies to the SAP DCs, as indicated in Table 11.5.

Development Component	Software Component
tc/bpem/facade/ear	BPEM-FACADE
tc/je/sdo21/api	ENGFACADE

Table 11.5    Dependencies Required to Consume the SAP BPM API

SAP BPM API classes are included in a number of SAP-provided packages. Taking the com.sap.bpm.pm.api package as an example, the following main objects or managers are included:

• ProcessDefinitionManager
  Represents the collection of all process definitions.
• ProcessInstanceManager
  Represents the collection of all instances of a particular SAP BPM process.
• TaskInstanceManager
  Class to manage instances of a task.
• ProcessStartManager
  Class responsible for managing the functionality of starting processes.
• ProcessModelManager
  Manages the objects related to process models.

Uniform Resource Indicator Concept

Some general behaviors and concepts across the different SAP BPM objects need to be considered to understand how to use the API. One of those concepts is the URI. Every object accessed and used via the SAP BPM API can be addressed via its URI. The URI can be considered as a unique identifier for any SAP BPM objects during runtime. A lot of methods on the objects require the URI as input. After getting access to the ProcessDefinition object, you can call the getId() method on it to retrieve its URI.

In the next section, we’ll provide an excerpt to illustrate how to use the SAP BPM API to start an SAP BPM process.

Start a Process

To start a process from the SAP BPM API, follow these steps:

1. Get a reference to the ProcessDefinitionManager.
2. Access the ProcessDefinition object from the ProcessDefinitionManager.
3. Retrieve a ProcessStartEvent object.
4. Create an input data object, and populate it with data.
5. Start the process.

Sample source code to start an SAP BPM process is presented in Listing 11.2.

//Get a reference to the ProcessDefinitionManager – gives access on all 
//existing Process Definitions in the server.
ProcessDefinitionManager manager = BPMFactory.getProcessDefinitionManager();
//Access a specific process definition based on the vendor, name of the 
//DC, and the process name.
ProcessDefinition activeProcessDefinition = manager.getActiveProcessDefinition("rojoconsultancy.com", "dc_demoapi", "employeedata");
//Retrieve a ProcessStartEvent
Set<ProcessStartEvent> processStartEvents = BPMFactory.getProcessStartManager().getProcessStartEvents(activeProcessDefinition.getId());
ProcessStartEvent currentEvent = processStartEvents.iterator().next();
//Build the input data object, and populate it with values
DataObject inputDO = BPMFactory.getProcessStartManager().createDataObjectForStartEvent(currentEvent);
inputDO.set("firstname", "John");
inputDO.set("leaveType", "smith");
//Start process
if(currentEvent!=null)
{
URI startedInstanceID = BPMFactory.getProcessStartManager().startProcess(currentEvent, inputDO);
}

Listing 11.2    Sample Code to Create and Start a New SAP BPM Instance

For further details on this and other packages, classes, and methods available for the SAP BPM API, refer to the following link: http://bit.ly/2wIC9tp.