12 You Upgrading Services Gatekeeper

This chapter describes how to upgrade Oracle Communications Services Gatekeeper from version 6.0 to version 6.1. Upgrades are supported on the Linux, Solaris, and Windows operating systems.

For more information about supported operating systems, see "Services Gatekeeper System Requirements".

Upgrading from a Pre-6.0 Release

If you are upgrading from an release previous to 6.0, you must first upgrade to Services Gatekeeper 6.0 +patch set 2:

At this point, you have Services Gatekeeper 6.0 (with patch set 2) installed in your location. To upgrade to Services Gatekeeper 6.1, complete the tasks described in this chapter.

About Upgrading Services Gatekeeper

During the upgrade process, each server in the domain, one at a time, is stopped, upgraded to the new version, and then re-started. This process upgrades the WebLogic Server and the Services Gatekeeper core services, but leaves all communication services unchanged.

After all servers have been upgraded, you need to upgrade the communication services you use. You do this by using in-production redeployment, which is a WebLogic Server feature to upgrade communication services without interrupting traffic.

After the upgrade, the security identity of Services Gatekeeper is the same as it was before the upgrade.

The high-level workflow is:

  1. Gracefully shut down each Services Gatekeeper server.

  2. Upgrade each server. See "Upgrading Services Gatekeeper Servers" for details.

  3. Deploy new Services Gatekeeper applications.

  4. Verify that new traffic is processed.

You should always upgrade the servers in this order:

  1. Administration server

  2. First Access Tier server

  3. First Network Tier server

  4. Second Access Tier server

  5. Second Network Tier server

Oracle strongly recommends that you back up configuration data prior to the upgrade. See ”Managing, Backing Up, and Restoring Services Gatekeeper” in Services Gatekeeper System Administrator's Guide for more information.

Upgrade Restrictions

The following restrictions apply when upgrading Services Gatekeeper:

  • You can upgrade your Services Gatekeeper from release 6.0 + patch set 2 or later to release 6.1. If you need to roll the release level back, the rollback correctly returns the Services Gatekeeper software to the patch set level you upgraded from. However, regardless of the patch set level you started from, your database is automatically returned to the Services Gatekeeper 6.0 + patch set 2 level. If your implementation requires a later patch set database schema, you need to update it manually. Oracle recommends that if you are upgrading from Services Gatekeeper 6.0 + patch set 3 or higher, that you manually keep your database schema in sync. You do this by making a backup copy of the database and then restoring it after you have rolled back the Services Gatekeeper level. See your database documentation for instructions on how to backup and restore the database schema.

    If there is traffic during the database migration, the schema changes to the database tables may result in failure of some data insertions.

  • Do not make configuration changes (such as changing Services Gatekeeper MBean attributes) during the upgrade process until all of the servers in the cluster have been upgraded. This is especially important for new configuration options. Services Gatekeeper servers ignore settings that are not understood, and the local configuration file may not be updated properly.

  • During the upgrade, the location of the old Services Gatekeeper installation and the location of the new Services Gatekeeper installation must be in different directories.

  • Set the number for processes/sessions at database level in Oracle to suit your requirements. If your Oracle database is dedicated to Services Gatekeeper only, then 500 processes are recommended. If your Oracle database is shared between Services Gatekeeper and other systems, set the number for processes to between 1000 and 2000.

  • For Portal analytics, your customers must re-submit the password for the Analytics server.

Placeholders Used in This Chapter

In addition to the placeholders described in "Placeholders Used in this Guide", Table 12-1 describes the directories and values that are specific to upgrading.

Table 12-1 Upgrade-Specific Placeholders

Placeholder Description

new_Middleware_home

The new Middleware home directory is the directory under which you install Services Gatekeeper 6.1. Middleware home is the repository for common files that are used by Oracle Communications service delivery products such as Services Gatekeeper, WebLogic Server, and Java Development Kit.

new_Services_Gatekeeper_home

The directory in which the new version of the Services Gatekeeper software is installed. By default, this is new_Middleware_home/ocsg.

old_version

The two-digit version number, without periods, of the existing Services Gatekeeper version to be upgraded. For example, 60 represents version 6.0.

new_version

The two-digit version number, without periods, of the new Services Gatekeeper version to which you are upgrading. For example, 61 represents version 6.1.

new_domain_home

