9 Upgrading Oracle Communications Services Gatekeeper

This chapter describes upgrading Oracle Communications Services Gatekeeper 5.0 and 5.0.0.1 to Services Gatekeeper 5.1. It also has reference sections for updated database schemas and new CDRs, EDRs, and alarms.

About Upgrading Services Gatekeeper

A Services Gatekeeper 5.0 or 5.0.0.1 installation can be upgraded to Services Gatekeeper 5.1 without shutting down the entire cluster or domain. Applications can use Services Gatekeeper with minimal service interruption during the upgrade. The process is known as a Rolling Upgrade and is a Oracle WebLogic Server feature.

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

The process is based on a rolling scheme, where each server in the domain, one at the time, is stopped, upgraded to the new version, and then started. This process upgrades the WebLogic Server and the Services Gatekeeper Core services, but leaves all communication services as before the upgrade.

After all servers have been upgraded, the communication services in use need to be upgraded. This is done using in-production redeployment, which is a WebLogic Server feature that enables the communication services to be upgraded without any traffic interruption.

The high-level upgrade workflow is:

1. Upgrade each server using a rolling upgrade scheme. See "Upgrading Server to New Version" for details.

2. Upgrading PRM and deploying communication services. See "Upgrading PRM and Deploying Communication Services" for details.

3. Verify that new traffic is processed.

You should always upgrade the servers in this order:

1. Administration server

2. Access tier servers

3. Network tier server.

It is strongly recommended that you back up configuration data prior to the upgrade. See Oracle Communications Services Gatekeeper System Backup and Restore Guide, another document in this set, for more information on backing up Services Gatekeeper.

Limitations

The following limitations apply for the upgrade:

• Do not make configuration changes during the upgrade process until all the servers in the cluster have been upgraded. This is especially important for new configuration options. Servers will silently ignore settings that are not understood, and the local configuration file may not be updated properly. Using new configuration options may remove the capability of un-installing a maintenance upgrade in a rolling fashion.

• For a minor release, during the rolling upgrade, there must be two entirely separate installation directories. That is, the location of the old installation and the location of the new installation must be two different directories.

• After the upgrade it is possible that the panes in the Administration Console will not display properly. If this occurs, delete the browser's cache and cookies and restart your browser.

Variable Names Used in this Chapter

The following general variable names are referenced throughout this chapter:

• Middleware_Home—the top level directory of the original Services Gatekeeper version, either 5.0 or 5.0.0.1.

• New_Middleware_Home—the top level directory of the new Services Gatekeeper version, 5.1.

• Services_Gatekeeper_Home—the top level directory of the original Services Gatekeeper version, either 5.0 or 5.0.0.1.

• New_Services_Gatekeeper_Home—the top level directory of the new Services Gatekeeper version, 5.1.

• Domain_Name—the domain name directory of the WebLogic instance, located in the appropriate [New_]Middleware_Home directory at user_projects/domains.

Upgrading Server to New Version

To upgrade a server:

1. Stop the server gracefully so all in-flight requests are processed before the shutdown starts.

   For information on how to stop a server using the administration console, see the discussion on shutdown servers in a cluster in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help at:

   http://download.oracle.com/docs/cd/E15523_01/apirefs.1111/e13952/taskhelp/clusters/ServerShutdownCluster.html

   Note:

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

   For information about controlling the Graceful Shutdown command, see the discussion on graceful shutdown in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help at:

   http://docs.oracle.com/cd/E25054_01/apirefs.1111/e13952/taskhelp/startstop/ControlGracefulShutdowns.html

2. Install the new version of Services Gatekeeper. See "Installing Oracle Communications Services Gatekeeper" for details.

   Install it under a directory different from Middleware_Home directory used for the old version. Do not configure a domain.

3. Set up necessary environment variables.

   On Windows: run the script New_Middleware_Home\wlserver_10.3\server\bin\commEnv.cmd

   On UNIX: source the script New_Middleware_Home/wlserver_10.3/server/bin/commEnv.sh

4. Change directory to New_Middleware_Home/wlserver_10.3/common/templates/scripts/upgrade.

5. The upgrade script assumes that the JDK was installed in New_Middleware_Home /jdk160_29b11 (Oracle SUN) or New_Middleware_Home/jrockit_160_29_D1.2.0-10 (JRockit).

   If you are using the generic installer, update the JAVA_HOME variable in the file New_Middleware_Home/wlserver_10.3/common/templates/scripts/upgrade/build.xml:

   Set JAVA_HOME to the directory in which the JDK is installed.

