18 Deploying and Administering Communication Services

A Communication Service Packaging Example

The files holding the communication services that share the Parlay X 2.1 Third Party Call communication service layer consist of the following artifacts:

• wlng_at_third_party_call_px21.ear

• wlng_nt_third_party_call_px21.ear

+---APP-INF/lib
...
communication service_callback_client.jar
/<utilities 1>.jar
...
/<utilities n>.jar
+---META-INF/MANIFEST.MF
/application.xml
/weblogic-application.xml
/weblogic-extension.xml
+---<plug-in 1>.jar
...
+---<plug-in n>.jar
+---<plug-in 1>.war
...
+---<plug-in n>.war
+---<communication service>_service.jar

+---com/
+---org/
+---META-INF/MANIFEST.MF
+   instancemap
+   srv_depl.xml

Deploying SOAP and RESTful Facades on Multiple AT Clusters

For those communication services that have RESTful facades, both SOAP and RESTful facades are included in the standard EAR files.

If your installation needs to use multiple clusters of AT servers, you must make some adjustments. You cannot deploy the RESTful facade on multiple clusters within the same domain. You can deploy both the RESTful facade and the SOAP facade on a single cluster within the domain and deploy only the SOAP facade on multiple other clusters within that same domain.

To accomplish this, do the following:

1. Undeploy the standard EAR files for the communication services (including the session manager) you are using on any additional clusters your installation requires.

2. Replace the files with special equivalent EAR versions that contain only SOAP interfaces

The file names for .ear files for SOAP interfaces are identical to those of the standard files except that a _soap is appended to the end of the name. The following SOAP-only EAR files should be deployed (as needed) in this situation:

• wlng_at_call_notification_px21_soap.ear

• wlng_at_multimedia_messaging_px21_soap.ear

• wlng_at_payment_px30_soap.ear

• wlng_at_presence_px21_soap.ear

• wlng_at_push_message_ews_soap.ear

• wlng_at_session_soap.ear

• wlng_at_sms_px21_soap.ear

• wlng_at_subscriber_profile_ews_soap.ear

• wlng_at_terminal_location_px21_soap.ear

• wlng_at_third_party_call_px21_soap.ear

These files are found in the Middleware_home/ocsg/applications directory of your installation. Information on the content of these files is available in the ”Properties” section of each respective communication services reference in Services Gatekeeper Communication Service Reference Guide.

Understanding Communication Service Version Handling

Communication services are associated with release versions and can be upgraded using in-production deployment.

The version numbering is on the EAR level, which means that all network protocol plug-ins for a given collection of application-facing interface are redeployed.

The version number for a specific communication service is specified in the Weblogic-Application-Version attribute in META-INF/manifest.mf in wlng_at_communication service.ear and wlng_nt_communication service.ear, respectively.

For more information about how to develop applications for production redeployment, see ”Developing Applications for Production Redeployment" in Oracle Fusion Middelware Developing Applications for Oracle WebLogic Server.

Deploying and Undeploying Communication Services and Plug-ins

Communication services are deployed and undeployed as EAR files.

For a description of the different deployment options, see "Overview of the Deployment Process" in Oracle Fusion Middleware Understanding Oracle WebLogic Server.

The EAR file names for each communication service and the JAR names for the network protocol plug-ins are listed a table in the discussion on properties for each communication service chapter in Services Gatekeeper Communication Service Reference Guide.

The properties section also describes the JAR file for the plug-in and other artifacts, such as third-party libraries, used by the plug-in.

Following is an example on how to undeploy the Parlay X 2.1 Third Party Call communication service:

java weblogic.Deployer -adminurl http://<admin host>:<admin port> -user <admin user> -password <admin password -name wlng_nt_third_party_call_px21 -undeploy -graceful

If a plug-in has been removed from the EAR, use the mechanism described in "Performing a Hitless Upgrade".

Version Handling and Patching of Communication Services

See "Patch Management of Services Gatekeeper Systems" in Multi-tier Installation Guide for instructions on patching Services Gatekeeper, including communication services.

Installing and Configuring

Follow these steps to install and configure the API

1. Install OCSG single tier with cloud template.

2. Run addCommsPack.sh to install selected communication services, see reference for details.

3. Launch OCSG.

4. Create a plugin instance and add the route from the PluginManager MBean. Or run the script in the PTE MBean script tool as shown in Figure 18-1:

   Figure 18-1 Using PTE MBean Script Tool

   
   

