You can use the REST API of a service to access process instances of this very service. This is done by using the operation that is compiled to the service for building the instance list.

To use the REST API of a service in a Designer service, proceed as follows:

1. Prepare the instance list of the service to contain the data items you want to query for.
2. Get the OpenAPI descriptor file of the service.
3. Import the file to your Designer service.
4. Change the imported type for Condition.
5. Use a POST/ on the service interface to query for instances.

Step 1: Prepare the Instance List

If you want to query specific instance data via the service API, this data must be part of the instance list: As a visible column, or at least as a hidden one. You can configure the instance list as described on Configuring the Columns of the Instance List.

Step 2: Get the OpenAPI File

The OpenAPI file of the service interface can be downloaded from the Administration.

1. Find the service you want to query data from in the service administration and open the details page.
2. Click on the xUML Runtime API endpoint to download the descriptor file.

Step 3: Import the OpenAPI File

Import the downloaded service API descriptor as a connector to your service as described in detail on Creating an OpenAPI Connector. You only need to import the POST/ operation.

Step 4: Change the Condition Class

The imported POST/ operation needs some rework because some properties are missing from the Condition class (this is a known issue).
As a connector cannot be changed, you need to copy the imported connector as an API to the implementation folder to be able to change it:

Delete the imported connector afterwards.

Expand the Types package in the service panel tree to find the Condition class:

Add the missing properties as shown above:

Step 5: Query for Instances

The service API provides an endpoint to query process instances at <your service Name>Rest /POST/. The instances can be queried by all columns that are present on the instance list of the service (see Step 1: Prepare the Instance List).

This endpoint gets a query object and returns a list of persistent state objects and their states.

For how to provide the search options refer to Building Queries below.

Building Queries

The options parameter of the service API is of type InstanceListRequest. It comes with the properties listed in the table below. All properties are optional.

Query Parameters

{
  "from": "2024-01-01T00:00:00",
  "to": "2024-04-01T00:00:00",
  "sortDirection": "DESC"
}

{
  "roles": ["acme-manager"]
}

Query Parameter Types

Condition

If you do not see the properties e2eType and value, you need to add them as described in Step 4: Change the Condition Class.

PagingInstruction

SortInstruction

Building a Query

Using the filter property, you can filter the search result by one filter option.

The example shows how to build such a query in operation setInstanceListRequest :

The query above filters for attribute expressShipping of type pas.form.elements.datatable. filter.BooleanCondition if the value equals the value given by setQueryValue (which is true).

Sorting the Results

You can also sort the query results by adding a sort instructions to your query (see SortInstruction for more details on this class). The query results will be sorted by all configured conditions, similar to what SQL does with ORDER BY.

The example above shows how to sort the query result ascending by search key price .