Upgrading

Edit online

This section provides users with the information needed to understand the upgrading guidelines for Connect:Direct for Web Services.

Upgrading Guidelines

Edit online

Observe the following guidelines for upgrading IBM® Connect:Direct® Web Service from an earlier version.

  • Before you perform any upgrade procedure, create backup copies of the following IBM Connect:Direct Web Service database and system files. Taking a backing of the following files will helps you preserve your data and restore the previous set up in case of a failed upgrade.
    Note: The file path given below are relative to the installation directory.
  • If in any case upgrade installation is corrupted, you have the option to re-install the earlier version, replace the backup files and restart the services manually.
Table 1. Connect:Direct Web Services system files
File Name Path
application.properties mftws/BOOT-INF/classes
hiddenFile mftws/BOOT-INF/classes
ssl-server.jks mftws/BOOT-INF/classes
trustedKeystore.jks mftws/BOOT-INF/classes
script utilities bin directory
uninstall.sh UninstallerData
log4j2.yaml
Note: For users upgrading from a version <v6.1.0.3 backup log4j.properties file.
 mftws/BOOT-INF/classes

** for users upgrading from a version <= v6.0.0.4

Table 2. Connect:Direct Web Services database files upgrading from a version <=v6.0.0.4
File Name Path
Redis redis

* for users upgrading from v6.0.0.5 till v6.2.0.9

Table 3. Connect:Direct Web Services database files for users upgrading from a version >= v6.0.0.5 and a version <= 6.2.0.9
File Name Path
PostgreSQL PostgreSQL
Table 4. Connect:Direct Web Services files for users upgrading from a version >= v6.2.0.10
File Name Path
JSONFileSystem JSONFileSystem

Upgrading Connect:Direct Web Services on zLinux and AIX systems

Observe the following guidelines only when you upgrade from a version >= 6.1.0.0 and a version <= 6.2.0.9.
Note: Do not log into the Connect:Direct Web Services application until the database backup and restore scripts complete all of its processes as described below.
  1. Ensure that the following two scripts are placed inside the same directory other than the installation directory. These scripts come bundled in installer .tar.gz file.
    backup.sh
restore.sh
  2. Issue the following command to initiate database backup.
    Note: Ensure that the PostgreSQL database password, hostname, and port entries match the database connection details provided at a version >= 6.1.0.0 and a version <= 6.2.0.9
    bash-5.0# ./backup.sh

Enter absolute path of PostgreSQL bin directory:
/usr/bin

Enter PostgreSQL Password:

Enter PostgreSQL Hostname:
localhost

Enter PostgreSQL Port:
5432
  3. Initiate the upgrade process as described in Upgrading Web Services on AIX and Upgrading Web Services on zLinux.
  4. Execute the following command to initiate database restore.
    Note: From release CDWS 6.2.0.10, execution of restore.sh is not needed, as data backup and restore will be done automatically during upgrade.
    bash-5.0# ./restore.sh

Enter absolute path of PostgreSQL bin directory:
/usr/bin

Enter PostgreSQL Password:

Enter PostgreSQL Hostname:
localhost

Enter PostgreSQL Port:
5432
  5. The upgrade process is complete. You can now login to the application via. Web Console or RESTful API interface.

Upgrade Guidelines

Edit online

Observe the following guidelines:
  • You must plan the upgrade activity during a planned maintenance window.
  • Before you perform any upgrade procedure, create backup copies of Connect:Direct Web Services database and system files. For details see, Upgrading Guidelines.
  • A Connect:Direct user cannot perform any operation on IBM Connect:Direct Web Services during the upgrade process.
    Note: IBM Connect:Direct Web Services will restart during this process. It is recommended that you stop any instance of Web Services, if running.

    Do not stop the execution of the Postgres instance while upgrading. If this happens, the existing data in the previous Postgres instance will be lost.

Upgrading Web Services on Windows

Edit online

Procedure

To upgrade the IBM Connect:Direct Web Service on a Windows platform follow the steps given below.

