IBM Support

Readme for Cloud Pak for Automation 20.0.3 IF014

Fix Readme


Abstract

The following document is the documentation for IBM Cloud Pak for Automation 20.0.3 IF014.
Including download and installation information and the list of APARs that are resolved in this interim fix.

Content

Readme file for: IBM Cloud Pak® Automation
Product Release: 20.0.3
Update Name: 20.0.3 IF014
Fix ID: 20.0.3-WS-CP4A-IF014
Publication Date: 18 March 2022
Last modified date: 18 March 2022

Contents

Prerequisites

Components impacted 

Prior to installation

If you installed any of the Cloud Pak components on a Kubernetes cluster, you can update them with 20.0.3 IF014 by using the updated operator and the relevant container interim fixes. Updated images are
  • cp.icr.io/cp/cp4a/fncm/cpe:ga-556-p8cpe-la017
  • Previous interim fixes will have included fixes which may also be addressed with this interim fix. Consult the Related links section for readmes of previous interim fixes, at the bottom of this document. Some images shipped with those previous interim fixes have not been updated with this interim fix. Depending on what components and capabilities you have installed and configured, additional fix information may apply to you, and in which case it is  recommended that these images are updated to the latest available:

  • cp.icr.io/cp/cp4a/ban/navigator:ga-309-icn-la009
  • cp.icr.io/cp/cp4a/ban/navigator-sso:ga-309-icn-la009
  • cp.icr.io/cp/cp4a/bas/bastudio:20.0.3-IF011
  • cp.icr.io/cp/cp4a/bas/workflow-authoring:20.0.3-IF013
  • cp.icr.io/cp/cp4a/baw/pfs-prod:20.0.3-IF011
  • cp.icr.io/cp/cp4a/baw/workflow-server:20.0.3-IF013
  • cp.icr.io/cp/cp4a/baw/workflow-server-case-initialization:20.0.3-IF013
  • cp.icr.io/cp/cp4a/baw/workflow-server-dbhandling:20.0.3-IF013
  • cp.icr.io/cp/cp4a/fncm/taskmgr:ga-309-tm-la009
  • cp.icr.io/cp/cp4a/ums/ums:20.0.3-IF003
  • cp.icr.io/cp/cp4a/icp4a-operator:20.0.3-IF012
  • cp.icr.io/cp/cp4a/ads/ads-runtime:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-admin:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-bawadv:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-bpmn:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-content:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-event-forwarder:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-elasticsearch:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-flink:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-flink-taskmanager:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-flink-zookeeper:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-icm:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-ingestion:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-init:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-kibana:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-management:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-monitoring-app:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-odm:20.0.3-IF012
  • cp.icr.io/cp/cp4a/bai/bai-setup:20.0.3-IF012
  • cp.icr.io/cp/cp4a/baw/pfs-elasticsearch-prod:20.0.3-IF012
To deploy this interim fix as an update to a 20.0.3 deployment, follow the instructions in the Installing section. If you want to use the interim fix as a part of a new deployment or you want to upgrade a release prior to 20.0.3, refer to IBM Documentation. For more information, see IBM Cloud Pak for Automation 20.0.x.

Installing

Step 1: Get access to the interim fix container images
You can access the container images in the IBM image registry with your IBMid.
 
Create a pull secret for the IBM Cloud Entitled Registry
  1. Log in to MyIBM Container Software Library with the IBMid and password that is associated with the entitled software.
  2. In the Container software library tile, click "View library" and then click "Copy key" to copy the entitlement key to the clipboard.
  3. Log in to your Kubernetes cluster and set the context to the project/namespace for your existing deployment.
  4. Create a pull secret by running a kubectl create secret command.
    $ kubectl create secret docker-registry admin.registrykey --docker-server=cp.icr.io --docker-username=cp --docker-password="<API_KEY_GENERATED>" --docker-email=<USER_EMAIL>
    Note: The "cp.icr.io" value for the docker-server parameter is the only registry domain name that contains the images. Use "cp" for the docker-username. The docker-email must be a valid email address (associated to your IBM ID). Make sure you are copying the Entitlement Key in the docker-password field within double quotation marks.
  5. Take a note of the secret and the server values so that you can set them to the "pullSecrets" and "repository" parameters when you update the operator for your containers.
