3 Creating WebRTC Session Controller Applications, Packages, and Criteria

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.

Starting the WebRTC Session Controller Console

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:

  1. Start the WebRTC Session Controller domain server.

  2. Open a web browser.

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

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

Creating Criteria

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:

  1. Start the WebRTC Session Controller console.

    See "Starting the WebRTC Session Controller Console" for details on starting the Signaling Engine console.

  2. Select the Packages tab.

  3. Select the package to add criteria for from the Package Name table.

  4. Click Edit at the top of the window.

  5. Click Create Criteria.

    A blank criteria appears at the top of the criteria table and a Groovy script pane appears below the criteria table.

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

  7. In the Verb field, Enter a SIP method name or HTTP request that identifies the message to affect.

  8. In the Type field, enter (request or response) as appropriate.

  9. In the Network Service field enter the network service for messages that you want to affect.

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

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

  12. Click Save to save your new criteria. See "About the Groovy Scripts" for details.

Creating Packages

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:

  1. Start the Signaling Engine console.

    See "Starting the WebRTC Session Controller Console" for details on starting the Signaling Engine console.

  2. Click Lock and Edit.

  3. Click the Create Package. icon (blank page with "+" sign).

    The Create Package dialog box appears.

  4. Enter a logical name for the new package and click OK.

    Your new package now appears in the package table which is arranged alphabetically.

  5. Click Commit to make your changes take effect.

Creating Applications

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:

  1. Start the WebRTC Session Controller console.

    See "Starting the WebRTC Session Controller Console" for details on starting the Signaling Engine console.

  2. Select the Applications tab.

  3. Click the Edit button.

  4. Click Create.

    The Create Application dialog box appears.

  5. Enter a logical name for the application.

  6. Click OK.

    The Applications table appears with the new application in the top row.

  7. Select the Active check box if you want the application to take effect immediately.

  8. Description - Enter an informative description of the application.

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

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

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

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

  13. Any warning icons disappear and the new application is shown in the applications table.

  14. Click Save to make your changes take effect.

Exporting and Importing a Configuration

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:

  1. Click Edit in the upper right corner of the screen.

  2. Click Export.

    The configuration is exported to the wsc-config.xml file in your system directory for downloads.

To import a saved configuration:

  1. Click Edit in the upper right corner of the screen.

  2. Click Import.

  3. In the Import dialog, choose the XML file that contains the configuration that you want to import.

  4. Click OK.

Debugging Groovy Script Run Time Errors

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.

Figure 3-1 Groovy Script With a Syntax Error

Surrounding text describes Figure 3-1 .

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.

Figure 3-2 Groovy Script Validation Error

Surrounding text describes Figure 3-2 .

About the WebRTC Session Controller Console Validation Tests

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.