The directory in which you create the new Services Gatekeeper domain. By default, this is a subdirectory of the new_Middleware_home/user_projects/domains directory.

Domain Home Directory Relocation

During the upgrade process you can select to relocate the domain home in one of two ways:

  • Relocate the domain home for the new release in a directory distinct from the directory used for the previous version.

    To do so, set the domain.relocate property to true. Name the directories in the build.properties file. Table 12-2 uses (6.0) as the old release and (6.1) as the new release.

    Table 12-2 Relocating Domains When domain.relocate is True

    Property Description

    domain.relocate

    Relocate the domain home for the new release in a directory distinct from the directory used for the previous version. Enter:

    domain.relocate = true

    domain61.home

    The directory in which your new Services Gatekeeper domain resides.

    For example, domain61.home=/extradata/wlng_upgrade/install61/user_projects/domains/base_domain

    domain61.portal.home

    The directory in which your new Portal domain resides.

    For example, /extradata/wlng_upgrade/install61/user_projects/domains/portal_domain

    domain60.home

    The directory in which your old Services Gatekeeper domain resides.

    For example, domain60.home=/extradata/wlng_upgrade/install60/user_projects/domains/base_domain

    domain60.portal.home

    The directory in which your new Portal domain resides.

    For example, /extradata/wlng_upgrade/install60/user_projects/domains/portal_domain

    Here is an excerpt from an example file where domain.relocate is set to true.

    adminurl=t3://10.182.12.146:8001 
username=weblogic
password=weblogic123
 
domain.relocate=true
domain61.home=/extradata/wlng_upgrade/install61/user_projects/domains/base_
domain
domain61.portal.home=/extradata/wlng_upgrade/install61/user_
projects/domains/portal_domain
domain60.portal.home=/extradata/wlng_upgrade/install60/user_
projects/domains/portal_domain
domain60.portal.name=portal_domain
domain60.home=/extradata/wlng_upgrade/install60/user_projects/domains/base_
domain
domain60.name=base_domain
server.name=AdminServer
bea60.home=/extradata/wlng_upgrade/install60/
bea61.home=/extradata/wlng_upgrade/install61/
wlsold.home=/extradata/wlng_upgrade/install60/wlserver
wlsnew.home=/extradata/wlng_upgrade/install61/wlserver
ocsg.home=/extradata/wlng_upgrade/install61/ocsg
admin.host=10.182.12.146
admin.port=8001
production.mode=false
coherence.port=9323

    Note the highlighted entries.

  • Use the existing domain home directory for the new release. To do so, set the domain.relocate property to false.

    You do not need to specify the domain61.home and domain61.portal.home properties as was done in Table 12-2.

Handling Case Sensitivity in MySQL

If you are using Oracle database as data source of Services Gatekeeper, please ignore this section.

If you are using MySQL with Oracle Linux as the database for Services Gatekeeper, then complete the steps in this section.

Set the SQL Table name identifier, lower_case_table_names, to be case insensitive when starting mysqld.

To do so:

  1. Go to the location where my.cnf file is located. By default, my.cnf is typically located in /etc.

  2. Open the my.cnf file at a terminal to edit it:

    sudo vi $mysql/my.cnf

  3. Locate this start of the [mysqld] section seen as:

    [mysqld]

  4. Directly below this line, add the following entry:

    lower_case_table_names = 1

  5. Save the file.

  6. Restart mysql:

    sudo /etc/init.d/mysql restart

  7. To verify the change, run this command:

    mysqladmin -u root -p variables

Upgrading Services Gatekeeper Servers