Step 2: Update the installed operator
  1. Log in to your Kubernetes cluster and set the context to the project for your existing deployment.
    $ oc login https://<CLUSTERIP>:<port> -u <ADMINISTRATOR> -p <PASSWORD>
  2. If the persistent volume (PV) for the operator is defined by a hostPath, provide group write permission according to the PV hostPath.path definition (/root/operator).
    $ chmod -R g=u /root/operator
    $ chmod g+rw /root/operator
    Note: If you are using dynamic provisioning, this step is not needed as the PV is created automatically as per the Storage Class definition.
  3. Remove the .OPERATOR_TYPE file in case it exists from a previous deployment.
    $ rm -f /<hostPath>/.OPERATOR_TYPE
    Where hostPath is the value in your PV (root/operator).
  4. If Business Automation Insights is deployed, prune the Business Automation Insights deployment and jobs before you apply the updated custom resource YAML file.
    $ oc delete Deployment,Job -l \
> 'app.kubernetes.io/name=ibm-business-automation-insights'
    Tip: For Flink event processing to resume from its previous state, make sure that savepoints are created before the upgrade and specified in the updated CR. For more information see, https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/20.0.x?topic=tolerance-restarting-from-checkpoint-savepoint
  5. Upgrade the operator in your project by running the following command.  Note that there is no icp4a-operator:20.0.3-IF014 image for this iFix.  Use Operator version icp4a-operator:20.0.3-IF012 to deploy this iFix.
    $ ./scripts/upgradeOperator.sh -i <registry_url>/icp4a-operator:20.0.3-IF012 -p '<my_secret_name>' -a accept
    Where registry_url is the value for your internal registry or cp.icr.io/cp/cp4a for the IBM Cloud Entitled Registry. The my_secret_name is the secret that is created to access the registry, and accept means that you accept the license.
    Note: If you plan to use a non-admin user to install the operator, you must add the user to the "ibm-cp4a-operator" role.
    $ oc adm policy add-role-to-user ibm-cp4a-operator <user_name>
  6. Monitor the pod until it shows a STATUS of Running:
    $ oc get pods -w
    Note: When started, you can monitor the operator logs with the following command:
    $ oc logs -f deployment/ibm-cp4a-operator -c operator
Step 3: Update the custom resource YAML file for your deployment
Get the custom resource YAML file that you previously deployed (for example, scripts/generated-cr/ibm_cp4a_cr_final.yaml) and update the appVersion to "20.0.3.2".  The operator pulls the corresponding 20.0.3.2 container images based on the value of appVersion.
Note: If you are using a new CR from the "cert-kubernetes" GitHub repository that you download from the prerequisites step above, then the appVersion is already set to "20.0.3.2". To ensure you use the 20.0.3-IF014 images, make sure to refer to these updated images in your CR. See list of images and tags in the Prior to installation section, above.  Remember to remove these references to specific images when you upgrade to future versions.
 
Tip: If you use image tags in your CR in your current deployment, then the correct values of the tags can be found in the fully customizable (FC) CR pattern templates provided with the interim fix under ../cert-kubernetes/descriptors/patterns (for example, ibm_cp4a_cr_enterprise_FC_content.yaml has the corresponding image tags for the iFix along with all the parameters that can be customized for the deployment).  Verify that the secret named in the CR YAML file as the imagePullSecrets is valid. Note the secret might be expired, in which case you must re-create the secret.
Step 4: Apply the updated custom resource YAML file
  1. Check that all the components that you want to upgrade are configured with interim fix image tag values.
    $ cat scripts/generated-cr/ibm_cp4a_cr_final.yaml
  2. Update the configured components by applying the custom resource.
    $ kubectl apply -f scripts/generated-cr/ibm_cp4a_cr_final.yaml
