Configuring IBM Business Automation Workflow with an existing external Content Platform Engine

Edit online

Draft comment:
This topic only applies to BAW, and is located in the BAW repository. Last updated on 2025-03-13 12:15

You can configure IBM® Business Automation Workflow to work with an existing external Content Platform Engine, also called an external Enterprise Content Management (ECM) system.

Restriction: IBM Business Automation Workflow Enterprise Service Bus does not include an embedded Content Platform Engine and you cannot configure a Content Platform Engine for Enterprise Service Bus.

Configure Business Automation Workflow to work with an existing external FileNet® Content Manager system in two ways:

Using an empty object store in an external FileNet Content Manager installation.
This approach is recommended when setting up a new Business Automation Workflow deployment environment. Each Business Automation Workflow environment must use unique object stores. Sharing object stores across environments is not supported. You cannot configure two separate IBM FileNet P8 domains on the same WebSphere® Application Server instance if each domain supports a different Business Automation Workflow product version.
Reassigning the BPM content store to an existing FileNet Content Manager domain.
This method is suitable if you already have a Business Automation Workflow deployment environment. Follow the instructions in this set of steps. You can configure multiple Business Automation Workflow environments to use a single IBM FileNet P8 domain, provided all environments are on the same product version. However, all environments sharing the domain must be either:
- Development profiles (IBM Workflow Center), or
- Production profiles (IBM Workflow Server)
Additional considerations:
- Do not reuse the Design Object Store (DOS) and Target Object Store (TOS) from a development profile in a production profile. Create separate object stores for each profile type.
- A single IBM Content Navigator installation cannot be shared between development and production environments. Each profile type must have its own IBM Content Navigator instance.
- IBM Content Navigator desktops have a one-to-one relationship with case-related plug-ins. Reusing custom widgets from development in production may lead to functionality issues.
Note:
- If the Business Automation Workflow environments are not on the same product version, the gateway service installation might fail due to version-related dependencies.
- Mixing development and production profiles within the same domain is not supported.

Before you begin

To configure Business Automation Workflow with an existing external Content Platform Engine, ensure the following prerequisites are met:

Only standard and clustered ECM environments are supported. Single-server or multi-server (non-clustered) network deployment ECM environments are not supported.
The external Content Platform Engine must be configured on a WebSphere Application Server profile enabled for Java 8. If not, the Case configuration tool will fail.
The Content Platform Engine must have a domain already set up, which may include multiple object stores. When configuring the Content Platform Engine, there is a three-to-three correlation between the Business Automation Workflow server and the Content Platform Engine object stores:
- Business Automation Workflow document store (must be a new, empty object store)
- Design object store
- Target object store
Business Automation Workflow and FileNet Content Manager must use the same LDAP user repository.
Both systems must use the same LDAP configuration properties, including user and group name attributes:
- Business Automation Workflow: user-full-name-prop and group-name-prop
- Content Platform Engine: userShortNameAttribute and GroupNameAttribute
  For more information, see Configuring the user registry and Directory service providers.
When creating the WebSphere Application Server profile for the external Content Platform Engine, use a hostname with a domain name suffix, for example: MyDmgrHost.my_domain.com.
Business Automation Workflow and Content Platform Engine must use the same registry to enable single sign-on (SSO). For example, both may use federated repositories such as Virtual Member Manager (VMM). A configuration where Business Automation Workflow uses VMM and Content Platform Engine uses a stand-alone LDAP is not supported by WebSphere Application Server.
If using shared LDAP repositories, they must be added to the WebSphere federated repositories on both the Content Platform Engine and Business Automation Workflow.

About this task

Note: You cannot reverse this configuration and return to using the IBM Business Automation Workflow embedded Content Platform Engine. After you configure, you must always use the external Content Platform Engine.

Back up your system configuration and databases before you begin this configuration. This backup means that you can roll back your configuration if needed. See Backing up and restoring administrative configuration files.

Procedure