To upgrade a server, perform the following on each machine that hosts your Administration Server, Access Tier server, and Network Tier server:

  1. If your old version of Services Gatekeeper includes Services Gatekeeper Reports, undeploy your Services Gatekeeper Reports application EAR file (edr_to_analytic.ear), which is located in the new_Middleware_home/ocsg/applications directory.

    For more information about using the Administration Console to undeploy applications, see ”Deploying and Undeploying Communication Services and Plug-ins” in Services Gatekeeper System Administrator's Guide.

  2. Stop the server gracefully so that all processing requests are completed before the shutdown begins.

    For information about how to stop a server by using the Administration Console, see ”Starting, Stopping, and Administering Servers” in Services Gatekeeper System Administrator's Guide.

    Note:

    In high-volume traffic situations, you may encounter an excessively long shutdown period. Set a Graceful Shutdown Timeout or enable the Ignore Sessions During Shutdown option to remedy that behavior.

    For information about controlling graceful shutdowns, see the section about controlling graceful shutdowns in Oracle WebLogic Server Administration Console Online Help at

    http://docs.oracle.com/cd/E24329_01/apirefs.1211/e24401/taskhelp/startstop/ControlGracefulShutdowns.html

  3. Install JDK on your system and set the JAVA_HOME environment variable. See Table 3-1 for the JDK correct version (1.8.0.31 or above).

    Download the JDK from the Java page on the Oracle Technology Network website at:

    http://www.oracle.com/technetwork/java/index.html

  4. Install the new version of Services Gatekeeper in the new_Middleware_home directory. Do not configure a domain yet.

    During the upgrade, the old installation and new installation must be in different directories.

    See "Installing Services Gatekeeper" for details.

  5. If you are upgrading Reports, perform the tasks in "Upgrading Services Gatekeeper Reports".

  6. (Administration server only) Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory.

    Note:

    Only perform steps 7 through 11 once on each of your administration servers.

  7. (Administration server only) Unzip the migration.zip archive into the upgrade directory.

    The migration subdirectory is created.

  8. (Administration server only) Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade/migration/old_version directory.

  9. (Administration server only) Change the permissions for the old_version directory:

    chmod +x oldversion

  10. (Administration server only) If your implementation does not use the default value for domain_home, correct the DOMAIN_HOME_DIR entry in the new_Middleware_home/wlserver/common/templates/scripts/upgrade/migration/runConfigurationMigration.sh script.

  11. (Administration server only) At a command prompt, enter one of the following:

    • On Solaris and Linux:

      sh runConfigurationMigration.sh DatabaseType DatabaseHost DatabasePort DatabaseName DatabaseUsername DatabasePassword

    • On Windows:

      runConfigurationMigration.bat DatabaseType DatabaseHost DatabasePort DatabaseName DatabaseUsername DatabasePassword

    where:

    • DatabaseType is either Oracle or MySQL.

    • DatabaseHost is the host name of the database server.

    • DatabasePort is the port number through which the database host listens.

    • DatabaseName is the name of the database or service hosting the Services Gatekeeper data.

    • DatabaseUsername is the user name that will access the Services Gatekeeper database.

    • DatabasePassword is the password for the database user.

  12. Ensure that the Administration Server is running.

    For more information, see ”Starting and Stopping Servers” in Services Gatekeeper System Administrator's Guide.

  13. Shut down all Administration Servers, Access Tier servers, and Network Tier servers.

    For more information, see ”Starting and Stopping Servers” in Services Gatekeeper System Administrator's Guide.

  14. To upgrade the Administration Server, perform the following on the system hosting your Administration Server:

    1. Verify that you have shut down the Administration server.

    2. On the machine that hosts the Admin Server, verify that you have installed the new version of Services Gatekeeper. Do not configure a domain yet.

      During the upgrade, the old installation and new installation must be in different directories.

      See "Installing Services Gatekeeper" for details.

    3. Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory.

    4. Ensure that you are using the correct version of the JDK and that the JAVA_HOME environment variable is set correctly.

    5. Open the build.properties file in a text editor.

    6. Edit the following parameters:

      Important:

      Edit the directory-related variables based on the setting of the domain.relocate parameter. See "Domain Home Directory Relocation".

      • domain.relocate: Set to true to relocate to a new directory.

      • server.name: The name of the Administration Server.

      • adminurl: The address of the Administration Server using the following format:

        URIscheme://IPaddress:Port

        For example:

        t3://203.0.113.24:7001

      • username: The main administrator user name.

      • password: The main administrator password.

      • admin.host: The name of the server that is hosting the Administration Server.

      • admin.port: The listen port of the Administration Server.

      • production.mode: Set this to true for production systems and to false for demonstration systems.

      • domain61.home: The directory in which your Services Gatekeeper domain resides.

      • domain60.home: The directory in which your old Services Gatekeeper domain resides.

      • domain60.name: The name of your old Services Gatekeeper domain.

      • domain60.portal.name: The name of your old Services Gatekeeper Portal domain.

      • domain61.portal.home: The directory in which your Services Gatekeeper portal domain resides. By default, /.../user_projects/domains/portal_domain.

      • domain60.portal.home: The directory in which your old Services Gatekeeper portal domain resides. By default, /.../user_projects/domains/portal_domain.

      • bea60.home: The old_Middleware_home directory.

      • wlsold.home: The directory in which old Services Gatekeeper release installed WebLogic Server.

      • bea61.home: The new_Middleware_home directory.

      • wlsnew.home: The directory in which Services Gatekeeper 6.1 installed WebLogic Server.

      • ocsg.home: The directory in which Services Gatekeeper 6.1 is installed.

      • coherence.port: The Coherence listen port for Services Gatekeeper 6.1. Use a port that is not occupied.

    7. Save and close the build.properties file.

    8. At a command prompt, enter the following:

      ant upgrade

    9. Go to <domain60.home>/bin (or <domain61.home>/bin if the domain home directory is re-located).

      Restart the Administration Server.

  15. To update the security provider configuration,

    1. Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory.

    2. Open the build.properties file in a text editor.

      Verify that the coherence.port property is set to a port that is NOT occupied.

      If you edited build.properties, save the file.

    3. Enter the following at the command line:

      sh new_Middlware_home/wlserver/common/bin/wlst.sh migrateSecurityProviders.py

    4. Go to <domain60.home>/bin (or <domain61.home>/bin if the domain home directory is re-located).

      Restart the Administration Server.

  16. From the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory, enter the following at the command line:

    sh new_Middlware_home/wlserver/common/bin/wlst.sh undeploy.py

  17. To upgrade the Access Tier server:

    Important:

    If your Access Tier server and Administration Server are installed in the same location, skip this step.

    1. Verify that you have shut down the Access Tier server.

    2. On the machine that hosts the Access Tier server, verify that you have installed the new version of Services Gatekeeper. Do not configure a domain yet.

      During the upgrade, the old installation and new installation must be in different directories.

      See "Installing Services Gatekeeper" for details.

    3. Set the necessary environment variables.

      Windows: Run the script new_Middleware_home\wlserver\common\bin\commEnv.cmd

      Solaris and Linux: Source the script new_Middleware_home/wlserver/common/bin/commEnv.sh

    4. Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory and open the build.properties file in a text editor.

    5. Edit the following parameters:

      Note:

      Edit the directory-related variables based on the setting of the domain.relocate parameter. See "Domain Home Directory Relocation".

      • domain.relocate: Set to true to relocate to a new directory.

      • server.name: The name of the Administration Server.

      • adminurl: The address of the Administration Server using the following format:

        URIscheme://IPaddress:Port

        For example:

        t3://203.0.113.24:7001

      • username: The main administrator user name.

      • password: The main administrator password.

      • admin.host: The name of the server that is hosting the Administration Server.

      • admin.port: The listen port of the Administration Server.

      • production.mode: Set this to true for production systems and to false for demonstration systems.

      • domain61.home: The directory in which your Services Gatekeeper domain resides.

      • domain60.home: The directory in which your old Services Gatekeeper domain resides.

      • domain60.name: The name of your old Services Gatekeeper domain.

      • domain60.portal.name: The name of your old Services Gatekeeper Portal domain.

      • domain61.portal.home: The directory in which your Services Gatekeeper portal domain resides. By default, /.../user_projects/domains/portal_domain.

      • domain60.portal.home: The directory in which your old Services Gatekeeper portal domain resides. By default, /.../user_projects/domains/portal_domain.

      • bea60.home: The old_Middleware_home directory.

      • wlsold.home: The directory in which old Services Gatekeeper release installed WebLogic Server.

      • bea61.home: The new_Middleware_home directory.

      • wlsnew.home: The directory in which Services Gatekeeper 6.1 installed WebLogic Server.

      • ocsg.home: The directory in which Services Gatekeeper 6.1 is installed.

      • coherence.port: The Coherence listen port for Services Gatekeeper 6.1. Use a port that is not occupied.

    6. Save and close the build.properties file.

    7. At a command prompt, enter the following:

      ant upgrade

    8. Go to <domain60.home>/bin (or <domain61.home>/bin if the domain home directory is re-located).

      Restart the Access Tier server.

  18. To upgrade the Network Tier, perform the following on the Network Tier server:

    Note:

    If your Network Tier and Administration Server are installed in the same location, skip this step.

    1. Verify that you have shut down the Network Tier server.

    2. On the machine that hosts the Network Tier server, verify that you have installed the new version of Services Gatekeeper. Do not configure a domain yet.

      During the upgrade, the old installation and new installation must be in different directories.

      See "Installing Services Gatekeeper" for details.

    3. Set the necessary environment variables.

      Windows: Run the script new_Middleware_home\wlserver\common\bin\commEnv.cmd

      Solaris and Linux: Source the script new_Middleware_home/wlserver/common/bin/commEnv.sh

    4. Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory and open the build.properties file in a text editor.

    5. Edit the following parameters:

      Important:

      Edit the directory-related variables based on the setting of the domain.relocate parameter. See "Domain Home Directory Relocation".

      • domain.relocate: Set to true to relocate to a new directory.

      • server.name: The name of the Administration Server.

      • adminurl: The address of the Administration Server using the following format:

        URIscheme://IPaddress:Port

        For example:

        t3://203.0.113.24:7001

      • username: The main administrator user name.

      • password: The main administrator password.

      • admin.host: The name of the server that is hosting the Administration Server.

      • admin.port: The listen port of the Administration Server.

      • production.mode: Set this to true for production systems and to false for demonstration systems.

      • domain61.home: The directory in which your Services Gatekeeper domain resides.

      • domain60.home: The directory in which your old Services Gatekeeper domain resides.

      • domain60.name: The name of your old Services Gatekeeper domain.

      • domain60.portal.name: The name of your old Services Gatekeeper Portal domain.

      • domain61.portal.home: The directory in which your Services Gatekeeper portal domain resides. By default, /.../user_projects/domains/portal_domain.

      • domain60.portal.home: The directory in which your old Services Gatekeeper portal domain resides. By default, /.../user_projects/domains/portal_domain.

      • bea60.home: The old_Middleware_home directory.

      • wlsold.home: The directory in which old Services Gatekeeper release installed WebLogic Server.

      • bea61.home: The new_Middleware_home directory.

      • wlsnew.home: The directory in which Services Gatekeeper 6.1 installed WebLogic Server.

      • ocsg.home: The directory in which Services Gatekeeper 6.1 is installed.

      • coherence.port: The Coherence listen port for Services Gatekeeper 6.1. Use a port that is not occupied.

    6. Save and close the build.properties file.

    7. At a command prompt, enter the following:

      ant upgrade

    8. Restart the Network Tier server.

  19. Redeploy the rest.jar application, which is located in the new_Middleware_home/ocsg/applications directory.

    1. Stop the Administration Server.

    2. Go to the old_domain_home/config directory and open the config.xml file in a text editor.

    3. Set the <source-path> parameter to new_Middleware_home/ocsg/applications/rest.jar. For example:

      <library>
     <name>rest-core#1.0@1.0.0.0</name>
     <target>WLNG_NT_Cluster,WLNG_AT_Cluster</target>
     <module-type xsi:nil="true"></module-type>
     <source-path>${OCSG6.1_home}/ocsg/applications/rest.jar</source-path>
     <security-dd-model>DDOnly</security-dd-model>