Note: Before you perform any upgrade procedure, create backup copies of Connect:Direct Web Services database and system files. For details see, Upgrading Guidelines.

  1. If you downloaded the software from IBM Passport Advantage, unzip the Installer zip file and double click on MFTWebServices.exe file.
    Note: For information on the how to download software using Passport Advantage see, Passport Advantage.
    InstallAnywhere window appears containing a progress bar and Cancel button. Wait for the progress bar to complete to 100%.
  2. In the Upgrade Confirmation window, click Upgrade to continue with the upgrade.
  3. The Upgrade Guidelines window appears. This window serves as a welcome screen with a Guided Setup on the left. The Guided Step up is an upgrade status panel. As you complete each task, the status panel is updated. Click Next.
  4. Read the upgrade guideline screen displayed and press ENTER to continue.
  5. Click Next to continue.
  6. The Ports window appears. Enter the following:
    Attention: CDWS 6.2.0.10 onwards steps related to Postgres are not applicable
    • PostgreSQL database port. For example:
    PostgreSQL database Port

    Default: 5432
    Note: Follow this step only if you are upgrading from version prior to v6.0.0.5.
  7. Click Next to continue.
  8. In the Pre-Installation Summary window, review the information, and then click Next.
  9. The Upgrade Guideline screen displays. Click Next to continue.
  10. The Upgrade Notice displays. Click Next to continue.
  11. Configuration data backup begins.
  12. User is one step away from Upgrade and the Pre-upgrade summary displays.
  13. Click Upgrade to continue.
  14. Old version of the IBM Connect:Direct Web Services is removed before the new version is installed.
Note:
  • Previous version CDWS logs can be found at INSTALLATION_DIRECTORY/OldVersions/logs.
  • Redis data is automatically backed up in case installation procedure detects failure when migrating data from redis to postgres (while upgrading from CDWS version prior 6.0.0.5). In this case Redis data can be found at INSTALLATION_DIRECTORY/redisDataBackup.

Upgrading Web Services on UNIX

Edit online

About this task

To upgrade the IBM Connect:Direct Web Services from command line on UNIX follow the steps given below.

Procedure

Log on to the UNIX system and ensure that you have executable privileges required to upgrade the software. You can create an account specifically for this purpose.
Note: Ensure that you login to the same functional account to upgrade and install Connect:Direct Web Services. The screen shots given below are examples and not definitive of what you see on your screen.

On upgrading installer with different user getting error message

  1. Untar the installer .tar.gz file. Refer cdws_install_cdws_overview.html table.
  2. Run following script. 
    MFTWebServicesInstall.sh
  3. The installation menu appears. Enter the instance option serial number to upgrade and press ENTER to confirm.

    Specify the instance that you want to upgrade.

    1. $HOME/MFTWebServices

    Enter 1 for first instance, 2 for second instance, and so on:

    ============================================

    MFTWebServices (created with InstallAnywhere)

    ---------------------------------------------------------------------------

    Preparing CONSOLE Mode Installation...

    ============================================

    Please Wait

    -----------------

    .............................................................................….….….…...

    ==========================================
  4. Read the upgrade guideline screen displayed and press ENTER to continue.
    Upgrade Guidelines

    ---------------------------

    Welcome to the upgradation wizard for MFTWebServices.

    This wizard is going to guide you through the upgradation of

    MFTWebServices.

    You are strongly recommended to quit all programs before continuing with this

    upgrade.

    Respond to each prompt to proceed to the next step in the upgrade.

    Licensed Materials - Property of IBM Corp. © IBM Corporation and other(s).

    2023.

    PRESS <ENTER> TO CONTINUE:
  5. The Upgrade Notice displays. Read the Upgrade Notice and press ENTER to continue.
    Upgrade Notice

    ----------------------

    The existing installation of MFTWebServices in

    $HOME/MFTWebServices is going to be upgraded.

    The existing library files will be uninstalled, but all configuration data

    such as properties file, Keystore, Truststore and configuration files will be

    retained.

    Before you proceed with the upgrade, backup your existing configuration data.

    During MFTWebServices upgrade , the installer is going to attempt to backup

    your existing configuration data.

    Note: During Upgrade the user will not be able to login or perform any

    operation on MFTWebServices.

    Do not 'quit' before Upgrade process is completed.

    PRESS <ENTER> TO CONTINUE:
  6. Configuration data backup begins.

    ==========================================

    Backup of Configuration data

    ------------------------------------------

    Configuration data backup is successful

    ============================================
  7. User is one step away from Upgrade. The pre-upgrade summary is displayed.
    Press ENTER to continue.

    ==============================================

    Pre-Upgrade Summary

    --------------------------------

    Review the following information before you continue the upgrade:

    Product Name:

    MFTWebServices

    Install Folder:

    $HOME/MFTWebServices

    Install Set:

    Typical

    Base Upgrade Version

    6.0.0.5

    Product will be upgraded to

    6.3.0.0

    Disk Space Information (for Installation Target):

    Required: 345 MegaBytes

    Available: 4,634.47 MegaBytes

    PRESS <ENTER> TO CONTINUE:
  8. Old version of the IBM Connect:Direct Web Service is removed before the new version is installed.
    =============================================

    Please Wait

    --------------------

    Uninstalling older installation : ConnectDirectWebServices-6.0.0.5

    ==============================================
  9. Upgrade to a new version is complete. The following output is displayed:
    Upgrade Complete

    -----------------------------

    ConnectDirectWebServices-6.0.0.5 has been successfully upgraded to

    ConnectDirectWebServices-6.3.0.0 and located at:

    $HOME/MFTWebServices

    PRESS <ENTER> TO EXIT THE INSTALLER:

