4 Application Subscription Management

This chapter describes the use of Application Subscription Management in Oracle Communications Services Gatekeeper.

Overview of the Application Subscription Management Service

Services Gatekeeper supports Open Mobile Alliance (OMA) General Service Subscription Management (GSSM) functionality including subscription management, subscription profile access and subscription validation with Application Subscription Management.

Application Subscription Management includes both a communication service and a RESTful interface for managing and querying service subscription status. Application Subscription Management grants or restricts application access to a subscriber's communication service(s) depending on subscription status.

For information on the OMA GSSM specification see:

http://technical.openmobilealliance.org/Technical/release_program/gssm_v1_0.aspx

For information on using the Application Subscription Management communication service, including configuring subscriptions using SMPP, see the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide.

Application Interfaces

Services Gatekeeper provides a RESTful interface for Application Subscription Management in addition to the Mbean interface accessible from the Administration Console or Platform Test Environment (PTE).

For more information on using the RESTful interface, see the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper RESTful Application Developer's Guide.

Support for OAuth Authentication

Services Gatekeeper supports OAuth authentication in Application Subscription Management. Services Gatekeeper generates and stores an OAuth token for subscription requests using OAuth. Subsequent application access requests for subscriber services usage require a valid OAuth accessToken. The Services Gatekeeper OAuth Interceptor uses the provided accessToken to confirm a subscriber's identity before permitting subscriber services usage.

See "Configure Application OAuth Scope", for information on enabling OAuth accessTokens in Application Subscription Management.

For information about Services Gatekeeper OAuth support, see Oracle Communications Services Gatekeeper OAuth Guide.

Events and Statistics

The Application Subscription Management communication service generates Event Data records (EDRs) to assist system administrators and developers in monitoring the service.

Event Data Records

Table 4-1 lists the EDRs generated by Application Subscription Management operations.

Table 4-1 Application Subscription Management Class EDRs

EDR ID	Description
409001	An application created a subscription using createSubscription.
409002	An application deleted a subscription using deleteSubscription.
409003	An application confirmed a subscription using confirmSubscription.
409004	A subscriber list of application subscriptions was generated using listSubscriptionsBySubscriberAddress.
409005	An application subscription list was generated using listSubscriptionsByApplicationName.
409006	An application subscription was retrieved using getSubscriptionById.
409007	An application subscription response was sent.
409008	An application subscription request was created using createSubscription from SMPP.
409009	An application subscription was suspended.
409010	An application subscription was unsuspended.
409101	createSubscription was called in the Access Tier.
409102	deleteSubscription was called in the Access Tier.
409103	confirmSubscription was called in the Access Tier.
409104	listSubscriptionsBySubscriberAddress was called in the Access Tier.
409105	listSubscriptionsByApplicationName was called in the Access Tier.
409106	getSubscriptionById was called in the Access Tier.
409107	notifySubscription callback in the Access Tier.
409110	suspend was called in the Access Tier.
409111	unsuspend was called in the Access Tier.

Managing Application Subscription Management

This section describes the properties and workflow for setting up the Application Subscription Management plug-in instance.

The Application Subscription Management plug-in supports loading an XML configuration file that includes subscription management settings for managed applications. Additional operations are provided for retrieving configuration, listing subscriptions and connecting to an SMSC.

Properties for Application Subscription Management

Table 4-2 lists the technical specifications for the communication service.

Table 4-2 Properties for Application Subscription Management

Property	Description
Managed object in Administration Console	domain_name- OCSG > server_name > Communication Services > Plugin_app_subscription
MBean	Domain=com.bea.wlcp.wlng Name=wlng_nt _app_subscription InstanceName=Plugin_app_subscription Type=oracle.ocsg.plug-in.subscription.management.SubscriptionPluginMbean
Network protocol plug-in service ID	Plugin_app_subscription
Network protocol plug-in instance ID	The ID is assigned when the plug-in instance is created. See the chapter on managing and configuring the plug-in manager in Oracle Communications Services Gatekeeper System Administrator's Guide.
Service type	AppSubscription
Interfaces with the network nodes using:	SMPP Esme System Type and Version
Deployment artifacts:	wlng_nt_app_subscription.ear and wlng_at_app_subscription_rest.ear

Configuration Workflow for Application Subscription Management

The Services Gatekeeper installation includes two optional packages used with Application Subscription Management. By default, these packages are not installed. You must install and deploy the following packages before configuring Application Subscription Management:

• wlng_at_app_subscription_rest.ear

• wlng_nt_app_subscription.ear

You must create and configure a plug-in instance after installing the packages. The following lists the steps for configuring the plug-in:

1. Deploy the Application Subscription Management plug-in ear packages. See "Deploying Application Subscription Management Packages", for more information.

2. Create an Application Subscription Management plug-in instance. See "Creating an Application Subscription Management plug-in Instance", for more information.

3. Configure the Application Subscription Management plug-in attributes. See "Editing Application Subscription Management Attributes", for more information.

4. Load and retrieve application subscription configurations. See "Loading Application Subscription Configuration Files" and "Retrieving Application Subscription Configuration Files", for more information.

5. Retrieve application subscription lists. See "Retrieving Application Subscription Lists", for more information.

6. Configure application OAuth scope if necessary. See "Configure Application OAuth Scope", for more information.

7. Connect to an SMSC. See "Connecting to an SMSC", for more information.

Deploying Application Subscription Management Packages

To deploy the necessary packages:

1. Log into the Administration Console.

2. Click Deployments under Domain Structure.

3. Click Install.

4. If needed, enter the path to the applications directory in Path. The default location for the applications directory is Oracle_Home/ocsg_5.1/applications.

5. Select wlng_at_app_subscription_rest.ear.

6. Click Next.

7. Select Install this deployment as an application.

8. Click Next.

9. Select any optional settings that are needed in your environment. For more information on deployment settings, see the chapter on the deployment model in Oracle Communications Services Gatekeeper System Administrator's Guide.

10. Click Next.

11. Review your deployment choices and click Finish.

12. Repeat steps 1 through 11 for the wlng_nt_app_subscription.ear application file.

Creating an Application Subscription Management plug-in Instance

You must create one or more instances of the Application Subscription Management plug-in to manage subscription requests. Create an instance of the Application Subscription Management plug-in as follows:

1. Log into the Administration Console.

2. Expand OCSG in the Domain Structure pane.

3. Click on the name of the administration or managed server you want to create the Application Subscription Management plug-in instance on.

4. Expand the Container Services node in the Oracle Communications Services Gatekeeper pane.

5. Select PluginManager.

6. Click the Operations tab.

7. In the Select An Option pull down menu select createPluginInstsance.

8. Enter Plugin_app_subscription in the PluginServiceId field.

9. Enter a unique name in the PluginInstanceId field.

10. Click Invoke.

11. Add a route to the ASM plug-in using the pluginManager Mbean.

The Platform Test Environment MBean interface can also be used to create and manage Application Subscription Management plugins. For information on using the Platform Test Environment, see Oracle Communications Services Gatekeeper Platform Test Environment Guide.

Editing Application Subscription Management Attributes

Each instance of the Application Subscription Management plug-in can be configured with its own attributes. For example, you can configure an instance of the plug-in for each type of short message service center (SMSC) used in your environment.

To configure the Application Subscription Management plug-in attributes listed in "Reference: Attributes and Operations for Application Subscription Management":

1. Log into the Administration Console.

2. Expand the OCSG node in Domain Structure.

3. Select the administration or managed server where you created the Application Subscription Management plug-in.

4. Expand Communication Services in Oracle Communications Services Gatekeeper.

5. Select the Application Subscription Management plug-in instance to configure.

6. Click Attributes.

7. Select the checkboxes of the attributes you wish to change.

8. Enter the new values for the attribute(s).

9. Click Update Attributes.

Loading Application Subscription Configuration Files

Create and manage subscription configurations for application services using the loadAppSubscriptionsXml operation. You use this operation with an XML configuration file containing subscription parameters described in "Operation: loadAppSubscriptionsXml".

Example 4-1 shows a sample subscription management XML configuration file used to load application subscription data into Services Gatekeeper.

Example 4-1 Sample Subscription Management XML Configuration File