</library>

    4. Save and close the config.xml file.

  20. Redeploy the daf.externalaction.jar application, which is located in the new_Middleware_home/ocsg/applications directory.

    1. Stop the Administration Server (if it was restarted).

    2. Go to the old_domain_home/config directory and open the config.xml file in a text editor.

    3. Replace the following text:

      <library>
     <name>DafExternalActions#6.0.0.0@6.0.0.0</name>
     <target>WLNG_NT_Cluster,WLNG_AT_Cluster</target>
     <module-type xsi:nil="true"/>
    <source-path>/extradata/wlng_ 
upgrade/install60/ocsg/applications/oracle.sdp.daf.externalaction-6.0.0.0.
jar</source-path>
     <security-dd-model>DDOnly</security-dd-model>
     <staging-mode xsi:nil="true"/>
     <plan-staging-mode xsi:nil="true"/>
</library>

      with this text:

      <library>
     <name>DafExternalActions#6.1.0.0@6.1.0.0</name>
     <target>WLNG_NT_Cluster,WLNG_AT_Cluster</target>
     <module-type xsi:nil="true"/>
    <source-path>/extradata/wlng_ 
upgrade/install61/ocsg/applications/oracle.sdp.daf.externalaction-6.1.0.0.
jar</source-path>
     <security-dd-model>DDOnly</security-dd-model>
     <staging-mode xsi:nil="true"/>
     <plan-staging-mode xsi:nil="true"/>
