IBM Support

Readme for Cloud Pak for Business Automation 21.0.3 IF006

Fix Readme


Abstract

The following document is for IBM Cloud Pak for Business Automation 21.0.3 IF006. It includes the CASE package download, installation information, and the list of APARs that are resolved in this interim fix.

Content

Readme file for: IBM Cloud Pak® for Business Automation
Product Release: 21.0.3
Update Name: 21.0.3 IF006
Fix ID: 21.0.3-WS-CP4BA-IF006
Publication Date: 18 March 2022
Last modified date: 18 March 2022

Before installation
  1. Ensure you take regular backups of any databases associated with the environment.
  2. Ensure your operators are in a healthy state before upgrading.
    If one or more operators are failing, then it can prevent the system from completing an upgrade.
    It is recommended to check a few of the important CR statuses to ensure there are not failures and the statuses appear ready for the various installed components. Check the status of the following CRs when they exist: 
    oc get icp4acluster -o yaml
oc get AutomationUIConfig -o yaml 
oc get Cartridge -o yaml 
oc get AutomationBase -o yaml 
oc get CartridgeRequirements -o yaml
  3. Required when you are using Business Automation Insights
    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, Restarting from a checkpoint or savepoint

Installing the interim fix

Cloud Pak for Business Automation 21.0.3 interim fixes are released to the v21.3 operator channel. If your environment has access to IBM entitled registry and has an automatic v21.3 channel subscription then production installations are upgraded automatically. This upgrade generally occurs when the interim fix is released. Once the operator is upgraded, it triggers rolling updates for all the pods it manages to ensure they are updated to the appropriate version to match the operator.
Important: If you used any individual image tag settings in your CP4BA CR, it could prevent the operator from updating the images to the appropriate version. Ensure you remove any of these settings for a production installation when you upgrade.
The CASE package associated with this interim fix is ibm-cp-automation-3.2.6.tgz.

Depending on the current setup and state of your existing environment, there are various manual actions that might be required. The following scenarios cover what actions might be needed for a particular setup.
  • Scenario 1: You are using a starter installation.
    Actions: Starter environments do not support upgrades. Although you can use the interim fix content, install a new starter environment and use the CASE package from this interim fix.
  • Scenario 2: Your installation is version 21.0.2.x or earlier.
    Actions: If you are using a version before 21.0.3, then you must upgrade first. To upgrade your environment, follow the Upgrading automation containers instructions.
    When you perform the upgrade, you can substitute the CASE package from this interim fix for the 21.0.3 CASE package while you follow the instructions.
  • Scenario 3: You are using an air gapped environment.
    Actions: To upgrade a 21.0.3 air gapped environment mirror the entitled registry images to the local registry by completing the same steps on the bastion host that you used to install. For more information about this installation, see Setting up a mirror image registry.
    Make sure to use the CASE package from this interim fix.
    Once the images are mirrored, the automatic channel subscription completes the upgrade.
  • Scenario 4: Your v21.3 channel subscription is set to manual.
    Actions: If your channel subscription is set to manual, then you must approve any operator upgrades.
      a. Select the CP4BA operator from the OCP web console under Operators>Installed Operators.
      b. Go to the subscription tab for the operator.
      c. Trigger the operator update.
    Once the operator is updated, it triggers the upgrade of the other CP4BA images.

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 from Config Map icp4adeploy-cp4ba-access-info and section bai-access-info
    • Get the list of all indexes using the Elasticsearch URL (using example URL https://iaf-system-es-myproject.apps.myserver.cp.ibm.com), user (using placeholder <elastic-search-user>), and password: 
      • curl -X GET -u <elastic-search-user>:<password> "https://iaf-system-es-myproject.apps.myserver.cp.ibm.com/_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: 
      • curl -X DELETE -u <elastic-search-user>:<password> "https://iaf-system-es-myproject.apps.myserver.cp.ibm.com/<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): 
      • curl -X GET -u <elastic-search-user>:<password> "https://iaf-system-es-myproject.apps.myserver.cp.ibm.com/_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.
  1. Update Kafka certificates when you are using Business Automation Insights
    If you are using Business Automation Insights and upgrading from an IBM Automation Foundation version before 1.3, the operator will fail to become ready after the upgrade and kafka/zookeeper pods show SSL errors. To resolve the issue, follow the "To renew the leaf certificates for Kafka" instructions in Changes to CA certificate and key does not automatically rotate Kafka leaf certificates.
  2. Review the installation
    It is recommended that you review the CR yaml status section and operator logs after the upgrade to ensure there are no failures preventing your pods from upgrading.
    oc get icp4acluster -o yaml > CP4BAconfig.yaml
oc logs deployment/ibm-cp4a-operator -c operator > operator.log
    If you are interested in verifying the expected image digest for a particular image, then you can review the ibm-cp-automation\inventory\cp4aOperatorSdk\resources.yaml file in the CASE package. This file has a listing of the images managed by the CP4BA operator and their expected digest for this particular interim fix level.

Uninstalling

There is no procedure to uninstall the interim fix.

List of Fixes

APARs fixed by this interim fix are listed in the following tables.
The columns are defined as follows: 
Column 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
General
APAR Title Sec. Cont. B.I.
N/A
N/A

Back to top

Cloud Pak for Business Automation Operator
APAR Title Sec. Cont. B.I.
N/A N/A

Back to top

Automation Document Processing
APAR Title Sec. Cont. B.I.
N/A N/A

Back to top

Automation Decision Services
APAR Title Sec. Cont. B.I.
N/A N/A

Back to top

APAR Title Sec. Cont. B.I.
N/A N/A

Back to top

Business Automation Insights
APAR Title Sec. Cont. B.I.
N/A N/A

Back to top

Business Automation Navigator
APAR Title Sec. Cont. B.I.
N/A N/A

Back to top

Business Automation Studio
APAR Title Sec. Cont. B.I.
N/A N/A

Back to top

Business Automation Workflow including Automation Workstream Services
APAR Title Sec. Cont. B.I.
N/A N/A X

Back to top

Enterprise Records
APAR Title Sec. Cont. B.I.
N/A
N/A

Back to top

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

Operational Decision Management
APAR Title Sec. Cont. B.I.
N/A N/A   

Back to top

User Management Service
APAR Title Sec. Cont. B.I.
N/A N/A X

Back to top

Workflow Process Service
APAR Title Sec. Cont. B.I.
N/A N/A   

Back to top

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":"CloudPak4Automation Platform"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

    Document Information

    Modified date:
    18 March 2022

    UID

    ibm16563463

    Page Feedback