Migrating Process Federation Server containers from 21.0.1 to 21.0.2

When you upgrade from IBM Cloud Pak® for Business Automation 21.0.1 to 21.0.2, the default Elasticsearch cluster provided by Cloud Pak for Business Automation to store the Process Federation Server indexes is removed and replaced with a new Elasticsearch cluster.

As this new Elasticsearch cluster version prevents reusing indexes created with Business Automation Workflow 21.0.1, saved searches that are stored in an Elasticsearch index must be exported before the upgrade, and imported again after the upgrade. Process Federation Server then re-indexes the data of all the federated systems (BPD and Case) .
Note: This migration procedure does not apply if you use your own Elasticsearch cluster to store the Process Federation Server indexes, as the cluster (and its data) will be kept as it is during the upgrade procedure.

Authenticating against User Management Services (UMS) to be able to export and import data using the command-line

To use command-line utilities such as curl to call the Process Federation Server REST API, and export and import saved searches, you must first obtain an access token by authenticating against the UMS server (see the generic UMS Password crendential flow procedure). You must also perform the following steps, specific to Process Federation Server:
  1. Gather the Process Federation Server UMS_CLIENT_ID and UMS_CLIENT_PASSWORD from the <icp4bacluster-instance-name>-pfs-config-secret kubernetes secret: this secret contains the UMS client configuration file as key ums.xml, from which the information can be retrieved:
    <?xml version="1.0" encoding="UTF-8"?>
<server description="IBM BPM Process Server">
<featureManager>
<feature>openidConnectClient-1.0</feature>
</featureManager>
<openidConnectClient id="umsClient" 
[...] 
clientId="UMS_CLIENT_ID" clientSecret="UMS_CLIENT_PASSWORD"
[...]
</openidConnectClient>
</server>
  2. With the information gathered in step 1, you can now request an access token from UMS by calling the following API (the example given here uses curl on the command-line):
    curl -k -u UMS_CLIENT_ID:UMS_CLIENT_PASSWORD -X POST -d "grant_type=password&scope=openid&username=PFS_USERNAME&password=PFS_PASSWORD" https://UMS_SSO_BASE_URL/oidc/endpoint/ums/token
    where:
    • PFS_USERNAME and PFS_PASSWORD are the credentials of the user for which you request an access token.
    • UMS_SSO_BASE_URL is the location of the <icp4bacluster-instance-name>-ums-sso-route kubernetes route in your Cloud Pak for Business Automation deployment.
  3. You can then reuse the access_token attribute's value from the JSON response returned by UMS after a successful authentication to authenticate against Process Federation Server as user PFS_USERNAME by providing this value as the token for Bearer authentication when calling the Process Federation Server REST API, as shown in the following example:
    curl -k -H "Authorization: Bearer ACCESS_TOKEN" [...]
    where ACCESS_TOKEN is the value of the access_token attribute of the JSON response of a successful UMS authentication.

Exporting saved searches before the upgrade

Note: Only users with the adminSavedSearch role can export a saved search. For more information about defining custom authorizations for Process Federation Server users, see Specifying Process Federation Server user authorizations in the IBM Cloud Pak for Business Automation.
  1. Call the https://PFS_BASE_URL/rest/bpm/federated/v1/searches/transfer REST API to export the saved searches, where PFS_BASE_URL is the location of the <icp4bacluster-instance-name>-pfs-route kubernetes route in your Cloud Pak for Business Automation deployment. For more information about this REST API, see Saved Search Transfer Import / Export Resource - GET Method . The JSON response of this REST API call contains the two following attributes:
    • status, that provides the response HTTP status.
    • results, an array that contains all the exported saved searches.

  2. Save the content of the results attribute as a .json file, that you will use after the upgrade to re-import the saved searches.

Importing saved searches after the upgrade

  1. Call the POST https://PFS_BASE_URL/rest/bpm/federated/v1/searches/transfer REST API, with the fieldValidationBypass parameter set to true, to import the previously exported saved searches, where PFS_BASE_URL is the location of the <icp4bacluster-instance-name>-pfs-route kubernetes route in your Cloud Pak for Business Automation deployment. For more information about this REST API, see Saved Search Transfer Import / Export Resource - POST Method.
Here is a curl command-line example that calls this API to import the saved searches, previously exported to an exported.json file, using the UMS access token ACCESS_TOKEN to authenticate against Process Federation Server:
curl -k -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d @exported.json https://PFS_BASE_URL/rest/bpm/federated/v1/searches/transfer?fieldValidationBypass=true

Rebuilding federated systems indexes after the upgrade

While after the update, the Process Federation Server BPD indexers automatically rebuild the federated BPD systems indexes in the new Elasticsearch cluster, re-indexing the Case federated systems data must be explicitly triggered, using the Case indexing REST API (for more information about the the Case indexing REST API, see Indexing case instances).