7 Upgrading Convergence

This chapter describes how to upgrade Oracle Communications Convergence.

This chapter does not explain how to install patches on Convergence.

About Upgrading Convergence

In this chapter, the release from which you are upgrading is called the old release, and the release to which you are upgrading is called the new release.

Upgrading to a new release of Convergence consists of the following tasks:

  • Planning the upgrade

  • Reviewing the upgrade impacts

  • Performing the pre-upgrade tasks

  • Upgrading Convergence

  • Performing the post-upgrade tasks

Before upgrading a production environment, you should first test the upgrade in a test environment. See "Testing the Upgrade in a Test Environment" for more information.

Supported Upgrade Paths

You can upgrade to the new version of Convergence from the 3.0.1.x version.

See "Upgrading from 3.0.1.x to 3.0.2" for more information.

Planning Your Convergence Upgrade

Depending on the components affected by the upgrade, your upgrade team may include the following:

  • A system administrator, to manage any changes to Oracle certified application server and to upgrade other Oracle Communications software.

  • A UNIX administrator, to manage accounts, network setup, and IP configurations.

Identify who might be affected by the upgrade. For example:

  • You might need to give your system administrators and users notice of downtime.

  • Tell your system administrator in advance about any changes to the system architecture.

  • Train your administrators, users, and developers on new functionality introduced by the upgrade that has an impact on their role.

You might need to make changes to your system after the upgrade is complete to accommodate new or modified features or functionality. For example, if the new release provides new security functionality, additional system configuration steps may be required. See "Upgrade Impacts" for more information.

The best way to estimate the duration of an upgrade is to perform it on a test system with a copy of the production data. See "Testing the Upgrade in a Test Environment" for more information.

Oracle recommends scheduling your upgrade during non-peak hours to minimize the disruption to your operations.

Testing the Upgrade in a Test Environment

Oracle recommends running the upgrade procedure on a test system that models your production environment. Test the upgrade by doing the following:

  • Successfully completing all the pre-upgrade, upgrade, and post-upgrade tasks.

  • Comparing the default behavior between the old and the new releases.

  • Test that your customizations are preserved. Recreate any custom configurations and customizations that could not be upgraded.

  • Confirming that all new behavior and functionality works.

  • Restarting the Convergence server.

  • Log into Convergence and verify its version number

Upgrade Impacts

This section explains any important system changes introduced in the new release of Convergence.

This section does not describe new features or functionality. See Convergence Release Notes for information about new features.

Upgrade Impacts from Version 3.0.1.x to 3.0.2

Upgrading to the new version of Convergence includes the following system changes:

Java Development Kit Changes

The new version of Convergence requires an updated version of the Java Development Kit (JDK) on the Convergence server. See "System Requirements" for more information. Upgrade Java before upgrading Convergence.

Directory Server Schema Changes

The new version of Convergence requires an updated version of the directory server schema.

Unified Communications Suite Software Compatibility Changes

The new version of Convergence may be compatible with a few older versions of other Unified Communications Suite software. However, it is recommended to upgrade the other Unified Communications Suite software to the latest version to use with this release of Convergence. See "Software Requirements" for more information.

Oracle WebRTC Session Controller Upgrade

The new version of Convergence requires an updated version of WebRTC Session Controller. If you already integrate Convergence with WebRTC Session Controller to provide Web real-time communication services, you must upgrade WebRTC Session Controller and reconfigure Convergence. See "System Requirements" for more information.

Upgrading from 3.0.1.x to 3.0.2

To upgrade to the new release of Convergence, complete the following:

Pre-Upgrade Tasks (3.0.1.x to 3.0.2)

Before upgrading Convergence, do the following:

  1. Install or upgrade the following software:

    • Upgrade the JDK

    • (Optional) Install Oracle Access Manager

    • Install OpenLDAP client or Install Oracle Directory Server Enterprise Edition (ODSEE) based LDAP client

  2. Determine whether you need to update the directory server schema version.

    See "Preparing the Directory Server" for more information.

  3. Upgrade or install all required and optional Unified Communications Suite software needed to deliver your existing and planned Convergence services. For example, if you are integrating Convergence with Contacts Server to deliver the address book service, install Contacts Server. If you decide to upgrade to a new version of Oracle Communications Messaging Server, upgrade Messaging Server.

    Refer to your application installation documentation for upgrade and installation instructions.

  4. Create a directory (dir) on each Convergence host system.

  5. Download the Convergence software for your operating system from the Oracle software delivery web site:

    https://edelivery.oracle.com/

    The Convergence software is included in the Oracle Communications Messaging Server and Oracle Communications Calendar Server software package.

  6. Extract the Convergence software to dir.

Upgrading Convergence (3.0.1.x to 3.0.2)

You use the commpkg upgrade command to upgrade to the new version of Convergence. The commpkg upgrade command upgrades Convergence with an in-place package replacement that cannot be reversed.