</library>

    4. Save and close the config.xml file.

  21. (Complete this step if you use Node Manager.) Open the new_Middleware_home/wlserver/server/bin/startNodeManager.sh file in a text editor.

    1. Add this line to the JAVA_OPTIONS:

      JAVA_OPTIONS="${JAVA_OPTIONS} -Djava.security.egd=file:/dev/./urandom"

    2. Start Node Manager:

      new_Middleware_home/bin/startNodeManager.sh

  22. Restart your servers in the following order: Administration Server, then first Access Tier server, then second Access Tier server, then first Network Tier server, and then second Network Tier server.

  23. Redeploy the pubsub-1.0.war application, which is located in the Middleware_home/wlserver/common/deployable-libraries/ directory.

    1. Stop the Administration Server.

    2. Go to the old_domain_home/config directory and open the config.xml file in a text editor.

    3. Replace the following text:

      <library>
     <name>pubsub#1.0@1.7.0.0</name>
     <target>WLNG_AT_Cluster</target>
     <module-type>war</module-type>
     <source-path>${OCSG6.0_home}/wlserver_10.3/common/deployable-libraries/pubsub-1.0.war</source-path>
     <security-dd-model>DDOnly</security-dd-model>
</library>

      with this text:

      <library>
     <name>pubsub#1.0@3.0.0.0</name>
     <target>WLNG_AT_Cluster</target>
     <module-type>war</module-type>
     <source-path>${OCSG6.1_home}/wlserver/common/deployable-libraries/pubsub-1.0.war</source-path>
     <security-dd-model>DDOnly</security-dd-model>
     <staging-mode xsi:nil="true"></staging-mode>
     <plan-staging-mode xsi:nil="true"></plan-staging-mode>
     <cache-in-app-directory>false</cache-in-app-directory>