Step 5: Verify the updated automation containers
The operator reconciliation loop might take several minutes. When all of the pods are Running, you can access the status of your containers by running the following commands:
$ oc status
$ oc get pods -w
$ oc logs <operatorPodName> -f -c operator
Step 6: Performing the necessary tasks after installation
  1. Update the deployment to use the Business Automation Insights Content event emitter:
    1. Retrieve the bai-content-emitter.jar file by following the steps in topic: Retrieving the Content event emitter module for configuration in the Cloud Pak to retrieve bai-content-emitter.jar from the CPE container.
    2. Log in to the Administration Console for Content Platform Engine (ACCE)
    3. Disable the Content Emitter subscription
      • Go to Object Stores > object store name > Events, Actions, Processes > Subscriptions > ContentEventEmitterSubscription (or the name used for the existing Content event emitter subscription).
      • Go to the Configuration sub-tab, uncheck Enabled, and click Save.
    4. Go to Object Stores > object store name > Browse > Root Folder > CodeModuleEmitter (or the path for where the existing Business Automation Insights Content event emitter is located).
    5. Click on EmitterCodeModule, or the name of the existing Code Module object.
    6. Click on Actions, then select Checkin, checkout, cancel > Exclusive Checkout.
    7. Click Checkout.
    8. Click on Actions, then select Checkin, checkout, cancel > Checkin.
    9. Click on Add, then click Browse to select the bai-content-emitter.jar you retrieved in the previous steps. Click Add Content.
    10. Check Update all Action class instances that reference earlier versions of this Code Module class:
    11. Click Check In Major Version.
    12. Enable the BAI Content event emitter.
      • Go to Object Stores > object store name > Events, Actions, Processes > Subscriptions > ContentEventEmitterSubscription (or the name used for the existing Content event emitter subscription).
      • Go to the Configuration sub-tab, check Enabled, and click Save.

The updated code module is immediately available for use and no restart of the CPE pods is needed. Newly emitted content events will be created with the correct data types for all document properties.

Existing properties in events emitted before the fix was applied will still show as the data type "keyword", while new properties in events emitted after the fix is applied will show as the correct data type with the appropriate set of operators for the filter. In order to correct the data type and the allowed operators for filters for all document properties in emitted events and not just new properties, the existing index would need to be deleted and recreated, which will remove the historical record of previously emitted events. If you not require the additional operators for the filters (such as "<", ">", "is between", or "is not between" for filters on numeric properties) you do not need to delete the index. Documents on the object store will not be impacted if you delete the index.

To delete and recreate the index:

  1. Update the BAI Content event emitter code module (see steps above on how to apply the fix to an object store that was previously configured to use the BAI Content event emitter). Note that if you choose to disable the emitter, do not enable until the rest of these steps have been completed.
  2. Stop the BAI Content Flink job:
    • Log into the OCP cluster and switch to the project where CP4BA is deployed. In the instructions that follow, the examples assume the name icp4adeploy is used for the deployment. 
      oc login https://<cluster-ip>:<port> -u <cluster-admin> -p <password>
