9 Sample Applications

This chapter describes the sample applications provided with Oracle Communications Service Broker.

About Sample Applications

To help you develop your own applications on top of Service Broker, Service Broker is provided with a set of sample applications. Table 9-1 describes these applications.

Table 9-1 Service Broker Sample Applications

Application	Description
Local Number Portability (LNP)	Plays an announcement to a calling party and redirects the call to a specified number. See "Local Number Portability Application" for more information.
Ring Back Tone (RBT)	Plays an announcement to the calling party until the called party answers the call. See "Ringback Tone Application" for more information.
Screening	Screens calls based on the calling party number and called party number. See "Screening Application" for more information.
Location Service	Receives a SIP Subscribe message with a NoteMM event in the body, logs the contents of the event, and responds with a SIP Notify message. See "Location Service Application" for more information.
Presence	Receives a request from a SOAP client about location and state of the mobile subscriber, retrieves the requested information from an HLR, and responds with this information to the SOAP client. See "Presence Application" for more information.

The sample applications are provided as a Java source code. You need to compile and deploy them on an OCCAS 5.0.

Note:

The sample applications are provided for educational purposes only. The applications include a minimum functionality and are not intended for usage in a production environment out-of-the-box. For example, the applications do not provide database connectivity, configuration, monitoring, and management capabilities that are required in a production environment.

Sample Application Files

The applications are stored in ocsb61/samples.zip. After you unzip the applications, each application is stored in its own folder. All application folders have a unified structure. Figure 9-1 shows the folder structure of an application folder.

Figure 9-1 Structure of an Application Folder

Table 9-2 describes these folders and files.

Table 9-2 Contents of an Application Folder

Folder or File	Description
/src	This folder contains the Java source code of the application.
/WEB-INF/sip.xml	The SIP Servlet-defined configuration files for the SIP application. For more information about SIP servlets, see the discussion about SIP servlet application development in Oracle Communications Converged Application Server SIP Application Development Guide.
/WEB-INF/web.xml	The Java EE standard configuration file for the Web application.
/build.xml	This file defines parameters for building a WAR file from the sources. For more information on the parameters you can define in build.xml, see the discussion about developing SIP servlets using Eclipse in Oracle Communications Converged Application Server SIP Application Development Guide.

Deploying Sample Applications

You need to deploy sample applications on an OCCAS application server.

1. Open the build.xml file for the application that you want to deploy.

2. Determine the libraries that you need to add to CLASSPATH in the OCCAS server.

3. In the OCCAS server, add the libraries specified in build.xml to CLASSPATH.

   All the libraries are located under OCCAS installation

4. Edit sip.xml of the application to configure the application as required.

5. Do one of the following:

   • If ant is defined in the environment, run the following command:

     ant build
     

   • If ant is not defined in the environment, under OCCAS installation, run the following commands:

     cd /home/pdadmin/Oracle/Middleware/user_projects/domains/base_domain/bin
     source setDomainEnv.sh
     
     ant build
     

     This creates a WAR file in the same directory where build.xml is located.

6. Move the WAR file to the /applications subdirectory of your development domain. OCCAS automatically deploys the applications located in this subdirectory. For more information on deploying SIP applications, see the discussion on developing SIP servlets using eclipse in Oracle Communications Converged Application Server SIP Application Development Guide.

Configuring Sample Applications

Configuration settings of an application are stored in sip.xml. This file contains both general settings that you need to define for any SIP applications and application-specific parameters.

OCCAS SIP Application Development Guide provides a detailed information on the general configuration parameters that you can define in sip.xml. Table 9-3 explains specific sections within OCCAS SIP Application Development Guide where you can learn more about these parameters. Application-specific parameters are explained in this chapter in the respective sections.

Table 9-3 General Settings Defined in sip.xml

Settings	Where to Learn More
Servlet mapping	See the overview of SIP servlet application development.
Deploying a SIP application to a cluster environment	See the discussion about marking SIP Servlets as Distributable, in the best practicies chapter.
Ensuring security of a SIP servlet	See the chapter about securing SIP servlet resources.

Local Number Portability Application

The Local Number Portability (LNP) application receives a call and then performs one of the following:

• Redirects the call to another number and plays an announcement to the calling party if a new phone number is defined in the application's configuration.

