Installing the capabilities in the Red Hat OpenShift console

If you want to select the capabilities to install and use only the default values, then it is easier to do that in the Form View of the Cloud Pak for Business Automation operator.

Before you begin

  1. Log in to your OCP or ROKS cluster as a cluster administrator.

    To allow a non-administrator user to install the Cloud Pak capabilities, see the What to do next section in Installing the IBM Cloud Pak catalogs and operators.

  2. If you used the All namespaces option to install the Cloud Pak operator, switch to the project that you created for your CP4BA deployment.
  3. In the Installed Operators view, verify the status of the IBM Cloud Pak for Business Automation operator installation reads succeeded, and verify the deployment by checking that all the pods are running.

Procedure

  1. Use the operator instance to apply a custom resource by clicking CP4BA deployment > Create Instance.
  2. In the Form View of the deployment editor, enter the values for everything that you want to include in your deployment.
    1. Enter a Name value or use the default icp4adeploy.
    2. Enter 24.0.0 as the appVersion value.
    3. Accept the License by setting the value to true.
    4. Set Deployment Type to starter.

      The size of the Cloud Pak foundational services instance is set to starterset.

    5. Open the Shared Configuration section and enter values for the following parameters. For more information about the shared parameters, see Shared configuration parameters.
      Table 1. Shared configuration parameters
      Shared configuration parameters Values
      Purchased CP4BA license Set to non-production.
      Platform Set to OCP or ROKS.
      OCP Platform Set to Red Hat OpenShift Service on AWS (ROSA) or Azure Red Hat OpenShift (ARO).
      root_ca_secret The default is icp4a-root-ca.
      sc_drivers_url This parameter is necessary if you want to provide IBM Content Collector for SAP Applications (ICCSA) libraries. All the files must be compressed in a single file.
      external_tls_certificate_secret Leave the value empty to sign all external routes with the root_ca_secret.
      IAM Settings If you do not want to use cpadmin for the default_admin_username parameter, provide a non-default admin user the IBM Identity Management (IM) foundational service.
      Trusted certificate list Leave blank to generate a self-signed signer certificate.
      CP4BA Egress Settings Leave the default value as true to restrict access to the internet.
      Purchased licenses for FNCM and BAW Leave blank.
      Storage configuration Select a file-based dynamic storage class and a block storage class from the list under Storage for starter and Block Storage Class.
      Important: If you want to store data with Microsoft Azure File, then enter the name of the storage class that you created with the NFS protocol for the file-based dynamic storage class. For more information, see Storage considerations.
    6. Select the capabilities that you want to include.
      Tip: If you do not want to include a capability, leave the value as false. For more information about the capabilities and their dependencies, see Capabilities for starter deployments.
      Restriction: Automation Document Processing does not support a cluster with a Linux on Z (s390x) architecture.
      • FileNet Content Manager
      • Business Automation Application
      • Operational Decision Manager
      • Automation Decision Services
      • Automation Document Processing
      • Business Automation Workflow Authoring and Automation Workstream Services
    7. Open the Optional Components section, choose whether to include, for example, Business Automation Insights and enter valid values for the parameters of the selected capabilities in the list.
      Restriction:
      • Due to a limitation in the Form View, the repo_service_url parameter in IBM FileNet® Content Manager is still visible when IBM Automation Document Processing (ADP) runtime is set to false. If you do not want to include ADP, you do not need to set a value for this configuration parameter.
      • If you want to install only ADP, the Business Automation Studio Configuration appears in the Advanced configuration of the Form View due to a limitation. Ignore the Studio and Playback parameters as these are not needed. Before you click Create, remove the bastudio_configuration section in the YAML view.
      Tip: You can copy and paste parameters from the cert-kubernetes custom resource starter templates in the YAML View and edit the parameters. For more information about downloading cert-kubernetes, see Preparing for a starter deployment. You can edit the CR file in the editor, but it is best if you have the CR complete and verified before you save your changes in the editor. For example, go to http://www.yamllint.com/ to verify the contents of your file.

      For more information about the olm_ configuration parameters that are used to switch between the Form View and the YAML View, see Business Automation configuration parameters for Operator Hub.

    8. Optional: To enable the Deep Learning capability (disabled by default) with GPU nodes, click the YAML View, and add the following parameters to the file under the spec section.
      Note: Enable Deep Learning only if you have GPU nodes on your cluster.
      ca_configuration:
        ocrextraction:
          deep_learning_object_detection:
            enabled: true
        deeplearning:
          gpu_enabled: true
          nodelabel_key:   # The unique node label key/value on the GPU node. For example: ibm-cloud.kubernetes.io/gpu-enabled:true.
          nodelabel_value:  # The node label value on the GPU node.  For example: "true". Set this value when `gpu_enabled` is set to true
            
    9. Optional: If you plan on processing low-quality documents or documents that contain handwritten text, set the global.use_iocr parameter to all or auto to enable the deployment of OCR engine 2.
  3. When you are ready, click Create.

    The page switches to the CP4BA deployment tab, where you can watch the Status.

  4. You can click the deployment name (icp4adeploy), and go to the Conditions section at the bottom of the page to see the status updates and any messages.

    You can also click the YAML tab to monitor the state of the selected capabilities.

    YAML view to monitor status

