In Rhino SAS API, an event is a structure for capturing call processing data to be sent to SAS. For example, if you want to send data to SAS to indicate that a call is being diverted, you can define an event called DIVERTING_CALL, which has parameters to capture data such as the phone number to which the call is diverted.

By convention, events are defined in the mini-bundle file in the same module where they are used.

Event structure

The structure of an event is as follows:


  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16


  
<EVENT_NAME>:
    level: <event-level>
    summary: <event-summary>
    user_exp: <user-experience>
    details: <call-details>
    call_flow:
        caption: <call-flow-caption>
        data: <call-flow-data>
        protocol: <call-flow-protocol>
        call_leg: <call-leg>
        direction: <call-flow-direction>
        local_address: <call-flow-local-address>
        remote_address: <call-flow-remote-address>
        message: <protocol_message>
        message_id: <call-flow-message-id>
        call_info_id: <call-flow-call-info-id>

This structure contains these fields:

  • <EVENT_NAME>: The name of the event. By convention, event names are capitalized.

  • level: The level of the event. For more information, see Event level.

  • summary: The summary of the event. SAS displays this information as the Event Summary of the event.

  • user_exp: The user experience information of the event. SAS displays this information in the User Experience view.

  • details: Detailed information about the event. SAS displays this information as the detailed text of the event in the Detailed Timeline view.

  • call_flow: The call flow information of the event. SAS displays this information in the Call Flow view.

    This field contains the following subfields (lines 7-16):

    • caption: The text that SAS displays above the arrows in the ladder diagram for the event.

    • data: The protocol message data to add to the call flow diagram.

    • protocol: The protocol to which the message belongs.

    • call_leg: A string that identifies the call leg to which the message belongs.

    • direction: The direction of the call flow.

    • local_address: The local IP address and port that the message is sent from or received at.

    • remote_address: The remote IP address and port that the message is sent from or received at.

    • message: The protocol message data for display in the Message tab of the details panel of the call flow diagram.

    • message_id: The ID of the protocol message.

    • call_info_id: The ID of the "call info" marker that can be used to modify the event or supply additional information for it after it is logged.

Note If you send the same call flow events from multiple nodes, send them using the same fields to ensure correct association within SAS. Otherwise, SAS will display the events separately.

For information about the SAS user interface, check the SAS documentation listed in Related information.

For each event, the level and summary fields are mandatory. If the call_flow field is specified, the data, protocol, and direction subfields are mandatory.

All text fields can contain parameterized text using the Liquid template language. For example, New target: {{ var_data[0] }}.

Tip

  • Don’t use HTML tags. SAS ignores them when it displays an event.

  • Use the <sas:fixed-width-font> and </sas:fixed-width-font> tags to display text in a fixed-width font. The Event example section has an example.

SAS uses two types of predefined event variables: static_data and var_data. These variables are arrays.

  • The static_data variable contains an array of the static data associated with the event, with each element of the array being a 32-bit integer.

  • The var_data variable contains an array of variable data associated with the event, with each element of the array being variable length data (typically a string).

In your event definition, you can use these variables to format the event data that SAS displays. For example, Attempts in the last minute: {{ static_data[0] }} or User agent string: {{ var_data[0] }}.

SAS assigns relevant values to these variables when it needs to display the event data that you send with the staticParam() method or the varParam() method. For more information about using these methods, see Create and send an API message.

In addition, SAS provides predefined Liquid filters that you can use in your event definition. For example, with the if_blank filter, you can get the specified string if the input string is blank. For details about these filters, see Predefined Liquid filters.

Event level

The level of an event determines how SAS displays the event in its GUI.

You can assign one of the following levels to an event:

  • 100: A high-level event that SAS displays in the User Experience view.

  • 80: A user-friendly event that SAS displays in the Detailed Timeline view.

  • 60: A protocol event where the protocol is of interest to the user. SAS displays events of this level in the protocol flows group.

  • 40: An event that SAS displays in the Detailed events group.

  • 20: A diagnostic event that SAS displays in the Engineering level events group. Events of this level are for application engineers.

Event example

The following event named INCOMING_MESSAGE for reporting an HTTP message received contains the summary, details, level, and call_flow fields, in which the call_flow field contains several subfields:

INCOMING_MESSAGE:
  summary: 'Received HTTP {{ var_data[3] }} from {{ var_data[2] }}'
  details: |
            Received HTTP message from {{ var_data[2] }}:{{ static_data[1] }}
            On {{ var_data[1] }}:{{ static_data[0] }}<sas:fixed-width-font>{{ var_data[0] }}</sas:fixed-width-font>
  level: 60
  call_flow:
    caption: '{{ var_data[3] }}'
    data: '{{ var_data[0] | binary }}'
    protocol: HTTP
    direction: in
    local_address: '{{ var_data[1] }}:{{ static_data[0] }}'
    remote_address: '{{ var_data[2] }}:{{ static_data[1] }}'
    message_id: '{{ var_data[4] }}'

In this example, the binary filter is used on the call flow data. For more information, see Predefined Liquid filters.

Previous page Next page