</library>

    4. Save and close the config.xml file.

    5. Restart your Administration Server, then your first Access Tier server, and then your second Access Tier server.

  24. Follow the procedure in "Deploying New Services Gatekeeper Applications".

Services Gatekeeper Post-Upgrade Tasks

This section lists tasks that you need to complete after upgrading the Services Gatekeeper server software.

Reset Text-based API Passwords

If you use the Services Gatekeeper API management features, and your APIs use Text-based security, you need to reset their passwords after upgrading the Services Gatekeeper software. This is required by a change to the Services Gatekeeper security requirements, so you can reset the same usernames and passwords if you want to. Start Services Gatekeeper, and open the Partner and API Management GUI. For each API that uses Text security, set a username and password.

Deploying New Services Gatekeeper Applications

After upgrading, you must undeploy all deprecated applications and redeploy the new Services Gatekeeper applications. You do this by using the hitless upgrade procedure. For more information about hitless upgrades, see the following:

About the Deployment Methods

You can redeploy an application by one of the following ways:

  • Accessing WebLogic Server Admin console

  • The command-line based deployment tool, weblogic.Deployer. For more information about this tool, see "A Weblogic.Deployer Command-Line Reference" in Fusion Middleware Deploying Applications to Oracle WebLogic Server.

    For example:

    java weblogic.Deployer 
        -adminurl t3://192.168.1.2:7001 
        -user weblogic 
        -password weblogic123 
        -redeploy 
        -name wlng_at_sms_px21 
        -source C:\temp\bea\ocsg61\ocsg\applications\wlng_at_sms_px21.ear 
        -retiretimeout 60

The Redeployment Process

