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:
- 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>
- 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):
where: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/tokenPFS_USERNAME
andPFS_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.
-
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:
wherecurl -k -H "Authorization: Bearer ACCESS_TOKEN" [...]
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.
- 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.
-
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
- 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).