Use Process Reporting APIs

When you submit a webinterface and trigger a process, you create process instances. Those instances are stored within a RunMyProcess internal database, and you can query them by configuring process reports from IDE, or by using the Process Reporting APIs.

In this tutorial, we will explain step by step how to configure a Composite API to query the Process Reporting API. This will enable you to create charts dashboards, to use the reporting data in a RunMyProcess application or to expose it to a third-party application.

Technically, configuring a process report by adding columns and filters will build a specific url so you can retrieve the process instances matching criterias. The purpose of this tutorial is to understand how this url is built, how the parameters are passed, so you can retrieve process instances via APIs without using native reports (and inject that information in Webinterfaces for example).

Basic Use Case

Let's assume a simple use case for the sole purpose of this tutorial.

You have developped a car purchase application in which every instance is an order associated to an amount and some car details. If the application is supposed to manage stocks, then you'll need to compare how many cars were available in the first place in a specific country with how many were purchased in that country. Comparing those numbers will give you the remaining ones, available for purchase in this country.

The goal is to be able to display the number of remaning cars to a end user that is willing to order a new car to prevent him from purchasing non-available cars.

In that case, the "number of cars purchased for a specific country" can be retrieved using Process Reporting APIs since all the necessary data is already present in process instances.

Process and report configuration

After drawing your process, you had configured measures to be used as custom columns or filters in your webinterface and process reports.

Here's the list of measures in our example process:

Here's a process report displaying process instances:

This process report can have static filters and can also filter on connected user's metadata. You could save it and embed it into your webinterfaces.

Let's add the filters car_country == "Italy" and car_price < 500000:

)

Then click on RSS feed icon (1). That should open a new tab in your browser. Url looks like:

https://live.runmyprocess.com/live/112501473324764966/requestreport/car_booking.csv?
nb=1000&first=0&
filter=MODE+PARENT+PROJECT+PROCESS&
operator=EE+IS+EE+EE&value=TEST+NULL+12411671+13551174&
column=name%20status%20MEASURE_1%20MEASURE_2%20MEASURE_3%20MEASURE_4%20published&language=en

and xml content looks like:

Every entry node is a process instance. So a process report actually calls the report feed url, then parse the xml feed and render it in a table view.

Process Reporting API

Let's have a closer look to the report feed url:

nb is the number of items to retrieve

first is the starting index of the query

column is the list of custom columns (=measures) to be displayed.

name%20status%20measure_1%20measure_1%20measure_3%20measure_4

name and status are system measures, whereas measure_x are the custom measures you've created:

filter is the list of measures you're filtering on

PROJECT:    filter on instances that belong to a specific project (by default it's the current project)
MODE:       filter on execution mode (TEST/ACCEPTANCE/LIVE)
MEASURE_1:  filter on car_country
MEASURE_4:  filter on car_price
PARENT:     filter on instances related to a subprocess (PARENT = ANY) or to father processes only (PARENT = NULL)
PROCESS:    filter on process id

operator is the list of operators to be applied on filters

EE  means Equal(=)
LT  means Lower Than (only for numeric measures)
GT  means Greater Than (only for numeric measures)
IS  means Equal (only for system measures)
CONTAINS means Contains (designed for strings)
NOT_CONTAINS means Doesn't contain (designed for strings)
IN means Appears In the following list separated by coma (ex : country IN France,USA
NOT_IN means opposite of IN

value is the list of values to be applied on related filters & operators

So basically the query we try to perform is:

PROJECT     EE  85524
MODE        EE  TEST
PARENT      IS  NULL
PROCESS     IS  109611
MEASURE_1   EE  Italy
MEASURE_4   LT  500000

Configure a Composite API to perform queries on process instances

Let's build a Composite API that will accept as input parameters country and max_price and that will return the list of matching cars as JSON.

Create the provider.

Create a new Provider. For the 3 environments, fill in url with https://live.runmyprocess.com/ and Authentication scheme with RunMyProcess Secured Connection.

Create the connector

From the provider, create a new Connector. Connector url is

https://live.runmyprocess.com/live/112501473324764966/requestreport/car_booking.csv?
nb=1000&first=0&
filter=MODE+PARENT+PROJECT+PROCESS&
operator=EE+IS+EE+EE&value=TEST+NULL+12411671+13551174&
column=name%20status%20${country}%20MEASURE_2%20MEASURE_3%20${max_price}%20published&language=en

Result format is XML, and Accept media type is application/atom+xml.

Notice MEASURE_1 and MEASURE_4 values have been replaced by ${country} and ${max_price}.

You should then be able to test your connector and pass input parameters:

Related Topics

For more information, you can also consult the following pages

• Charts
• Reports
• Connectors