To deploy the new Services Gatekeeper applications:

  1. Undeploy the following deprecated application EAR files and the SMPP EAR file (which does not support hitless upgrade:

    • wlng_nt_oauth2.ear

    • wlng_nt_portal.ear

    • wlng_nt_native_smpp_sms.ear

  2. Deploy the new Portal Server, Parlay, and XQoS application EARs files, which are located in the new_Middleware_home/ocsg/applications directory:

    • wlng_nt_oauth2.ear

    • wlng_at_qos_px40.ear

    • wlng_at_rest_portal_service.ear

    • oracle.sdp.daf.externalaction-6.0.0.0.jar (must be named ”DafExternalActions” when deployed)

    • wlng_nt_portal.ear

    • daf-multitier-at.ear (for cluster implementations only)

    • daf-multitier-nt.ear (for cluster implementations only)

    • daf.war (for standalone implementations only)

  3. Redeploy the Services Gatekeeper 6.0 communication services application EAR files, which are located in the new_Middleware_home/ocsg/applications/ directory:

    • wlng_nt_qos.ear

    • wlng_nt_session.ear

    • wlng_nt_call_notification_px21.ear

    • wlng_nt_multimedia_messaging_px21.ear

    • wlng_nt_presence_px21.ear

    • wlng_nt_sms_px21.ear

    • wlng_nt_terminal_location_px21.ear

    • wlng_nt_device_capabilities_px30.ear

    • wlng_nt_native_smpp_sms.ear

    • wlng_nt_terminal_status_px21.ear

    • wlng_nt_third_party_call_px21.ear

    • wlng_nt_subscriber_profile_ews.ear

    • wlng_nt_push_message_ews.ear

    • wlng_nt_multimedia_messaging_mm7.ear

    • wlng_nt_native_ucp_sms.ear

    • wlng_nt_payment_px30.ear

    • wlng_nt_address_list_px30.ear

    • wlng_nt_acr_px21.ear

    • wlng_at_portal_service.ear

    • wlng_at_rest_portal_service.ear

    • wlng_at_acr_parlay_rest.ear

    • wlng_at_address_list_px30.ear

    • wlng_at_addresslist_parlay_rest.ear

    • wlng_at_oauth2.ear

    • wlng_at_session.ear

    • wlng_at_callable_policy.ear

    • wlng_at_call_notification_px21.ear

    • wlng_at_multimedia_messaging_px21.ear

    • wlng_at_presence_px21.ear

    • wlng_at_sms_px21.ear

    • wlng_at_terminal_location_px21.ear

    • wlng_at_device_capabilities_px30.ear

    • wlng_at_terminal_status_px21.ear

    • wlng_at_third_party_call_px21.ear

    • wlng_at_third_party_call_px30.ear

    • wlng_at_call_notification_px30.ear

    • wlng_at_audio_call_px30.ear

    • wlng_at_subscriber_profile_ews.ear

    • wlng_at_push_message_ews.ear

    • wlng_at_multimedia_messaging_mm7.ear

    • wlng_at_payment_px30.ear

    • interceptors.ear

    • xparam_interceptors.ear

    • wlng_at_payment_parlay_rest.ear

    • wlng_at_sms_parlay_rest.ear

    • wlng_at_terminallocation_parlay_rest.ear

    • wlng_at_multimedia_messaging_parlay_rest.ear

    • wlng_prm.ear

    • wlng_at_qos_rest.ear

    • wlng_at_qos_px40.ear

  4. Redeploy the new Reports application EAR file, which is located in the new_Middleware_home/ocsg/applications directory.

    • edr_to_analytic.ear

  5. Reconfigure your Services Gatekeeper Reports.

    For more information, see ”Managing StatisticService” in Services Gatekeeper System Administrator's Guide.

Cleaning Up Files After Upgrading

The general process for removing the old Services Gatekeeper files after upgrading includes:

  1. Making a backup copy of the old Services Gatekeeper middleware_home directory and its subdirectories

  2. Removing the contents of the old middleware_home directory except for the domain_home directories if you locate them under middleware_home. You can safely remove everything under the old middleware_home except for the domain_home and its subdirectories. If your domain_home is not under middleware_home you can safely just remove everything in middelware_home.

  3. Starting the new Services Gatekeeper servers to ensure that they work correctly.

  4. Then you can remove the backup copy of the old Services Gatekeeper implementation.

Upgrading Services Gatekeeper Reports

To upgrade Services Gatekeeper Reports, complete the tasks described in this section.

Reset Text-based API Passwords

If you use the Services Gatekeeper API management features, and your APIs use Text-based security, you need to reset their passwords after upgrading the Services Gatekeeper software. This is required by a change to the Services Gatekeeper security requirements, so you can reset the same usernames and passwords if you want to. Start Services Gatekeeper, and open the Partner and API Management GUI.

For each API that uses Text security, set a username and password.

Reports Upgrade Process

To upgrade Services Gatekeeper Reports:

  1. Go to the new_Middleware_home/ocsg/applications directory.

  2. Deploy the edr_to_analytic.ear file targeted to the Network Tier cluster.

  3. Deploy the analytics_proxy.war file targeted to the Application Tier cluster.

For Portal analytics, your customers must re-submit the password for the Analytics server.

Upgrade Troubleshooting

This section provides remedies for common problems that occur after a Services Gatekeeper upgrade.

A Network Tier Server Cannot Rejoin Its Coherence Cluster

New versions of Services Gatekeeper may upgrade the Oracle Coherence version. Because of that, sometimes the upgraded server cannot join servers running the earlier version because of the version mismatch. To fix this issue:

  1. Edit the script new_Middleware_home/wlserver/common/templates/scripts/upgrade/configCoherence.py and update the following variables:

    • ADMIN_USER_NAME: The WebLogic administrator user name.

    • ADMIN_PASSWORD: The WebLogic administrator password.

    • ADMIN_URL: The WebLogic administration console URL.

    • FIRST_TIME: Set this to true if this is the first Network Tier server you are upgrading; false otherwise.

  2. Run the script using the following command:

    # . ../../../bin/wlst.sh configCoherence.py

A Network Tier Server Cannot Rejoin Its Services Gatekeeper Cluster

Sometimes an upgraded Services Gatekeeper has a different OAuth 2.0 EBJ home instance from other Network Tier servers and is not be able to join the cluster. To fix this issue:

  1. Start the Network Tier server Administration Console:

    http://server_address:port/console

    Note:

    The default Administration Console port is 7001.

  2. In the Change Center panel, click Lock & Edit.

  3. In the Domain Structure panel, select your Services Gatekeeper domain and then Deployments.

  4. In the Summary of Deployments pane, select wlng_nt_outh2, then Targets.

  5. Select wlng_nt_oauth2, and click Change Targets.

  6. Under Clusters, select Part of the cluster, and deselect the server that cannot join the cluster. Click Yes.

  7. In the Change Center, click Activate Changes.

  8. Restart the other Network Tier servers in the cluster.

  9. Following the same procedure above, reset the wlng_nt_oauth2 targets to All servers in the cluster, and click Yes.

  10. Restart the server that could not rejoin its cluster.

Portal Domain is Not Upgraded

If portal domain has same host with Administration Server, and domain60.portal.home and domain60.portal.name are properly configured, the portal domain upgrades correctly.

When the portal domain does not upgrade correctly, complete the following steps:

Reconfigure the Server 

  1. Stop the portal server.

  2. Review the contents of the build.properties file. Update it, if necessary.

  3. Go to the new_Services_Gatekeeper_home/wlserver/common/templates/scripts/upgrade directory.

  4. Run the ant script for upgrade:

    ant upgrade

Redeploy the .WAR and .EAR Files 

  1. Start the portal server.

  2. Redeploy the following .ear files:

    • apimgmtportal-core

    • apimgmtportal-help

    • apimgmtportal-language

    • apimgmtportal-plugin-statistics

    • apimgmtportal-theme-default

    • clusterProxy

  3. Deploy the new .war file, clusterProxy.

Administration Console Pages are Not Displayed Properly

After the upgrade, the pages in the Administration Console may not display properly. If this occurs, delete the browser's cache and cookies and restart the Administration Console.

Rolling Back the Upgrade

At times, and in the event of an unrecoverable failure. you way need to roll back to the original domain. This section describes how you can revert your domain environment back to the previous setup.

On the Administration Access Tier and Network Tier servers, the old_Services_Gatekeeper_home/user_projects/domains/ directory contains the domain_backup and portal_backup sub directories.

Complete the following steps on the Administration server, Access Tier server, and Network server, in their upgrade order.

Administration Server 

  1. Copy the backup domain to original domain name.

  2. Restart the Administration Server.

Access Tier Server 

  1. Copy the backup domain to original domain name.

  2. Restart the Access Tier Server.

Network Tier and Migration Scripts 

  1. Go to old_Services_Gatekeeper_homewlserver/common/templates/scripts directory and locate the compressed file,migration.zip.

  2. Unzip the file, extracting it to under the ole (6.0) directory.

  3. Execute the appropriate script runConfigurationRollback.sh(Linux) or runConfigurationRollback.bat(Windows)

    • runConfigurationRollback.sh (Linux)

    • runConfigurationRollback.bat (Windows)

  4. Restart the Network Tier Server from the old domain.