<?xml version="1.0" encoding="UTF-8"?>
<subscriptions xmlns="http://oracle/ocsg/appSubscription/types" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  
  <!-- SP code -->
  <subscription serviceNumber="tel:1234">
        <application  appInstanceId="domain_user" applicationName="Oracle News" 
                      endpoint="http://www.oracle.com" expirePeriod="36000000" subscriptionChannel="ALL">
           <metaInfo key="key1" value="value1"/>
           <metaInfo key="key2" value="value2"/>
           <subscribeInfo text="Subscribe 123" notification="You have subscribed Oracle News successfully"/>
           <unsubscribeInfo text="Un-Subscribe 123" notification="You have unsubscribed Oracle News successfully"/>
           <suspendInfo text="Suspend 123" notification="You have suspended Oracle News successfully"/>
           <unsuspendInfo text="Un-Suspend 123" notification="You have unsuspended Oracle News successfully"/>
           <resourceId>createoutboundMessage</resourceId>
        </application>
        
        <application  appInstanceId="domain_user_1" applicationName="Oracle Jokes" 
                      endpoint="http://www.oracle.com" expirePeriod="36000000" subscriptionChannel="WEB_RESTFUL">
           <subscribeInfo text="Subscribe 456" notification="You have subscribed Oracle Jokes successfully"/>
           <unsubscribeInfo text="Un-Subscribe 456" notification="You have unsubscribed Oracle Jokes successfully"/>
           <suspendInfo text="Suspend 456" notification="You have suspended Oracle Jokes successfully"/>
           <unsuspendInfo text="Un-Suspend 456" notification="You have unsuspended Oracle Jokes successfully"/>
           <resourceId>createoutboundMessage</resourceId>
        </application>
  </subscription>
  
  <!--App code-->
  <subscription serviceNumber="tel:5678">
    <application  appInstanceId="domain_user_2" applicationName="Google Weather" 
                      endpoint="http://www.google.com" expirePeriod="36000000" subscriptionChannel="SMS">
           <subscribeInfo text="Subscribe" notification="You have subscribed Google Weather successfully"/>
           <unsubscribeInfo text="Un-Subscribe" notification="You have unsubscribed Google Weather successfully"/>
           <suspendInfo text="Suspend" notification="You have suspended Oracle Jokes successfully"/>
           <unsuspendInfo text="Un-Suspend" notification="You have unsuspended Oracle Jokes successfully"/>
           <resourceId>createoutboundMessage</resourceId>
        </application>
  </subscription>
  
</subscriptions>

Load the new or update an existing application subscription configuration using the following procedure:

1. Log into the Administration Console.

2. Expand OCSG under Domain Structure.

3. Click on the name of the administration or managed server you want to create the application subscription configuration on.

4. Expand Communication Services.

5. Select the Application Subscription Management plug-in instance you want to configure.

6. Click Operations.

7. In the Select An Operation pull down menu select loadAppSubscriptionsXml.

8. Copy and paste your XML configuration file contents in the xml field.

9. Click Invoke.

Retrieving Application Subscription Configuration Files

Retrieve the current application subscription configuration in a plug-in instance using the following procedure:

1. Log into the Administration Console.

2. Expand OCSG under Domain Structure.

3. Click on the name of the administration or managed server from where you want to retrieve the subscription configuration.

4. Expand Communication Services.

5. Select the Application Subscription Management plug-in instance you want to retrieve the subscription configuration from.

6. Click Operations.

7. In the Select An Operation pull down menu select retrieveAppSubscriptionsXml.

8. Click Invoke.

Retrieving Application Subscription Lists

Retrieve a list of application subscriptions in Services Gatekeeper using the following procedure:

1. Log into the Administration Console.

2. Expand OCSG under Domain Structure.

3. Click on the name of the administration or managed server from where you want to retrieve the subscription list.

4. Expand Communication Services.

5. Select the Application Subscription Management plug-in instance you want to retrieve the subscription list from.

6. Click Operations.

7. In the Select An Option pull down menu, select retrieveAppSubscriptionsList.

8. Click Invoke.

Configure Application OAuth Scope

You must configure application scope when using OAuth authentication with Application Subscription Management. Configure the application's resourceId as an OAuth scopeId in Services Gatekeeper using the loadAppSubscriptionResourceXml operation in the OAuthResourceMbean.

1. Log into the Administration Console.

2. Expand OCSG under Domain Structure.

3. Click the name of the administration or managed server where the OAuth container service is hosted.

4. Expand Container Services.

5. Expand OAuthService.

6. Select OAuthResourceMBean.

7. Click Operations.

8. In the Select an Option pull down menu, select loadAppSubscriptionResourceXml.

9. Enter the XML string as shown in Example 4-2. Set the resource id to the same value used when loading the application subscription configuration. See "Loading Application Subscription Configuration Files", for more information. Set the interfaceName, methodName and tokenExpirePeriod as required. See Oracle Communications Services Gatekeeper OAuth Guide, for more information on the loadAppSubscriptionResourceXml operation.

Example 4-2 loadAppSubscriptionResourceXml Sample XML Configuration File

<?xml version="1.0" encoding="UTF-8"?>
<resources xmlns="http://oracle/ocsg/oauth2/management/xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <!-- amountTransaction  -->
  <resource id="OneAPIMMS" name="mms" 
        interfaceName="oracle.ocsg.parlayrest.plugin.MmsPlugin" methodName="sendMessage"
        tokenExpirePeriod="3600">
  </resource>
