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 or INSTANCES. 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 and BPEL for tasks
    • Process and Case 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 and excludes 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 the interaction 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 completed
    • active: 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.
    The default value is 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 see
    • Assigned: only case instances that are assigned to the population
    The default value is 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 the searchFilter parameter of the GET /v1/tasks REST API.
  • json_query (object): new JSON syntax that supports AND, OR and NOT combination of conditions. The json_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 Search aliases 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, and order (string), either ASC or DESC (default to ASC) 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 the sort 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 the calcStats parameter set to true), specified by setting the type (string) parameter of the stats object to Basic
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) otherwise
    • teams (array of objects): list of process teams to share the search query with. If null, undefined or empty while shared is true, 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 field teamId for the process team identifier.
  • owner (object): information about the user that owns the reusable search query
  • creator (object): information about the user that created the reusable search query
  • lastUpdater (object): information about the user that last updated the reusable search query
  • creationDate (string): ISO8601 timestamp of when the reusable search query was created
  • lastUpdateDate (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"
}