IBM Support

Migration of IBM embedded WebSphere Application Server to IBM WebSphere Liberty Application Server

Product Documentation


Abstract

Starting with IBM Content Collector 4.0.1 Fix Pack 10 (4.0.1.10), the IBM Content Collector Web Application Server has been migrated from IBM embedded WebSphere Application Server (eWAS) to IBM WebSphere Liberty Application Server (WAS Liberty). The Liberty server version used in the Content Collector 4.0.1 Fix Pack 10 is version 19.0.0.3.

Content

With the server migration from IBM embedded WebSphere Application Server (eWAS) to IBM embedded WebSphere Liberty Application Server (WAS Liberty), Content Collector has modified the deployment scripts and the following web application components to support WebSphere Liberty Runtime:

  • AfuWeb
  • API
  • Configuration
  • DocViewer
  • Report Viewer
  • Services

Migration to WebSphere Liberty does not have many functional differences compared to the traditional eWAS other than the ones listed under the Known issues / Limitations section of this document.

Steps involved

  1. IBM Content Collector Web Application basic changes
  2. Replacing certificates on the Liberty Web Application Server
  3. Automated Migration of eWAS Certificate Stores to WebSphere Liberty Server Certificate Store
  4. Establishing a trust relationship with IBM FileNet P8
  5. Known issues / Limitations
 

I. IBM Content Collector Web Application basic changes

Note: Read <ICC_installation_directory> as the name of your IBM Content Collector installation directory. For example:

C:\Program Files (x86)\IBM\ContentCollector or c:\progra~2\IBM\ContentCollector

Service name changes

With the server migration, the following Content Collector service names have changed:

  • IBM Content Collector Web Application is now IBM Content Collector Web Application Liberty
  • IBM Content Collector Documentation is now IBM Content Collector Documentation Liberty

Liberty Server paths

The Liberty profile uses the following structure to create servers for respective services:

  • <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AFUWeb 
  • <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AFUInfoCenter

The Liberty server logs are available at the following locations:

  • <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AFUWeb\logs
  • <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AFUInfoCenter\logs

Java upgrade

Starting with Content Collector 4.0.1 Fix Pack 10 (4.0.1.10), the IBM Content Collector Server has been upgraded to use IBM Java 8. The current IBM Java version used is Java(TM) SE Runtime Environment build 8.0.5.10.

 

II. Replacing certificates on the Liberty Web Application Server

 

There is a change in the type of certificates with the WebSphere Liberty Server migration for Web Application Server and the referred paths. Perform the following steps for replacing the certificates for the WebSphere Liberty Web Application Server.

After the Certificate Authority (CA) sends you a new digital certificate, you must delete the existing certificate and add the new one to the key database from which you generated the request.

 
1. Requesting a new certificate
  1. Log in to the computer on which the IBM Content Collector server is installed.
  2. Open a command prompt as administrator and go to the following directory:
    <ICC_installation_directory>\AFUWeb\wlp\usr\servers\<Liberty_Server_Name>
  3. Type ikeyman to open the IBM Key Management tool.
  4. Go to the Key Database File menu and click Open.
  5. Select PKCS12 from the drop-down list of the Key database type field in the pop-up window.
  6. Type or paste the file name key.p12 in the File Name field or click the Browse button and select the key.p12 file.
  7. Ensure that the Location field is updated as per the following:
    <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AfuWeb\resources\security
  8. Click OK.
  9. Enter the password when prompted to and click OK. The default password is Passw0rd.
    Note that the password is case sensitive. In a production environment, change the password as described in the topic about updating default key store passwords using scripting in the IBM WebSphere Application Server Liberty Knowledge Center.
  10. Create a new certificate request.
    Select Personal Certificate Requests from the Key database content drop-down list and click New.
  11. Specify a label for the digital certificate request in the Key Label field. For example, Production Certificate for Content Collector.
  12. Accept the default values of the remaining fields.
  13. Click OK. A confirmation window is displayed verifying that you have created a request for a new digital certificate.
    The Personal Certificate Requests field shows the key label of the new digital certificate request you created.
  14. Send the file to a Certificate Authority (CA) to request a new digital certificate, or cut and paste the request into the request forms of the CA's website. If you have a Windows domain CA, you can follow the procedure described in Submitting a certificate request to do so. If you use a different CA to certify the certificate request, follow the procedure that applies for the respective CA.
