Working with Events

All service logic in an application is performed in response to the occurrence of an event. Events can be standard or custom.

Standard Events

By default, the SCE includes the following standard events.

ServiceLoad

Triggered when an application is first loaded. This event can be handled by an application that needs to perform pre-application initialization, such as a one-time environment initialization. Regardless of the number of sessions specified in the Console, only a single session is launched with the ServiceLoad handler to ensure that one-time initialization tasks are performed only once overall and not once per session.

ServiceUnload

Triggered just before an application is unloaded and after every running session has completed and terminated. This event is typically handled by applications that need to perform a one-time, post-application cleanup, such as to clean up resources allocated in the ServiceLoad handler. Like the ServiceLoad handler, it executes only once regardless of the number of sessions launched using the Console.

SessionEnd

Triggered when a session navigates to an End Session plug-in action component (PAC). Before terminating the session’s application variables and starting a new iteration, the application server can call the SessionEnd handler to provide session-specific cleanup. An application can handle the SessionEnd event to ensure that some end-of-call logic is called in every case, regardless of how the session ends. For example, the SessionEnd handler is a place to write a call detail record because it is guaranteed to be called no matter how the session ended.

SessionStart

Triggered when a session starts executing. Unlike the ServiceLoad and ServiceUnload event handlers, it is triggered in every running session. This event can be handled by an application that needs to execute service logic immediately, such as a load testing application that generates network messages or requests immediately or an outbound telemarketing application that searches a database for outbound calls and then initiates those calls immediately. Inbound calling applications typically do not handle the SessionStart event since the application logic is triggered by the arrival of an inbound call. An inbound calling application usually provides a handler for a SipDialogRequested or similar event, which represents the arrival of an incoming call. When the session starts, no logic is executed, and the session remains inactive until the SIP Invite handler is called.

Timer

Triggered when an application timer elapses. An application can have multiple timers active simultaneously.

The SCE also includes standard events that are generated when these standard messages are received from outside of the application:

  • Application

    • SigtranNotification

  • Application Server Events

    • ServiceLoad

    • ServiceUnload

    • SessionEnd

    • SessionStart

    • Timer

  • Communication Event

    • Handoff

  • Conferencing Event

    • ActiveSpeakerNotification

  • IN Calling Name Delivery Events (GR-1188)

    • ParameterProvideValue

  • IN Service Control Point Events (GR-1299)

    • Analyze_Route

    • Close

    • Continue

    • Disconnect

    • Info_Analyzed

    • Info_Collected

    • Resource_Clear

    • Terminiation_Attempt

    • Update_Data

  • IN Toll Free Events (GR-533)

    • Connect

    • ProvideInstructionsStart

  • Media/IVR Events

    • MediaActiveSpeaker

    • MediaDTMF

    • MediaInactiveSpeaker

    • MediaPlayDone

    • MediaPlayFailed

    • MediaRecordDone

    • MediaRecordFailed

  • Radius Events

    • AccessAccept

    • AccessChallenge

    • AccessReject

    • AccessRequest

    • AccountingRequest

    • AccountingResponse

    • Client Status

    • ServerStatus

  • Session/Call Control Events

    • SipDialogRequested

    • SipDialogTerminated

    • SipMsgOutsideDialog

    • SipMsgWithinDialog

  • Subscriber Profile Event (IMS Sh Interface)

    • ShMessage

  • User/Device Registration Events

    • RegisterRequest

    • UnregisteredRequest

Add Custom Events

It may be necessary for you to have an application handle events from external systems. These custom events used for a single application can be added to the SCE and are available in the workspace pane only when that specific application is open.

  1. Click the Events tab at the bottom of the workspace pane.

  2. Right-click the Custom Events folder, and then click Add Custom Event. The Add a Custom Event window appears.

    _images/AddCustomEvent2.png

  3. Type the Name of the event.

  4. Type the Display Name for the event, which will appear as the name of this event as it is listed in the workspace pane.

  5. Click Add to add parameters that specify additional event information.

Tip

Click Insert to add a parameter below the parameter currently selected. Click Delete to remove a parameter.

  1. Click OK.

The new function is listed on the workspace pane under Custom Events.

Tip

You can right-click on an existing custom event to select an option to delete, modify, or copy it.

Event Handling Considerations

Synchronous and Asynchronous Event Handling

The SCE allows you to handle an event either synchronously or asynchronously.

Events are handled asynchronously by creating a specific handler function that is called when the event occurs. When this approach is used, the Application Server interrupts the current path of execution, calls the handler function when the event occurs, and returns to the previous execution context when the handler function completes. A SIPDialogTerminated event is an example of an event that would typically be handled asynchronously because it can arrive at any point during the call flow.

Events are handled synchronously by using the Communication PACs at a specific point in the call flow to block it until a specific event occurs. For example, an application designer may prefer to handle an event synchronously after sending a SIP Dialog Requested to a remote host. The application then waits until a SIPDialogResponse event message is received.

Events can be handled in different ways, and a single event can be handled differently at various points in the call flow.

Disable Event Handling

If a critical section of an application must run uninterrupted, you can temporarily disable event handling while that section executes. Events can be disabled and enabled using JavaScript.

When event handling is disabled, all incoming events are queued and then passed to the application when event handling is enabled again.

Use Server.enableEvents (false) to disable event handling, and use Server.enableEvents (true) to enable event handling.

Working with Sessions

Application sessions are created when the following actions occur:

  • The Console launches an XTML application within an Application Server.

  • The operator uses the Console to specify the number of sessions to be created.

  • The application server creates and launches the specified number of sessions.

  • Each session independently navigates though the specified call flow until it reaches an EndSession PAC.

  • The application server terminates the session and frees the associated resources.

  • The application server re-initializes the session and prepares it for the next iteration.

  • This process repeats until an operator uses the Console to unload the application or until each of the sessions reach the maximum number of iterations specified when the application was loaded.

To implement control over sessions, you can build handler functions for the following standard events: ServiceLoad, ServiceUnload, SessionStart, and SessionEnd.

Example of Handler Execution

This example details the step-by-step scenario where an XTML audio conferencing application is started with 1,000 sessions.

After the document is parsed and compiled and a session is started, the logic in the handler function for ServiceLoad executes.

When the ServiceLoad handler has finished executing, 1,000 sessions of the application are created, and the SessionStart event handler is called in each of these sessions. Then each of the 1,000 sessions begins executing independently.

When a session reaches an End Session PAC, the SessionEnd handler is called. When either the handler function for SessionEnd is complete or another End the Session PAC is reached, the session’s iteration is considered complete, the variables are re-initialized, and the next iteration begins.

When the application is unloaded, by either a command from the Console or by reaching the specified number of maximum iterations, one session is created and the ServiceUnload handler is called in that session. When that handler is complete, the application is unloaded and any associated resources are freed.