5. Configure plug-in settings

   1. Connect to OCSG MBean using the WebLogic console or the PTE tool. Or run scripts using PTE as in the step above. Different plugins have different settings. This example provides settings for SMS, MMS, Payment and Location. Note that all these examples use PTE simulators as southbound services; you must change the settings if using your actual southbound communication service.

   2. If Qos and Payment are not required, disable these plugins by running script in PTE so that no periodic error will be thrown.

6. Now all the communication services settings are ready. If the southbound services are the PTE simulators, start the plugin simulators in PTE as shown in Figure 18-2.

   Note:

   If using actual communication services, this last step is not needed.

   Figure 18-2 Starting Plugin Simulator

   
   

7. Create the API for communication services.

   1. If using REST to create API, reference examples for SMS, MMS, Payment and Location.

   2. If using OCSG portal, select "Existing Communication Service" when creating API, and choose correct service and interface:

      Figure 18-3 Creating API in OCSG

      
      

      Then on next page, the corresponding methods will be auto added into resource table:

      Figure 18-4 API Resource Table

      
      

8. Create service provider group, service provider, application etc. as usual.

9. Note, to enable specified communication service, some SLA items need to be manually added into the service provider group SLA and application SLA using ServiceLevelAgreement MBean. See references for SMS, MMS and MMS.

Send Traffic

Sending traffic is different in DAF than in a traditional service in the following ways:

• In DAF, the URL is <your ip and port>/<api>/<api version>/<function name>. In a traditional service, the URL sometimes includes the user ID. For example, <your ip and port>/rest/<plugin>/<function name>/<user id>/...

• The format of the send payload can be found by right clicking the resource table item and selecting View Details when creating the API. The schema of the XML payload is shown in the detail view. Figure 18-5 shows an example:

  Figure 18-5 Example Schema of XML Payload

  
  

  The following lines show an example of an XML payload for an SMS send:

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <sendSms>
    <receiptRequest>
      <correlator>987654321</correlator>
      <endpoint>http://10.182.14.7:13444/jaxws/SmsNotification</endpoint>
      <interfaceName>interfaceName</interfaceName>
    </receiptRequest>
    <addresses>tel:1234</addresses>
    <message>Hello world</message>
  </sendSms>
  

Authentication

The traditional way of doing authentication is by logging into the sesssion manager and that authentication is then used to access the communication service. With DAF, north bound authentication (text, OAuth, or appkey) must be done on the DAF side.

In most cases, you cannot use traffic users in DAF to access traditional communication service traffic because SLA structures are completely different between the DAF user and the traditional communication-service user. In other words, most communication service interfaces should be exposed to DAF. The only exception is to start a notification listener. If you set SessionRequired to Disabled in ApplicationSessionMBean, you can use DAF users to receive notifications - in other words, to start a notification listener.

Service Types and Interfaces

When you create an API, only the service types and interfaces enabled in MBean can be listed in the Existing Commucication Service.

• To see the enabled service types and interfaces, on the Admin console navigate to ${domain}->OCSG->${ManagedServerName}->Container Services->DafGeneralInformation->DafGeneralInformation and invoke the operation retrieveAvailableDafCSConfigurations.

• To see theall the configured service types and interfaces, on Admin console navigate to ${domain}->OCSG->${ManagedServerName}->Container Services->DafGeneralInformation->DafGeneralInformation and invoke the operation retrieveDafCSConfigurations.

• To enable or disable the service types and interfaces, on the Admin console navigate to ${domain}->OCSG->${ManagedServerName}->Container Services->DafGeneralInformation->DafGeneralInformation and invoke the operation updateDafCSConfigurations. You can invoke the operation retrieveDafCSConfigurations first and then do add/remove/update. Set the enable attribute to true if you want to enable service types or interfaces.

  When enabled in the MBean, the service type or displayName attribute is shown in the portal.

OCSG has provided out-of-the-box confiugrations of service types and interfaces.

By default not all interfaces will be exposed to partner manager for DAF traffic. Table 18-1 describes the provided service types and interfaces.

Dynamic Versus Static Mode

You can configure the API to use communication services in two ways: Dynamic Mode or Static Mode. Table 18-2 shows the differences between dynamic and static mode.

Choosing an Alias When Multiple Aliases Are Matched

To allow you to specify the alias when multiple aliases are matched for the client SSL, you can specify the alias name by MBean, using the Private Key Alias on the SSL tab, or by using the oracle.sdp.daf.keystore.alias JVM parameters.

