| Oracle® Communications Service Broker Subscriber Store User's Guide Release 6.1 E29459-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Service Broker Subscriber Store User's Guide Release 6.1 E29459-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the SOAP Subscriber Provisioning API, the application programming interface client applications use to manage profiles in the Oracle Communications Service Broker Subscriber Store.
The Subscriber Provisioning API is a Document-style SOAP API that provides operations for creating, updating, retrieving and removing profiles in the Subscriber Store.
The operations in the API correspond to what are commonly called the CRUD operations, which is an acronym for create, read, update, and delete.
In the Subscriber Provisioning API, the operations are named:
storeSubscriber: Creates subscriber profiles.
getSubscriber: Returns data that makes up a subscriber profile.
updateSubscriber: Modifies subscriber profiles.
deleteSubscriber: Removes subscriber profiles from the Subscriber Store.
The Subscriber Provisioning API provides a WSDL file that describes the operations and data types in the API. After installing Service Broker and enabling Web service connectivity, you can access the Subscriber Provisioning WSDL at the following default location:
https://host:port/soap/SubscriberProvisioning?wsdl
where host is the host name or IP address and port is the server port number you specified as the server address (as described in "Enabling HTTP Network Access").
The protocol type (http or https), SOAP root URI (/soap, by default), and service name are all configurable in the Service Broker domain. Your path to the WSDL may be different.
"Subscriber Provisioning API Reference" contains reference information about each operation, along with sample requests and responses.
The subscriber profile data model defines the elements of a subscriber profile. The model includes general information for the subscriber along with feature-specific information, such as Policy Controller data.
The subscriber profile data model is defined by an XML Schema file. You can access the schema at the following default location:
http://host:port/soap/SubscriberProvisioning?xsd=1
where host is the host name or IP address and port is the server port number you specified as the server address (as described in "Enabling HTTP Network Access").
As shown in Figure 5-1, the top-level data elements that compose the subscriber profile are:
The following sections provide information on the data elements of the subscriber profile. For more information on how specific applications use the data, see the Service Broker product implementation guide specific for your controller type.
The globalProfileData element defines general properties for a subscriber. Multiple Service Broker applications use these values. This element contains the following elements:
accountState: The account lifecycle state that indicates the status of the account, such as active or inactive. See "Using Subscriber Account Lifecycles" for more information about account lifecycle states.
accountType: The account type from the options prepaid, postpaid, or hybrid. Hybrid accounts can use both prepaid and postpaid charging methods.
dateOfBirth: The birth date of the subscriber. The date is in YYYYMMDD format. For example, 19910128.
groups: Group identifier for the subscriber.
language: The language to use for the subscriber. Service Broker applications that interact with subscribers can use this attribute to select a response or adapt a message for the subscriber.
notificationChannel: The notification channel used to send notifications to the user.
subscriberActivationDate: The date, in YYYYMMDD format, when the subscriber account was first activated, such as 20111231.
The ifcProfileData element contains the iFC logic for the subscriber. The iFC defines the service chain for a particular subscriber, which services are invoked and the order in which they are invoked.
The PcrfProfileData element contains subscriber data used by the Policy Controller. PcrfProfileData includes the following elements:
allowUnknownServices: Whether the subscriber is permitted to access services that are not specifically allocated to that subscriber, as indicated by the services field.
homeZone: The home, non-roaming network zone for the subscriber. Policy Controller administrators can apply charging rates or service access decisions based on whether the subscriber is using the network from their home zone.
The homeZone element is made up of a locationType, which identifies the protocol type in which the location information is represented, such as IEEE-802.11a or 3GPP-GERAN. Depending on the location type, it also includes elements that identify the location as specified for that type.
Possible values for locationType can be: CGI, SAI, RAI, TAI, ECGI, TAI_ECGI. Depending on the value of locationType, the following additional elements may also be present:
CI
ECI
LAC
MCC
MNC
RAC
SAC
TAC
For example, if the location type is CGI, then the location-type specific parameters that should be set are: CI, LAC, MCC, and MNC.
For more information on the location identification protocol, see the following 3GPP specifications:
services contains one or more service elements. The service defines the services this subscriber can access. Each service has the following fields:
description: A description of the service.
endDate: The date, in YYYYMMDD format, on which the service availability ends for an individual subscriber. Along with the startDate value, this value enables you to make services available to subscribers within a specific date range.
id: The identity of the Policy Controller application described by this service element. See Oracle Communications Service Broker Policy Controller Implementation Guide for more information.
startDate: The date, in YYYYMMDD format, on which service availability begins. Along with the endDate value, this value enables you to make services available to subscribers within a specific date range.
subscriberCategory: An application-defined service level for a given subscriber, such as gold, silver, or bronze. The Policy Controller rules determine how a category dictates the level of service access for the subscriber.
The counterProfileData element contains subscriber usage data represented as one or more counterData elements. Each counterData element identifies a resource or usage balance and its associated regions defined by a set of consecutive value ranges. See "Understanding Counter Regions", for an example of how regions can be used in the Subscriber Store.
counterData contains the following:
id: A unique string identifier for the counter.
region(s): One or more consecutive counterRegion resource balance value ranges used to categorize a subscriber's usage status. The value of a subscriber's resource counter determines the region that the subscriber is currently in.
The counterRegion element consists of the following:
regionID: A unique string identifier for the region.
activationDate: The date on which the region became active. For example, 20120712.
deactivationDate: The date on which the region will become inactive. For example, 20120818.
quota: The available quota for the region if this region has a quota.
usage: The currently used resource amount for the region.
meteringMethod: Indicates a how counter tracks subscriber usage. The following methods are supported:
VOLUME: The amount of resource usage. For example, bytes.
DURATION: The length of time a resource is used. For, example, seconds or minutes.
counterType: Indicates the type of metric used to track subscriber usage. The following types are supported:
SECONDS
MINUTES
BYTES
regionTotal:
totalQuota: The total amount of resource quota available in a region.
totalUsage: A subscriber's total resource usage within a region.
The following sample scenario provides an example of how counter regions are used in the Subscriber Store.
In this example, counter regions model a fair usage scenario for a data subscriber. The subscriber's service provider implements a data plan including reduced (throttled) data speeds triggered by the subscriber's total data usage across the thresholds as shown in Figure 5-2.
As the subscriber's usage accumulates in the fair usage counter, he moves through the Monthly, Throttled, and Restricted counter regions. The subscriber exists in only one region at a time.
Service Broker applications can use the subscriber's current region to enforce the correct data throttling and access limitations. The bandwidth and access values in the example are not part of the counter data model, but rather part of the rules enforced based on the data model.
The redirectionProfileData element defines subscriber redirection behavior. The Service Broker Redirection Application uses these values to redirect sessions requiring subscriber attention, such as a low balance, to an alternative destination application. Redirection data stored in a subscriber's profile overrides the default redirection behavior configured in the charging IM.
See the chapter on the Redirection Application in Service Broker Online Mediation Controller Implementation Guide for more information.
The following fields are included in the redirectionProfileData element:
criteria: Indicates the type of message triggering redirection supplied by the online charging system. Supported values are FUI, NO_MONEY_NOTIFICATION, and LOW_CREDIT_NOTIFICATION.
redirectAddressType: Defines the address type of the address specified in the element. Supported values are IPV4, IPV6, URL, and SIP_URI.
redirectAddressAddress: The address of the redirection server.
validityTime: The allowed time, in seconds, remaining for a redirected subscriber to access network resources.
immediately: Indicates whether redirection should happen IMMEDIATELY or NON_IMMEDIATELY (after the value specified in Validity Time). When the type is set to NO_MONEY, this value must be set to IMMEDIATELY.
The profileDataExtension element stores custom data elements in the profile. For example, the Policy Controller rule engine can make policy decisions based on dynamically defined subscriber attributes.
The extensionId value identifies the Service Broker component that uses the data extension. For the Policy Controller, for example, the extensionId value is pcrf. Each data extension entry consists of one or more name-value pairs, as specified by the Service Broker component that uses it.
The userIdentifier element contains the unique identifier for a subscriber on a particular network. A subscriber can belong to multiple networks, for instance, if they own multiple devices used to access different networks. Therefore, a subscriber can have multiple userIdentifier elements.
Each userIdentifier element consists of the identifier value and the type of the identifier. The type represents the system in which the ID belongs. It may have one of the following values:
END_USER_E164: The subscriber's identity in ITU-T E.164 format, as defined in recommendations E164 and CE164.
END_USER_IMSI: The subscriber's identity in International Mobile Subscriber Identity format, as defined in ITU-T recommendations E212 and CE212.
END_USER_SIP_URI: The subscriber's identity in a SIP network.
END_USER_NAI: The subscriber's identity in a mobile IP Network Address Identifier format.
END_USER_PRIVATE: The subscriber's private identity in a credit-control server.
END_USER_GLOBAL_UID: A unique global user ID generated by Service Broker to identify subscribers internally. Service Broker generates this ID automatically when you create a subscriber profile.
The value for each identifier type varies by the network type. For example, the identifier for the URI type should be in the form of a SIP URL, such as sip:username@example.
The Subscriber Provisioning service responds to client request errors with a ProvisioningException error response. You can use the information in the response to troubleshoot client application errors.
The ProvisioningException response includes the faultcode and faultstring elements, which indicate the type of error and provide more information about the error. For example:
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<faultcode>S:Server</faultcode>
<faultstring>Profile not found : 55555656|END_USER_E164</faultstring>
<detail>
<ns2:ProvisioningException
xmlns:ns2="http://ws.subscriber_store.service.rcc.app.ocsb.oracle/">
<message>Profile not found : 55555656|END_USER_E164</message>
</ns2:ProvisioningException>
</detail>
</S:Fault>
</S:Body>
</S:Envelope>
This example shows the error response if the subscriber ID passed in the getSubscriber request was not found in the Subscriber Store.
If a SOAP request does not contain a required element, the ProvisioningException response indicates an invalid input parameter error and identifies the missing element.
For example, a storeSubscriber request with an incomplete userIdentifier element generates the following error:
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<faultcode>S:Server</faultcode>
<faultstring>Invalid input parameters:
{userIdentifier=null}</faultstring>
<detail>
<ns2:ProvisioningException xmlns:ns2=
"http://ws.subscriber_store.service.rcc.app.ocsb.oracle/">
<message>Invalid input parameters:{userIdentifier=null}</message>
</ns2:ProvisioningException>
</detail>
</S:Fault>
</S:Body>
</S:Envelope>
As indicated by the faultstring, the userIdentifier element in the request message is invalid or missing. Similarly, the content of the ProvisioningException response for other types of errors provides information on the nature of the error that caused the exception.
|
 Copyright © 2011, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|