Begin your configuration by checking that there is no content such as folders and documents in the IBM Business Automation Workflow object store. Use the IBM Administration Console for Content Platform Engine to check that there is no content.
1. In the domain navigation tree, open Object Stores > docs.
2. In the object store navigation tree, open Search.
3. Click New Object Store Search.
4. For each of the following classes, run a search: Document.
5. If the result set is empty, there is no existing content.
See Using the IBM Administration Console for Content Platform Engine
Note: Any content that you do not remove from the BPM content store is deleted when you complete this configuration.
Check the version level of the FileNet Content Manager. It must be a supported version to work with IBM Business Automation Workflow. Review the Software Product Compatibility Reports to help ensure that compatible component products are at their proper supported versions for IBM Case Manager and IBM Business Automation Workflow.
Configure single sign-on (SSO) security for the external FileNet Content Manager, including the configuration of the user registry and trusted realm. Follow the instructions in Configuring single sign-on with LPTA for an external Content Platform Engine.
Stop the IBM Business Automation Workflow deployment environment.
Start the IBM Business Automation Workflow deployment manager to have the changes take effect.
Set up a network shared directory between all computers in the IBM Business Automation Workflow cluster and the Content Platform Engine cluster.
The shared directory must be the same on all computers. The computers must have the same operating system.
- By default, the shared directory on the IBM Business Automation Workflow computer is install_root/CaseManagement/properties. If you customized the path to the shared directory, use that customized path.
  - On the Content Platform Engine computer, create a folder with the same path as the IBM Business Automation Workflow shared directory.
  - You can mount remote file systems. You can also use network file systems or distributed file systems to share files across computers, such as NFS, GPFS.
- By default, the shared path on the IBM Business Automation Workflow computer is install_root\CaseManagement\properties. If you customized the path to the shared directory, use that customized path. If the path is a UNC path to share files among Windows servers, use a forward slash, for example //WIN129146/shareFolder instead of \\WIN129146/shareFolder.
  1. On the Content Platform Engine computer, create a folder with the same path as the IBM Business Automation Workflow shared directory.
  2. Share the directories between the computers.
Designate a user from the shared repository to be the administrator for the object store. Business Automation Workflow uses this user to do administrative operations like the creation of document class definitions. Then, map this user to the IBM Business Automation WorkflowEmbeddedECMTechnicalUser role.
1. Check that the user defined in the Authentication Alias that is assigned to the EmbeddedECMTechnicalUser role is a user from the shared repository.
  1. Select Servers > Deployment Environments > DE name > Authentication aliases. Note the alias name that is used for the EmbeddedECMTechnicalUser role.
  2. Select Security > Global Security. Expand the Java Authentication and Authorization Service section and select J2C authentication data. Verify that the user who is assigned to the EmbeddedECMTechnicalUser alias is a user from the shared user repository.
2. If the user assigned to the EmbeddedECMTechnicalUser does not qualify, that is, the user is not from the shared repository, do the following steps.
  1. Create an authentication alias with credentials from the shared user repository for the Content Platform Engine administrator.
    1. In the WebSphere administrative console for the IBM Business Automation Workflow server, select Security > Global Security. The Global Security page opens.
    2. Expand the Java Authentication and Authorization Service section and select J2C authentication data. The JAAS - J2C Authentication Data page opens.
    3. Click New and add an authentication alias with LDAP credentials for the object store administrator.
  2. Change the EmbeddedECMTechnicalUser role to use the new authentication alias that you created. This authentication alias is for FileNet Content Manager. To change the EmbeddedECMTechnicalUser role to use the new authentication alias, in the WebSphere administrative console, select Servers > Deployment Environments. Select your deployment environment and continue to Authentication Aliases. You see the EmbeddedECMTechnicalUser and can modify that alias.
