You can use the xUML Runtime API of a service to access process instances of this service. This is done by configuring a connector with the OpenAPI file of the service you want to access.

To use the xUML Runtime API in a Designer service, proceed as follows:

1. Define search keys on the service to be queried.
2. Get the OpenAPI descriptor file of the xUML Runtime API of the service.
3. Import the file as a connector to your Designer service.
4. Use a POST on the persistent state class to query for instances.

Step 1: Define Search Keys

In general, persistent state classes can be queried by so called search keys. If you want to query for specific instance data, this data need to be defined as a search key. You can do that by adding this data to the instance list of the service. All data items of the instance list are persistent state search keys.

Step 2: Get the OpenAPI File

The OpenAPI file of the xUML Runtime API of the service 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 as a Connector

Import the downloaded xUML Runtime API descriptor as a connector to your service as described in detail on Creating an OpenAPI Connector. You only need to import the xUML_Runtime_API/pstate/classes/{class}/queryObjects/POST operation.

Step 4: Query for Instances

The Runtime API provides an endpoint to query process instances at xUML_Runtime_API/pstate/classes/{class}/queryObjects/POST. The persistent state database that stores the process instances can be queried by search keys that are defined on the persistent state class (see Step 1: Define Search Keys).

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

For how to build a query refer to Building Queries below.

Building Queries

The query parameter of the Runtime API is of type XUMLPersistentStateObjectQueryWithKeys . 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"
}

["Error"]

{
  "attribute": "expressShipping",
  "operator": "=",
  "value": "true",
  "conditionsType": "simple"
}

{
  "attributeType": "attribute",
  "attributeName": "price",
  "direction": "ASC"
}

Query Parameter Types

XUMLPersistentStateObjectQueryCondition

XUMLPersistentStateObjectQueryDateCondition

XUMLPersistentStateObjectQuerySortCondition

Building Complex Queries

Using the conditions property of the query parameter, you can build complex queries by joining multiple queries together by a disjunction (or) or a conjunction (and).

Assuming you have two simple queries  conditions[0] and  conditions[1] of type XUMLPersistentStateObjectQueryCondition, you can join them to an and query using a conditionsType of conjunction :

In the example above,  conditions[0] and  conditions[1] are simple queries. They also could be complex queries instead. Like that you can build very complex combinations of and and or queries.

Sorting the Results

You can also sort the query results by adding sort conditions of type XUMLPersistentStateObjectQuerySortCondition to your query (see XUMLPersistentStateObjectQuerySortCondition 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 .