POST /rest/bpm/federated/v1/searches/transfer[?fieldValidationBypass={boolean}][&validateOnly={boolean}]
The 'results' section of the query result returned from one of these REST APIs or the content of the file generated with parameter 'outputFile' can be used as input to this REST API to import saved searches to Process Federation Server:
Valid field names that may be used in the 'exportedFrom' section are based on the 'systemID' and 'id' names of the returned from this REST API:
Valid field names that may be used in the 'fields' and 'sort' sections within the 'savedSearch' section are based on the metadata fields names returned from these REST APIs:
Valid field names that may be used in the 'conditions' section within the 'savedSearch' section are based on the metadata fields names returned from this REST API:
The name of a saved search definition to import must be unique among all shared saved search definitions. The value specified in the 'importName' section provided in the list of saved search to import must therefore be unique. The ID of the saved search definition will be assigned by the system and will be returned in the response JSON when the import of all saved searches completes successfully.
Only saved search administrators (users with the action role as defined by the server.xml "adminSharedSavedSearch" security-role)
can import a saved search definition using another user's ID.
See the following to get the list of action roles for the current user
See the section 'authorization-roles id="com.ibm.bpm.federated.rest.authorization"' in the Process Federation Server server.xml to allow users or groups into this role.
Only users with the action role ACTION_CREATE_SHARED_SAVED_SEARCH as defined by the server.xml "createSharedSavedSearch" security-role
can import a shared saved search definition.
See the following to get the list of action roles for the current user
See the section 'authorization-roles id="com.ibm.bpm.federated.rest.authorization"' in the Process Federation Server server.xml to allow users or groups into this role.
| Name | Value Type | Description |
|---|---|---|
| fieldValidationBypass | boolean | Specifies whether or not field name validation should be suppressed, so that saved search definitions can be created even if a business data field is not yet known. If this parameter is not specified, false is used as the default value. |
| validateOnly | boolean | Specifies whether or not the saved search definitions must only be sanity-checked and validated without being effectively imported. If this parameter is not specified, false is used as the default value. |
The default content type is application/json.
{ "description": "Saved Search Transfer List ",
"type": "object",
"properties":
{
[
"importName" : {
"description": "The name that will be assigned to saved search at import time",
"required":true,
"type" : "string"
},
"exportedFrom" : {
"systemId" : {
"description" : "ID of the IBM Business Automation Workflow system",
"required":false,
"type" : "string"
},
"id" : {
"description" : "The ID of the federated IBM Business Automation Workflow system",
"required":true,
"type" : "string"
}
},
"savedSearch" :
{
"id" : {
"description": " The ID of this Saved Search - This is a system generated ID and will be returned 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 checked 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"
},
"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."
}
}
},
"organization": {
"description": "Organization of the tasks, Only allowed value is 'byTask'. Default is 'byTask'.",
"enum":
[
"byTask"
],
"required":false,
"type": "string"
},
"interaction": {
"description": "Interaction filter for this search to limit the data based on task state. May be overridden by the 'interaction' query parameter
'claimed' This implies the retrieval of tasks which are already claimed by the current user. Tasks contained in suspended process instances are excluded.
'available' This implies the retrieval of tasks which can be claimed by the current user. Tasks contained in suspended process instances are excluded.
'claimed_and_available' This implies the retrieval of tasks as implied by the claimed or available filter values.
'completed' This implies the retrieval of completed tasks which are claimed by the current user.
'all' This implies the retrieval of tasks for which the current user is allowed to see.",
"enum":
[
"claimed",
"available",
"claimed_and_available",
"completed",
"all"
],
"required":false,
"type": "string"
},
"size" : {
"description": " The number of tasks 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 will be included in the task query that have
at least one task indexed with this field. May be overridden by the 'sort' query parameter.
Will default to taskDueDate and taskPriority if this saved search did not specify and the query parameter
sort was also not specified.
see the following to get the lists of fields
/rest/bpm/federated/v1/searches/tasks/meta/constraintFields
/rest/bpm/federated/v1/searches/tasks/meta/businessDataFields"
},
"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 tasks.",
"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/tasks/meta/constraintFields
/rest/bpm/federated/v1/searches/tasks/meta/businessDataFields",
"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/tasks/meta/constraintFields
/rest/bpm/federated/v1/searches/tasks/meta/businessDataFields",
}
}
}
}
]
}
}
[
{
"importName": "my_bpm_saved_search_1",
"exportedFrom": {
"id": "bpm1"
},
"savedSearch": {
"owner": "admin",
"shared": false,
"teams": null,
"size": 10000,
"organization": "byTask",
"name": "my_bpm_saved_search_1",
"interaction": "completed",
"id": "1006",
"sort": [
{
"field": "taskDueDate",
"order": "ASC"
}
],
"fields": [
"taskSubject",
"instanceName",
"taskStatus",
"taskPriority",
"rfc@String",
"GMApproval@Boolean",
"HiringManager@String",
"taskDueDate"
],
"conditions": []
}
},
{
"importName": "my_bpm_saved_search_2",
"exportedFrom": {
"id": "bpm2"
},
"savedSearch": {
"owner": "admin",
"shared": true,
"teams": [
{
"teamName": "Managers",
"teamId": "24.581a472b-5016-479a-b5b5-0a9701c2c42c",
"processAppName": "System Data"
}
],
"size": 10000,
"organization": "byTask",
"name": "my_bpm_saved_search_2",
"interaction": "claimed_and_available",
"id": "1004",
"sort": [
{
"field": "taskDueDate",
"order": "ASC"
}
],
"fields": [
"taskSubject",
"instanceName",
"taskStatus",
"taskPriority",
"GMApproval@Boolean",
"EmploymentStatus@String",
"RequisitionNumber@String",
"taskDueDate"
],
"conditions": []
}
},
]
The default content type is application/json.
{ "description": "Saved Search Transfer List ",
"type": "object",
"properties":
{
"imported" : [
"importName" : {
"description": "The name that will be assigned to saved search at import time",
"required":true,
"type" : "string"
},
"exportedFrom" : {
"systemId" : {
"description" : "ID of the IBM Business Automation Workflow system",
"required":false,
"type" : "string"
},
"id" : {
"description" : "The ID of the federated IBM Business Automation Workflow system",
"required":true,
"type" : "string"
}
},
"savedSearch" :
{
"id" : {
"description": " The ID of this Saved Search - This is a system generated ID and will be returned 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 checked 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"
},
"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."
}
}
},
"organization": {
"description": "Organization of the tasks, Only allowed value is 'byTask'. Default is 'byTask'.",
"enum":
[
"byTask"
],
"required":false,
"type": "string"
},
"interaction": {
"description": "Interaction filter for this search to limit the data based on task state. May be overridden by the 'interaction' query parameter
'claimed' This implies the retrieval of tasks which are already claimed by the current user. Tasks contained in suspended process instances are excluded.
'available' This implies the retrieval of tasks which can be claimed by the current user. Tasks contained in suspended process instances are excluded.
'claimed_and_available' This implies the retrieval of tasks as implied by the claimed or available filter values.
'completed' This implies the retrieval of completed tasks which are claimed by the current user.
'all' This implies the retrieval of tasks for which the current user is allowed to see.",
"enum":
[
"claimed",
"available",
"claimed_and_available",
"completed",
"all"
],
"required":false,
"type": "string"
},
"size" : {
"description": " The number of tasks 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 will be included in the task query that have
at least one task indexed with this field. May be overridden by the 'sort' query parameter.
Will default to taskDueDate and taskPriority if this saved search did not specify and the query parameter
sort was also not specified.
see the following to get the lists of fields
/rest/bpm/federated/v1/searches/tasks/meta/constraintFields
/rest/bpm/federated/v1/searches/tasks/meta/businessDataFields"
},
"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 tasks.",
"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/tasks/meta/constraintFields
/rest/bpm/federated/v1/searches/tasks/meta/businessDataFields",
"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/tasks/meta/constraintFields
/rest/bpm/federated/v1/searches/tasks/meta/businessDataFields",
}
}
}
}
],
"failed" : [
"name" : {
"description" : "The name of the saved search that failed to be imported in Process Federation Server.",
"required" : true
"type" : "string"
}
"error" :
{"description": "The detail about the error that prevented this saved search from being imported.",
"type" : "object",
"properties" :
{"status": {"type": "string",
"description": "The status of the previous API call."
},
"exceptionType": {"type": "string",
"description": "The classname associated with the exception."
},
"errorNumber": {"type": "string",
"description": "Message ID of the exception."
},
"errorMessage": {"type": "string",
"description": "Message text of the exception."
},
"errorMessageParameters": {"type": ["string"], "optional": true,
"description":"Message text parameters of the exception."
},
"programmersDetails": {"type": "object", "optional": true,
"description":"Additional exception details, for example, a stack trace."
}
}
}
],
"malformed" : [
"name" : {
"description" : "The name of the saved search that was found not properly formed.",
"required" : true
"type" : "string"
},
"error" :
{"description": "The detail about the saved search format error.",
"type" : "object",
"properties" :
{"status": {"type": "string",
"description": "The status of the previous API call."
},
"exceptionType": {"type": "string",
"description": "The classname associated with the exception."
},
"errorNumber": {"type": "string",
"description": "Message ID of the exception."
},
"errorMessage": {"type": "string",
"description": "Message text of the exception."
},
"errorMessageParameters": {"type": ["string"], "optional": true,
"description":"Message text parameters of the exception."
},
"programmersDetails": {"type": "object", "optional": true,
"description":"Additional exception details, for example, a stack trace."
}
}
}
]
}
}
{
"imported": [
{
"savedSearch": {
"owner": "uid=admin,o=defaultWIMFileBasedRealm",
"shared": false,
"aliases": [],
"size": 10000,
"organization": "byTask",
"name": "my_bpm_saved_search_1",
"interaction": "completed",
"id": 484,
"sort": [
{
"field": "taskDueDate",
"order": "ASC"
}
],
"conditions": [],
"fields": [
"taskSubject",
"instanceName",
"taskStatus",
"taskPriority",
"rfc@String",
"GMApproval@Boolean",
"HiringManager@String",
"taskDueDate"
]
},
"exportedFrom": "bpm1"
},
{
"savedSearch": {
"owner": "uid=admin,o=defaultWIMFileBasedRealm",
"shared": true,
"aliases": [],
"size": 10000,
"organization": "byTask",
"name": "my_bpm_saved_search_2",
"interaction": "claimed_and_available",
"id": 485,
"sort": [
{
"field": "taskDueDate",
"order": "ASC"
}
],
"conditions": [],
"fields": [
"taskSubject",
"instanceName",
"taskStatus",
"taskPriority",
"GMApproval@Boolean",
"EmploymentStatus@String",
"RequisitionNumber@String",
"taskDueDate"
]
},
"exportedFrom": "bpm2"
}
],
"failed": [],
"malformed": [],
"status": 201
}
| Code | Description |
|---|---|
| 200 OK | The request completed successfully. |
| 201 Created | Successful completion, new resource created. |
| 400 Bad Request | The parameters are not valid or they are missing. |
| 401 Unauthorized | The caller is not authorized for this request. |
| 403 Forbidden | The caller is not allowed to complete 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. |
8.5.7
Parent Topic: Saved Search Transfer Import / Export Resource