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 JavaScript Object Notation (JSON) data format and the Session Initiation Protocol (SIP) protocol.
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 IP Multimedia Subsystem (IMS) core. The sections that follow explain information you need to know to set up this communication.
See the 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.
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.
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.
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
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.
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
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.
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.
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.
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.
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() }
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.
The Script Library tab is a repository of validated Groovy scripting code that you can reference in any of your packages.
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 Short Message Service (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.
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. The TemplateContext interface of the oracle.wsc.feature.webrtc.template package in the WebRTC Session Controller JSONRTC protocol is called 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.
This section describes the integration parameters associated with the Signaling Engine that are configured through the WebRTC Session. Table 2-2 shows the system integration parameters that you can access from your Groovy scripts.
Table 2-2 Accessing Integration and Package Filter Parameters
Parameter | Description |
---|---|
Proxy Registrar URI |
Enter a SIP proxy server/Registrar URI. The value you enter in this field becomes the default SIP proxy server/Registrar URI for any new application you create. Access this parameter in Groovy as context.properties.proxyRegistrar using SipContext, AuthenticationContext, TemplateContext, or WebContext. |
Dynamic Media Anchoring Type |
Select a media anchoring option supported by WebRTC Session Controller. The possible selections are:
The supported Media Engine session type, is assigned to the Groovy constant ME_CONFIG_NAME_DMA, in the Groovy library |
Media Engine MSRP |
Select a message Session Relay Protocol (MSRP) to Media Engine from Signaling Engine. The possible selections are:
Access this parameter in Groovy as context.properties.webMSRP using SipContext, AuthenticationContext, TemplateContext, or WebContext. |
Signaling Engine MSRP |
Select an MSRP to Signaling Engine from Media Engine.
Access this parameter in Groovy as context.properties.netMSRP using SipContext, AuthenticationContext, TemplateContext, or WebContext. |
File Transfer |
Enter a pattern for resolving file_transfer packages by SDP. The default pattern is:
Access this parameter in Groovy as context.properties.fileTransferPattern using SipContext, AuthenticationContext, TemplateContext, or WebContext |
MSRP |
Enter a pattern for resolving MSRP packages by the Session Description Protocol (SDP). The default pattern is:
MSRP signaling is carried in SIP INVITE requests. When WebRTC Session Controller receives a SIP INVITE, it determines whether the request should be processed as a call, msrp chat or msrp file transfer. To do so, it looks at these regex expressions. Access this parameter in Groovy as context.properties.msrpPattern using SipContext, AuthenticationContext, TemplateContext, or WebContext. |
For a description about configuring these parameters through the Administration console, see "Global Integration Parameters of the Signaling Engine" in WebRTC Session Controller System Administrator's Guide.
You can access the parameters listed in through a number of contexts. In the access strings, the context entry can be SipContext, AuthenticationContext, TemplateContext, or WebContext interface. The code sample in Example 2-1 accesses a SIP package using the SipContext Interface.
Example 2-1 Accessing SipContext Interface of the SIP Package
@groovy.transform.CompileStatic Map<String, Object> resolveProcessingParameters(final SipContext sipContext) { final WscSipMessage sipMessage = sipContext.wscSipMessage final def proxy = sipContext.properties.proxyRegistrar return [ package_type : resolvePackageType(sipMessage), network_service : resolveNetworkService(sipMessage) }
For a description about these WSC API interfaces, see WebRTC Session Controller Configuration API Reference.
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.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-3 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-3 Java and Groovy Actions on the Normalized Format
Translation Action | Groovy Code |
---|---|
Get the age |
|
Get the first name |
|
Get the list of messages |
|
Get message 2 from the list |
|
Modify the last name |
|
Add a middle name |
|