2 About Building JSON to SIP Communication

This chapter explains how you use WebRTC Session Controller Signaling Engine (Signaling Engine) to build up and tear down calls, and translate them between the JSON data format and the SIP protocol.

About Building JSON to SIP Communication

Figure 2-1 shows the sessions and subsessions used in making a simple JSON to SIP call flow. Client applications first set up JSON sessions that include WebSocket connections to start communicating with Signaling Engine. Signaling Engine then starts subsessions to communicate with the client application, and SIP sessions to communicate with your IMS core. The sections that follow explain information you need to know to set up this communication.

Figure 2-1 Signaling Engine Call Flow Overview

Surrounding text describes Figure 2-1 .

Securing Signaling Engine Connections

See the Oracle Communications WebRTC Session Controller Security Guide for information on securing:

  • Signaling Engine-SIP connections.

  • Client application to Signaling Engine connections.

  • Internal Signaling Engine internal components and processes.

  • WebRTC to SIP connections.

About Connecting to a Client Application

Signaling Engine uses the JSONRTC protocol to communicate between client applications and the WebRTC Session Controller console. Signaling Engine establishes communication using an HTTP/HTTPS handshake message using a value of webrtc.oracle.com for Sec-WebSocket-Protocol.

See "JSONRTC Protocol Reference" and WebRTC Session Controller Application Developer's Guide for details on this protocol and how to use it to develop client applications.

About Sessions and Subsessions

Figure 2-1 shows an overview of how Signaling Engine handles JSON sessions, WebSockets, and subsessions, and how they relate to SIP sessions. First, Signaling Engine opens a protocol session using the WebRTC Session Controller Configuration API, and within that session Signaling Engine then opens a WebSocket connection. Inside the WebSocket connection, Signaling Engine uses the JSONRTC protocol to open a subsession to pass messages between the browser and the Signaling Engine. Finally Signaling Engine opens a SIP session to communicate with your IMS core.

There is one WebSocket connection for one WSCSession/WebRTC JSON session. However if a network problem interrupts the WebRTC session, the WebSocket connection can be reestablished with session information (rehydrated) if the problem is fixed before the connection timeout limit is reached. If the time limit is reached, the WebRTC session exits. See WebRTC Session Controller System Administrator's Guide for details.

Each subsession is associated with a WebRTC Session Controller package, which defines the allowable actions for the WebSocket and its subsessions. A subsession is the scope in which a particular package operates. There are generally several subsessions in a session.

Each subsession is responsible for maintaining the media session between the client application and the peer (media server, SIP phone, web client, and so on). When call is torn down, the media stream and the subsession are closed.

Usually each Signaling Engine subsession has one corresponding SIP session. However, a SIP session may not always required. If for example, a SubSession that just sends a SIP MESSAGE outside of a dialog would not create a media session or require a SIP session.

If a WebSocket is disconnected unexpectedly, Signaling Engine can start a new one to continue using the existing subsessions. This enables you to continue sessions if a WebSocket connection is unexpectedly terminated by a network failure, HTML refresh, or other service interruption.

A session has several states from INITIAL to TERMINATED. When the client sets up the WebSocket session with the server, the session is in an ESTABLISHED state. When the session is closed, it is in a TERMINATED state.

About JSON to SIP Communication

Figure 2-2 shows the JSON and SIP message flow for a call originating from the client application and how the messages relate to JSON sessions, WebSocket connections, subsessions, and SIP sessions.

Figure 2-2 Default WebRTC Session Controller FROM_APP Call Flow Detail

Description of Figure 2-2 follows
Description of "Figure 2-2 Default WebRTC Session Controller FROM_APP Call Flow Detail"

The client application initiates communication with Signaling Engine by sending a wsc.session object (not shown), which includes the handshake and connect message.

The call shown in Figure 2-2 originates from a client application (WebRTC-enabled browser) using the RFC WebSocket protocol. In this case Signaling Engine translates the JSON data into SIP protocol messages for the SIP server to respond do. The call recipient (not shown) may be a SIP device served by the SIP server itself, or another WebRTC browser using another Signaling Engine implementation.