Add the new authentication alias to the list of system lane users as described in Configuring additional system lane users. This ensures the successful execution of any content integration step that runs in the context of a system lane. These steps help perform document or folder operations on an ECM system or BPM document store. As described in Building a service that integrates with an ECM system or a BPM store, the Content Platform Engine administrator must be included in the system lane users. This inclusion ensures that the content integration step does not fail due to missing user permissions.
Grant administrator roles to the user that you chose for the EmbeddedECMTechnicalUser role.
1. Go to Users and Groups > Administrative user roles and click Add.
2. Select Administrator, Deployer, Operator roles in the Roles list and click Search.
3. In the Available user list, select the EmbeddedECMTechnicalUser role-mapped user and add it to the Mapped to role list. Click OK to apply all changes.
4. Log in to the Process Admin Console. In the Group Management window, search for the tw_admins and tw_authors groups, and add the EmbeddedECMTechnicalUser role-mapped user to both groups.
Restart the IBM Business Automation Workflow deployment manager.
Synchronize the custom profiles with the deployment manager profile.
For each custom profile, run the following command on the custom node:
```
custom_profile_install_root/bin/syncNode.bat dmgr_hostname dmgr_soap_port -user de_admin_user -password de_admin_password
```
Configure the FileNet Content Platform Engine.
1. Log in to the IBM Administration Console for Content Platform Engine on the FileNet Content Platform Engine as a domain administrator.
2. If you are creating a new Content Platform Engine environment, create the three object stores for the IBM Business Automation Workflow document store, design object store, and target object store. For considerations on object store configuration, see Planning for an external Content Platform Engine.
  If you are augmenting IBM Case Manager, you already have the design object store and target object store and need to create only the IBM Business Automation Workflow document store. Use the IBM Administration Console for Content Platform Engine on the FileNet Content Platform Engine as described in Creating an object store. Use the following settings:
  - Use the user from step 7 when you grant administrative access to this object store. You can also use a group that contains this user.
    Important: If you don't complete this step, you might see errors in the SystemOut.log file because the ECM Technical User isn't considered a member of the Object Store Administrators.
  - Grant all users that work with IBM Business Automation Workflow basic access. You might want to use the #AUTHENTICATED-USERS security identifier as grantee to allow all users to work with the object store. The individual instance objects are automatically protected based on the teams that you create in IBM Business Automation Workflow.
  - When you choose the add-ons, check that the following extensions are installed. The add-ons are part of the default configuration.
    - For IBM Business Automation Workflow document store:
      
      Base Content Engine Extensions
    - For IBM Business Automation Workflow design object store and target object store:
      
      Base Application Extension
      
      Base Content Engine Extensions
      
      Process Engine Extensions
      
      Stored Search Extensions
      
      Worksplace Access Roles Extensions
      
      Worksplace Base Extensions
      
      Worksplace E-mail Extensions
      
      Worksplace Forms Extensions
      
      Worksplace Template Extensions
      
      Worksplace XT Extensions
  - After the object stores are created, the only access rights that you will need to add to the administrative user is PRIVILEGED_WRITE. In IBM Administration Console for Content Platform Engine on FileNet Content Manager, the checkbox that you must select is Modify certain system properties (in English).
  - After the target object store is created, you must create a new "Workflow System" for it. Open the target document store, go to Administrative > Workflow System, click New, and enter the values for your environment. Make a note of the connection point name because you need it in a later step when you run the case configuration tasks in the Case configuration tool. You can ignore the Broker servlet URL and Public listener URL in the Process Orchestration section.
  After the object stores are created, you can add a user with administrative permissions on the object store. See Update object store with new users and groups. The permissions that you must grant to the user are listed in Permissions required for the new object store.
Running a command and then starting IBM Business Automation Workflow finishes the configuration. However, you must also verify that the configuration is working.
1. Run the setBPMExternalECM admin command to configure IBM Business Automation Workflow to use an external Content Platform Engine.
  1. Ensure the IBM Business Automation Workflow deployment manager and the Content Platform Engine are running.
  2. Run wsadmin with the parameter -conntype SOAP from the dmgr_profile_root/bin directory.
  3. Run the setBPMExternalECM admin command and save your changes. Use NEW_EXTERNAL_OBJECT_STORE as the value for the -ecmEnvironment parameter. For example:
    Important: This command results in execution times that exceed the default timeout setting for wsadmin command execution. To change the default to allow for the execution time required, open the profile_root/properties/soap.client.props file and change the value for com.ibm.SOAP.requestTimeout to 0, which means no timeout. Remember to restore the previous value after you run the command.
    This command takes a long time to run. Do not close the command window. For example:
```
wsadmin -conntype SOAP -port 8879 -host myHostName.mycompany.com -user admin_user -password admin_password -lang jython
wsadmin>print AdminTask.setBPMExternalECM(['-clientDownloadServicePort', '9443', '-de', 'De1', '-ceUrl', 'iiop://CE.mycompany.com:2809/FileNet/Engine', '-ecmEnvironment', 'NEW_EXTERNAL_OBJECT_STORE', '-domainName', 'p8domain', '-objectStoreName', 'bpmdocs', '-designObjectStoreName', 'bpmdos'])
wsadmin>AdminConfig.save()
```
    Notes:
    
    The host and port parameters correspond to the deployment manager server host value and its SOAP port value.
    
    The -objectStoreName and -designObjectStoreName parameters are case-sensitive.
    
    If you see a message that updated .jar files exist on this deployment manager node machine, you must manually copy the updated files to the other custom node machines.
    See setBPMExternalECM command.
  4. If you started the deployment manager and node agents, manually restart them.
  5. Synchronize the configuration of the nodes.
  6. Restart the IBM Business Automation Workflow deployment environment by using the BPMConfig command. BPMConfig -start. See BPMConfig command-line utility.