• Forwards the call to the number originally specified by the called party if a new phone number is not defined in the application's configuration.

Application Call Flow

Service Broker invokes the Local Number Portability (LNP) application when Service Broker receives a call.

The call flow works as follows:

1. Service Broker sends a SIP INVITE to the application.

2. The application retrieves the called party number from the RequestURI.

3. The application checks whether the called party number is specified in the phone translation table. This table contains an original number-new number pairs. The phone conversion table is defined in sip.xml.

4. One of the following happens:

   • If there is no number that should replace the original called party number, the application responds to Service Broker with a SIP 302 Moved Temporarily. The application copies the called party number from the RequestURI of the SIP INVITE to the Contact header of the SIP 302 Moved Temporarily.

   • If there is a number that should replace the original called party number, the application requests Service Broker to play an announcement to the calling party and responds to Service Broker with a SIP 302 Moved Temporarily. The application sets the Contact header of this message to the new called party number.

     If an error occurs while playing the announcement, the application responds to Service Broker with a SIP 302 Moved Temporarily with the Contact set to a new called party number.

Modes of Playing an Announcement

Table 9-4 explains the modes that the LNP application can use to request Service Broker to play an announcement. You set the mode that the LNP application should use by setting the is-sync parameter in sip.xml.

Table 9-4 Modes of Playing an Announcement

Mode	Description	To Enable...
Asynchronous	Service Broker plays an asynchronous announcement on the calling leg. Only then the applications sends a SIP 302 Moved Temporarily on this leg. The application does not need to wait for the end of the announcement. After the application received a SIP 302 Moved Temporarily on the announcement request, the application can immediately redirect the calling leg to the new called phone number.	Set is-sync to false.
Synchronous	After the connection with the SRF is established, the application provides Service Broker with announcement information in the MSCML format in a SIP INFO.	Set is-sync to true.

Playing an Announcement Using the Asynchronous Mode

Figure 9-2 shows the call flow when the new number is specified in the phone translation table.

Figure 9-2 Updating the Called Party Number

Figure 9-3 shows the call flow when the new number is not specified in the translation table.

Figure 9-3 Leaving the Original Called Party Number Unmodified

Playing an Announcement Using the Synchronous Mode

Figure 9-4 shows a call flow where the application uses an MSCML request to request Service Broker to play an announcement.

Figure 9-4 Changing the Called Party Number and Requesting Service Broker to Play an Announcement Using MSCML

Setting Up the Phone Translation Table

The phone translation table is defined in sip.xml in the following form:

old number-new number

If you want to define multiple pairs, separate them with a semicolon (;). For example:

<javaee:param-name>phone-translation-table</javaee:param-name>
<javaee:param-value>00000002-[phone];0541234567-0521234567;0539724589-0539874279;0547777777-0548888888</javaee:param-value>

Specifying the Announcement to Be Played

You need to specify the announcement that OCSB plays before the call is redirected in sip.xml. You need to specify the following parameters:

• MRF alias:

  <javaee:init-param>
     <javaee:param-name>mrf-alias</javaee:param-name>
     <javaee:param-value>sip:mrf.1@domain</javaee:param-value>
  </javaee:init-param>
  

• Announcement URL:

  <javaee:init-param>
     <javaee:param-name>announcement-url</javaee:param-name>
     <javaee:param-value>http://index1</javaee:param-value>
  </javaee:init-param>
  

Ensure that the MRF alias and the announcement URL are set to the same values in the IM-SCF configuration. For more information on specifying the MRF alias and announcement URL, see the discussion on configuring announcements for IM-SCF in Oracle Communications Service Broker Modules Configuration Guide.

Ringback Tone Application

The Ringback Tone (RBT) application plays an announcement to the calling party until the called party answers the call.

The application requires IM-ASF and IM-SCF CAP 4 to be configured in Service Broker. For more information, see Oracle Communications Service Broker Modules Configuration Guide.

Application Call Flow

The call flow works as follows:

1. Service Broker receives a call from the MSC.

2. Service Broker sends a SIP INVITE to the RBT application.

3. The RBT application responds to Service Broker with a SIP INVITE. The SIP INVITE contains an SDP body in which c=0.0.0.0. This SIP INVITE is intended for the called party.

