This chapter describes how to develop a Presence and Subscriber Status eXtensions SIP application in the Oracle Communications Service Broker NG-IN solution.
Using the NG-IN solution, SIP applications can obtain mobile subscriber's information that is stored in SS7 network entities such as HLR. To obtain subscriber's information, a SIP application has trigger a SIP SUBSCRIBE message to Service Broker and specify inside the information that it needs. Service Broker returns the subscriber's information in a SIP NOTIFY message.
The following sections describe common parts of the SIP SUBSCRIBE and NOTIFY interface, such as headers and SIP errors, that the SIP application generates every time it communicates with Service Broker, regardless of the type of operation the SIP application requests to perform.
SIP applications can instruct Service Broker which SS7 entity to connect using the domain part of the To header. An application can set the domain part using one of the following methods:
Setting an alias
When a SIP application needs to communicate with an SS7 entity whose SCCP address is configured in the SS7 SSU, the application sets an alias that refers to this address.
Service Broker uses this alias to resolve the preconfigured SCCP address (that is point code or GT address). For example, if you set the To header to sip:1234567890@hlr01, then Service Broker will resolve hlr01 to a real SCCP address, based on the SCCP addresses configured in the SS7 SSU.
Note that if you specify an alias that resolves to a dynamic GT address, then you must also specify the GT digits, using the 'gtaddr' token. For example, sip:1234567890@hlr01;gtaddr=972543349098
Using an IM-PSX SIP domain
When a SIP application needs to communicate with an SS7 entity whose alias is preconfigured in IM-PSX, in the PsxSipDomain parameter, the application sets the IM-PSX SIP domain.
When you set the IM-PSX SIP domain in the domain part of the To header, for example, sip:1234567890@ocsb-psx.net, Service Broker uses the alias configured in the DefaultSs7EntityAlias parameter to resolve an SCCP address that is already configured in the SS7 SSU.
Using the Anonymous string
If a SIP application needs to communicate with an entity whose SS7 address is not configured in Service Broker, the application constructs the domain part of the To header using the "Anonymous" string.
Setting the "Anonymous" string means the application uses additional tokens in the To header to specify an SCCP address.
The "Anonymous" string requires an application to set the tokens described in Table 7-1.
Table 7-1 Tokens Required to Specify an SCCP Address
Token | Type | Description |
---|---|---|
gtaddr |
STRING |
Stands for Global Title Address. The parameter contains digits. |
nai |
STRING |
Stands for Nature of Address Indicator. Possible values:
|
np |
STRING |
Stands for Numbering Plan. Possible values:
|
netind |
STRING |
Stands for Network Indicator. Possible values:
|
tt |
BYTE |
Stands for Translation Type. |
spc |
Up to 24 bit decimal |
Stands for Signaling Point Code. |
ssn |
BYTE |
Stands for Subsystem Number. |
An application must set the tokens described in Table 7-1 as follows:
The netind token is always required.
One of the following tokens is required:
gtaddr. If an application uses the gtaddr token, to allow Service Broker to build the global title indicator, the application must set at least one of the following tokens: tt or nai.
spc accompanied by the ssn token
For example, the following combinations of tokens are considered valid:
netind, gtaddr, nai, np, tt
netind, gtaddr, tt
netind, gtaddr, tt, np
netind, gtaddr, nai
netind, spc, ssn
netind, gtaddr, nai, np, tt, spc, ssn
SIP applications specify the mobile subscriber whose information is required by using the domain part of the RequestURI.
SIP applications should set the RequestURI as follows:
Set the mobile subscriber's MSISDN in the user part
Set the IM-PSX address, as configured in PsxSipDomain, in the domain part.
A SIP application can use the noa token, to specify the MSISDN nature of address that is later used on the MAP interface. The possible noa token values are:
subscriber
unknown
national
To specify that the MSISDN nature of address is 'international', the SIP application must set the MSISDN in the RequestURI user part in a global format, with a leading '+' sign.
For example, a SIP application can set the RequestURI to:
sip:1234567890@ocsb-psx.net:5060;noa=national
sip:+972540987610@ocsb-psx.net:5060;
Service Broker uses the SIP NOTIFY message body to pass a MAP result to the SIP application. Service Broker passes the MAP result in one of the following formats:
"application/map-phase3+xml"
The SIP NOTIFY message body contains a full MAP operation result, encoded in XER.
"application/map-phase3+ber"
The SIP NOTIFY message body contains a full MAP operation result, encoded in BER.
"application/pidf+xml"
The SIP NOTIFY message body contains the mobile subscriber's state and location in PIDF format.
SIP applications use the Accept header to specify the SIP NOTIFY message body formats that the application supports. The value of the Accept header must be one that is also supported by the Service Broker, that is values configured under the IM-PSX AcceptHeadersMBean.
For example, "application/map-phase3+xml" and "application/pidf+xml". See "SIP NOTIFY Message Body Formats" for more information.
The Accept header is optional. If not specified, Service Broker assumes that the SIP application supports the body formats specified in the IM-PSX AcceptHeadersMBean.
SIP applications must always set the Expires header to zero. If an application does not set the Expires header, Service Broker assumes this header is set to zero.
Service Broker can return all standard SIP errors. Table 7-2 provides additional interpretation of some standard SIP errors specifically for Presence and Subscriber eXtensions applications.
Error | Description |
---|---|
400 Bad Request |
The application sets the value of the Expires header to a value other than zero. |
403 Forbidden |
The application sets the value of the domain part in the requestURI which is different from the PsxSipDomain. |
415 Unsupported Media Type |
The application sets the value of the Accept header to a format which Service Broker does not support. |
489 Bad Event |
This error may indicate one of the following problems:
|
500 Server Internal Error |
Unexpected internal error has occurred in Service Broker. |
603 Declined |
There's a mismatch between the Accept header value and the requested-info token value. For example, if the application requests mobile subscriber's location (sets the requested-info token to 'Mobile-location'), but does not support XER format (does not set "application/map-phase3+xml" in the Accept header) that is required to receive the mobile subscriber's location. |
Using the NG-IN solution, SIP applications can obtain a mobile subscriber's state and location that is stored in a network's HLR. Such information includes:
Subscriber's state. For example, reachable or busy.
Subscriber's location. For example, geographical location and VLR number.
Other subscribe's information. For example, extensions information.
The ability to obtain a mobile subscriber's state and location information is based on and the MAP ANY-TIME-INTERROGATION operation. SIP applications can request Service Broker to obtain a mobile subscriber's state and location information by using the SIP SUBSCRIBE message. Service Broker returns the state and location information inside the SIP NOTIFY message body.
The following sections describe how a SIP application needs to generate a SIP SUBSCRIBE message to Service Broker in order to obtain a subscriber's state and location, and then process the SIP NOTIFY message which Service Broker sends back to the SIP application.
The following SIP headers must be set in the SIP SUBSCRIBE message:
RequestURI
See "Specifying the Identity of a Mobile Subscriber" for more information.
To
See "Specifying the Address of an SS7 Entity" for more information.
Accept
See "SIP NOTIFY Message Body Formats" for more information.
Expires
See "Setting the Expires Header" for more information.
The SIP application must set the Event header to 'Presence'. In addition, the SIP application may define the requested-info token to specify the information that Service Broker needs to request from an HLR. For example, the application may request information only about the subscriber state without information about its location.
The SIP application can set requested-info token to one of the following values:
Mobile-state
Mobile-location
If the SIP application does not specify the requested-info token, Service Broker returns both the mobile subscriber's state and location.
Service Broker returns a mobile subscriber's state and location information inside a SIP NOTIFY message body. Depending on the information that the SIP application has requested from Service Broker, the SIP NOTIFY message body may contain either one of the following or both:
Subscriber's state - provided in PIDF format
Subscriber's location and any other information - provided in the XER or BER format
This section describes important SIP headers and the SIP message body that a SIP application receives from Service Broker.
The Subscription-State header value is always 'terminated'.
To explain the reason why a subscriber's state and location cannot be returned, the SIP application uses the reason token. Table 7-3 lists the possible values of the reason token:
Table 7-3 Possible Values of the Reason Token
Token Value | Description |
---|---|
timeout |
Interrogation terminated successfully. The result is available in the SIP NOTIFY message body. |
map_unknownsubscriber |
HLR does not recognize the subscriber whose subscription information has been requested. |
map_datamissing |
HLR stated that the some data is missing in the MAP operation request. |
map_unexpecteddatavalue |
HLR found unexpected data in the MAP operation request. |
map_systemfailure |
There is a problem to connect the HLR. |
unknown |
Unexpected internal Service Broker error occurred. |
addressresolutionfailure |
Service Broker failed to resolve the SCCP address alias, that is the SS7 entity address. |
map_atinotallowed |
HLR does not permit interrogation using the MAP-ANY-TIME-INTERROGATION operation. |
map_timeout |
HLR does not respond. |
The Content-Type header specifies the format of the SIP NOTIFY message body, as follows:
"application/map-phase3+xml" - the body contains the full MAP-ANY-TIME-INTERROGATION operation result structure encoded in the XER format.
"application/map-phase3+ber" - the body contains the full MAP-ANY-TIME-INTERROGATION operation result encoded in the BER format.
"application/pidf+xml" - the body contains subscriber's state encoded in PIDF format.
"multipart/mixed; boundary='frontier'" - the body contains multiple formats, both the subscriber's state encoded in PIDF and the full MAP-ANY-TIME-INTERROGATION operation result structure encoded in XER.
The SIP NOTIFY message body contains information about subscriber's state and location as they were requested by the SIP application in the Event header and requested-info token of the SIP SUBSCRIBE message (for more information, see "Event Header").
The information requested by the SIP application is delivered in the message body as follows:
Subscriber's state is provided in an XML according to the PIDF schema. For more information, see "Subscriber's State".
Subscriber's location and additional subscriber information is provided in the XER or BER format. For more information, see "Other Subscriber Information".
Subscriber's state is provided in an XML, according to the PIDF schema.
The following example shows how information about the subscriber's state is encoded:
<?xml version="1.0" encoding="UTF-8"?> <presence xmlns="urn:ietf:params:xml:ns:pidf " xmlns:ts="urn:ietf:params:xml:ns:pidf:terminal-status" entity="pres:123456789@psx-ocsb.net"> <tuple id="sg89ae"> <status> <basic>open</basic> <ts:state>reachable</ts:state> </status> <timestamp>2008-04-01T18:08:20Z</timestamp> </tuple> </presence>
Table 7-4 explains the PIDF elements and attributes.
Element | Description |
---|---|
presence |
The root element. The element includes the entity attribute and 0 or more tuple elements. The value of the entity attribute contains the value of the RequestURI received on the SIP SUBSCRIBE message with 'pres' uri-scheme. |
tuple |
Contains the mobile subscriber's state information that consists of a mandatory status element accompanied by the optional timestamp element. |
status |
Contains one optional basic element accompanied by the state element. |
basic |
Specifies a subscriber's availability for communications. Possible values:
|
ts:state |
Extension element that specifies the subscriber's state. Possible values:
The value of ts:state correlates with the value of basic as follows:
|
timestamp |
Specifies the date and time when the presence information was created. |
Subscriber's location and other information is provided in the XER or BER format. In this case, the SIP NOTIFY message body contains the full MAP operation result structure.
Using the NG-IN solution, SIP applications can obtain mobile subscriber's subscription information that is stored in an HLR. Such information includes:
Subscriber's basic information, for example, IMSI
Subscriber's service information, for example, indication on services that are invoked for incoming and outgoing calls, mobility changes, incoming and outgoing SMS.
The ability to modify this information is based on the following MAP operations:
MAP-ANY-TIME-SUBSCRIPTION-INTERROGATION
MAP-SEND-IMSI
The ability to obtain subscription information is based on MAP operations. To obtain subscription information, a SIP application has to construct a XER or BER representation of the MAP operation request, and pass it to Service Broker inside the SIP SUBSCRIBE message body. Service Broker returns the subscription information in the SIP NOTIFY message body.
The following sections specify SIP interface requirements for subscription information interrogation, in addition to the common requirements specified at "Understanding Common SIP Interface Concepts".
The following SIP headers must be set in the SIP SUBSCRIBE message:
RequestURI
See "Specifying the Identity of a Mobile Subscriber" for more information.
To
See "Specifying the Address of an SS7 Entity" for more information.
Accept
See "SIP NOTIFY Message Body Formats" for more information.
Expires
See "Setting the Expires Header" for more information.
SIP applications use the Content-Type header to specify the SIP SUBSCRIBE message body format, that is the MAP operation encoding format. Possible values are:
"application/map-phase3+xml" - when the MAP operation request inside the SIP SUBSCRIBE message body is encoded in XER
"application/map-phase3+ber" - when the MAP operation request inside the SIP SUBSCRIBE message body is encoded in BER
The SIP application should use two additional tokens to provide an indication of the MAP operation encoded inside the SIP message body:
op, which defines the MAP operation code. You can set this token to one of the following values depending on the operation you want to trigger:
58, when you want to trigger MAP-SEND-IMSI
62, when you want to trigger MAP-ANY-TIME-SUBSCRIPTION-INTERROGATION
dir, which defines the MAP operation direction. Set this token to "invoke".
For example:
Content-Type: "application/map-phase3+xml; op=62; dir=invoke"
Service Broker returns a mobile subscriber's subscription information inside a SIP NOTIFY message body. Service Broker passes the MAP operation result, as was received from the HLR, encoded in XER or BER. The SIP application can request a preferable format, using the Accept header. See "Specifying Supported SIP NOTIFY Message Body Formats" for more information.
The following SIP headers can provide additional information to the MAP operation result in the SIP message body.
The Subscription-State header value is always 'terminated'.
In case of a problem, the SIP application can use the reason token to identify the failure reason. Table 7-5 lists the possible reason token values:
Table 7-5 Possible Values of the Reason Token
Token Value | Description |
---|---|
timeout |
Interrogation terminated successfully. The result is available in the SIP NOTIFY message body. |
map_unknownsubscriber |
HLR does not recognize the subscriber whose subscription information has been requested. |
map_datamissing |
HLR stated that the some data is missing in the MAP operation request. |
map_unexpecteddatavalue |
HLR found unexpected data in the MAP operation request. |
map_systemfailure |
There is a problem to connect the HLR. |
unknown |
Unexpected internal Service Broker error occurred. An application may also receive this error if the XER or BER provided in the SIP SUBSCRIBE message body cannot be decoded to a MAP message. |
addressresolutionfailure |
Service Broker failed to resolve the SCCP address alias, that is the SS7 entity address. |
map_atsinotallowed |
HLR does not permit interrogation using the MAP-ANY-TIME-SUBSCRIPTION-INTERROGATION operation. |
map_bearerservicenotprovisioned |
The bearer service for which information is requested was not provisioned in the HLR. |
map_teleservicenotprovisioned |
The teleservice for which information is requested, was not provisioned. |
map_illegalssoperation |
Illegal supplementary service operation. |
map_ssnotavailable |
Supplementary service is not available. |
map_informationnotavailable |
The requested information is not available. |
Using the NG-IN solution, SIP applications can modify subscriber's data in an HLR or VLR. The ability to modify this information is based on the following MAP operations:
MAP-ANY-TIME-MODIFICATION
MAP-INSERT-SUBSCRIBER-DATA
SIP applications can request Service Controller to modify subscription information using the SIP SUBSCRIBE message. Service Controller returns the result of the modification operation inside the SIP NOTIFY message body.
The following sections describe how a SIP application needs to generate a SIP SUBSCRIBE message to Service Controller in order to modify subscriber's data, and then process the SIP NOTIFY message which Service Controller sends back to the SIP application.
The following sections describe the SIP headers that must be set in the SIP SUBSCRIBE message.
RequestURI
For more information, see "Specifying the Identity of a Mobile Subscriber".
To
For more information, see "Specifying the Address of an SS7 Entity".
Accept
For more information, see "SIP NOTIFY Message Body Formats".
Expires
For more information, see "Setting the Expires Header".
SIP applications use the Content-Type header to specify the SIP SUBSCRIBE message body format, that is the MAP operation encoding format. The header can contain one of the following values:
"application/map-phase3+xml", when the MAP operation request inside the SIP SUBSCRIBE message body is encoded in XER
"application/map-phase3+ber", when the MAP operation request inside the SIP SUBSCRIBE message body is encoded in BER
The SIP application can use two additional tokens to provide an indication of the MAP operation encoded inside the SIP message body:
op, which defines the MAP operation code. You can set this token to one of the following values depending on the operation you want to trigger:
7, when you want to trigger MAP-INSERT-SUBSCRIBER-DATA
65, when you want to trigger MAP-ANY-TIME-MODIFICATION
dir, which defines the MAP operation direction. Set this token to "invoke".
For example:
Content-Type: "application/map-phase3+xml; op=65; dir=invoke"
If the body is empty, Service Broker returns the SIP error 400 'Bad request'.
Service Broker returns a result of a modification operation inside a SIP NOTIFY message body. This section describes the SIP headers and the SIP message body that a SIP application receives from Service Controller.
The Subscription-State header value is always 'terminated'. If a problem occurs, the SIP application can set the reason token to the values described in Table 7-6.
Table 7-6 Possible Values of the Reason Token
Token Value | Description |
---|---|
addressresolutionfailure |
Service Controller failed to resolve the SCCP address alias, that is the SS7 entity address. |
map_bearerservicenotprovisioned |
The bearer service for which information is requested was not provisioned in the HLR. |
map_callbarred |
Operator determined barring or supplementary service barring management is active |
map_datamissing |
HLR stated that the some data is missing in the MAP operation request. |
map_illegalssoperation |
Illegal supplementary service operation. |
map_informationnotavailable |
The requested information is not available. |
map_sserrorstatus |
Supplementary service error status |
map_ssincompatibility |
Supplementary service incompatibility |
map_sssubscriptionviloation |
Supplementary service subscription violation |
map_teleservicenotprovisioned |
The teleservice for which information is requested, was not provisioned. |
map_atmnotallowed |
MAP ANY-TIME-MODIFICATION operation is not allowed by the HLR |
map_unexpecteddatavalue |
HLR found unexpected data in the MAP operation request. |
map_unknownsubscriber |
HLR does not recognize the subscriber whose subscription information was requested. |
timeout |
Interrogation terminated successfully. The result is available in the SIP NOTIFY message body. |
unknown |
Unexpected internal Service Controller error occurred. An application may also receive this error if the XER or BER provided in the SIP SUBSCRIBE message body cannot be decoded to a MAP message. |
The Content-Type header specifies the format of the SIP NOTIFY message body, as follows:
"application/map-phase3+xml", when the body contains the full modification operation result structure encoded in the XER format
"application/map-phase3+ber", when the body contains the full modification operation result structure encoded in the BER format