2. Check for errors in the IBM Business Automation Workflow logs. If you discover errors, resolve them and restart the IBM Business Automation Workflow server.
3. Check the CMIS component in the Component Health Center (Servers > Deployment Environments > de_name > Health Center) to verify that your external Content Platform Engine is up and running. The switch to the external Content Platform Engine removes the BPM content store configuration. Therefore, you cannot check the EmbeddedECM component anymore. Instead, check the CMIS component. The CMIS component also reports errors for the connection to the external Content Platform Engine.
  
  Note: Health Center is unable to check PostgreSQL.
You configured the external Content Platform Engine. To configure case management, do the remaining steps.
Optional: If you are planning to use an external IBM Content Navigator and it is not yet configured, follow the instructions in Configuring IBM Business Automation Workflow with an external IBM Content Navigator to configure it. Then, return and complete the remaining steps to configure case management.
Copy the ejb-lookup.jar file from the IBM Business Automation Workflow directory install_root/CaseManagement/configure/deploy (for example: /opt/IBM/WebSphere/AppServer/CaseManagement/configure/deploy) to the Content Platform Engine WebSphere Application Server directory install_root/lib/ext (for example: /opt/IBM/WebSphere/AppServer/lib/ext).
Restart the external Content Platform Engine to cause the configuration changes to take effect.
To import the external Content Platform Engine's signer and CA certificates to the Case configuration tool, follow the two steps:
1. Import the external Content Platform Engine SSL certificate into the IBM Business Automation Workflow Case configuration tool.
  1. On the IBM Business Automation Workflow computer, access https://cpe_host_name:ssl_port/wsi/FNCEWS40MTOM to obtain the external Content Platform Engine SSL certificate from the server. See Adding trusted certificates in Liberty.
  2. Import the certificate into the IBM Business Automation Workflow JVM by using the keytool command. For example:
```
/opt/IBM/baw/java/jre/bin/keytool -import -keystore
/opt/IBM/baw/java/jre/lib/security/cacerts -storepass changeit -file
/u/CPE/certificate.crt
```
2. Import the Content Platform Engine signer, see IBM Business Automation Workflow Case configuration tool returns an SSLHandshakeException error.
Start the IBM Business Automation Workflow Case configuration tool by running configmgr.exe in the directory workflow-home/CaseManagement/configure.
If the tool is run on Windows, it should be run with administrative privileges.
Tip: If security is not a concern, enable saving passwords in the file system by clicking Windows > Preferences and selecting the Save all passwords checkbox.
Open the profile configuration file with the extension.cfgp that was created when you configured your deployment environment.
This profile file, which contains the default settings, is located in either dmgr-profile-root/CaseManagement/de name/profiles/ICM_dev or dmgr-profile-root/CaseManagement/de name/profiles/ICM_prod.
Edit the setting for the remote Content Platform Engine server connection properties.

Note: The external Content Platform Engine, IBM Content Navigator and IBM Business Automation Workflow must be operational.
1. Click File > Edit Profile Properties.
2. In the first panel, click Test Connection to verify that the default values are correct and then click Next.
3. In the second panel, click Test Connection to verify that the default values are correct and then click Next.
4. In the third panel, replace the default settings for the embedded Content Platform Engine server with the settings for the external Content Platform Engine and then click Test Connection.
5. Click Finish.
Run the enabled configuration tasks in the order in which they are listed in the Case configuration tool.
For the details of each task, see the topic for your environment.
- Workflow Center: Preparing to run the case configuration tasks
- Workflow Server: Preparing to run the configuration tasks
Restart the IBM Business Automation Workflow environment.
For verification, see the topic for your environment.
- Workflow Center: Verifying the case applications in the development environment
- Workflow Server: Verifying the IBM Business Automation Workflow applications in the production environment
Optional: You can optionally configure the Content Services toolkit. For more details, see Optional: Configuring the Content Services toolkit.