6. Run the upgrade ant script. The script executes different ant targets for different server types. The script takes a set of arguments. See Table 9-1, "Arguments to the Upgrade Script".

   To upgrade

   • the administration server, execute the target upgrade.admin.

   • an access tier server, execute the target upgrade.at.

   • a network tier server, execute the target upgrade.nt.

   See Example 9-1, "Upgrading the Administration Server", Example 9-2, "Upgrading an Access Tier Server", and Example 9-3, "Upgrading a Network Tier Server".

   Table 9-1 Arguments to the Upgrade Script

   Argument	Description	Required
   -Ddomain50.home	Domain configuration directory used in the old version	Yes
   -Dbea50.home	Installation directory for the old installation	Yes
   -Dbea51.home	Installation directory for the new installation	Yes
   -Dserver.name	Name of the server to upgrade	Yes
   -Dwlsold.home	Installation directory used for WebLogic Server in the old installation	No
   -Dwlsnew.home	Directory used for WebLogic Server used in the new installation	No
   -Docsg.home	Directory used for Services Gatekeeper in the new installation	No
   -Dwl.server.name	The name of the AT or NT server to upgrade	No
   -Ddomain50.name	Name of the domain in the existing installation	No
   -Dadmin.host	Host name or IP address of the administration server	No
   -Dadmin.port	Administration port number for the administration server	No
   -Dproduction.mode	True if the server is in production mode. False otherwise.	No
   -Dnt.server.home	Directory of the network tier server to upgrade. Used only when upgrading an network tier server.	No

   
   

   Example 9-1 Upgrading the Administration Server

   ant upgrade.admin
       -Ddomain50.home=C:\temp\bea\ocsg500\user_projects\domains\ocsg-access-network-domain 
       -Dbea50.home=C:\temp\bea\ocsg500 
       -Dbea51.home=C:\temp\bea\ocsg510 
       -Dwlsold.home=C:\temp\bea\ocsg500\wlserver_10.3 
       -Dwlsnew.home=C:\temp\bea\ocsg510\wlserver_10.3 
       -Docsg.home=C:\temp\bea\ocsg510\ocsg_5.0 
       -Ddomain50.name=ocsg-domain
       -Dadmin.host=10.182.100.111
       -Dadmin.port=7001
       -Dproduction.mode=true
       -Dserver.name=AdminServer
   

   Example 9-2 Upgrading an Access Tier Server

   ant upgrade
       -Ddomain50.home=C:\temp\bea\ocsg500\user_projects\domains\ocsg-domain-at1
       -Dbea50.home=C:\temp\bea\ocsg500 
       -Dbea51.home=C:\temp\bea\ocsg510 
       -Dwlsold.home=C:\temp\bea\ocsg500\wlserver_10.3 
       -Dwlsnew.home=C:\temp\bea\ocsg510\wlserver_10.3 
       -Docsg.home=C:\temp\bea\ocsg510\ocsg_5.0 
       -Ddomain50.name=ocsg-domain
       -Dadmin.host=10.182.100.111
       -Dadmin.port=7001
       -Dproduction.mode=true
       -Dwl.server.name=WLNG_AT1
   

   Example 9-3 Upgrading a Network Tier Server

   ant upgrade.nt
       -Ddomain50.home=C:\temp\bea\ocsg500\user_projects\domains\ocsg-access-network-domain 
       -Dbea50.home=C:\temp\bea\ocsg500 
       -Dbea51.home=C:\temp\bea\ocsg510 
       -Dwlsold.home=C:\temp\bea\ocsg410\wlserver_10.3 
       -Dwlsnew.home=C:\temp\bea\ocsg510\wlserver_10.3 
       -Docsg.home=C:\temp\bea\ocsg510\ocsg_5.0 
       -Ddomain50.name=ocsg-domain
       -Dadmin.host=10.182.100.111
       -Dadmin.port=7001
       -Dnt.server.home=C:\temp\bea\ocsg410\user_projects\domains\ocsg-access-network-domain\servers\WLNG_NT1
       -DProduction.mode=true
       -Dwl.server.name=WLNG_NT1
   

7. If you are upgrading the administration server, you must enable SSL for all servers and create a new webservice-credential-provider. To do that, edit the script New_Services_Gatekeeper_Home/wlserver_10.3/common/templates/scripts/upgrade/configSSLWsPolicy.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.

   • AT_SERVERS: A comma separated list of application tier server names bounded by single quotes and enclosed in square brackets, for example: ['WLNG_AT1','WLNG_AT2'].

   • ADMIN_DOMAIN_NAME: The Services Gatekeeper network domain name.

   Run the script using the following command

   # . ../../../bin/wlst.sh configSSLWsPolicy.py
   