To upgrade Convergence on each Convergence host system:

  1. Verify that the GlassFish Server is running.

  2. Verify that the directory server is running.

  3. Verify that all the Unified Communications Suite software with which you intend to integrate Convergence is running.

  4. Make sure that the JAVA_HOME variable is set to JDK_location in the current shell or in GlassFish Server user profile.

  5. From dir, run the upgrade installer:

    ./commpkg upgrade
    

    See "commpkg Reference" for more information about the commpkg command.

  6. From the list of available Communications Products for upgrade, select Convergence and proceed with the upgrade.

  7. When the installer has completed the upgrade, restart the GlassFish Server domain on which Convergence is deployed:

    asadmin restart-domain Convergence_Domain
    

Post-Upgrade Tasks (3.0.1.x to 3.0.2)

After the Convergence upgrade has completed successfully, do any of the following that apply to you:

  • Configure Convergence to work with newly installed Unified Communications Suite software. For example, if as part of this upgrade, you are integrating Convergence with Contacts Server for the first time, you need to configure Convergence to communicate with Contacts Server.

    See "Configuring Convergence" for more information.

  • If, in a previous release of Convergence, you integrated Convergence with Oracle WebRTC Session Controller to deliver Web real-time communications services, you must upgrade WebRTC Session Controller. Refer to the WebRTC Session Controller documentation for information. Then you must reconfigure the integration between Convergence and WebRTC Session Controller. See the discussion about configuring WebRTC services in Convergence in Convergence System Administrator's Guide for more information.

  • All logging configurations except for the HTTPBIND, HTTPBIND_XFER, and HTTPBIND_AVATAR components are preserved. Configure logging properties for the HTTPBIND, HTTPBIND_XFER, and HTTPBIND_AVATAR components of Convergence using the iwcadmin command. The existing changes to HTTPBIND logging will not be preserved in the httpbind_log4j.conf file in Convergence configuration directory.

    After upgrade, HTTPBIND logs will be in the httpbind.log file in Convergence log directory even if they are changed before the upgrade. However, you can set the logging properties for the HTTPBIND, HTTPBIND_XFER, and HTTPBIND_AVATAR components by running the iwcadmin command. Setting the logging properties for these components is a one-time activity. So, once the logging properties are configured by using the iwcadmin command, you can freely upgrade to some other version later and the configuration changes will be preserved.

    This example shows how to set the logging properties for the HTTPBIND component after the appender reference is set for the component:

    iwcadmin -o log.HTTPBIND.appendername -v HTTPBIND_APPENDER
    iwcadmin -o log.appender.[HTTPBIND_APPENDER].type -v FILE
    iwcadmin -o log.appender.[HTTPBIND_APPENDER].location -v /var/opt/sun/comms/iwc/logs/iwc_httpbind.log
    iwcadmin -o log.appender.[HTTPBIND_APPENDER].sizetriggerval -v 5120
    iwcadmin -o log.appender.[HTTPBIND_APPENDER].maxbackupindex -v 7
    iwcadmin -o log.appender.[HTTPBIND_APPENDER].pattern -v '[%d{DATE}] %-5p %c [%t] %m%n'
    

    Similarly, you can set the logging properties for the HTTPBIND_XFER and HTTPBIND_AVATAR components by running the iwcadmin command.

    See the discussion about Logging in Convergence System Administrator's Guide for more information.

About Migrating Convergence Deployment from GlassFish Server 3 to GlassFish Server 5

Convergence supports both GlassFish Server 3 and GlassFish Server 5. If you are migrating Convergence deployment from GlassFish Server 3 to GlassFish Server 5, do the following to prepare Convergence for migration:

Note:

You have to manually install and configure GlassFish Server 5.

Note:

GlassFish Server 5 requires Oracle JDK 8 Update 144 to Oracle JDK 8 Update 152.

Planning Backup

You must implement a backup for the following directories before migrating Convergence deployment from GlassFish Server 3 to GlassFish Server 5:

  • Backup Convergence configuration directory.

  • Backup Convergence customization directory in case of any customization is done in Convergence GlassFish Sever 3 deployment.

  • Backup output of iwcadmin -l command.

  • Stop GlassFish Server 3 domain where Convergence is deployed. In the following example, the domain is iwcdomain:

    GlassFish_Home/bin/asadmin stop-domain iwcdomain
    

    where, GlassFish_Home is the directory in which the GlassFish Server software is installed.

Migrating Convergence Deployment from GlassFish Server 3 to GlassFish Server 5

You can not upgrade GlassFish Server 3 to GlassFish Server 5 directly, as Update Tool and pkg command are no longer part of GlassFish Server5. However, there are different approaches that you can use to migrate an existing Convergence deployment in GlassFish Server 3 to GlassFish Server 5.

