This chapter explains how to create the applications, packages, and criteria that WebRTC Session Controller Signaling Engine (Signaling Engine) uses to establish and modify communication between your client applications and IMS core.
You use the WebRTC Session Controller console GUI to create and manage the applications, packages, and criteria that Signaling Controller uses to translate and modify messages between client applications and your IMS core.
This procedure requires a running WebLogic server, and that you know the WebLogic username and password that you created for the domain. See the discussion on getting started in WebRTC Session Controller System Administrator's Guide for instructions on creating and starting a WebLogic domain.
To start the WebRTC Session Controller console:
Start the WebRTC Session Controller domain server.
Open a web browser.
Access this URL:
http://localhost:port/wsc-console
or this command if HTTP security is configured:
https://localhost:port/wsc-console
Where:
localhost is the IP address of the system running the WebLogic domain or the value localhost.
port is the port of the domain. The default port is 7001.
This command starts the WebRTC Session Controller console on a local system using the default port:
http://localhost:7001/wsc-console
The WebLogic user login screen appears. Enter the username and password you set when creating the WebLogic domain.
The WebRTC Session Controller console window appears.
The item marked weblogic in this screen capture is the username of the user or group logged into the WebRTC Session Controller console. In this case it shows the default user, Weblogic.
The Accessibility item brings up the WebRTC Session Controller console accessibility tools. For details see the discussion on starting the WebRTC Session Controller console in the WebRTC Session Controller Installation Guide.
The Logout item logs the current user out of the WebRTC Session Controller console.
Each Signaling Engine criteria contains a single Groovy script that performs all translation and processing tasks for a single type of JSON or SIP message. You must create separate criteria for all possible JSON or SIP message that your Signaling Engine implementation processes. In synchronous request/response communication, you must create a separate criteria for each request and response message.
Before creating a new criteria, look through the Groovy code in the default packages, and in the Script Library to see whether there is already some code that accomplishes what your message requires.
Criteria are applied to messages based on this information included in each criteria:
Direction - Either FROM_APP for messages originated in a WebRTC-enabled browser, or FROM_NET for messages originating from your IMS core (SIP server or proxy).
Verb - Identifies the message action verb (SIP method or JSON action) that the criteria matches. For example PUT, GET, INVITE, complete, shutdown, and so on.
Type - The type of message; can be one of:
request
response
message
error
acknowledgment
Network Service - Identifies the application that the message is being used for.
To create a Signaling Engine criteria:
Start the WebRTC Session Controller console.
See "Starting the WebRTC Session Controller Console" for details on starting the Signaling Engine console.
Select the Packages tab.
Select the package to add criteria for from the Package Name table.
Click Edit at the top of the window.
Click Create Criteria.
A blank criteria appears at the top of the criteria table and a Groovy script pane appears below the criteria table.
In the Direction field, select either FROM_APP or FROM_NET. If the criteria affects calls originating in a WebRTC-enabled browser, select FROM_APP. If the criteria is for calls originating in the IMS core, select FROM_NET.
In the Verb field, Enter a SIP method name or HTTP request that identifies the message to affect.
In the Type field, enter (request or response) as appropriate.
In the Network Service field enter the network service for messages that you want to affect.
In the Groovy Script window enter a Groovy script as appropriate for this criteria.
The Groovy script defines all actions for this criteria. See "About the Groovy Scripts" for more information.
Click Validate to ensure that your Groovy script meets the Signaling Engine validation requirements.
See "About the WebRTC Session Controller Console Validation Tests" for a list of the validation tests and error messages.
Click Save to save your new criteria. See "About the Groovy Scripts" for details.
A package is a collection of all the criteria (Groovy scripts) necessary to translate the telecom messages in a session from JSON to SIP and back. So creating a new package really just creates a shell that you fill with criteria. This procedure assumes that you have already created the criteria required.
To create a package:
Start the Signaling Engine console.
See "Starting the WebRTC Session Controller Console" for details on starting the Signaling Engine console.
Click Lock and Edit.
Click the Create Package. icon (blank page with "+" sign).
The Create Package dialog box appears.
Enter a logical name for the new package and click OK.
Your new package now appears in the package table which is arranged alphabetically.
Click Commit to make your changes take effect.
Each application is a collection of packages that contain the criteria that translate (and probably change) WebRTC application to SIP network communication for a single program. This procedure assumes that you have already created the criteria and packages required.
Applications reference your WebLogic security groups. Create any security groups your implementation requires before following this procedure.
To create an Application:
Start the WebRTC Session Controller console.
See "Starting the WebRTC Session Controller Console" for details on starting the Signaling Engine console.
Select the Applications tab.
Click the Edit button.
Click Create.
The Create Application dialog box appears.
Enter a logical name for the application.
Click OK.
The Applications table appears with the new application in the top row.
Select the Active check box if you want the application to take effect immediately.
Description - Enter an informative description of the application.
Request-URI - Enter the URI that messages are allowed to originate from. The WebRTC application's name. The default location is /ws/webrtc/
application_name.
Resource Limits - Select the pencil icon to enter resource limits and the Resource Limits screen appears. Enter positive integers to set maximum session limits; enter 0 to prohibit any sessions, and -1 to allow unlimited sessions.
Max sessions - Enter the grand total number of sessions that the original session can spawn.
Max sessions per user - Enter the total number of sessions that a subscriber is allowed to spawn.
Max sub sessions per user -Enter the total number of sessions that each user is allowed to spawn within a session.
Max sub sessions per session - Enter the total number of sub sessions spawned by a single session.
Click OK.
Allowed Domains - Click the pencil icon to edit the list of cross-origin resource sharing (CORS) domains to share data with this application. Allowed Domains window appears. Enter all domains to allow cross-origin resources sharing (CORS) with this application. Click OK when finished.
Packages - Click the pencil icon to edit the list of packages that apply to this application. The Packages window appears. Move all packages that apply to this application to the Selected Packages list. Move all others to the Existing Packages list. Click OK when finished.
Any warning icons disappear and the new application is shown in the applications table.
Click Save to make your changes take effect.
You can export your current configuration settings to a file or import a set of configuration settings from a file to which a configuration instance was previously saved.
To export a configuration:
Click Edit in the upper right corner of the screen.
Click Export.
The configuration is exported to the wsc-config.xml file in your system directory for downloads.
To import a saved configuration:
Click Edit in the upper right corner of the screen.
Click Import.
In the Import dialog, choose the XML file that contains the configuration that you want to import.
Click OK.
You can diagnose Groovy script problems using the stack trace in the domain_home/wsc.log file, which contains Signaling Engine stack trace messages. You identify the individual Groovy script by searching for the individual criteria method name that contains the criteria information. See "About the Groovy Scripts" for details on the signature that each script uses, and the method it invokes.
Figure 3-1 shows an illustration of a formatting problem in the register package, in the FROM_APP/connect/request/default criteria shown highlighted. The red arrows show the problem, the sipReq variable is used before it is declared.
This is a violation of Java syntax, and as you would expect, the operation failed and these debugging messages were written to the wsc.log file:
Caused by: groovy.lang.MissingPropertyException: No such property: sipReq for class: Script2
at org.codehaus.groovy.runtime.ScriptBytecodeAdapter.unwrap(ScriptBytecodeAdapter.java:50)
at org.codehaus.groovy.runtime.callsite.PogoGetPropertySite.getProperty(PogoGetPropertySite.java:49)
at org.codehaus.groovy.runtime.callsite.AbstractCallSite.callGroovyObjectGetProperty(AbstractCallSite.java:231)
at Script2.pkg_register_dir_FROM_APP_typ_request_verb_connect_netsvc_default(Script2.groovy:705)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:606)
at org.codehaus.groovy.reflection.CachedMethod.invoke(CachedMethod.java:90)
at groovy.lang.MetaMethod.doMethodInvoke(MetaMethod.java:233)
at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:1085)
at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:952)
at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:909)
at groovy.lang.Closure.call(Closure.java:411)
at org.codehaus.groovy.jsr223.GroovyScriptEngineImpl.callGlobal(GroovyScriptEngineImpl.java:411)
at org.codehaus.groovy.jsr223.GroovyScriptEngineImpl.callGlobal(GroovyScriptEngineImpl.java:405)
at org.codehaus.groovy.jsr223.GroovyScriptEngineImpl.invokeImpl(GroovyScriptEngineImpl.java:394)
...
The package and criteria values of the offending Groovy script are identified in this line from wsc.log:
Script2.pkg_register_dir_FROM_APP_typ_request_verb_connect_netsvc_default(Script2.groovy:705)
This messages shows the method name that Signaling Engine creates from each criteria's package name and criteria values (highlighted).
In this example, the criteria with the syntax error is in the register package. Within that package the criteria with the problem has a FROM_APP direction; a request type; a connect verb; and a default network service. This matches the syntax error of the FROM_APP/connect/request/default criteria shown in Figure 3-1.
In addition, as you are developing your Groovy scripts, you can validate the scripts by clicking the Validate button in the Groovy Script editor pane. Syntax errors and other issues are reported in the console as shown in Figure 3-2.
The WebRTC Session Controller console runs validation tests to confirm that your Groovy scripts, Groovy library, packages, and applications are all valid. It runs the validation tests each time you commit changes to an application, package, or criteria, or click the Validate button.
Table 3-1 lists the validation error types and their error messages.
Table 3-1 WebRTC Session Controller Groovy Script Validity Tests
Error Type | Error Message |
---|---|
APPLICATION_NAME_NOT_UNIQUE |
Application name application_name is not unique. |
RESOURCE_LIMITS_PROFILE_NAME_IS_NOT_UNIQUE |
Resource limits profile name resource_limit_profile_name is not unique. |
INVALID_RESOURCE_NAME |
Invalid resource name resource_name, do not enter invalid characters. |
INVALID_APP_NAME |
The application_name application contains invalid characters. |
INVALID_REQUEST_URI |
The request_URI request URI contains invalid characters. |
INVALID_SECURITY_EXPRESSION |
The security_expression security expression contains invalid characters. |
INVALID_ALLOWED_DOMAINS_EXPRESSION |
The domains_expression domains expression contains invalid characters. |
INVALID_RESOURCE_LIMITS_NAM |
Invalid resource name resource_name in application_name application. |
PACKAGE_NAME_NOT_UNIQUE |
Package name package_name is not unique.. |
SCRIPT_NAME_NOT_UNIQUE |
Script name script_name is not unique for package package_name. |
MODULE_NAME_NOT_UNIQUE |
Module name module_name is not unique. |
INVALID_PKG_NAME |
The package_name package contains invalid characters. |
INVALID_CRITERIA_VERB |
The verb_name verb name contains invalid characters. |
INVALID_CRITERIA_TYPE |
The type_name type contains invalid characters. |
INVALID_CRITERIA_NETWORK |
The network_name network contains invalid characters. |
PKG_REQUIRED |
At least one package is required for the application application_name. |
INVALID_PACKAGE_REFERENCE |
Package name package_name is referenced from app application_name but it does not exist. |
GROOVYALL_COMPILATION_ERRORS |
Error occurred for the criteria criteria, in the package package_name and the error message is reason at line number line_number. |
GROOVY_COMPILATION_ERRORS |
Error is reason, at line number line_number. |
DUPLICATE_CRITERIA |
Duplicate criteria found for criteria direction, verb, type, network_service in package package_name. |
GROOVYALL_SCRIPT_RESTRICTION |
Error occurred for the criteria criteria, in the package package_name and the error message is reason. |
GROOVY_SCRIPT_LIBRARY_COMPILATION_ERRORS |
Script library validation error is reason at line number line_number. |
ME_INVALID_LOGIN |
Invalid credentials found, for the media engine. |
ME_ADDRESS_IS_NOT_UNIQU |
Media engine address address is not unique. |
ME_PORT_IS_INVALID |
Invalid media engine port port_number. |
ME_NODE_NOT_REACHABLE |
Server not reachable with address address and port port_number. |
ME_LIFE_CYCLE_ERROR |
Media engine life cycle is not initiated for the server server_name and port port_number. |
INVALID_MODULE_NAME |
The module_name moduel contains invalid characters. |
INVALID_MODULE_REFERENCE |
Nonexistant module module_name is referenced from application application_name. |
INVALID_SCRIPT_TYPE |
The script script_name contains an error of type error_type. |
GROOVY_SCRIPT_LIBRARY_RESTRICTIONS |
Error occurred in script library reason. |
GROOVY_SCRIPT_RESTRICTIONS |
Error message is reason. |