Silent Upgrade for Connect:Direct Web Services

Edit online

Connect:Direct Web Services administrators can use procedures defined in the following sections to run an unattended install with minimal user interaction. Silent installs can be used for repetitive installs in your deployment.

Upgrade Considerations

  • Ensure that the installation executable file, script, and silentInstall.properties file are placed in the same directory. Also, do not rename these files.

  • The same silentInstall.properties file that was used to perform silent installation must be used to upgrade Connect:Direct Web Services to a different version.

  • When you upgrade from version < 6.0.0.5 the user must update database properties that is, Redis properties (REDIS_PORT) must be replaced with changed PostgreSQL properties (POSTGRES_PORT and POSTGRESQL_PASSWORD) in the silentInstall.properties file.

    Attention: CDWS 6.2.0.10 onwards steps related to Postgres are not applicable
A Silent install is implemented in two steps:
  1. Supply values in the silentInstall.properties file included in software package, Fix Pack 3 (v6.0.0.3) and above.

    silentInstall.properties file defines the installation configuration that you would normally enter during an interactive installation process (console-mode installation). The silentInstall.properties file is subsequently used to silently install Connect:Direct Web Services.

    Before you begin

    The following Connect:Direct Web Services minimum version levels are required to perform silent installation:

    Table 5.
    Product Minimum Version
    IBM Connect:Direct Web Services Fix Pack 3 (v6.0.0.3)
    The following table lists script files to be used by Operating Systems to perform unattended installation.
    Table 6. Silent Installer script name by OS
    Operating System Silent installation script name
    Windows MFTWebServicesInstall.bat
    UNIX MFTWebServicesInstall.sh
  2. To perform silent installation see the following examples:

    UNIX environment (RHEL)

    When executing the MFTWebServicesInstall.sh, pass the argument silent to the script.

    [user@SolQA-02 CDWS_6.1.0.1]$ ./MFTWebServicesInstall.sh silent
Installing Webservices...
Installer installed/upgraded correctly.
Please refer INSTALLATION_DIRECTORY/README.txt for getting started with MFTWebservices.
Press any key to continue.....

    WINDOWS environment

    To install in a Windows environment, execute the MFTWebservicesInstall.bat file available in the download folder. 
    C:\Users\Administrator\Desktop\CDWS_Installer\CDWS_6.1.0.0_01_05_2020>MFTWebservicesInstall.bat 
Installing Webservices...
"Exit Code: 0"
Installer installed/upgraded correctly.
Please refer INSTALLTION_DIRECTORY/README.txt for getting started with MFTWebservices.
Press any key to continue . . .

    Error Handling during Silent Install

    • If you encounter problems when performing a silent installation review the log file, failure.txt, available inside the logs directory at the same location where you have installed Connect:Direct Web Services.
    • If silent installation does not begin:
      • Cleanup the registry settings in the .com.zero.registry.xml

        In UNIX environment, this file is located in /var for Root users and $HOME/for non-root users. In Windows, this file is located in C:\Program Files\Zero G Registry.

      • Edit the Zero G registry file to remove entries that begin with MFTWebServices and delete any entries beginning with the following tag: 
        <product name="MFTWebServices">...</product>
      • Attempt silent installation again.

Connect:Direct Web Services Silent Install and Silent Upgrade Example

Edit online
Procedure
  1. Download the installation package from Fix Central and navigate to the directory where the installation package is downloaded.

    The following files will be used to perform Silent Installation:

    • silentInstall.properties

    • MFTWebservices.exe

    • MFTWebservicesInstall.bat (for Windows)
    • MFTWebServicesInstall.sh (for UNIX)
  2. Modify the silentInstall.properties file based on your requirements.