As Figure 2-2 shows, Signaling Engine translates the JSON messages to SIP and passes them to the SIP server, and translates the SIP messages to JSON and passes them back to the client. Signaling Engine groups the Groovy-based translation code segments into applications, packages, and criteria. Each application represents all JSON to SIP communication for a collection of related Signaling Engine features. Each of the features is composed of a package, which is a collection of individual criteria that each perform a single translation action. These criteria contain the individual Groovy scripts that perform each action.

See "About SIP to Client Communication" for a description of how Signaling Engine processes messages that originate in your IMS core.

About SIP to Client Communication

This section explains how Signaling Engine processes messages what originate from your IMS core. For example, if a subscriber using a SIP phone attempts to communicate with a Signaling Engine client application. The call could originate from any SIP device or another Signaling Engine implementation. From the Signaling Engine perspective, these calls originate from a SIP server.

Figure 2-3 shows a sample call flow initiated by a SIP phone and how Signaling Engine translates the SIP messages from the phone's SIP server to the JSON data format that the client application can use for communication.

Figure 2-3 Default Signaling Engine FROM_NET Call Flow Detail

Description of Figure 2-3 follows
Description of "Figure 2-3 Default Signaling Engine FROM_NET Call Flow Detail"

About Storing Data Within Sessions

As you are building up and tearing down calls, you will probably need to store data within Signaling Engine for different messages to use, such as customer subscriber data. Signaling Engine provides an attribute store to hold data that you use within sessions. You use the getSessionStore() class in the oracle.wsc.feature.webrtc.template package (TemplateContext interface) to retrieve data from the attribute store. The attribute store is created when a WebSocket session or SIP session is created within Signaling Engine, and is persistent until that session is torn down.

Understanding the WebRTC Session Controller Components

Using the WebRTC Session Controller console, you equate one WebRTC-enabled client application to a WebRTC Session Controller application. Each Signaling Engine application in turn, is a collection of WebRTC Session Controller packages that each roughly equate to a single real time WebRTC feature. Each package contains any number of Groovy scripts, called criteria, that each perform a single translation function on a single type of call message. The sections below provide more detail on applications, packages, and criteria.

About Applications

A WebRTC Session Controller application represents a single client application or service that sends messages between a browser and a SIP server through WebRTC Session Controller. Each application must have at least two packages, one for translating from the SIP server to the application and one for translating from the application to the SIP server. Each application has:

  • An informal name.

  • An active/inactive setting.

  • An informal description.

  • References to the WebRTC Session Controller packages that contain the Groovy scripts that performs message processing and translation.

  • A Request URI that the application uses to communicate with a SIP server or proxy.

  • The WebLogic security group. The security groups is required, and the Weblogic Server contains some default security groups that you can use. For details on using security groups, see the discussion on users, groups, and security roles in Oracle Fusion Middleware Securing Resources and Policies for Oracle Weblogic Server.

  • A list of Allowed Domains that serve as a white list of domains the application is allowed to contact.

  • Resource limits that allow you to protect system performance by limiting an application's impact on Signaling Engine. These resource limits can also serve as application white- and black-lists for individual applications.

See "About Packages" for details on the packages that comprise an application.

About Packages

A package defines a service provided by the JSONRTC protocol. It consists of a group of messages such as requests and responses that are sent between the client and the server. Table 2-1 lists the packages that are available through the WebRTC Session Controller console on the Packages tab.

Table 2-1 WebRTC Session Controller Packages

Package Description

call

Provides the ability to start a voice or video call, upgrade from a voice to a video call, establish a DataChannel.

capability

Provides exchange capability such as file transfer or video sharing.

chat

Provides one-to-one and group chat service.

file_transfer

Provides the ability to transmit files, share images, and so on.

message_notification

Provides the ability to notify the client of information such as pending voice mails, fax messages, and so on.

messaging

Provides a standalone message capability.

register

Registers a SIP session request.