After the CA sends you a new digital certificate, you must delete the existing certificate and add the new one to the key database from which you generated the request.
2. Deleting an existing certificate
  1. Take a backup of your existing digital certificate before deleting it, should you need to recreate it later.
  2. Ensure that the key.p12 key database file is open in the IBM Key Management tool and the Personal Certificates and default are selected under the Key database content section.
  3. Click Delete. You are asked to confirm the deletion. The label of the digital certificate you just deleted no longer appears in the Personal Certificates field.
3. Receiving a new certificate to replace an existing one
  1. Click Receive to open the Receive Certificate from a File window.
  2. Select the newly issued certificate. If the CA sends the certificate as part of an email, you might need to cut and paste the certificate into a separate file.
  3. Click OK.
    The Personal Certificates field of the IBM Key Management window shows the label of the new certificate.
  4. Close the IBM Key Management tool.
 
4. Stopping and restarting service for WebSphere Application Server Liberty (IBM Content Collector Web Application service)
  1. Go to Start > All Programs > IBM Content Collector > Stop Services and click Stop ICC Web Applications to stop the service.
  2. Go to Start > All Programs > IBM Content Collector > Start Services > and click Start ICC Web Applications to restart the service.

Important: If you use Microsoft Exchange, the IBM Content Collector Web Application service must be started by an account with administrator privileges.

 
5. Checking the new certificate status
  1. Open a web browser and enter the following URL in the address field:
    https://server host name:11443/AFUWeb/init
    where,
    • server host name: is the host name of the computer running the embedded web application server. This is the same as the computer running the IBM Content Collector server.
    • 11443: is the default port for connections to the embedded web application server.
  2. If you installed part of the Content Collector web applications on an external web application server, you must use an HTTPS call to the Configuration Web Service instead:
    https://<ICC_Server>:11443/AFUConfig/Configuration?type=ibm.ctms.configWebService&unique=default
    where, <ICC_Server> is the host name of the machine on which you installed the IBM Content Collector Server. You should be able to establish an HTTPS connection.
  3. Import the public key certificate of your CA into your browser, if you receive security warnings in your browser.
 

III. Automated Migration of eWAS Certificate Stores to WebSphere Liberty Server Certificate Store

Note: The automated migration of embedded WebSphere Application Server certificate stores is introduced in Fix Pack 10 Interim Fix 7.
Automated migration during installation
During the installation of the web application, migration of eWAS certificate stores or restoration of Liberty certificate store is handled as follows:
  1. eWAS certificate stores are migrated to WebSphere Liberty Server certificate store if:
    1. The <ICC_installation_directory>\AFUWeb_cert_backup directory is present, and
    2. It contains the eWAS certificate stores (key.p12, trust.p12, and so on).
      Note:
      • If you have eWAS certificates backed up in a separate directory, you can place them in AFUWeb_cert_backup directory prior to the installation of web applications.
      • After migration, eWAS certificate stores will be placed in <ICC_installation_directory>\AFUWeb_cert_backup _ewas directory.
  2. Liberty certificate store is restored if:
    1. The <ICC_installation_directory>\AFUWeb_cert_backup directory is present, and
    2. It contains the Liberty certificate store (key.p12).
In most of the upgrade scenarios, either of the 2 cases mentioned above will be satisfied and migration / restore will happen automatically during installation. If none of the cases are satisfied, a self-signed certificate will be generated during the installation.
Independent migration of certificate stores
For migrating certificate stores without having to install or reinstall the web application, you can perform the following procedure.
Steps to migrate eWAS certificate stores to WAS Liberty certificate store:
  1. Open the command prompt as administrator and go to the following:
    <ICC_installation_directory>\AFUWeb
  2. Run the following command:
    afu_ewas_migrate_cert.bat migrate eWASCertDir [OutputDir]
  • Replace eWASCertDir with the directory where eWAS certificate stores are present
  • Replace OutputDir with the directory where Liberty certificate store key.p12 should be stored. If not specified, the default location is set to the following directory:
    <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AFUWeb\resources\security
IV. Establishing a trust relationship with IBM FileNet P8
 

