8 Developing a Presence and Subscriber Status SIP Application

This chapter describes how to develop a Presence and Subscriber Status eXtensions SIP application in the Oracle Communications Service Broker NG-IN solution.

Understanding Common SIP Interface Concepts

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.

Specifying the Address of an SS7 Entity

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 8-1.

Table 8-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: unknown subscriberNumber nationalReserved nationalSignificant international
np	STRING	Stands for Numbering Plan. Possible values: unknown isdn generic data telex maritimeMobile landMobile isdnMobile
netind	STRING	Stands for Network Indicator. Possible values: national international
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 8-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

Specifying the Identity of a Mobile Subscriber

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;

SIP NOTIFY Message Body Formats

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.

Specifying Supported SIP NOTIFY Message Body Formats

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.

Setting the Expires Header

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.

Handling SIP Errors

Service Broker can return all standard SIP errors. Table 8-2 provides additional interpretation of some standard SIP errors specifically for Presence and Subscriber eXtensions applications.

Table 8-2 SIP Errors

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: The application sets the Event header with an unsupported value The application does not set the Event header at all The application sets the requested-info token with an unsupported value.
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.

Obtaining Subscriber's State and 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.

Generating a SIP SUBSCRIBE Message

The following SIP headers must be set in the SIP SUBSCRIBE message:

Common SIP Headers

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"

Event Header

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.

Processing a SIP NOTIFY Request

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.

Subscription-State Header

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 8-3 lists the possible values of the reason token:

Table 8-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.

Content-Type Header

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.

SIP Message Body

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 XERor BERformat. For more information, see "Other Subscriber Information".

Subscriber's State

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 8-4 explains the PIDF elements and attributes.

Table 8-4 PIDF Elements

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: Open Close
<ts:state>	Extension element that specifies the subscriber's state. Possible values: Reachable Unreachable Busy Unknown The value of <ts:state> correlates with the value of <basic> as follows: When <basic> contains "Open", <ts:state> contains "Reachable". When <basic> contains "Close", <ts:state> may contain "Unreachable", "Busy", or "Unknown".
<timestamp>	Specifies the date and time when the presence information was created.

Other Subscriber Information

Subscriber's location and other information is provided in the XER or BERformat. In this case, the SIP NOTIFY message body contains the full MAP operation result structure.

Obtaining Mobile Subscriber's Subscription Information

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:

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".

Generating a SIP SUBSCRIBE Message

The following SIP headers must be set in the SIP SUBSCRIBE message:

Common SIP Headers

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"

Event Header

SIP applications must set the Event header to 'SubQuery'.

Content-Type Header

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"

Processing the SIP NOTIFY Message

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.

Subscription-State Header

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 8-5 lists the possible reason token values:

Table 8-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 XERor 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.

Modifying Mobile Subscriber's Information

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 Broker to modify subscription information using the SIP SUBSCRIBE message. Service Broker 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 Broker in order to modify subscriber's data, and then process the SIP NOTIFY message which Service Broker sends back to the SIP application.

Generating a SIP Subscribe Message

The following sections describe the SIP headers that must be set in the SIP SUBSCRIBE message.

Common SIP Headers

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".

Event Header

The SIP application must set the Event header to 'SubUpdate'.

Content-Type 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'.

Processing a SIP Notify Message

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 Broker.

Subscription-State Header

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 8-6.

Table 8-6 Possible Values of the Reason Token

Token Value	Description
addressresolutionfailure	Service Broker 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 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.

Content-Type Header

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