Querying Persistent State Objects via the Runtime API

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.

If you want to have a some instance data as a search key but do not want to show it, you can define it as a hidden data item in the instance list.

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 Download 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

Property	Type	Description	Allowed Values		Example
creation	XUMLPersistentStateObjectQueryDateCondition	Provide a condition to filter objects by creation date.			{ "from": "2024-01-01T00:00:00", "to": "2024-04-01T00:00:00", "sortDirection": "DESC" }
update	XUMLPersistentStateObjectQueryDateCondition	Provide a condition to filter objects by last update date.
limit	Integer	Use this property to limit the count of returned objects. Use this together with offset for pagination.	1000	Default limit.	5000
states	Array of String	Provide a list of states selected persistent state objects must be in to be part of the result set. All objects that are in one or more of the listed states are selected (disjunction (OR)).			["Error"]
condition	XUMLPersistentStateObjectQueryCondition	Provide a query condition. This can be a simple one or a complex query constructed with a combination of and and or queries.			{ "attribute": "expressShipping", "operator": "=", "value": "true", "conditionsType": "simple" }
offset	Integer	Offset of the return results if limit has been set. Use these two together for pagination.			5001
sort	Array of XUMLPersistentStateObjectQuerySortCondition	Provide a sort condition. sort needs to be escaped when used in Action Script (`sort`).			{ "attributeType": "attribute", "attributeName": "price", "direction": "ASC" }

Query Parameter Types

XUMLPersistentStateObjectQueryCondition

Property	Type	Description	Allowed Values		Example
attribute	String	Name of the search key attribute to use for comparison.	a valid name of an existent persistent state class property that is a search key		expressShipping
operator	String	Operator for the comparison of attribute and value.	=	Equal	=
			!=	Not equal
			<	Less than
			<=	Less or equal
			>	Greater
			>=	Greater or equal
value	String	Value to compare the attribute against.			true
conditionsType	String	Type of the condition.	simple	Marks the condition as simple query condition.	simple
			conjunction	Marks the condition as conjunction (and) of conditions.
			disjunction	Marks the condition as disjunction (or) of conditions.
conditions	Array of XUMLPersistentStateObjectQueryCondition	Recursive list of queries that are related by and or or. You can use this list to build complex nested query structures.	a list of valid queries

XUMLPersistentStateObjectQueryDateCondition

Property	Type	Description	Allowed Values		Example
from	DateTime	Date range to take persistent state object from. from and to need to be escaped when used in Action Script (`from`and `to`).	a valid DateTime		2024-01-01T00:00:00
to	DateTime
sortDirection	String	Sorting direction.	ASC	Sort in ascending order.	DESC
			DESC	Sort in descending order.

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.