What to do next

To verify that your deployment is up and running:

Check the foundational services and CP4BA deployment status
First check the status of the foundational services Conditions is Ready, PrereqReady, Running. You can then check the CP4BA deployment status.
Note: If you are able to run a script, then you can also run the post installation shell script to help you validate your deployment. For more information, see Validating your starter deployment.
Access the capability services

A ConfigMap is created in the namespace to provide the cluster-specific details to access the services and applications. Components that are successfully deployed have URLs in the ConfigMap. If any components failed, the URLs and credentials are not included. The ConfigMap name is prefixed with the deployment name (default is icp4adeploy). You can find the ConfigMap containing the routes information by clicking Workloads > ConfigMaps and then searching for the string "cp4ba-access-info"

.ConfigMaps

The contents of the ConfigMap depends on the components that are included. Each component has one or more URLs, and if needed a username and password.

<component1> URL: <RouteUrlToAccessComponent1>
<component1> Credentials: <UserName>/<Password> (optional) 
<component2> URL: <RouteUrlToAccessComponent2>
<component2> Credentials: <UserName>/<Password> (optional) 
Note: The bastudio-access-info section provides access information for the Cloud Pak dashboard (Zen UI) and Business Automation Studio, which is installed by several patterns, including Business Automation Workflow. The included URLs and credentials can be used to access the applications designers of the installed components.

You can also click the YAML tab in the CP4BA deployment (icp4adeploy) to view the endpoints uri of the installed capabilities.

After you have the routes and admin user information, check whether you need to do the following tasks.

Tip: If you want or need to update values in a starter deployment that you made in the Form View, you must edit the deployment in the YAML View. You can edit true or false values in the Form View, but the other parameters need to be done in the YAML View. You can access the custom resource from the YAML tab, or by clicking Actions > Edit ICP4ACluster.

YAML view

Log in to the IBM Cloud Pak Platform UI (Zen UI)
Business Automation Studio uses the Zen UI to provide a role-based user interface for all Cloud Pak capabilities. Capabilities are dynamically available in the UI based on the role of the user that logs in. You can find the URL for the Zen UI by clicking Networking > Routes and looking for the name cpd, or by running the following command.
oc get route | grep "^cpd"

You have two options to log in, Enterprise LDAP and IBM provided credentials (cpadmin only). To log in to the Admin Hub to configure the LDAP, then click IBM provided credentials (cpadmin only). You can get the details for the IBM-provided cpadmin user by getting the contents of the platform-auth-idp-credentials secret in the namespace used for the CP4BA deployment.

oc -n <namespace> get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d && echo

If you want to log in using the configured LDAP, then click Enterprise LDAP and enter the cp4admin user and the password in the cp4ba-access-info ConfigMap. The cp4admin user has access to Business Automation Studio features.

If you want to add more users, you need to log in with the Zen UI administrator. The kubeadmin user in the Red Hat OpenShift authentication and the IBM-provided cpadmin user have the Zen UI administrator role.

When logged in, you can add users to the Automation Developer role to enable users and user groups to access Business Automation Studio and work with business applications and business automations.

For more information about adding users, see Completing post-deployment tasks for Business Automation Studio. For more information about the Automation Developer role, see Roles and permissions.

Note: If you included multiple capabilities from IBM FileNet Content Manager (FNCM), Automation Document Processing (ADP), and Business Automation Application (BAA) in your CP4BA deployment, then use the Navigator for CP4BA heading in the cp4ba-access-info ConfigMap and the custom resource status fields to find the route URL for IBM Business Automation Navigator.

If you included IBM FileNet Content Manager (FNCM) without the other capabilities, then use the Navigator for FNCM heading in the cp4ba-access-info ConfigMap and the custom resource status fields to find the route URL for IBM Business Automation Navigator.