</resources>

Connecting to an SMSC

Application Subscription Management plug-in instances must connect to an SMSC to accept and confirm subscription requests by SMS. Connect each plug-in instance to its SMSC using the following procedure:

1. Log into the Administration Console.

2. Expand OCSG under Domain Structure.

3. Click on the name of the administration or managed server where the Application Subscription Management plug-in to connect to an SMSC is hosted.

4. Expand Communication Services.

5. Select the Application Subscription Management plug-in instance you want to connect to an SMSC. The plug-in Attributes tab contains the SMSC connection information. See "Editing Application Subscription Management Attributes", for more information on configuring SMSC connection attributes.

6. Click Operations.

7. In the Select An Operation pull down menu select connect.

8. Click Invoke.

9. Click Attributes and check the ActiveStatus value. A true value indicates successful connection to the configured SMSC.

Handling Traffic from Applications without Subscriptions

Application Subscription Management checks for a valid subscription before allowing an application to use a subscriber communication service. However, some applications may not use subscriptions to manage message delivery. For example, a service provider may use an application in Services Gatekeeper to send a subscriber a text message about an emergency or pending service outage.

Services Gatekeeper only validates subscription status for applications configured in the Application Subscription Management XML file. Messages originating from applications not configured in the XML file bypass subscription validation and are sent through the normal delivery pathway. See "Loading Application Subscription Configuration Files", for information on the Application Subscription Management configuration file.

Reference: Attributes and Operations for Application Subscription Management

This section describes the attributes and operations for configuration and maintenance.

Attributes list

• Attribute: ActiveStatus

• Attribute: ConnectDelayValue

• Attribute: SmscAddress

• Attribute: SmscPort

• Attribute: LocalAddress

• Attribute: LocalPort

• Attribute: BindType

• Attribute: NumberTransmitterConnections

• Attribute: NumberReceiverConnections

• Attribute: NumberTransceiverConnections

• Attribute: EsmeSystemId

• Attribute: EsmePassword

• Attribute: EsmeSystemType

• Attribute: SmppVersion

• Attribute: EsmeTon

• Attribute: EsmeNpi

• Attribute: EsmeAddressRange

• Attribute: RequestTimerValue

• Attribute: EnquireLinkTimerValue

• Attribute: RetryTimesBeforeReconnect

• Attribute: RetryTimesBeforeGiveUp

• Attribute: WindowingSize

• Attribute: WindowingMaxQueueSize

• Attribute: WindowingMaxWaitTime

• Attribute: DeliverSmRespCommandStatus

• Attribute: MessageIdInHexFormat

• Operation: loadAppSubscriptionsXml

• Operation: retrieveAppSubscriptionsXml

• Operation: retrieveAppSubscriptionsList

• Operation: connect

Attribute: ActiveStatus

Scope: LocalUnit: Not applicableFormat: Boolean

Specifies the SMSC connection status for this plug-in.

Attribute: ConnectDelayValue

Scope: ClusterUnit: Not applicableFormat: Integer

Attribute exposed for management.

Attribute: SmscAddress

Scope: ClusterUnit: Not applicableFormat: String

The hostname or IP address of the SMSC.

Attribute: SmscPort

Scope: ClusterUnit: Not applicableFormat: String

The port number on the SMSC host to connect to.

Attribute: LocalAddress

Scope: localUnit: Not applicableFormat: String

The local machine name or IP address.

Attribute: LocalPort

Scope: localUnit: Not applicableFormat: String

The start port which the SMPP SMSC should bind to.

Attribute: BindType

Scope: ClusterUnit: Not applicableFormat: Integer

Specifies how the plug-in connects to the SMSC.

Attribute: NumberTransmitterConnections

Scope: ClusterUnit: Not applicableFormat: Integer

Number of transmitter connections used towards the SMSC when BindType is 0 or 2.

Attribute: NumberReceiverConnections

Scope: ClusterUnit: Not applicableFormat: Integer

Number of receiver connections used towards the SMSC when BindType is 0 or 3.

Attribute: NumberTransceiverConnections

Scope: ClusterUnit: Not applicableFormat: Integer

Number of transceiver connections used towards the SMSC when BindType is 1.

Attribute: EsmeSystemId

Scope: ClusterUnit: Not applicableFormat: String

The system ID that the plug-in uses when binding to the SMSC.

Attribute: EsmePassword

Scope: ClusterUnit: Not applicableFormat: String

The password that the plug-in uses when binding to the SMSC.

Attribute: EsmeSystemType

Scope: ClusterUnit: Not applicableFormat: String

The system type that the plug-in uses when binding to the SMSC.