4. When Service Broker receives a ringing event from the called party, Service Broker sends a SIP 180 Ringing to the RBT application.

5. The RBT application sends a SIP INVITE to Service Broker for the entity that plays the announcement.

6. When the announcement entity answers the call, and Service Broker receives the answer event, Service Broker responds to the RBT application with a SIP 200 OK.

7. The RBT application sends a SIP 183 Session In Progress to Service Broker. This connects the called party to the announcement.

8. Service Broker plays the announcement to the calling party.

9. When the called party answers the call, the application disconnects the announcement leg and sends the messages as follows:

   • SIP Re-INVITE to the both called party

   • SIP 200 OK to the calling party with the updated SDP.

   This connects the calling party to the called party.

Figure 9-5 and Figure 9-6 (continued) show a call flow for the RBT application.

Figure 9-5 RBT Application Call Flow

Figure 9-6 RBT Application Call Flow (cont'd)

Specifying the MRF URI for Playing an Announcement

You specify the URI of the MRF that should play an announcement to the calling party in sip.xml. For example:

<javaee:init-param>
   <javaee:param-name>mrf-uri</javaee:param-name>
   <javaee:param-value>sip:1234567890@10.162.34.115:5091</javaee:param-value>
</javaee:init-param>

Ensure that the MRF URI is set to the same value in the IM-SCF configuration. For more information on specifying the MRF alias and announcement URL, see the discussion on configuring announcements for IM-SCF in Oracle Communications Service Broker Modules Configuration Guide.

Screening Application

The Screening application checks whether a pair of the calling party number and called party number is defined in the screening table in sip.xml. If the application finds this pair, the Screening application allows the call to continue. Otherwise, the application releases the call.

The Screening application requires IM-ASF and IM-SCF CAP to be configured in Service Broker. For more information, see Oracle Communications Service Broker Modules Configuration Guide.

Application Call Flow

The call flow works as follows:

1. Service Broker receives a call from the MSC.

2. Service Broker sends a SIP INVITE to the application.

3. The Screening application retrieves the called party number and calling party number from the SIP INVITE as follows:

   • The application retrieves the called party number from the RequestURI header.

   • The application retrieves the calling party number from the PAssertedIdentity header, if exists. Otherwise, the application retrieves this number from the From header.

4. The Screening application checks whether the screening table in sip.xml contains the retrieved calling party number and called party number pair.

5. One of the following happens:

   • If the application does not find the pair of the calling number and called number, then the application sends to Service Broker a SIP 400 Bad Request message. This triggers Service Broker to release the call.

   • If the application finds the pair of the calling number and called number, then the application sends to Service Broker a SIP 302 Moved Temporarily message. In this message, the application set the Contact header to the value that was set in the original RequestURI.

Figure 9-7 shows a call flow when the Screening application finds the calling party number and called party number in the screening table and allows the call to continue.

Figure 9-7 Calling Party and Called Party Numbers Found in the Screening Table

Figure 9-8 shows a call flow when the Screening application does not find the calling party number and called party number in the screening table and releases the call.

Figure 9-8 Calling Party and Called Party Numbers Are Not Found in the Screening Table

Specifying Calling Party Number and Called Party Number

The pairs of calling party numbers and called party numbers are defined in the screening table in sip.xml. The screening table contains numbers in the following format:

calling number-called number

The screening table can contain multiple pairs of calling and called numbers. The pairs pairs are separated with a semicolon (;).

Java regular expressions can be used for calling and called numbers.

The following example shows how you can define a screening table:

<javaee:init-param>
    <javaee:param-name>screening-table</javaee:param-name>
    <javaee:param-value>0541234567-0521234567;053.*-054.*</javaee:param-value>
 </javaee:init-param>

Location Service Application

The Location Service application retrieves location information about a mobile subscriber from the SIP Subscribe message received from Service Broker.

The Location Service application requires IM-PSX Plugin and IM-ASF to be configured in Service Broker. For more information, see Oracle Communications Service Broker Modules Configuration Guide.

Application Call Flow

The call flow works as follows:

1. The VLR sends to Service Broker a Note-MM-Event.

2. Service Broker puts the BER encoded Note-MM-Event into the body of a SIP Subscribe and sends the SIP Subscribe to the Location Service application.

3. The application checks whether the SIP Subscribe contains a Note-MM-Event by checking the value of the <operationCode> element in the body of the SIP Subscribe.

4. One of the following happens:

   • If the SIP Subscribe contains a Note-MM-Event (the <operationCode> contains 89), then the application responds to Service Broker with a terminating SIP Notify whose x-wcs-tcap-termination-reason header is set to end. The body of the SIP Notify contains a return result. Then Service Broker sends a NoteMM-Event-Res to the VLR.

   • If the SIP Subscribe does not contain a Note-MM-Event (the <operationCode> contains another value), then the application responds to Service Broker with a terminating SIP Notify whose x-wcs-tcap-termination-reason header is set to abort. Then Service Broker sends an Abort message to the VLR.

Figure 9-9 shows a call flow when the Location Service application finds a NoteMM-Event in the SIP Subscribe.

Figure 9-9 EventMM-Event Found in the SIP Subscribe

Figure 9-10 shows a call flow when the Location Service application does not find a NoteMM-Event in the SIP Subscribe.

Figure 9-10 EventMM-Event Not Found in the SIP Subscribe

Presence Application

The Presence application receives a request from a SOAP client about location and state of the mobile subscriber, retrieves the requested information from an HLR, and responds with this information to the SOAP client. A SOAP client might be, for example, a Web application that allows the user to enter a mobile phone number and receive information about the location and state of the mobile subscriber.

The application requires IM-ASF and IM-PSX MAP3 to be configured in Service Broker.

Application Call Flow

The call flow works as follows:

1. A SOAP client sends a request to the application. The request contains the mobile phone number whose location and state the Presence application should retrieve from the HLR. See "SOAP Requests and Responses" for more information about the structure of a SOAP request.

2. The application retrieves the mobile phone number from the received request. The application generates a SIP Subscribe which contains the retrieved mobile phone number and sends the SIP Subscribe to Service Broker.

3. Service Broker translates the SIP Subscribe to a MAP AnyTimeInterrogation and sends it to the HLR.

4. Then Service Broker sends a SIP 202 Accepted to confirm that the SIP Subscribe was received. If IM-PSX is configured to generate a SIP Notify with the Subscription-State set to pending, then Service Broker sends this SIP Notify to the application. The application responds with a SIP 200 OK.

5. The HLR responds to Service Broker with a MAP AnyTimeInterrogationResult.

6. Service Broker translates the MAP AnyTimeInterrogationResult to a SIP Notify and sends it to the application.

7. The application retrieves the state and location from the SIP Notify.

8. The application sends a response with the information about the state and location of the mobile subscriber to the SOAP client. See "SOAP Requests and Responses" for more information about the structure of a SOAP response.

Figure 9-11 shows a call flow for the Presence application.

Figure 9-11 Call Flow for the Presence Application

SOAP Requests and Responses

A SOAP request has the following format:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sam="http://samplews.ws.examples.oracle/">
   <soapenv:Header/>
   <soapenv:Body>
      <sam:getLocation>
         <arg0>phone_number</arg0>
      </sam:getLocation>
   </soapenv:Body>
</soapenv:Envelope>

A SOAP response has the following format:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sam="http://samplews.ws.examples.oracle/">
   <soapenv:Header/>
   <soapenv:Body>
      <sam:callbackMessage>
         <arg0>[state]</arg0>
         <arg1>[location information]</arg1>
      </sam:callbackMessage>
   </soapenv:Body>
</soapenv:Envelope>

Setting Up the Presence Application to Communicate with Service Broker

Table 9-5 describes the parameters that you need to configure to allow the Presence application to communicate with Service Broker. The configuration parameters are defined in sip.xml.

Table 9-5 Presence Application Configuration Parameters

Parameter	Description
ocsb-address	The address of Service Broker. The application uses this address when routing the SIP Subscribe messages to Service Broker. Default: sip:127.0.0.1:7060
presence-application-address	The address of the Presence application. Default: sip:127.0.0.1:5060
psx-sip-domain	The SIP domain of the Presence application. The domain must be the same as the PSX SIP domain configured in the IM-PSX configuration in Service Broker.