Use the LDAP user registry
The LDAP server has a set of predefined users and groups to use with your starter environment. Changes to the user repository are not persisted after a pod restart.
  • To provide a user for Task Manager, the following LDAP users and groups are created by the deployment.
    • In the OCP console, select the project in which you deployed the Cloud Pak, and then click Workloads > Secrets > <deployment-name>-openldap-customldif > Data > Reveal Values.
    • Usernames: cp4admin, user1, user2, up to and including user10.
    • Group names: TaskAdmins, TaskUsers, and TaskAuditors.

    The cp4admin user is assigned to TaskAdmins. The LDAP users user1 - user5 are assigned to TaskUsers, and the users user6 - user10 are assigned to TaskAuditors.

  • To modify an existing user's password:
    Note: Do not change the password of the cp4admin user after the Content Platform Engine (CPE) is initialized. Changing the password of the Domain admin user needs extra steps. For more information, see Update System User credentials.
    1. In the Red Hat OpenShift console, go to Workloads > Secrets, and select the icp4adeploy-openldap-customldif secret.
    2. Click Actions > Edit Secret.
    3. Change the password for a specified user and click Save.
    4. Go to Workloads > Pods, and search for the openldap pod.
    5. In the overflow menu for the pod, click Delete Pod to restart it.
  • To add a user:
    1. In the Red Hat OpenShift console, go to Workloads > Secrets, and select the icp4adeploy-openldap-customldif secret.
    2. Click Actions > Edit Secret.
    3. Copy and paste the attributes from an existing user, take out the unnecessary attributes, put the information for the new user, and click Save. The following example is for the user newuser:
      dn: uid=newuser,dc=example,dc=org
      uid: newuser
      cn: newuser
      sn: newuser
      userPassword: <password>
      objectClass: top
      objectClass: posixAccount
      objectClass: organizationalPerson
      objectClass: inetOrgPerson
      objectClass: person
      uidNumber: 14583345
      gidNumber: 1456456
      homeDirectory: /home/newuser/
      mail: newuser@example.org 

      The uidNumber must be a unique and different number from the existing uidNumbers.

    4. Go to Workloads > Pods, and search for the openldap pod.
    5. In the overflow menu for the pod, click Delete Pod to restart it.
    6. Sign in to the Common Web UI by following the steps in Accessing your cluster by using the console.
    7. Follow the steps in Managing console access to add the user to the Cloud Pak Platform UI (Zen).
  • To add a group:
    1. In the Red Hat OpenShift console, go to Workloads > Secrets, and select the icp4adeploy-openldap-customldif secret.
    2. Click Actions > Edit Secret.
    3. Copy and paste the attributes from an existing group, take out the unnecessary attributes, put the information for the new group, and click Save.

      The following example is for a group name of "NewGroup".

      dn: cn=NewGroup,dc=example,dc=org
      objectClass: groupOfNames
      objectClass: top
      cn: NewGroup
      member: uid=user1,dc=example,dc=org
      member: uid=user2,dc=example,dc=org
      member: uid=user3,dc=example,dc=org
      member: uid=user4,dc=example,dc=org
    4. Go to Workloads > Pods, and search for the openldap pod.
    5. In the overflow menu for the pod, click Delete Pod to restart it.
    6. Sign in to the Common Web UI by following the steps in Accessing your cluster by using the console.
    7. Follow the steps in Managing user groups to add the group to the Cloud Pak Platform UI (Zen).
Create a storage policy and associate the Advanced Storage Area that is created during the deployment
  1. Create a storage policy and associate the storage policy with the existing advanced storage area. See Storage policies for more information.
  2. Assign the newly created storage policy to an existing document class.
Enable GraphQL integrated development environments for FileNet Content Manager
The GraphQL integrated development environment (IDE) is not enabled by default because of a security risk. If you want to include this capability in your starter environment, add the parameter to enable the IDE.
  1. Click Actions > Edit ICP4ACluster, then click YAML to go into the YAML view.
  2. Add the following parameters to the file:
    graphql:
          graphql_production_setting:
            enable_graph_iql: true
  3. Apply the updated custom resource YAML file.

    In the next reconciliation loop, the operator picks up the change and includes GraphQL with your deployment.

Import sample data for IBM Business Automation Insights
If you selected Business Automation Insights as an optional component, you can test and explore the component by importing sample data.

For more information, see https://github.com/icp4a/bai-data-samples.

Enable Business Automation Insights for FileNet Content Manager
If you selected Business Automation Insights as an optional component and included the Content event emitter in your deployment, you must update the deployment to add the Kafka certificate to the trusted certificate list.
  1. Create a secret with your Kafka certificate, for example:
    oc create secret generic eventstreamsecret --from-file=tls.crt=eventstream.crt
  2. Update the trusted_certificate_list parameter to the YAML View in the OCP console to include the secret that you created.
    shared_configuration:
          trusted_certificate_list: ['eventstreamsecret']

    If other certificates are in the list, use a comma to separate your new entry.

  3. Save the updated custom resource YAML file.
Verify the creation of the CDD repository for Content Designer

If you installed FileNet Content Manager, use an ssh command line to go into the gitea-deploy pod to run the following command:

ls -l /data/git/repositories/content-designer/
  • If the output shows cdd.git, then the content-designer directory exists and the Git repository is created successfully.
    drwxr-xr-x 7 git git 147 May 5 15:58 cdd.git
  • If the output does not show the CDD repository, go to the operator logs to understand why the deployment failed.