| Oracle® Communications Service Broker Subscriber Store User's Guide Release 6.0 Part Number E23529-02 |
|
|
View PDF |
| Oracle® Communications Service Broker Subscriber Store User's Guide Release 6.0 Part Number E23529-02 |
|
|
View PDF |
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. These values are used by multiple Service Broker applications. 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, 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 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 3GPP specifications: TS 29.060, TS 29.061, and TS 29.274.
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, and bronze. The Policy Controller rules determine how a category dictates the level of service access for the subscriber.
Service Broker applications use the profileDataExtension element to store 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 an end user on a particular network. An end user 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 specific 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, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|