The Process Federation Server REST APIs

Edit online

Process Federation Server includes REST APIs that you can use to build custom client applications to support task worker scenarios in federated environments, for example, querying a federated task list, working on the returned tasks, and starting new instances from a federated launch list.

Note: Process Federation Server is not available in IBM® Business Automation Workflow Express.

The Process Federation Server REST APIs are based on the federated Business Automation Workflow or IBM BPM REST APIs but differ in the following ways:

Process Federation Server REST APIs focus on a subset of APIs that are required for task worker scenarios.
Process Federation Server REST APIs are for aggregate sets of resources, such as the task list. The APIs query a distributed index on the process federation server, instead of querying each of the federated systems individually as is the case for the federated REST APIs. This query behavior improves performance and offloads expensive queries from the federated systems.
For working with individual resources, for example, claiming or working on an individual task, client applications work directly against the system that hosts the task. In this way, existing client code that interacts with a single system resource will continue to work as is.

To ease the transition of existing clients from the federated APIs to the Process Federation Server REST APIs, the Process Federation Server REST APIs use the same API signature as the federated REST APIs.

REST APIs

The Process Federation Server REST APIs include the following REST APIs. An example URL is provided for each of the APIs. Many of the URLs represent an HTTP GET request, which means that you can test REST API GET methods directly in your browser and examine the response content.

Launch Entities REST API

Provides a federated list of the processes, services, and BPEL invocation tasks that can be started by the current logged-on user. The following figure shows how the REST services for the launch interact with the components in the federated environment.

The figure is explained in the surrounding text.

Attributes are returned for each startable item and depend on the federated system type. The attributes include a system ID that indicates the system that the item runs on. The federationResult section in the response data contains an entry for each system ID that indicates the URLs to use for working with that system.

Example: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/launchableEntities

Saved Search REST API

Provides methods for creating, retrieving, updating, and deleting saved searches in federated environments. The searches are stored in the Process Federation Server database.

Note: Although you can run an ad hoc search to retrieve a list of process instances, you cannot save and then retrieve a saved search for process instances.

Examples:

Create a saved search: [POST][include saved search payload]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/tasks

Retrieve a specific saved search: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/tasks/2

Update specific saved search: [PUT][include saved search payload]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/tasks/My Saved Search

Delete a saved search: [DELETE]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/tasks/2

Retrieve a list of searches available to the requesting user: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/tasks

Retrieve a list of saved search authorization roles for the requesting user: [GET]
```
https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/actions
```
Depending on the user's role, the appropriate actions are returned:
- Users with the ACTION_ADMINISTER_SHARED_SAVED_SEARCHES action role can create or update a shared saved search definition to be owned by another user's ID.
- Users with the ACTION_CREATE_SHARED_SAVED_SEARCH action role can create or update saved search definitions to be shared.
- Users with the ACTION_RUN_SAVED_SEARCH action role cannot create or update saved search definitions.
- Users with no action role (the API returns an empty array) can create and update personal saved searches.
For more information about authorizations for saved searches in federated systems, see Federated systems and authorization for saved searches.

The saved search payload for the POST (create) and PUT (update) methods is an HTTP request payload in JSON format. For example:

{ "name": "My Saved Search",
  "shared": false,
  "conditions": [{"field": "applicationName", "value": "Process1", "operator": "Equals" }],
  "sort": [{"field": "taskDueDate","order": "ASC"}],
  "fields": ["taskDueDate","taskId","applicationName"],
  "interaction": "claimed",
  "size": 10 }

Attention: Before V8.5.7, any user could modify or delete a shared saved search that another user created. This behavior is improved in the Saved Search API introduced in V8.5.7 by allowing only the saved search owner and administrators to modify or delete shared saved searches. If you want the Process Federation Server Saved Search APIs to behave the same as the deprecated Saved Search API, set the value of the adminSharedSavedSearch action role in the server.xml file on the process federation server to ALL_AUTHENTICATED_USERS.

You can also restrict the rights to create and update saved searches to a user or group of users. For more information, see Administering Process Portal searches and saved searches.

V21.0.2 Search Metadata REST API

Provides metadata related to saved searches. Use the API to determine the filter criteria you can apply to fields in the task query and whether the fields support full-text search. A parameter is also available to retrieve this information for business data fields. In addition, you can use the API to retrieve the allowed values for task status and task priority.

By default, the returned metadata applies to a task search, but if you set the parameter searchType to INSTANCE_SEARCH you can retrieve instance search metadata instead. The following example returns the list of fields that can be used in an instance saved search:
Example: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/meta/fields?searchType=INSTANCE_SEARCH

Available fields

Example: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/meta/fields

Returns name/type pairs for each of the fields in the search. The data type can take one of the following values: String, Date, Time, Decimal, Boolean

Filter criteria

Example: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/meta/constraintFields

Returns the fields that can be used as filters. Each field also includes the data type and a full_text_searchable attribute.

Business data fields

Example: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/meta/businessDataFields

Returns the business data fields. Each field also includes the data type and a full_text_searchable attribute. For example,

