PUT /rest/bpm/federated/v1/instances[?offset={integer}][&size={integer}][&getFieldsValues={boolean}][&alphabeticalSort={boolean}][&calcStats={boolean}][&filterByCurrentUser={boolean}][&includeAllBusinessData={boolean}][&systemID={string}][&instanceType={string}][&caseScope={string}][&queryFilter={string}]
Valid field names that may be used in the 'fields' and 'sort' sections are based on the metadata fields names returned from these REST APIs:
Valid field names that may be used in the 'conditions' section are based on the metadata fields names returned from this REST API:
| Name | Value Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| offset | integer | Specifies the index (origin 0) of the first entity in the query result set. Offset 0 refers to the first entity in the result set; offset 1 to the second entity, and so on. If this parameter is not specified, 0 is used as the default value. Use this parameter with the size parameter to provide paging in the process instance list. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| size | integer | Specifies the maximum number of entities to be returned. If this parameter is not specified, 25 is used as the default value. Use this parameter with the offset parameter to provide paging in the process instance list. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getFieldsValues | boolean | If set to true, the search execution will not return any matching process instance but will return instead a single item with one array attribute per requested field. This array contains the actual values gathered in the federated indices for this field across all the process instances matching the search:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| alphabeticalSort | boolean | By default, this parameter is set to false: the values that result from a sorted query on string fields are case-sensitive (lexicographical sorting order). For example, in ascending order: "Alan", "Zoe", "bernard". Set this parameter to true if you want the query result values to be case-insensitive (alphabetical sorting order). For example, in ascending order: "Alan", "bernard", "Zoe. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| calcStats | boolean | Specifies that 'stats' response values should be returned. The statistics will include the total number of process instances found in this query, the number of active process instances that are at risk, overdue, and on track. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| filterByCurrentUser | boolean | This parameter is a flag that indicates whether or not the search results should be restricted to the entities that are
associated with the current user. A value of Note: This parameter is used only when the request is executed by a user who belongs to the "adminSavedSearch" security-role. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| includeAllBusinessData | boolean | By default, this parameter is set to false. If set to true, all existing business data will be returned in the process instances list. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| systemID | string | The ID of a federated IBM BPM system. Use the ID to filter the results for a specific federated system. systemID is a universally unique identifier (UUID), such as f1436904-793d-4a38-8c64-7634dbdae6f6. Use the Process Federation Server /federated/v1/systems rest query to retrieve the list of available systemID. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| instanceType | string | Possible values are:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| caseScope | string | Scope of the search for Case instances (Note that Case instances are only available when running BAW Containers). Possible values are:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| queryFilter | string | A condition language expression that provides additional filtering. You can reference any of the fields that are defined in the saved search definition. This filter will be combined with the conditions of the saved search definition. The queryFilter parameter is a group of expressions separated by the AND & OR keywords, optionally grouped within parenthesis, similar to a SQL WHERE clause (including the usage of single quotes for string literals). Example: (Expression1 OR Expression2) AND Expression3 The syntax of an expression is as follows: <expression> := <field> <operator> [<value>] <expression> := [(]<expression> AND <expression>[)] <expression> := [(]<expression> OR <expression>[)] <field> can be any of the process instance fields that are returned by the saved search. <operator> depends on the type of the field. The following table details which operator is available for which type of field:
Note that there might be some restrictions on the available operators for some predefined fields, in which case a CWMFS4102E error will be returned by the rest API, with an explanation message that lists the operators available for the field. <value> itself has the same type than the field. Here is the supported syntax for <value>:
|
The default content type is application/json.
{ "description": "Process Instance Saved Search",
"type": "object",
"properties":
{
"id" : {
"description": " The ID of this Saved Search - This is a system generated ID and will be returend in the response.
When doing the following functions the 'id' will be handled differently
Create: The ID must be omitted when creating a saved search definition.
Update: If supplied in the incoming payload it must match the id of the saved search definition being updated.
Ad hoc execution: If supplied in the incoming payload it will be ignored.",
"required":false,
"type" : "integer"
},
"name" : {
"description": " The name of this Saved Search. The name will be check with the following rules
* An 'owner' may only own one saved search with the name(shared or not shared)
* There may only be one saved search shared with the name
* Saved searches that are not shared may have the same name if they have different owners
* Must not be a number (to avoid name/id conflicts)",
"required":true,
"type" : "string"
},
"owner" : {
"description": " The owner of this Saved Search - This will be assigned by the system to the current logged in user's
unique user ID. When included it must be the unique security name. With many user registries, this is
the user's distinguished name (dn, sometimes referred to as the long name).
Only saved search administrators (users with the action role ACTION_ADMINISTER_SHARED_SAVED_SEARCHES)
can create a saved search using another user's ID
see the following to get the list of action roles for the current user
/rest/bpm/federated/v1/searches/actions",
"required":false,
"type" : "string"
},
"shared" : {
"description": " Should this Saved Search be shared with others, Default is false.
Only users with the action role ACTION_CREATE_SHARED_SAVED_SEARCH
can create a shared saved search.
see the following to get the list of action roles for the current user
/rest/bpm/federated/v1/searches/actions",
"required":false,
"type" : "boolean"
},
"teams": {
"type": "array",
"description": "The team that the saved search is shared with.
If the saved search is shared an empty teams array indicates that the shared saved search is shared globally with everybody.
The array can optionally include one team to share the saved search with.
The teamId must be a team that the user is a member of or manager of.
Saved search administrators can share with any team.
Sharing with multiple teams may be supported in future releases.",
"required":false,
"properties" : {
"teamId": {"type": "string",
"description": "The team id."
},
"teamName": {"type": "string",
"description": "The team name. Used in returned JSON and ignored if included as part of payload."
},
"processAppName": {"type": "string",
"description": "The process app where the team was defined / modeled. Used in returned JSON and ignored if included as part of payload."
}
}
},
"fields" : {
"description": " The list of fields to include in this Saved Search",
"required":false,
"type" : "[string]"
},
"aliases": {
"type": "array",
"description": "The aliases for business data fields of a saved search.",
"required":false,
"properties" : {
"field": {
"type": "string",
"description": "The business data field the alias is for."
},
"processName": {
"type": "string",
"required": false,
"description": "The name of the process for which this alias is defined (optional)."
},
"snapshotId": {
"type": "string",
"required": false,
"description": "The snapshot id for which this alias is defined (optional)."
},
"alias": {
"type": "string",
"description": "The alias for the field."
}
}
},
"interaction": {
"description": "Interaction filter for this search to limit the data based on process instance state.
'active' This implies the retrieval of process instances which are currently active and not suspended.
'failed' This implies the retrieval of process instances which have failed.
'completed' This implies the retrieval of process instances which have been completed.
'all' This implies the retrieval of all process instances that the current user is allowed to see, and is the default value.",
"enum":
[
"active",
"failed",
"completed",
"all"
],
"required":false,
"type": "string"
},
"size" : {
"description": " The number of results to be returned when this Saved Search runs.
May be overridden by the 'size' query parameter.
When used with 'offset' query parameter provides the paging function.
Will default to 25 during execution if this saved search did not
specify and the query parameter size was also not specified. ",
"required":false,
"type" : "integer"
},
"sort": {
"description": "Field name to sort on. Only federated system indexes that have
at least one item indexed with this field will be included for the search.
Will default to instanceDueDate if not specified.
see the following to get the lists of fields:
/rest/bpm/federated/v1/searches/meta/fields?searchType=INSTANCE_SEARCH
/rest/bpm/federated/v1/searches/meta/businessDataFields?searchType=INSTANCE_SEARCH",
"required":false,
"type" : "[object]",
"object" : {
"field": {
"description" : "The name of the field to sort on.",
"type": "string",
"required" : true
},
"order": {
"type": "string",
"description": "Ordering for this field - ascending or descending.",
"enum":
[
"ASC",
"DESC"
]
}
},
"conditions": {
"description" : "The conditions that will be converted into query filters to run on the search engine.
These conditions are added together to produce a list of matching process instances.",
"required" : false,
"type" : "[object]",
"object" : {
"field": {
"type": "string",
"description": "Field name to filter on. May be omitted when operator is 'FullTextSearch' to imply that all
fields should be searched.
see the following to get the lists of fields
/rest/bpm/federated/v1/searches/meta/constraintFields?searchType=INSTANCE_SEARCH
/rest/bpm/federated/v1/searches/meta/businessDataFields?searchType=INSTANCE_SEARCH",
"required" : false
},
"operator": {
"type": "string",
"description": "Operation to perform between the stated field and the stated value.
Will default to 'Equals' if omitted.",
"enum":
[
"Equals",
"NotEquals",
"Contains",
"StartsWith",
"LessThan",
"GreaterThan",
"FullTextSearch"
]
},
"value": {
"type": "string",
"description": "Value to be compared against the actual field value. With 'FullTextSearch' the value may be multiple
words and may contain wildcards (*,?,~). 'FullTextSearch' operator is only allowed for constraint fields
where the full_text_search attribute is true (searchable strings)
see the following to get the lists of fields with attributes
/rest/bpm/federated/v1/searches/meta/constraintFields?searchType=INSTANCE_SEARCH
/rest/bpm/federated/v1/searches/meta/businessDataFields?searchType=INSTANCE_SEARCH",
}
}
}
}
{
"shared": true,
"teams":[
{
"teamId":"24.eb30156e-52c8-4ec5-9be6-02290d02f827",
"teamName":"GeneralManagers",
"processAppName":"Hiring Sample"
}
],
"interaction": "all",
"size": 25,
"name": "MySavedSearch",
"sort": [
{
"field": "instanceDueDate",
"order": "ASC"
}
],
"conditions": [
{
"field": "instanceDueDate",
"value": "2016-03-02T05:00:00.000Z",
"operator": "LessThan"
}
],
"fields": [
"instanceDueDate",
"instanceName",
"instanceId",
"instanceStatus",
"instanceProcessApp",
"instanceSnapshot",
"bpdName",
"department",
"gmApproval",
"hiringManager",
"location"
]
}
The default content type is application/json.
{ "description": "Query Result Set",
"type": "object",
"properties":
{ "identifier" : {"type": "string",
"description": "Name of the query result set attribute that identifies an entity."
},
"federationResult":
[
{ "systemID": {"type": "string",
"description": "ID of the IBM Business Automation Workflow system that the request was sent to."
},
"statusCode": {"type": "integer",
"description": "HTTP status code that was returned from this IBM Business Automation Workflow system."
},
"taskCompletionUrlPrefix": {"type": "string",
"description":"The prefix to use for services in this federated IBM Business Automation Workflow system."
},
"restUrlPrefix": {"type": "string",
"description":"The prefix to use for processes in this federated IBM Business Automation Workflow system."
},
"portalSupportUrlPrefix": {"type": "string",
"description":"The prefix to use for access to the portal for this federated IBM Business Automation Workflow system (BPD only)."
},
"systemType": {"type": ["string"],
"description":"The type of this federated IBM Business Automation Workflow system, either "SYSTEM_TYPE_WLE", or "SYSTEM_TYPE_WPS"."
},
"version": {"type": "object",
"description":"The product version on this federated IBM Business Automation Workflow system."
}
}
],
"query": {"type": "string",
"description": "Name of the query that is associated with this query result set."
},
"entityTypeName": {"type": "string",
"description": "Type of entities that are returned as the result of the query."
},
"totalCount": {"type": "integer",
"description": "The number of items in the entire result set."
},
"size": {"type": "integer",
"description": "The number of items returned in the query."
},
"requestedSize": {"type": "integer",
"description": "The number of items requested to be returned in the query."
},
"offset": {"type": "integer",
"description": "The offset into the entire result set where this query response should begin."
},
"attributeInfo":
[ { "name": {"type": "string",
"description": "Attribute name."
},
"type": {"type": "string",
"description": "Attribute type."
},
"isArray": {"type": "boolean",
"description": "Specifies whether the attribute has an array of values."
},
"content": {"type": "string",
"description": "A string that identifies attributes with a well-known value range."
},
"sourceAttribute": {"type": "string",
"description": "The related query table and attribute that provides information about this attributes."
},
"sourceQueryTableIdentifier": {"type": "string", "optional": true,
"description": "The ID of the source attribute's table, as defined in the query table definition."
}
}
],
"stats" :
[ {
"total: {"type": "integer",
"description": "The total number of entities for this query."
},
"open: {"type": "integer",
"description": "The number of entities in the open / active state for this query."
},
"onTrack: {"type": "integer",
"description": "The number of entities in the ontrack state for this query."
},
"overdue: {"type": "integer",
"description": "The number of entities in the overdue state for this query."
},
"atRisk: {"type": "integer",
"description": "The number of entities in the atrisk state for this query."
}
}
],
"items":
[ { "type": "object",
"description": "Entities contained in this query result set; the system ID of the system hosting the entity, a list of attribute names and values as selected by selectedAttributes, and the entities' key (using its source attribute name)."
}
]
}
}
{
"attributeInfo": [
{
"sourceQueryTableIdentifier": "n/a",
"name": "PROCESS_APP_ACRONYM",
"isArray": false,
"type": "STRING",
"sourceAttribute": "instanceProcessApp",
"content": "process.processappacronym.string"
},
{
"sourceQueryTableIdentifier": "n/a",
"name": "PI_PIID",
"isArray": false,
"type": "ID",
"sourceAttribute": "instanceId",
"content": "instance.piid.key"
},
{
"sourceQueryTableIdentifier": "n/a",
"name": "PI_DUE",
"isArray": false,
"type": "TIMESTAMP",
"sourceAttribute": "instanceDueDate",
"content": "instance.duetime.date"
},
{
"sourceQueryTableIdentifier": "n/a",
"name": "PI_NAME",
"isArray": false,
"type": "STRING",
"sourceAttribute": "instanceName",
"content": "instance.processinstancename.string"
},
{
"sourceQueryTableIdentifier": "n/a",
"name": "SNAPSHOT_NAME",
"isArray": false,
"type": "STRING",
"sourceAttribute": "instanceSnapshot",
"content": "instance.snapshotname.string"
},
{
"sourceQueryTableIdentifier": "n/a",
"name": "PT_NAME",
"isArray": false,
"type": "ID",
"sourceAttribute": "bpdName",
"content": "process.processtemplatename.key"
},
{
"sourceQueryTableIdentifier": "n/a",
"name": "PI_STATUS",
"isArray": false,
"type": "ID",
"sourceAttribute": "instanceStatus",
"content": "instance.status.key"
},
{
"sourceQueryTableIdentifier": "n/a",
"name": "PROCESS_INSTANCE.PIID",
"isArray": false,
"type": "ID",
"sourceAttribute": "instanceId",
"content": "instance.piid.key"
}
],
"totalCount": 1,
"offset": 0,
"queryExecuteTime": "2021-03-31T12:34:40Z",
"requestedSize": 25,
"identifier": "PROCESS_INSTANCE.PIID",
"query": null,
"federationResult": [
{
"restUrlPrefix": "http://baw-db21.mycompany.com:9080/rest/bpm/wle",
"systemID": "4a8a5317-808e-48fe-964e-ff489ed356ce",
"displayName": "BPM20002",
"systemType": "SYSTEM_TYPE_WLE",
"portalSupportUrlPrefix": "http://baw-db21.mycompany.com:9080/portal",
"id": "bpm20002",
"taskCompletionUrlPrefix": "http://baw-db21.mycompany.com:9080/teamworks",
"version": "8.6.2.20002",
"indexRefreshInterval": 2000,
"statusCode": "200"
}
],
"size": 1,
"items": [
{
"SNAPSHOT_NAME": "VS_8600",
"PI_STATUS": "Active",
"PI_NAME": "Advanced Employee Requisition NG (List) for Roland Peisl (6528)",
"systemID": "4a8a5317-808e-48fe-964e-ff489ed356ce",
"PI_DUE": "2021-04-02T12:23:34.924Z",
"PROCESS_APP_ACRONYM": "HSAV1",
"PROCESS_INSTANCE.PIID": "6528",
"PI_PIID": "6528",
"PT_NAME": "Advanced HR Open New Position"
}
],
"entityTypeName": "INSTANCE"
}
| Code | Description |
|---|---|
| 200 OK | The request completed successfully. |
| 400 Bad Request | The parameters are not valid or they are missing. |
| 401 Unauthorized | The caller is not authorized for this request. |
| 406 Not Acceptable | The requested content type or content encoding is not supported. |
| 415 Unsupported Media Type | The content type or content encoding of the request is not supported. |
| 500 Internal Server Error | A severe problem occurred. |
| 503 Service Unavailable | The federated request could not be delivered to individual federation targets. |
| 504 Gateway Timeout | The federated response has partial content because of missing individual responses. |
21.0.2
Parent Topic: Process Instance List Resource