The different approaches that you can use to migrate the Convergence deployment to GlassFish Server 5 from GlassFish Server 3 are as follows:

Approach 1

In this approach, you configure and deploy Convergence in GlassFish Server 5 and copy the changes from GlassFish Server 3 deployment. This approach can be used to migrate any previous Convergence deployment to the latest.

In this approach, you perform the following steps:

  1. Download the glassfish5.zip file and unzip the file under required location.

    GlassFish Server 5 contains default domain, domain1. A new domain can also be created for deploying Convergence. If the default domain is used, the admin password and master password has to be updated.

  2. Configure AS_JAVA variable in the GlassFish_Home/config/asenv.conf file.

    where, GlassFish_Home is the directory in which the GlassFish Server software is installed.

    Example, AS_JAVA=/usr/jdk/jdk1.8.0_152
    
  3. Enable secure admin to login into admin console remotely. In this example, the administrator port is 4848.

    GlassFish_Home/asadmin enable-secure-admin --port 4848
    
  4. Start GlassFish Server 5 domain. In the following example, the domain is domain1:

    GlassFish_Home/bin/asadmin start-domain domain1
    
  5. From dir, run the installer:

    ./commpkg install
    

    See "commpkg Reference" for more information about the commpkg command.

  6. Run the Convergence initial configuration script to configure Convergence.

  7. Login to Convergence to check deployment in GlassFish Server 5.

  8. Check the configuration details from previous deployment using iwcadmin -l output and redo the changes using iwcadmin command.

  9. If you want to enable customization , enable the Convergence server for customization using the iwcadmin command:

    iwcadmin -o client.enablecustomization -v true
    
  10. Make sure to have customization directory available for GlassFish Server 5 as required and copy the changes in the customization directory from previous deployment to GlassFish Server 5 location.

  11. Restart GlassFish Server 5 and check the deployment.

Approach 2

In this approach, Convergence is upgraded to 3.0.2 by modifying savestate file with GlassFish Server 5 installation details. The silent configuration file, called saveState is created in the Convergence_Home/data/setup/Iwc-config-YYYYMMDDHHMMSS directory.

where, Convergence_Home is installation location for the Convergence software and YYYYMMDDHHMMSS represents the date and time of the saveState file.In this approach, you perform the following steps:

  1. Download the glassfish5.zip file and unzip the file under required location.

    GlassFish Server 5 contains default domain, domain1. If the default domain is used, the admin password and master password has to be updated. A new domain can also be created for deploying Convergence, with same admin user details as with GlassFish Server 3.

  2. Configure AS_JAVA variable in the GlassFish_Home/config/asenv.conf file.

    where, GlassFish_Home is t.he directory in which the GlassFish Server software is installed.

    Example, AS_JAVA=/usr/jdk/jdk1.8.0_152
    
  3. Enable secure admin to login into admin console remotely. In this example, the administrator port is 4848.

    GlassFish_Home/asadmin enable-secure-admin --port 4848
    
  4. Start GlassFish Server 5 domain. You will need to specify the GlassFish domain in which you plan to deploy Convergence. In the following example, the domain is domain1:

    GlassFish_Home/bin/asadmin start-domain domain1
    
  5. Modify the saveState file created when Convergence is deployed using GlassFish Server 3. Modify GlassFish Server 3 locations by GlassFish Server 5 location and port details. The parameters like iwc.appsrv.* (iwc.appsrv.installDirectory, v, or iwc.appsrv.DocumentRootDirectory) has to be updated properly. Following is the example of saveState file created in GlassFish Server 3 deployment:

    iwc.appsrv.installDirectory = /opt/glassfish3
    iwc.appsrv.DomainDirectory = /opt/glassfish3/glassfish/domains/domain1
    iwc.appsrv.DocumentRootDirectory = /opt/glassfish3/glassfish/domains/domain1/docroot
    iwc.appsrv.TargetName = server
    iwc.appsrv.virtualServerID = server
    iwc.appsrv.portNumber = 443
    iwc.appsrv.AdminHost =hostname
    iwc.appsrv.AdminPort = 4848
    iwc.appsrv.AdminUserID = admin
    iwc.appsrv.AdminUserPassword = encrypted_password
    iwc.appsrv.IsSecureAdminServerInstance = true
    
  6. From dir, run the upgrade installer:

    ./commpkg upgrade
    

    See "commpkg Reference" for more information about the commpkg command.

  7. Restart GlassFish domain.

  8. Login to Convergence to check deployment in GlassFish Server 5.

  9. If customization was enabled in GlassFish Server 3 deployment, make sure the parameter client.enablecustomization is set to true after Convergence upgrade. Otherwise, you can enable the Convergence server for customization using the following iwcadmin command:

    iwcadmin -o client.enablecustomization -v true
    
  10. Make sure to have customization directory available for GlassFish Server 5 as required and copy the changes in the customization directory from previous deployment to GlassFish Server 5 location.

  11. Restart GlassFish Server 5 and check the deployment.