The following rules apply:

• If you specify the oracle.sdp.daf.keystore.alias and its value is matched in multiple aliases, the alias of the oracle.sdp.daf.keystore.alias value is used.

• If you do not specify oracle.sdp.daf.keystore.alias or the oracle.sdp.daf.keystore.alias value is not matched in multiple aliases, and if the MBean alias is matched in multiple aliases, the value of the Private Key Alias on the SSL tab is used.

• If either of the above two cases are satisfied, you may choose to use any one of the multiple aliases.

Additional Considerations

You should also consider the following:

1. When the Key Store configuration changes, enable SSL on the managed server and restart the DAF module.

2. The following apply to the key store and trust store configuration:

   1. For single-tier and single-tier standalone, the certification of the back-end service must be imported into OCSG trust store, which is specified by the WebLogic KeyStores MBean. Certification of the OCSG key store must be imported into the back-end service's trust store.

   2. For a single-tier cluster environment, to echo the OCSG node, certification of the back-end service must be imported into the OCSG trust store, which is specified by the WebLogic KeyStores MBean. Certification of the OCSG key store must be imported into the back-end service trust store and it is recommended that all nodes use the same private key store string.

   3. For a multi-tier cluster environment, to echo the OCSG node, certification of the back-end service must be imported into the NT trust store, which is specified by the WebLogic KeyStores MBean. Certification of the NT key store must be imported into the back-end service trust store and it is recommended that all NT nodes use the same private key store string.

Configuring Two-Way SSL for Southbound

Southbound service is required to support two-way SSL and must be configured correctly. You can use either spring boot or another weblogic server as the southbound SSL server. If you are using another WebLogic server as the SSL server, the configuration is same as "Configuring Two-Way SSL for Northbound".

For southbound two-way SSL, OCSG acts as the client. Follow these steps to configure southbound two-way SSL:

1. Generate a private key pair and a private key store using the following keytool command:

   keytool -import -alias myCa1 -trustcacerts -file cert.cer -keystore ${ORACLE_HOME}/wlserver/server/lib/DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase
   

2. Configure the items server.ssl.key-store, server.ssl.key-store-password and server.ssl.key-password correctly based on the information from step 1.

3. Export the private key into a certificate file and import it into the OCSG's trust store.

4. Generate a trust key store and configure server.ssl.trust-store and server.ssl.trust-store-password correctly.

5. Import the OCSG's private key into the trust store.

6. Restart SSL for the first server on the Weblogic console for single-tier. For multi-tier, you configure each NT server one by one.

Using the Tool

Follow these steps to use the addCommsPack.sh tool:

1. Prepare a valid single-tier installer file.

2. Set the environment variable JAVA_HOME to the JDK location. Otherwise the tool will prompt the user to enter the location.

3. Shut down OCSG.

4. Run the following script and specify the domain location:

   ${ORACLE_HOME}/wlserver/common/templates/scripts/addCommsPack/addCommsPack.sh ${DOMAIN_HOME} ${SINGLETIER_INSTALLER_FILE}
   

5. When the script finishes, restart OCSG.

The tool can add any application, server service as long as the required information is present in the list files.

You can customize the tool by editing the following files:

• pkgList

  Contains the required application package names, for example wlng_nt_sms_px21.ear. One line per package. Each line that starts with # is treated as a comment and ignored during processing.

• serviceList

  Contains the required service's full class name, for example oracle.ocsg.protocol.smpp.SMPPServerService. One line per server service. Each line that starts with # is treated as a comment and ignored during processing.

• featuresetList

  Contains the list of optional feature set names to be added to the installation inventory, for example ocsg_app_sms. One line per feature set. Each line that starts with # is treated as a comment and ignored during processing.

Finding Container services

Table 18-5 describes the Services Gatekeeper Java EE container services. The interfaces to these, with common classes, are packaged in

Middleware_home/ocsg/server/lib/wlng/wlng.jar

The container services are packaged in separate JARs, located in

Middleware_home/ocsg/server/lib/wlng/wlng.jar

Patching Container Services

You patch container services using the SmartUpgrade utility. See ”SmartUpgrade Support for JDBC” in Oracle Fusion Middleware Administering JDBC Data Sources for Oracle WebLogic Server.

You patch container services and WebLogic Server using the upgrade process. See "Understanding the 12c Upgrade Process" in Oracle Fusion Middleware Upgrade Planning Guide.