11.6    SAP Business Process Management OData

Today’s technology environment encourages openness of systems. Data generated by a system should be easily accessed by third-party applications. It’s in that spirit that the SAP BPM API was made available. Unfortunately, the SAP BPM API only worked from within SAP NetWeaver. In an effort to achieve true openness, it was important to make the functionalities provided by the SAP BPM API accessible from outside of SAP PO by using well-adopted standards.

That is why , the SAP BPM Open Data Protocol (known as SAP BPM OData or OData API) functionality was introduced since SAP NetWeaver 7.3 EHP 1 SP 09. SAP BPM OData is a REST-based set of services that provides the same functionality as the SAP BPM API. It’s an OData wrapper of the SAP BPM API. A series of URLs are available to access it externally.

Note

To find out more about OData, refer to www.odata.org.

Because the SAP BPM OData is REST based, the following principles apply:

• It can be accessed via HTTP.
• Each SAP BPM OData functionality is exposed by way of a special URL.
• You’ll need to authenticate with a valid UME user. The user will need to have the required roles and actions on his profile to perform tasks in SAP BPM. In general, the user needs to have the SAP_BPM_ODATA and SAP_BPM_ODATA_INBOX roles assigned.
• Inputs to the SAP BPM OData services can be provided in JavaScript Object Notation (JSON) or XML.
• Depending on the functionality used, different HTTP methods can be used (GET, POST, PUT, and DELETE).

The base URL for SAP BPM OData is http://<hostname>:<port>/bpmodata.

Depending on the function that you want to perform using SAP BPM OData, extra characters need to be added after the base URL. The extra information after the URL has the following general format:

/<service_name>/<path_segment(s)>/<OData_resource_path_and_query_options>

The URL variables can be explained as follows:

• <hostname>
  The hostname of SAP PO.
• <port>
  The port of SAP PO.
• <service_name>
  The service or feature to be called. A number of services are available in SAP BPM OData. Some of these services will be explored in the next section.
• <path_segment(s)>
  Each service has a different set of path segments. Note, however, that the <path_segment> isn’t mandatory for all service types.
• <OData_resource_path_and_query_options>
  The resource path specifies the operation to be performed on the service. The query options contain the data that needs to be queried or passed to the operation.

In addition, note that SAP BPM objects have a unique identifier assigned to them during runtime. These IDs are also used in SAP BPM OData to uniquely refer to these objects.

11.6.1    OData Services for Tasks and Task Data

SAP BPM OData supports OData services for tasks, task data, value help, and processes. As an illustration, we’ll explore the tasks and task data services in the next sections.

OData Services for Tasks

This service can be used to perform different types of actions on tasks, such as retrieving the list of available tasks, reading their data, and claiming and releasing them. There also are many more features included in this service.

This service is represented by the service named tasks.svc. As a result, the base URL becomes http://<hostname>:<port>/bpmodata/tasks.svc.

For a list of URIs available for the tasks service, refer to http://bit.ly/2hKWg7A.

OData Services for Task Data

This service can be used to read data of a task and perform operations such as reading the data of the task’s input and output and completing a task.

This service is represented by the service named taskdata.svc. As a result, the base URL becomes http://<hostname>:<port>/bpmodata/taskdata.svc.

For a list of URIs available for the task data service, refer to http://bit.ly/2uq3m7t.

11.6.2    Error Handling

When unexpected circumstances are encountered during an OData request, a response is returned from SAP PO with an HTTP error status code. The fault response also generally contains a log ID that can be used in the Log Viewer application to further investigate the cause of the exception.

For a full list of possible HTTP status codes that might be returned by the OData service and their meanings, refer to www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.