Attribute: SmppVersion

Scope: ClusterUnit: Not applicableFormat: String

The SMPP version supported by this plug-in.

Attribute: EsmeTon

Scope: ClusterUnit: Not applicableFormat: Integer

The ESME type of number (TON) used for the address parameter in a bind operation.

Attribute: EsmeNpi

Scope: ClusterUnit: Not applicableFormat: Integer

The ESME numbering plan indicator (NPI) used for the address parameter in a bind operation.

Attribute: EsmeAddressRange

Scope: ClusterUnit: Not applicableFormat: String

The address range that the plug-in uses when binding to the SMSC.

Attribute: RequestTimerValue

Scope: ClusterUnit: Not applicableFormat: Integer

The maximum time, in seconds, between the submission of a request to the SMSC and the receipt of the corresponding response before the connection is terminated.

Attribute: EnquireLinkTimerValue

Scope: ClusterUnit: Not applicableFormat: Integer

The minimum interval between ENQUIRE_LINK requests to the SMSC, in seconds.

Attribute: RetryTimesBeforeReconnect

Scope: ClusterUnit: Not applicableFormat: Integer

The maximum number of failed heartbeats before reconnecting to the SMSC.

Attribute: RetryTimesBeforeGiveUp

Scope: ClusterUnit: Not applicableFormat: Integer

The maximum number of times to try to reconnect to the SMSC before giving up.

Attribute: WindowingSize

Scope: ClusterUnit: Not applicableFormat: Integer

The number of simultaneous outstanding requests to the SMSC allowed.

Attribute: WindowingMaxQueueSize

Scope: ClusterUnit: Not applicableFormat: Integer

The number of requests allowed to wait in the windowing queue.

Attribute: WindowingMaxWaitTime

Scope: ClusterUnit: Not applicableFormat: Integer

The maximum amount of time, in seconds, that each request can wait in the windowing queue.

Attribute: DeliverSmRespCommandStatus

Scope: ClusterUnit: Not applicableFormat: Integer

The command status of the DELIVER_SM_RESP used when an application cannot be reached.

Attribute: MessageIdInHexFormat

Scope: ClusterUnit: Not applicableFormat: Boolean

Specifies the messageId format used in submitSMResp, submitMultiResp, and dataSMResp operations. True indicates hex format and false indicates decimal format.

Operation: loadAppSubscriptionsXml

Scope: Cluster

Loads application subscriptions configuration XML content.

Signature:

loadAppSubscriptionsXml(String)

Table 4-3 Subscription Management Configuration File Elements

Element Name	Unique	Description	Required
serviceNumber	Y	The target telephone number if subscribed by SMS. The number can be a service provider number, or an application number.When using a service provider number, multiple application registrations share the same number, but must use different subscription short message text.	Y
appInstanceId	Y	The application's instance ID.	Y
applicationName	Y	The application's name.	Y
endpoint	N	The application's endpoint where Services Gatekeeper sends subscription notifications.	Y
reqLimit	N	The maximum request time limit.	N
expirePeriod	N	The number of seconds a subscription is valid.	Y
subscriptionChannel	N	The subscription channel. Supported values are ALL, WEB_RESTFUL or SMS.	N
metaInfo.key	N	The new added EDR attribute key.	N
metaInfo.value	N	The new added EDR attribute value.	N
subscribeInfo.text	N	A regular expression describing accepted SMS subscribe request format.	Y
subscribeInfo.notification	N	The notification SMS text after subscription confirmation.	Y
unsubscribeInfo.text	N	A regular expression describing accepted SMS unsubscribe request format.	Y
unsubscribeInfo.notification	N	The notification SMS text after unsubscription confirmation.	Y
suspendInfo.text	N	A regular expression describing accepted SMS suspendInfo request format.	Y
suspendInfo.notification	N	The notification SMS text after a subscription suspension.	Y
unsespendInfo.text	N	A regular expression describing accepted SMS unsuspendInfo request format.	Y
unsuspendInfo.notification	N	The notification SMS text after a subscription unsuspension.	Y
resourceId	N	The value mapped to the OAuth scopeId.	N

Operation: retrieveAppSubscriptionsXml

Scope: Cluster

Retrieves currently configured application subscriptions XML content.

Signature:

retrieveAppSubscriptionsXml()

Operation: retrieveAppSubscriptionsList

Scope: Cluster

Retrieves a list of current application subscriptions.

Signature:

retrieveAppSubscriptionsList()

Operation: connect

Scope: Cluster

Connects the Application Subscription Management plug-in instance to the configured SMSC.

Signature:

connect()