The advanced search query definition
Advanced search capability is made available through a JSON schema that defines search
queries.
Main structure
The advanced search query definition in JSON format is composed of four main sections that specify:
- where to perform the search (
datasource
field) - whose data should be searched (
population
field) - what additional conditions the source entries must match to be returned by
the search (
filters
field) - how to format and to present the results (
output
field)
datasource
The
datasource
section includes the following fields that are all optional:datatype
(string) defines the type of data to retrieve:TASKS
orINSTANCES
.TASKS
is the default value.systemTypes
(array of strings) defines the type of systems where the data is to be retrieved from:Process
,BPEL
,Case
. The default value depends on the type of data:Process
andBPEL
for tasksProcess
andCase
for instances
systemFilter
(object) defines a list of systems to include or not when searching. This is an object with two fields (arrays of strings),includes
andexcludes
to respectively list IDs of systems to include or exclude for the search.
The following example shows the details of a
datasource
section to search for
BPD (Process) and BPEL tasks on all systems except the one with system ID
"4a8a5317-808e-48fe-964e-ff489ed356ce":"datasource": {
"datatype": "TASKS",
"systemTypes": ["Process", "BPEL"],
"systemFilter": {
"excludes": ["4a8a5317-808e-48fe-964e-ff489ed356ce"]
}
}
This other example shows the details of a
datasource
section to search for case
instances on all systems:"datasource": {
"datatype": "INSTANCES",
"systemTypes": ["Case"]
}
population
The
population
section currently supports a single target and can be omitted
from the search query:target
(string):SELF
(searching your own tasks and instances)
The following example shows the details of the default
population
section:"population": {
"target": "SELF"
}
filters
A filter is a set of conditions on public task or instance fields. Only the tasks or instances
that match the additional conditions defined in the
filters
section
will be returned by the search. The filters
section includes the
following fields that are all optional:interaction
(string) leverages private fields to allow easy filtering by state. It is the equivalent of theinteraction
field of Saved Searches and supports the same values:claimed
: tasks that have been claimed and are not yet completed (not valid for instances search)available
: tasks that have not yet been claimed and are not yet completed (not valid for instances search)claimed_and_available
: tasks that are not yet completed (not valid for instance search)completed
: tasks or instances that are completedactive
: instances that are not yet completed (not valid for task search)failed
: instances that have failed (not valid for task search)all
: all tasks and instances whatever their current state.
all
.caseScope
(string) is the scope of the search for case instances. Possible values are:Allowed
: all case instances that the population is allowed to seeAssigned
: only case instances that are assigned to the population
Assigned
.v1_conditions
: Saved Search conditions (array of conditions which must all match)v1_queryFilter
(string): SQL-like syntax, same as the queryFilter parameter of GET /v1/tasks and PUT /v1/instances REST API.v1_searchFilter
(string): full text search syntax, same as thesearchFilter
parameter of the GET /v1/tasks REST API.json_query
(object): new JSON syntax that supports AND, OR and NOT combination of conditions. Thejson_query
filter is a JSON Object (tree). The fields are Saved Search conditions (field, operator, value) that can be combined with and, or, and not.The following example illustrates a query in JSON syntax:"json_query": { ”not": { ”or": [{ "field": "taskPriority", "operator": "GreaterThan", "value": 100 }, { ”and": [{ "field": "customer", "operator": "Equals", "value": ”ACME corp." }, { "field": "product", "operator": "Equals", "value": "CP4BA" }] }] } }
The following example shows the details of a
filters
section to retrieve claimed
tasks that have a priority higher than 100, and that have at least one field that includes the
"ACME" word (full text search across all the task fields values):
"filters": {
"interaction": "claimed",
"json_query": {
"field": "taskPriority",
"operator": "GreaterThan",
"value": 100
},
"v1_searchFilter": "ACME"
}
output
The
output
section defines how to present the results, based on the following
fields that are all optional:fields
(array of strings): list of fields to return for each task or instance.includeAllBusinessData
(boolean): return all business data fields at once.false
is the default value.usersFullName
(boolean): specifies how to format user's information in the results (full name or user ID).true
is the default value.aliases
(array of objects): list of aliases (same as Saved Searchaliases
field)sort
(array of objects): specifies how to sort the results. Each object in the array has two fields,field
(string) is the name of a fields to sort the results on, andorder
(string), eitherASC
orDESC
(default toASC
) depending on whether the results should be respectively sorted by ascending or descending field value.alphabeticalSort
(string): sort by alphabetical versus lexicographical order (for string fields referenced in thesort
field).size
(integer): maximum number of results in the response (the default number is 25).stats
(object): statistics to return with the results. There is currently a single type of statistics that can be returned (same than when executing a Saved Search with thecalcStats
parameter set totrue
), specified by setting thetype
(string) parameter of thestats
object toBasic
The following example shows the details of an
output
section for a task search
requesting task narrative, task id, instance id, task at risk time and all business data for the
matching tasks, sorted by ascending task at risk time, with a maximum of 50 results, and basic
statistics alongside the results:"output": {
"fields": ["taskNarrative", "taskId", "instanceId", "taskAtRiskTime"],
"includeAllBusinessData": true,
"sort": [{
"field": "taskAtRiskTime",
"order": "ASC"
}],
"size": 50,
"stats": {
"type": "Basic"
}
}
Reusable search queries metadata
Similarly to Saved Searches, advanced search queries definitions can be stored and shared with team, using the Reusable search queries REST API.
metadata
Reusable search queries have an additional
metadata
(object) field, which has
the following fields: name
(string): a mandatory unique name for the reusable search query;description
(string): an optional description for the reusable search query;sharing
(object): optional information about the reusable search query is shared. It includes the following fields:shared
(boolean):true
to share with other users,false
(default value) otherwiseteams
(array of objects): list of process teams to share the search query with. Ifnull
,undefined
or empty whileshared
istrue
, then the search query is shared with everybody. To share with a specific process team that you are a member or manager of, define this team in the array (note that a single value is currently supported) by using an object with fieldteamId
for the process team identifier.
owner
(object): information about the user that owns the reusable search querycreator
(object): information about the user that created the reusable search querylastUpdater
(object): information about the user that last updated the reusable search querycreationDate
(string): ISO8601 timestamp of when the reusable search query was createdlastUpdateDate
(string): ISO8601 timestamp of when the reusable search query was last updated
The following example shows the details of the
metadata
section for a reusable
search query: "metadata": {
"name": "my tasks list",
"description": "a search query that retrieves my task list",
"sharing": {
"shared": true,
"teams": [{
"teamId": "24.6615a4b0-fd38-4ea5-8bc0-69d2f107369e",
"teamName": "Human Resources",
"processAppName": "Hiring Sample"
}],
},
"owner": {
"id": "jane.doe@acme.com",
"fullName": "Jane Doe"
},
"creator": {
"id": "admin@acme.com",
"fullName": "Administrator"
},
"lastUpdater": {
"id": "user.name@ibm.com",
"fullName": "User Name"
},
"creationDate": "2024-01-31T12:34:42.183Z",
"lastUpdateDate": "2024-02-01T16:03:12.874Z"
}