Each WebRTC Session Controller package contains a group of criteria that contain the Groovy scripts to translate a logical group of messages from JSON to SIP or SIP to JSON. For example, Signaling Engine provides an example call package that includes all of the JSON (FROM_APP) and SIP (FROM_NET) criteria to build up and tear down a JSON to SIP call, including:

  • JSON start messages (request, response, and error)

  • JSON complete message

  • JSON prack message

  • JSON shutdown message

  • SIP INVITE messages (request and response)

  • SIP CANCEL message

  • SIP ACK messages (request and response)

  • SIP UPDATE messages (request and response)

  • SIP PRACK message

  • SIP BYE messages (request and response)

A package generally contains criteria for a single client application. Each package can be used by any number of Signaling Engine applications.

See the WebRTC Session Controller console to inspect the default packages provided, and "About Criteria" for details about the criteria that comprise a package.

About Criteria

Each WebRTC Session Controller criteria matches one kind of JSON or SIP message and runs the code in a Groovy script against it. For example, one criteria translates an INVITE request message from SIP to JSON, and another translates the response back from JSON to your SIP format.

Each criteria uses this information to identify the messages it translates:

  • A FROM_APP or FROM_NET direction that specifies whether the message originated in a WebRTC-enabled browser, or your SIP IMS core.

  • A verb matching the type of JSON or SIP request or response. For example, an UPDATE verb matches SIP UPDATE requests and response messages, and a complete verb matches a JSON complete request or response message.

  • A type of message for the criteria to match. For example request or response. See "JSONRTC Protocol Reference" for the list of supported type values.

  • A Network Service name. Each default criteria uses a Script Library call to return the network service of the call. A default network service name is the default.

See "About the Groovy Scripts" for details on the Groovy scripts.

By default, WebRTC Session Controller contains useful criteria that you can use to build and tear down calls, and use as stubs to add functionality that your implementation requires. You can use these default criteria as provided but you will probably modify them to fit your implementation's needs.

This is the default FROM_NET/INVITE/request/default criteria Groovy script:

def sipRequest = context.originatingSipMessage
def webMessage = context.webFactory.createWebRequest("start")
webMessage.header = [
  initiator : sipAddressToString(sipRequest.from),
  target    : sipAddressToString(sipRequest.to)
]
// SDP
if (sipRequest.sdp) {
  webMessage.payload = [sdp : sipRequest.sdp]
}
def sdpString = sipRequest.sdp

if(context.mediaFactory.isAvailable() && sdpString!=null) {
  def sdpOffer = context.mediaFactory.createSdpOffer("1", sdpString,
Constants.ME_CONFIG_NAME, null, sipAddressToString(sipRequest.to),
sipAddressToString(sipRequest.from));
  def ascFuture = sdpOffer.send()
  context.getTaskBuilder("processMediaResponseToSendWebMsg").withArg("ascFuture",
ascFuture).withArg("webMessage",webMessage).onSuccess(ascFuture).build();
}
else{
  webMessage.send()
}

About the WebRTC Session Controller Console

You use the WebRTC Session Controller console to create, organize, use, and extend the applications, packages, and criteria for your implementation.

At the highest level, you use the Applications tab to create and manage applications, that roughly equate to a single web client application. See "Creating Applications" for details on creating applications.

Figure 2-4 shows the WebRTC Session Controller console with the Packages tab exposed. Each package is listed with its direction, verb, type, and network service. The Groovy script used in each criteria is shown on the bottom right of the pane. You enter or change the Groovy script for each package in this pane. You can also reference any existing Groovy code stored in the Script Library tab. See "Creating Packages" for details on creating packages for your applications.

Figure 2-4 WebRTC Session Controller Console Packages Tab

Surrounding text describes Figure 2-4 .

The Script Library tab is a repository of validated Groovy scripting code that you can reference in any of your packages.

About the Groovy Scripts

Groovy is a scripting languages based on, and very similar to the Java programming language. Each Signaling Engine package contains its own individual Groovy scripts that translate messages matching its criteria specifications. The translation is either from WebRTC Session Controller's normalized format to SIP, or SIP to the normalized format depending on the direction you set. Packages require that you set up one criteria for translating in one direction, and a corresponding criteria for translating messages in the other direction. Signaling Engine then translates the normalized format to a format that your browser/application uses and back again.

