Skip to main content
Skip table of contents

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:

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

service_api_imported_connector.png

Delete the imported connector afterwards. Expand the Types package in the service panel tree to find the Condition class:

service_api_change_condition_class.png

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):

service_api_connector_with_parameters.png

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

DESC

Sort in descending order.

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:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.