{
   "result":[{
      "name":"customer_name",
      "type":"String",
      "full_text_searchable":true
     },
     { 
      "name":"phone",
      "type":"Integer",
      "full_text_searchable":false
     }
     ]
}

By design, Process Federation Server returns all business data fields that it detects as included in process instances. It does not detect business data fields that are modeled but not included in any instances yet.

Status and priority

Examples: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/meta/taskStatus

Returns the allowed values for the task status.

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/meta/priority

Returns the allowed values for the task priority.

Global Team REST API

Provides a list of teams the calling user can share saved searches with.

Note: This API only includes BPD process teams defined by process applications deployed on federated Business Automation Workflow V18.0.0.1 servers and later. This API does not apply to BPD teams defined by process applications deployed on federated business process management servers V8.6.0 and earlier.

Example: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/globalTeams

Returns an array of teams the calling user can share saved searches with. An empty array means that the calling user can only share saved searches with everybody.

Systems Metadata REST API

Provides information about the federated systems. Use the API to detect whether a system is available or to retrieve system-specific settings. Attributes are returned for each system and depend on the system type.

Example: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/systems

Task List REST API

Provides the federated task list. The following figure shows how the REST services for the task list interact with the components in the federated environment.

Fields are returned for each task and depend on the federated system type. The fields include a system ID that indicates the system that the task runs on. The federationResult section in the response data contains an entry for each system ID that indicates the URLs to use for working with that system.

Examples:

Base task query URL: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/tasks

Base task query URL with saved search referenced by ID: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/tasks?savedSearch=2

Task query with interaction filter and specific task fields and sort fields: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/tasks?interaction=claimed_and_available&size=25&offset=0&fields=taskState,taskDueDate,taskPriority,instanceName,taskActivityName,assignedToUser,taskStatus&sort=taskDueDate,taskPriority

Task query for the second page of search results: [PUT][include saved search payload]
```
https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/tasks?size=10&offset=10
```

V21.0.2 Process Instance List REST API

Provides the federated process instance list. Fields are returned for each process instance, and only return BPD process instances, as this API only applies to data from BPD systems. The fields include a system ID that indicates the system that the process instance runs on. The federationResult section in the response data contains an entry for each system ID that indicates the URLs to use for working with that system.

Examples:

Base process instance list query URL: [PUT] [include saved search payload]
```
https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/instances
```
process instance list query for the second page of search results: [PUT] [include saved search payload]
```
https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/instances?size=10&offset=10
```

Note: If you run Process Federation Server in a container environment, this API also returns Case instances. For more information, see the detailed description of the Process Instance List Resource.

Saved Search Transfer REST API

Provides methods for exporting and importing saved searches in federated environments. The exported saved searches are retrieved from federated systems version 8.5.7 or later. The imported searches are stored in the Process Federation Server database. The saved search definitions that are recorded in the Process Federation Server database can be retrieved as a list and exported.

Examples:

Export a specific saved search: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/transfer/bpd/system/federatedSystem1/search/MySavedSearch

Export a list of saved searches from a federated system to the requesting user: [GET]

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/transfer/bpd/system/federatedSystem1

Export a list of saved searches from all federated systems to the requesting user: [GET]
```
https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/transfer/bpd/systems
```
Import one saved search or more: [POST][include list of saved searches payload]
```
https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/transfer
```
Export a list of saved searches recorded in the Process Federation Server database: [GET]
```
https://pfsHost.mycompany.com:9443/rest/bpm/federated/v1/searches/transfer
```

Users can only import shared saved searches if their role allows them to create or administer such saved searches.

The list of saved searches payload for the POST method is an HTTP request payload in JSON format, and corresponds to the result list returned by the GET methods. For example:

[
    {
      "importName": "my_pfs_saved_search_1",
      "exportedFrom": {
        "id": "federatedSystem1"
      },
      "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",
          "nombre@String",
          "GMApproval@Boolean",
          "orderID@String",
          "HiringManager@String",
          "taskDueDate"
        ],
        "conditions": []
      }
    },
    {
      "importName": "my_pfs_saved_search_2",
      "exportedFrom": {
        "id": "federatedSystem2"
      },
      "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": []
      }
    }
  ]

For more information about how to use this Saved Search Transfer REST API, see Importing saved searches into Process Federation Server.

Process Portal is an example of the types of client application that you can build by using the Process Federation Server REST APIs.

V20.0.0.2 REST APIs for the Team Performance Dashboard

As of V20.0.0.2, Process Federation Server introduces a new set of REST APIs that allow BPD Team managers to gather key performance indicators for their teams. These new REST APIs can be leveraged to create a federated Team Performance Dashboard, similar to the non-federated Team Performance Dashboard that is available in Process Portal.

Note: These new REST APIs are only available when Process Federation Server is setup to use an external Elasticsearch cluster.

Note: These APIs work only for teams that were defined with Business Automation Workflow servers V20.0.0.2 and later, or with earlier versions which have APAR JR63189 installed.

Team Summaries REST API

Returns the list of BPD teams managed by the calling user, with the following information for each BPD team:

team id
team name
team description
id of the BPD process application that defines the team
name of the BPD process application that defines the team
number of open tasks for this team
number of on track tasks for this team
number of tasks that are at risk for this team
number of overdue tasks for this team
number of tasks completed today for this team

This API provides an overview of all the BPD teams that are managed by the calling user.

Example:

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v2/dashboards/teamsummary

Team Summary REST API

This API is similar to the Team Summaries API, except that it returns the information for only one of the BPD teams that are managed by the calling user.

The following example retrieves information about the team whose id is 24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574:

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v2/dashboards/teamsummary/24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574

Team Tasks Turnover Rate REST API

Returns the number of tasks created and completed hourly or daily, within a customizable time frame, for a BPD team managed by the calling user. For each data point returned by this API (one per hour or one per day for the chosen time frame), the following information is returned:

the number of tasks created for this team
the number of tasks completed for this team

The following example retrieves one data point per hour for the last 48 hours for the team whose id is 24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574:

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v2/dashboards/teamtasktrend/24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574?units=HOUR&numPeriods=48

The following example retrieves one data point per day for the last 31 days for the team whose id is 24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574:

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v2/dashboards/teamtasktrend/24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574?units=DAY&numPeriods=31

Team Member List REST API

Returns a list of users that are members of a team managed by the calling user, with the following information for each user:

name
full name
job title
phone number
email address
number of tasks assigned
number of tasks completed today

The following example retrieves information about members of the team whose id is 24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574:

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v2/dashboards/teammember/24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574

Team Member Summary REST API

Returns information about all of the user's tasks (including tasks from other teams), along with the user information:

number of tasks completed today
email address
phone number
number of tasks that are overdue
job title
name
full name
number of tasks that are at risk
number of open tasks
number of tasks that are on track

The following example retrieves user information and statistics about the tasks of a team member whose team id is 24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574, and whose username is fdadmin:

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v2/dashboards/teammember/24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d57/fdadmin

Team Tasks REST API

Runs an ad hoc saved search on the tasks of a team managed by the calling user.

The following example retrieves a list of tasks for the team whose id is 24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d574:

https://pfsHost.mycompany.com:9443/rest/bpm/federated/v2/dashboards/teamtasks/24.d0d5eaa0-8b7e-4e8c-85e7-5676d3e9d57

Response data

In addition to the requested content, REST API responses that return a list of federated resources include a federationResult data section that provides information about the federated systems in the federated environment. The data section includes an entry for each federated system. The federationResult section can include the following attributes:

Table 1. Attributes in the federationResult section
Attribute	Description
indexRefreshInterval	Task list queries are based on the Process Federation Server index. The indexRefreshInterval attribute indicates how often the index is updated, so that you can understand how fresh the returned data is. For example, if you modify a task and then immediately query the task list again, you might not see your update. Take this lapse time into consideration when you develop custom applications that are based on the REST service. Consider caching updates locally until the data is refreshed. The value, in milliseconds, is based on the value of the indexRefreshIntervalForClients property in the `ibmPfs_federatedSystem` element in the server.xml configuration file. By default, the index is cached for 2 seconds, so you might not see status changes immediately. For more information about the configuration property, see Configuration properties for the Process Federation Server index.
statusCode	Indicates the status of the federated system. The value of the attribute depends on whether the system can be queried by the process federation server. Attribute values. 200 The federated system is running normally. 408 The REST request cannot access the federated system because the request timed out. 503 The REST request cannot be processed because the federated system is unavailable. By default, the system status is cached for 300 seconds, so you might not see status changes immediately. You can change the cache time by updating the ibmPfs_restConfig cacheRefreshTime property in the server.xml configuration file, for example: `cacheRefreshTime="200s"`
taskCompletionUrlPrefix	Indicates the root URL for completing tasks from a federated system, for example, `https://bpmHost.mycompany.com:9443/teamworks`. To complete a task from a specific system, use the taskCompletionUrlPrefix attribute to go directly to it. The value is based on the value for the ibmPfs_federationSystem taskCompletionUrlPrefix property in the server.xml configuration file. If the system uses an HTTP server or reverse proxy server, use the URL of the HTTP server or reverse proxy server in front of the federated system as the value in the server.xml file.
restUrlPrefix	Indicates the root URL for REST requests on a federated system, for example, `https://bpmHost.mycompany.com:9443/rest/bpm/wle`. To make REST requests to a system (for example, to modify a task on this system), use the restUrlPrefix attribute to go directly to it. The value is based on the value that is configured for the ibmPfs_federationSystem restUrlPrefix property in the server.xml configuration file. If the system uses an HTTP server or reverse proxy server, use the URL of the HTTP server or reverse proxy server in front of the system as the value in the server.xml file.
systemType	Indicates the federated system type, for example: `SYSTEM_TYPE_WLE` for BPD systems `SYSTEM_TYPE_WPS` for BPEL systems
displayName	The name that is used for Process Federation Server in user interfaces and messages.
systemID	Indicates the unique identifier of the federated system, for example, "a85ce736-a156-49cc-a41f-1a8ed9693357". The systemID attribute is included in every federated resource so that you can associate the resource to a system.
version	Indicates the version of the federated system, for example, "8.5.7.0"