The advanced search query definition

The advanced search query definition in JSON format is composed of five main sections that specify:

• The version of the JSON format of the advanced search query definition (jsonFormat field)
• Where to perform the search (datasource field)
• Whose data must be searched (population field)
• What extra conditions the source entries must match to be returned by the search (filters field)
• How to format and to present the results (output field)

It can take one of the following values:

• v1: It defines the initial format of the JSON format and is the default value. When using this format, you must always declare fields in your query by using a simple string representing the field name. In this format, no support is available for business data fields that are defined at the task level (exposed from client-side human services) and you can reference only the following:
  • The following APIs return the Business data variables that are defined at the process instance level:
    • Business Automation Workflow: /rest/bpm/federated/v1/searches/tasks/meta/businessDataFields
    • Process Federation Server: /rest/bpm/federated/v1/searches/tasks/meta/businessDataFields
  • The following APIs return the system fields:
    • Business Automation Workflow:
      • Fields: /rest/bpm/wle/v1/searches/tasks/meta/fields
      • Constraints: /rest/bpm/wle/v1/searches/tasks/meta/constraintFields
    • Process Federation Server:
      • Fields: /rest/bpm/federated/v1/searches/tasks/meta/fields
      • Constraints: /rest/bpm/federated/v1/searches/tasks/meta/constraintFields
• v2: This version of the format is added in Business Automation Workflow 25.0.0 and provides the support of variables that are defined at the task level (exposed from client-side human services). In this format, when you declare fields to output, to filter on using the filters.json_query section, to use as an alias or to sort on, you must provide the field name and the field kind that can be set to System, Instance, or Task.

Example:

{  
    "name": "customer",  
    "kind": "Instance"  
} 

The following APIs return the fields that are declared with kind set to “Instance” or “Task”:

• Business Automation Workflow: /rest/bpm/federated/v1/searches/tasks/meta/businessDataFields?includeTaskFields=true
• Process Federation Server: /rest/bpm/federated/v1/searches/tasks/meta/businessDataFields?includeTaskFields=true

The following APIs return the fields that are declared with kind set to “System”:

• Business Automation Workflow:
  • Fields: /rest/bpm/wle/v1/searches/tasks/meta/fields
  • Constraints: /rest/bpm/wle/v1/searches/tasks/meta/constraintFields
• Process Federation Server:
  • Fields: /rest/bpm/federated/v1/searches/tasks/meta/fields
  • Constraints: /rest/bpm/federated/v1/searches/tasks/meta/constraintFields

For more details on the REST API to retrieve system and business data fields, see the following topics:

• REST interface for BPD-related resources - Search Definition MetaData By Type Resource
• IBM® Process Federation Server REST APIs

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 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"]
}

The population section defines which tasks and instances must be returned by the search and can contain a single field that is named target, which can take one of these following values:

• SELF: Returns tasks and instances that are either owned by or available to the current user.
• MANAGED_TEAMS: Returns tasks and instances that are either owned by or available to users who belong to teams managed by the current user.

The following example shows the details of the default population section:

"population": {
    "target": "SELF"
}

A filter is a set of conditions on public task or instance fields. Only the tasks or instances that match the additional conditions that are defined in the filters section are 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 are 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 that 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.
  Note:

  The v1_conditions, v1_queryFilterand, v1_searchFilter fields ease the migration from the V1 saved searches to the V2 advanced search queries and from now on use the new syntax available by using the json_query field.

  In the v1_* fields, whichever value is given to jsonFormat, system fields, and business data variables are only referenced as a simple string representing their name. The v1_* fields do not provide any support for business data variables that are defined at the task level.

• 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 conditions (field, operator, value) that can be combined with and, or, and not.
  The following example illustrates a query in JSON syntax (v2 format):

  "json_query": {
      "not": {
        "or": [
          {
            "field": {
              "name": "taskPriority",
              "kind": "System"
            },
            "operator": "GreaterThan",
            "value": 100
          },
          {
            "and": [
              {
                "field": {
                  "name": "customer",
                  "kind": "Instance"
                },
                "operator": "Equals",
                "value": "ACME corp."
              },
              {
                "field": {
                  "name": "product",
                  "kind": "Task"
                },
                "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": {
      "and": [
        {
          "field": {
            "name": "taskPriority",
            "kind": "System"
          },
          "operator": "GreaterThan",
          "value": 100
        },
        {
          "operator": "FullTextSearch",
          "value": "ACME"
        }
      ]
    }
  }

The preceding example is also equivalent to:

"filters": { 
  "interaction": "claimed", 
  "json_query": { 
    "field": { 
      "name": "taskPriority", 
      "kind": "System" 
    }, 
    "operator": "GreaterThan", 
    "value": 100 
  }, 
  "v1_searchFilter": "ACME" 
}

The output section defines how to present the results, based on the following fields that are all optional:

• fields: Array of fields to return for each task or instance. If jsonFormat is set to “v2”, then the fields to return must be specified with the field name and the field kind that can be set to System, Instance, or Task.
  Example:

  "fields": [ 
    {  
      "name": "taskPriority",  
      "kind": "System"  
    },  
    {  
      "name": "customer",  
      "kind": "Instance"  
    }, 
    {  
      "name": "product",  
      "kind": "Task"  
    } 
  ]

  If jsonFormat is not set or set to “v1”, the fields value is an array of strings:

  Example:

  "fields": ["taskPriority","customer"]

• includeAllBusinessData (Boolean): Return all business data fields at once.false is the default value.
• usersFullName (Boolean): Specifies how to format the user's information in the results (full name or user ID). true is the default value.
• aliases (array of objects): List of aliases. If jsonFormat is set to “v2”, then each alias is defined with the field name and the field kind that can be set to System, Instance or Task, and the alias name.
  Example:

  "aliases": [ 
    {  
      "field": { 
        "name": "product",  
        "kind": "Task" 
      }, 
      "alias": "myAlias" 
    } 
  ] 

  If jsonFormat is not set or set to “v1”, the fields value is an alias is simply defined with the field name and the alias name.

  Example:

  "aliases": [ 
    {  
      "field": "product", 
      "alias": "myAlias" 
    } 
  ]

• sort (array of objects): Specifies how to sort the results. Each object in the array has the following two properties:
  • Field that identifies the field to sort on. If jsonFormat is set to “v2”, then the field value is a JSON object with name and kind properties. If jsonFormat is not set or set to “v1”, the field value is a simple string.
  • Order (string), either ASC or DESC (default to ASC) depending on whether the results should be sorted by ascending or descending field value.
• alphabeticalSort (string): sort by alphabetical versus lexicographical order (for string fields that are 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. Currently, there is 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, which are sorted by ascending task at risk time, with a maximum of 50 results, and basic statistics alongside the results:

"output": {
    "fields": [
      {
        "name": "taskNarrative",
        "kind": "System"
      },
      {
        "name": "taskId",
        "kind": "System"
      },
      {
        "name": "instanceId",
        "kind": "System"
      },
      {
        "name": "taskAtRiskTime",
        "kind": "System"
      }
    ],
    "includeAllBusinessData": true,
    "sort": [
      {
        "field": {
          "name": "taskAtRiskTime",
          "kind": "System"
        },
        "order": "ASC"
      }
    ],
    "size": 50,
    "stats": {
      "type": "Basic"
    }
  }

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 (currently, a single value is 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"
}