Most packages use synchronous communication, so most criteria are created in pairs; one that translates messages from the client application (JSON) to SIP, and the other to translate from SIP to JSON. However the traffic can be asynchronous, as with SMS messages for example.

Figure 2-5 shows how criteria use Signaling Engine components to translate messages. The register package shown contains two criteria, one for FROM_NET messages and the other for FROM_APP messages.

Figure 2-5 Signaling Engine Criteria Components

Surrounding text describes Figure 2-5 .

Every criteria uses this Java signature:

void method (TemplateContext context) { Groovy script }

At run time, Signaling Engine converts the criteria identifying information (FROM_APP or FROM_NET, the verb, message type, and network service) to a method name. However, you only encounter this method name while debugging criteria operations.

The signature calls the TemplateContext interface of the oracle.wsc.feature.webrtc.template package in the WebRTC Session Controller JSONRTC protocol to act on the Groovy script. This interface includes all of the other JSONRTC protocol interfaces that specify the specific Java methods that you can use to get information from or set information to a message.

See WebRTC Session Controller Configuration API Reference for details on this API.

Finally every criteria contains a Groovy script that acts on the information obtained from the context. It is in these scripts that you add any new functionality or redirection instructions that change the behavior or destination of the message. In addition to simple translation, you can add any other processing that your implementation requires to each message. For example, you could:

  • Map JSON information to SIP fields so that your SIP server accepts it.

  • Map SIP header information to a form that your web application can use.

  • Route the message to a specific URL based on its JSON information.

  • Route the message to a specific URL based on its SIP information.

  • Incorporate features such as redirecting a message to a different URL for example, to prevent bill shock.

See WebRTC Session Controller Configuration API Reference for details on the packages and methods of the API.

About the Script Library

The Groovy scripts you create for a package will probably use some functionality provided in the script library. The script library contains a set of useful methods that you can add to as required by your implementation. To use one of these methods, select the Script Library tab, click Edit, make your changes, then click Save. Example methods in the Script Library include code to:

  • Return a user address based on the characteristics of a SIP string.

  • Set the SIP routing URI.

  • Set the SIP message contact parameter.

  • Copy SDP data to a SIP header.

The Groovy code that you create in a package's criteria is appended to the code in the script library at run time. So you can reuse any of the library code in the scripts that you create for each individual package. You can also add more code to the library as needed, and use it in other individual packages.

After changing the code in either a package or the library, you need to validate it to ensure that it compiles correctly. You use the Validate button on the Package and Script Library tabs to validate individual package scripts or the script library.

Note:

WebRTC Session Controller does not support global variables in the Groovy script library.

About the Normalized Data Format

As pictured in Figure 1-1 Signaling Engine converts messages into a normalized data format in the process of translating them between SIP and JSON. All messages are converted to the normalized format, regardless of whether they originated in a WebRTC client application, or from your IMS core.

The syntax for the normalized format is straightforward:

Map<String, Object>

For example, this JSON data format message:

{
"age":25,
"name":{
"first":"joe",
"last":"smith"
},
"messages":["msg 1","msg 2","msg 3"]
}

Is translated to this normalized message format, which is a hash map representation of the message:

{"age"=25,
{"name"={"first"="joe","last"="smith"}},
{"messages"=["msg1","msg2","msg3"]}}

Notice that the messages array is a nested hash map of its own.

Table 2-2 lists a variety of actions that you might perform while creating a Groovy translation script and the Groovy code that performs the action.

Table 2-2 Java and Groovy Actions on the Normalized Format

Translation Action Groovy Code

Get the age

def age = map.age

Get the first name

def firstName = map.name.first

Get the list of messages

def messages = map.messages

Get message 2 from the list

def message2 = messages[1]

Modify the last name

map.name.last = "doe"

Add a middle name

map.name.middle = "bob"