Approach 3

In this approach, the GlassFish Server 3 installation directory contents will be replaced with GlassFish Server 5 installation directory contents.

In this approach you perform the following steps:

  1. Move the GlassFish Server 3 location to a different location by using the following command:

    mv GlassFish3_Home GlassFish3_backup_location
    

    where, GlassFish3_Home is the directory in which the GlassFish Server 3 software is installed and GlassFish3_backup_location is the directory where the GlassFish Server 3 software is moved.

  2. Download the glassfish5.zip file and unzip the file into the same installation directory as the GlassFish Server 3.

    GlassFish Server 5 contains default domain, domain1. A new domain can also be created for deploying Convergence. If the default domain is used, the admin password and master password has to be updated. You should provide the same username and password as in GlassFish Server 3.

  3. Configure AS_JAVA variable in the GlassFish_Home/config/asenv.conf file.

    where, GlassFish_Home is t.he directory in which the GlassFish Server software is installed

    Example, AS_JAVA=/usr/jdk/jdk1.8.0_152
    
  4. Enable secure admin to login into admin console remotely. In this example, the administrator port is 4848.

    GlassFish_Home/asadmin enable-secure-admin --port 4848
    
  5. Start GlassFish Server 5 domain. You will need to specify the GlassFish domain in which Convergence is deployed. In the following example, the domain is domain1:

    GlassFish_Home/bin/asadmin start-domain domain1
    
  6. From dir, run the upgrade installer:

    ./commpkg upgrade
    

    See "commpkg Reference" for more information about the commpkg command.

  7. Restart GlassFish Server 5 domain.

  8. Login to Convergence to check deployment in GlassFish Server 5.

  9. Check the configuration details from previous deployment using iwcadmin -l output and redo the changes using iwcadmin command. This is done to make sure that most of the configurations is retained.

  10. If you want to enable customization , enable the Convergence server for customization using the iwcadmin command:

    iwcadmin -o client.enablecustomization -v true
    
  11. Make sure to have customization directory available for GlassFish Server 5 as required and copy the changes in the customization directory from previous deployment to GlassFish Server 5 location.

  12. Restart GlassFish Server 5 and check the deployment.

Note:

Existing customization may not work for three-pane layout. The same customization has to be done for GlassFish Server 5.

After the deployment of Convergence has been migrated from GlassFish Server 3 to GlassFish Server 5 successfully, login to convergence. The default layout selected is three-pane layout. You can change the layout by performing any of the following:

  • To change the layout for all the users, you can use the following iwcadmin command:

    iwcadmin -o user.common.layoutPreference -v classic
    

    Restart GlassFish Server.

  • To change the layout for specific users, you can perform either of the following:

    • You can change the layout to two-pane by using the User Interface. See the instruction to change the layout in Convergence Online Help.

    • You can change the layout to two-pane by adding the objectclass:sunUCPreferences and sunUCExtendedUserPrefs:layoutPreference=classic LDAP attributes for a user.

Migrating Convergence Deployment from GlassFish Server to Oracle WebLogic Server

Prerequisites for migrating Convergence from GlassFish Server to Oracle WebLogic Server are:

  • A previous version of Convergence is installed on GlassfFish 3 or GlassFish 5.

  • You must have installed Oracle WebLogic Server 12.2.1.3 and deployed Convergence on Oracle WebLogic Server.

To migrate Convergence deployment from GlassFish Server to Oracle WebLogic Server:

  1. Back up the configuration folder, c11n folder, and output of iwcadmin -1 command.

  2. Install the latest version of Convergence using commpkg tool and upgrade to Convergence 3.0.2.1.0 on GlassFish 3 or GlassFish 5.

  3. After successful upgrade, restart GlassFish Server.

  4. Copy the c11n folder to the docroot folder of the GlassFish domain.

  5. Restart the GlassFish Server to verify everything in the new version of Convergence is fine. For example, login to Convergence and verify that customizations that you have performed work appropriately with the upgraded version of Convergence.

  6. Stop GlassFish Server and start Oracle WebLogic Admin Server and Managed Server.

  7. Configure Convergence.

  8. Copy the backed up c11n folder to the path that is provided in the Document Root Directory (for example, /var/opt/sun/comms/iwc/web-src/client/iwc_static).

  9. Update the missing required configurations on Oracle WebLogic Deployment by comparing the outputs of iwcadmin -l command in GlassFish and Oracle WebLogic deployments.

  10. Copy the required configuration files from the backed up configuration folder to the new configuration folder (for example, advertising.json).

  11. Restart the Managed Server and Login to Convergence to verify that everything is working as expected. For example, you can login to Convergence and access the configured services.