8. If you are upgrading a version 5.0 administration server, you will need to add a flag to your domain's config.xml file that disables the enforcement of HTTP basic authentication requests. Services Gatekeeper handles such requests itself via OAuth 2.0 rather than the WebLogic Server.

   To add the necessary flag, open the file Middleware_home/user_projects/domains/Domain_Name/config/config.xml in an editor and add the line following line to the <security-configuration> element:

   <domain ...>
     ...
     <security-configuration>
       <name>ocsg-domain</name>
       <realm>
        ... ...
       </realm>
       <default-realm>myrealm</default-realm>
       <credential-encrypted>   {AES}...</credential-encrypted>
       <node-manager-username>weblogic</node-manager-username>
       <node-manager-password-encrypted>{AES}...</node-manager-password-encrypted>
       <!-- ADDED: Disable Basic HTTP Authentication -->
   <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>
       <!-- ADDED: END -->
      </security-configuration>
   

9. If you are upgrading an administration server, unpack the file New_Middleware_home/wlserver_10.3/common/templates/scripts/migration.zip.

   Two directories are created, 5.0 and 5.0.0.1.

10. If you are upgrading an administration server, set the environment variable, OCSG51_INSTALL_HOME to point to New_Services_Gatekeeper_Home, or directly modify the ${OCSG51_INSTALL_HOME} value in the runConfigurationMigration script.

11. If you are upgrading an administration server, run the configuration update script. The syntax is:

    runConfigurationMigration.Extension DB_type DB_Host DB_Port DB_Name DB_User Password

    Where:

    • Extension is the filename extension. Use sh for UNIX and bat for Windows.

    • DB_type is the database type. Use oracle for an Oracle Database or mysql for MySQL.

    • DB_Host is the host name, or IP address, of the server running the database.

    • DB_Port is the port number used by the database.

    • DB_Name is the database name for a MySQL database or the service name for an Oracle database.

    • DB_User is the user ID used to connect to the database.

    • Password is the password associated with DB_User.

12. Change to the Middleware_Home/user_projects/domains/Domain_Name/bin directory.

13. Change the permissions to read/write/execute on all files, by entering:

    chmod 755 *

14. Shutdown and restart the server.

Upgrading PRM and Deploying Communication Services

After the upgraded Services Gatekeeper domain has been started, Partner Relationship Management (PRM) needs to be upgraded to enable PasswordDigest and deploy new and upgraded communication services. This is done using a hitless upgrade procedure.

See the discussion on hitless upgrade using production redeployment in Oracle Communications Services Gatekeeper System Administrator's Guide and ”Redeploying Applications in a Production Environment” in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.

Upgrading PRM to Enable PasswordDigest

To upgrade PRM to support PasswordDigest, do the following:

1. Edit the script New_Services_Gatekeeper_Home/wlserver_10.3/common/templates/scripts/upgrade/configPRM.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.

   • AT_SERVERS: A comma separated list of application tier server names bounded by single quotes and enclosed in square brackets, for example: ['WLNG_AT1','WLNG_AT2'].

   • ADMIN_DOMAIN_NAME: The Services Gatekeeper network domain name.

2. Run the script using the following command:

   # . ../../../bin/wlst.sh configPRM.py
   

3. Redeploy New_Services_Gatekeeper_Home/applications/rest.jar using the WebLogic server Administration Console or the weblogic.Deployer command line application. For detailed information on WebLogic deployment strategies, see Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.

4. Configure the new Services Gatekeeper JMS module by making the following modifications to each WebLogic server's New_Middleware_Home/user_projects/domains/Domain_Name/config/config.xml:

   <?xml version='1.0' encoding='UTF-8'?>
   <domain>
     <name>ocsg-access-network-domain</name>
     ...
     ...
     <!-- BEGIN: REMOVE OCSG5.0/OCSG5.0.0.1 JMS MODULES -->
     <!--
     <jms-system-resource>
       <name>WLNGJMSResource</name>
       <target>WLNG_NT_Cluster</target>
       <descriptor-file-name>jms/wlng-jms.xml</descriptor-file-name>
     </jms-system-resource>
     -->
     <!-- END: REMOVE -->
     <!-- BEGIN: ADD OCSG5.1 JMS MODULES -->
     <jms-system-resource>
       <name>WLNGEDRResource</name>
       <target>WLNG_NT_Cluster</target>
       <sub-deployment>
         <name>WLNG_JMS_CLUSTER</name>
         <target>JMSServer-NT1,JMSServer-NT2</target>
       </sub-deployment>
       <descriptor-file-name>jms/wlng-edr-jms.xml</descriptor-file-name>
     </jms-system-resource>
     <jms-system-resource>
       <name>WLNGJMSResource</name>
       <target>WLNG_NT_Cluster</target>
       <descriptor-file-name>jms/wlng-cluster-jms.xml</descriptor-file-name>
     </jms-system-resource>
     <!-- END: ADD -->
     <jms-system-resource>
       <name>WLNG_ATJMSResource</name>
       <target>WLNG_AT_Cluster</target>
       <descriptor-file-name>jms/wlng_at-jms.xml</descriptor-file-name>
     </jms-system-resource>
     ...
   