Follow the below steps to establish a trust relationship between the IBM Content Collector Web Application Server and IBM FileNet P8:

  1. Open the command prompt and go to the following directory:
    <ICC_installation_directory>\AFUWeb\wlp\usr\servers\<ServerName>
  2. Type ikeyman to open the IBM Key Management tool.
  3. Go to the Key Database File menu and click Open. 
  4. Select PKCS12 from the drop-down list of the Key database type field in the pop-up window.
  5. Type or paste the file name key.p12 in the File Name field or click the Browse button and select the key.p12 file.
  6. Ensure that the Location field is updated as per the following:
    <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AfuWeb\resources\security
  7. Click OK.
  8. Enter the password when prompted to and click OK. The default password is Passw0rd.
    Note that the password is case sensitive. In a production environment, change the password as described in the topic about updating default key store passwords using scripting in the IBM WebSphere Application Server Liberty Knowledge Center.
  9. Select Signer Certificates from the Key database content drop-down list and click Add to add the certificate of the CA that issued the FileNet P8 Server certificate as trusted authority to the trust store.
    For certificates that are not issued by a root CA but by an intermediate CA, you must add the complete certificate chain up to the root CA.
  10. Close the IBM Key Management tool.
  11. Stop and restart the service for the WebSphere Application Server Liberty (IBM Content Collector Web Application service). 
    1. To stop the service, click Start > All Programs > IBM Content Collector > Stop Services > Stop ICC Web Applications.
    2. To restart the service, click Start > All Programs > IBM Content Collector > Start Services > Start ICC Web Applications.

V. Known issues / Limitations

  1. Support for IBM Content Collector Web Application services application programming interfaces (APIs) is available only from IBM Content Collector 4.0.1 Fix Pack 10 Interim Fix 5.
  2. Web Application deployment on External Web Application Server is available only from IBM Content Collector 4.0.1 Fix Pack 10 Interim Fix 5.
  3. After upgrading to 4.0.1 Fix Pack 10, IBM Content Collector Web application IsAlive page may give 500 Error on the first launch. This may be due to the longer time taken by deployment during Fix Pack installation, causing incomplete extraction of AfuFolder.
    Workaround: Uninstall and reinstall the IBM Content Collector Web Application.
  4. Due to SSL handshake communication error below issues may occur:
    • The SMTP Receiver service may fail to run
    • The Web Application Search Page may fail to load when launched through Notes client
    Note: This issue has been resolved in Content Collector 4.0.1 Fix Pack 10 Interim Fix 7 as part of the certificate migration.

    Workaround: Recreate the certificate:
    1. Delete key.p12 from <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AFUWeb\resources\security.
    2. Navigate to the AFUWeb directory and run afu_ewas_exchange_cert.bat. This step creates the certificate store used by Liberty.
    3. Restart IBM Content Collector Web Application.
  5. During ICC Web Application uninstallation or Content Collector repair if additional certificates were added to the Liberty certificate keystore, perform the following steps. This is required since the certificate type in eWAS is different than that in WebSphere Liberty. This issue has been resolved in Content Collector 4.0.1 Fix Pack 10 Interim Fix 7.

    Workaround: Backup and restore the Liberty certificate keystore manually
    1. Before uninstalling the Liberty Web Application profile, take a backup of the liberty profile directory:
      ..\AFUWeb\resources\security
    2. After the installation of the Liberty Web Application profile is completed, restore the certificate to the Liberty profile directory.
    3. Reconfigure the web application service.
  6. Archived email documents cannot be previewed or opened using IBM Content Navigator in IBM Content Collector 4.0.1 Fix Pack 10.
    This has been fixed in IBM Content Collector 4.0.1 Fix Pack 10 Interim Fix 5.
    Workaround: Reconfigure DocViewer
    1. Start ICC Web Application Service.
    2. Ensure that the isAlive page loads: https://<ICC_SERVER>:11443/AFUWeb/isAlive.jsp
    3. Perform the following:
      1. Extract OIT_windows.zip located at <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AFUWeb\apps\expanded\DocViewer.ear\DocViewer.war\WEB-INF\classes
        to
        <ICC_installation_directory>\AFUWeb\DocViewer\lib
      2. Copy convertFileToFormat.exe from <ICC_installation_directory>\AFUWeb\wlp\usr\servers\AFUWeb\apps\expanded\DocViewer.ear\DocViewer.war\WEB-INF\classes 
        to
        <ICC_installation_directory>\AFUWeb\DocViewer\lib
    4. Copy edclog.jar and edcutil.jar from <ICC_installation_directory>\lib
      to
      <ICC_installation_directory>\AFUWeb\afu\sharedLibraries
    5. Add <ICC_installation_directory>\AFUWeb\DocViewer\lib to system PATH variable.
    6. Restart web application service.
    7. Ensure that the isAlive page loads: https://<ICC_SERVER>:11443/AFUWeb/isAlive.jsp
      If the isAlive page loads, the DocViewer is configured and you can now preview or open email documents.

Document Location

Worldwide

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSAE9L","label":"Content Collector"},"Component":"","Platform":[{"code":"PF033","label":"Windows"}],"Version":"4.0.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
21 December 2020

UID

ibm10883054

Page Feedback