Table 7. Common Parameters for Window/Unix-based Silent installation
Parameters Mandatory/Optional Description
Read-Only parameters
INSTALLER_UI Use default value Do not modify this attribute.
CHOSEN_INSTALL_SET Use default value Do not modify this attribute.
Editable Parameters
USER_INSTALL_DIR M The directory where the installer will get installed.

For Unix, example: /root/MFTWebServices

For Windows, directories should be separated with double backslash. (\\)

Example: C:\\Program Files\\MFTWebservices
SSL_PORT M Port number used to communicate with the Jetty server.
KEYSTORE_PASS M This attribute can contain either clear text or base64 encoded password for the Keystore where the certificate will be placed. When a clear text password is provided, the value will be encrypted and updated in the silentInstall.properties file. The Keystore password must be 6 or more characters.
CONFIRM_PASS M This attribute should store the same value as KEYSTORE_PASS attribute.
TRUSTSTORE_PASS M This attribute can contain either clear text or base64 encoded password for the Truststore where the certificate will be placed. When a clear text password is provided, the value will be encrypted and updated in the silentInstall.properties file. The Truststore password must be 6 or more characters.
CONFIRM_TRUSTSTORE_PASS M This attribute should store the same value as TRUSTSTORE_PASS attribute.
CERTIFICATE_TYPE M

This attribute stores value for certificate type to be used for secured communication

Possible values:
  1. Generate Self Signed certificate
  2. Import CA Signed certificate

Default value: 1
TRUST_CERTIFICATE_FILE O

This attribute should contain the full path of the file with the file name. It only considers PEM format extension certificate.

For Unix, example: /root/Certificates/trustCert.pem

For Windows, directories should be separated with double backslash. (\\)

Example: C:\\Certificates\\trustCert.pem

Note: If set empty, then import will be skipped.
BACKUP_CONFIG_DATA O

This attribute decides whether to backup the data during uninstallation of the product.

Valid Values are:
  • yes to save the data after uninstallation (Default Value)
  • no to not save the data after uninstallation
Note: If yes is mentioned it will backup configuration data at $INSTALLATION_DIRECTORY/backup Files location.
Table 8. Common parameters based on certificate type
Parameters Mandatory/Optional Description
If certificate type is Self Signed certificate
CERTIFICATE_LABEL M This attribute should store the certificate label or alias of the certificate entered in lower case.
CERTIFICATE_EXPIRY_TIME M This attribute should store the expiry time in days.

Value entered should be greater than 0.
COMMON_NAME M

This attribute should store the Common Name of the certificate.

Values not allowed:
  • Special characters
  • IP addresses, Port numbers
  • "http:// or https://"
ORGANISATION M This attribute should store an Organization Name that must be registered with some authority at the national, state, or city level.

Use the legal name under which your organization is registered. Do not use an abbreviated form or use any of these symbols: ! @ # $ % ^ * ( ) ~ ? > < / \.
LOCALITY M This attribute should store the name of locality/city where the organization is located.
STATE M This attribute should store the name of state where the organization is located.
COUNTRY M This attribute should store country code in the standard format where the organization is located.
EMAIL_ID M This attribute should store e-mail ID for the support group.
DNS_NAME M This attribute should store the domain name secured by the certificate.
IP_ADDR M This attribute should store the IP address secured by the certificate.
EXPORT_CERTIFICATE_LOC O

This attribute should contain the valid absolute path to save the self signed public certificate.

For Unix, example : /root/MFTWebservices

For Windows, directories should be separated with double backslash. (\\)

Example : C:\\Program Files\\MFTWebservices

Note: If set empty, export will be skipped.
If certificate type is CA Signed certificate
CA_CERTIFICATE_FILE M This attribute should contain the full path of the file with the file name. It only considers PEM or PKCS12 format extension certificate. The file must contain the private key, the CA-signed certificate, the CA certificate and all intermediate certificates.

For Unix, example: /root/Certificates/certFile.pem

For Windows, directories should be separated with double backslash. (\\)

Example: C:\\Certificates\\certFile.pem
CA_CERTIFICATE_PASSWORD M This attribute should contain the private key password of the CA Signed certificate. The password would be the Base64 password.
CERTIFICATE_LABEL M This attribute should store the certificate label or alias of the certificate entered in lower case.