5. Restart all servers sequentially.

6. Once all the servers are running, redeploy New_Services_Gatekeeper_Home/applications/wlng_prm.ear.

5.0 to 5.1 Communication Services Deployments

If you are upgrading from Services Gatekeeper 5.0 to 5.1, deploy the following new communication services, located in New_Services_Gatekeeper_Home/applications/:

• wlng_at_acr_parlay_rest.ear

• wlng_at_address_list_px30.ear

• wlng_at_addresslist_parlay_rest.ear

• wlng_at_app_subscription_rest.ear

• wlng_at_multimedia_messaging_parlay_rest.ear

• wlng_at_oauth2.ear

• wlng_at_payment_parlay_rest.ear

• wlng_at_terminallocation_parlay_rest.ear

• wlng_at_qos_rest.ear

• wlng_at_sms_parlay_rest.ear

• wlng_at_portal_service.ear

• wlng_at_sms_parlay_rest.ear

• wlng_nt_acr_px21.ear

• wlng_nt_address_list_px30.ear

• wlng_nt_oauth2.ear

• wlng_nt_portal.ear

• wlng_nt_qos.ear

Redeploy the following 5.1 communication services located in New_Services_Gatekeeper_Home/applications/:

• wlng_at_sms_px21.ear

• wlng_at_multimedia_messaging_px21.ear

• wlng_at_payment_px30.ear

• wlng_at_terminal_location_px21.ear

• wlng_nt_payment_px30.ear

• wlng_nt_sms_px21.ear

• wlng_nt_multimedia_messaging_px21.ear

• wlng_nt_terminal_location_px21.ear

5.0.0.1 to 5.1 Communication Services Deployments

If you are upgrading from Services Gatekeeper 5.0.0.1 to 5.1, deploy the following new communication services, located in New_Services_Gatekeeper_Home/applications/:

• wlng_at_acr_parlay_rest.ear

• wlng_at_app_subscription_rest.ear

• wlng_at_qos_rest.ear

• wlng_at_portal_service.ear

• wlng_nt_acr_px21.ear

• wlng_nt_address_list_px30.ear

• wlng_nt_qos.ear

Redeploy the following 5.1 communication services located in New_Services_Gatekeeper_Home/applications/:

• wlng_at_sms_px21.ear

• wlng_at_multimedia_messaging_px21.ear

• wlng_at_payment_px30.ear

• wlng_at_terminal_location_px21.ear

• wlng_at_multimedia_messaging_parlay_rest.ear

• wlng_at_address_list_px30.ear

• wlng_at_addresslist_parlay_rest.ear

• wlng_at_oauth2.ear

• wlng_at_payment_parlay_rest.ear

• wlng_at_terminallocation_parlay_rest.ear

• wlng_at_sms_parlay_rest.ear

• wlng_nt_oauth2.ear

• wlng_nt_payment_px30.ear

• wlng_nt_sms_px21.ear

• wlng_nt_multimedia_messaging_px21.ear

• wlng_nt_terminal_location_px21.ear

• wlng_nt_address_list_px30.ear

Upgrade Troubleshooting

The following sections provide remedies for common problems that occur after a Services Gatekeeper upgrade.

A Network Tier Server Cannot Rejoin Its Coherence Cluster

Services Gatekeeper 5.1 upgrades the Coherence version from 3.5.3 to 3.7.1. Because of that, sometimes the upgraded server cannot join servers running the earlier version because of the version mismatch. To fix that issue, do the following:

1. Edit the script New_Services_Gatekeeper_Home/wlserver_10.3/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 NT 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 will have a different OAuth 2.0 EBJ home instance from other Network Tier servers and will not be able to join the cluster. To fix this issue, do the following:

1. Launch the Network Tier server's WebLogic 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 select Deployments.

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

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 final server.

Reference: Database Schema Changes

Table 9-2 lists database schema changes from Services Gatekeeper versions 5.0 and 5.0.0.1 to 5.1.

Table 9-2 5.0 to 5.1 Database Schema Changes

Table Name	New Column	Type
pl_sms_smpp_mt_sms	CLIENTCORRELATOR	VARCHAR2(30)
pl_sms_online_notif	CLIENTCORRELATOR	VARCHAR2(255)
	CALLBACKDATA	VARCHAR2(255)
	NOTIFICATIONFORMAT	VARCHAR2(20)
	SERVICETYPE	NUMBER
pl_payment_reservation_data	REFERENCESEQUENCE	NUMBER
pl_mms_online_notif	NORTHBOUNDTYPE	VARCHAR2(30)
	CLIENTCORRELATOR	VARCHAR2(255)
	CALLBACKDATA	VARCHAR2(255)
	NOTIFICATIONFORMAT	VARCHAR2(20)
pl_mms_offline_notif	NORTHBOUNDTYPE	VARCHAR2(30)
	NOTIFICATIONFORMAT	VARCHAR2(20)
pl_mms_mt_dr_mms	NORTHBOUNDTYPE	VARCHAR2(30)
	SENDERADDRESS	VARCHAR2(30)

Table 9-3 lists changes from Services Gatekeeper version 5.0.0.1 to 5.1.

Table 9-3 5.0.0.1 to 5.1 Database Schema Changes

Table Name	New Column	Type
oauth2_resource_owner	FROMRESOURCERULE	VARCHAR2(1)
oauth2_access_token	RESOURCE_OWNER	VARCHAR2(128)
	CLIENT_ID	VARCHAR2(32)
	APPINSTANCEID	VARCHAR2(64)
	INVOKE_COUNT	NUMBER
	MAC_ALGORITHM	VARCHAR2(40)
oauth2_refresh_token	RESOURCE_OWNER	VARCHAR2(128)
	CLIENT_ID	VARCHAR2(32)

Reference: Added Alarms

Table 9-4 outlines the added alarms.

Table 9-4 Added Alarms

Service	Added Range
Address List Management	88800001 to 88800003
Reporting	900001 to 900006
Email	981001 to 981004 981007 to 981011
Payment	114203 to 114209
Portals	390001 to 390006
QoS API	98000001 to 98000009
SLA	115001 to 115002

Reference: Added EDRs

The following sections list EDRs added to Application and Network Tiers for Services Gatekeeper 5.1

Application Tier EDRs

Table 9-5 outlines the added Application Tier EDRs.

Table 9-5 Added Application Tier EDRs

Communication Service	Added Range
Address List Management	91701 to 91703 29101 to 29119
Application Subscription Management	409101 to 409107
Audio Call	91501 92001 to 92002 26401 to 26405
Call Notification	91901 to 91902
Device Capabilities	91601 26501
MMS	90201 to 90210 91201 to 91205 26101 to 26108
Payment	91301 to 91304 26201 to 26207
Presence	91641 to 91646 26801 to 268011
SMS	90101 to 90109 91101 to 91105 26001 to 26007
Subscriber Profile	27001
Terminal Location	91401 to 91404 26301 to 26307
Terminal Status	91631 to 91634 26701 to 26705
Third Party Call	91611 91621 26601 to 26604

Network Tier EDRs

Table 9-6 outlines the added Network Tier EDRs.

Table 9-6 Added Network Tier EDRs

Communication Service	Added Range
Anonymous Customer Reference	408001 to 408003 409201 to 409203
Address List Management	28001 to 28019 29001 to 29019
Application Subscription Management	409001 to 409009
Audio Call	405003 to 405005
Device Capabilities	403003 to 403004
Email	8120 to 8122
Native SMPP	404001 to 404007 404101 to 404106
Native UCP	402020 to 402023 402030 to 402033
OAuth	20001 to 20006
Payment	15101 to 15107
QoS API	91801 to 91812 91819 to 91825
SMS	7021 to 2025 410101 to 410108 410001 to 410010
Terminal Location	9005 to 9007 9031 to 9033

Reference: Added CDRs

Table 9-7 outlines the added CDRs.

Table 9-7 Added CDRs

Module	Method	Description
Email	sendMessage	MT MMS to Email
	receiveEmail	MO Email to MMS
MMS	sendMessage	MT OneApi MMS
SMS	createOutboundMessage	MT OneApi SMS
Terminal Location	getLocation	MT OneApi Terminal Location