Querying Persistent State Objects via the Service API

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:

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.

Find the service you want to query data from in the service administration and open the details page.
Click Download 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:

Property	Type	Remark
e2eType	String	Type of the attribute to filter by.
value	Any	Value to compare against.

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.

Name	Type	Direction	Description
options	InstanceListRequest	in	Use this parameter to provide the search options.
externals	Boolean	in	Some of data of the service instances is stored to an external database for performance reasons. Use this parameter to define whether the external data of the service instances should be loaded or not.
response	<your service name>Instances	out	This parameter returns a complex object that contains a list of matching service instances together with some meta data.

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

Property	Type	Description	Allowed Values	Example
filter	Condition	Provide a query condition.		^{ ^{"from": "2024-01-01T00:00:00",} ^{"to": "2024-04-01T00:00:00",} ^{"sortDirection": "DESC"} ^}
paging	PagingInstruction	Provide options to paginate the results (number of results to return, number of elements to skip).
roles	Array of String	Specify an array of roles you want to get instances of. All instances the specified roles have no access to are omitted.	a list of valid roles	^{ ^{"roles": ["acme-manager"]} ^}
sort	Array of SortInstruction	Provide a list of attributes to sort by and the related direction.

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.

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
e2eType	String	Type of the of the attribute selected for the query. This type will always be one of the types listed in package pas.form.elements.datatable.filter.	...BooleanCondition	The attribute is of type Boolean.	pas.form.elements.datatable. filter.BooleanCondition
			...DateTimeCondition	The attribute is of type DateTime.
			...FloatCondition	The attribute is of type Float.
			...IntegerCondition	The attribute is of type Integer.
			...StringCondition	The attribute is of type String.
operator	String	Operator for the comparison of attribute and value.	`=`	Equal	=
			`!=`	Not equal
			`<`	Less than
			`<=`	Less or equal
			`>`	Greater
			`>=`	Greater or equal
value	Any	Value to compare the attribute against.			true

PagingInstruction

Property	Type	Description	Allowed Values		Example
limit	Integer	Maximum number of elements to return. This can be used to paginate the results.	any integer > 0		10
skip	Integer	Number of elements to skip. This can be used to paginate the results.	any integer		20

SortInstruction

Property	Type	Description	Allowed Values		Example
attribute	String	Name of the attribute to sort by.	a valid name of an attribute		expressShipping
direction	String	Sorting direction.	ASC	Sort in ascending order.	ASC
direction	String	Sorting direction.	DESC	Sort in descending order.	ASC

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.

PersistentState_Query_Example

Click here to download a simple example model that shows how you can query process instances from another service in Scheer PAS Designer.
For this example to work, you also need to deploy the Simple_Order_Service.

Related Pages:

xUML Service Interface