oc project <cp4ba-namespace>
    • Retrieve the Flink JobManager name 
      JOBMANAGER=`oc get pods | grep jobmanager | awk '{print $1}'`
    • Retrieve the Content Flink job ID 
      JOB_ID=`oc exec -it $JOBMANAGER -- flink list | grep bai-content | awk '{print $4}'`
    • Cancel the Content Flink job using the job ID 
      oc exec -it $JOBMANAGER -- flink cancel $JOB_ID
  3. Use Elastic Search API to delete the index used by BAI Content events.
    • Get Elastic Search URL, User, and Password
      • Get URL and User from Config Map icp4adeploy-bai-env and field elasticsearch-url, get Password from Secret icp4adeploy-bai-secrets and field elasticsearch-password
    • Retrieve the Business Performance Center pod name 
      • BPCPOD=`oc get pods | grep business-performance-center | awk '{print $1}'`
    • Get the list of all indexes using the Elasticsearch URL (using example URL https://icp4adeploy-ibm-dba-ek-client:9200), user (using placeholder <elastic-search-user>), and password: 
      • oc exec -it $BPCPOD -- curl -X GET -u <elastic-search-user>:<password> "https://icp4adeploy-ibm-dba-ek-client:9200/_mapping" -k | grep content-timeseries
      • Search the response JSON for an index with a name containing "content-timeseries".
      • This index is referred to as the placeholder <bai-content-timeseries-index> in further steps. For example, content-timeseries-idx-ibm-bai-2022.03.09-000001.
    • Delete the index: 
      • oc exec -it $BPCPOD -- curl -X DELETE -u <elastic-search-user>:<password> "https://icp4adeploy-ibm-dba-ek-client:9200/<bai-content-timeseries-index>" -k
    • Get the list of all Elastic Search indexes again to confirm there is no index with "content-timeseries" in the name (verify with the grep content-timeseries that nothing is found): 
      • oc exec -it $BPCPOD -- curl -X GET -u <elastic-search-user>:<password> "https://icp4adeploy-ibm-dba-ek-client:9200/_mapping" -k | grep content-timeseries
  4. Rerun the BAI setup job to recreate the index:
    • Install jq to parse the JSON for the BAI setup job: 
      yum install jq
    • List the jobs and find the job name containing bai-setup. 
      oc get jobs
    • This name is referred to as the placeholder <bai-setup-job-name> in further steps. For example, icp4adeploy-bai-setup.
    • Restart the BAI setup job: 
      oc get job <bai-setup-job-name> -o json | jq 'del(.spec.selector)' | jq 'del(.spec.template.metadata.labels)' | kubectl replace --force -f -
  5. Restart the BAI Content Flink job:
    • List the jobs and find the job name related to the Content job 
      oc get jobs
    • This name is referred to as the placeholder <content-job-name> in further steps. For example, icp4adeploy-bai-content.
    • Restart the Content job: 
      oc get job <content-job-name> -o json | jq "del(.spec.selector)" | jq "del(.spec.template.metadata.labels)" | kubectl replace --force -f -
    • Wait for the Content job to be up and running 
      oc get pods| egrep "NAME|<content-job-name>"
  6. Enable the BAI Content event emitter.
    • Log in to the Administration Console for Content Platform Engine.
    • Go to Object Stores > object store name > Events, Actions, Processes > Subscriptions > ContentEventEmitterSubscription (or the name used for the existing Content event emitter subscription).
    • Go to the Configuration sub-tab, check Enabled, and click Save.
 

Performing the necessary tasks after installation

For more information, see IBM Cloud Pak for Automation 20.0.x.

Uninstalling

For more information, see IBM Cloud Pak for Automation 20.0.x.

List of Fixes

APARs are listed in tables and table columns are defined as follows: 
Colunm title Column description
APAR The defect number
Title A short description of the defect
Sec. A mark indicates a defect related to security
Cont. A mark indicates a defect specific to the Cloud Pak integration of the component
B.I. A mark indicates the fix has a business impact. Details are found in the title column or the APAR document
FileNet Content Manager
APAR Title Sec. Cont. B.I.
PJ46742
BAI CONTENT EVENT EMITTER DOES NOT USE CORRECT TYPE FOR DOCUMENTPROPERTIES IN EMITTED EVENTS

Back to top

Known Limitations

For more information, see the support page Cloud Pak for Automation Known Limitations

Document change history

  • 18 March 2022: Initial publish.
    •

     

    [{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS2JQC","label":"IBM Cloud Pak for Automation"},"ARM Category":[{"code":"a8m0z0000001gWWAAY","label":"Other-\u003ECloudPak4Automation Platform"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"20.0.3"}]

    Document Information

    Modified date:
    23 March 2022

    UID

    ibm16564915

    Page Feedback