Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation
Guide That Contains This Content
[+] Expand All
[-] Collapse All

    Configuring Event Handlers Overview

    Event handlers define how the SRC VTA processes events. An event handler configuration includes the following options:

    • Events—Type of event including tracking, update, or callback event; for example, a service-start tracking event.
    • Priority—Priority at which event handlers are evaluated and executed. Event handlers are evaluated and executed from low to high.
    • Condition—Condition that the event handler evaluates to determine whether the event handler should process the event.
    • Actions—List of actions to be performed by the event handler.

    You can set up multiple event handlers to process events. For example, the first event handler could retrieve the balance for a quota account, and the next event handler could refill the quota account depending on whether the condition of the second event handler is met.

    When an event is received, the corresponding event type and condition configured for the event handler are evaluated based on the priority. When a condition is met, the corresponding actions are performed according to the event attributes. The action can update or add event attributes to the events for subsequent processing of the same event. An action can invoke a function provided by any processor. After an event handler has completed its processing, event processing continues with the next applicable event handler.

    The SRC VTA communicates with the SAE through the Enterprise JavaBean (EJB) adapter plug-in. When an event is sent by the ejb-adapter plug-in on the SAE, it is received by the SAEEventListener, which places the event in the event queue. Because you can have multiple VTA instances, each SRC VTA has a separate SAEEventListener. The SRC VTA takes events one by one and presents them to an ordered sequence of event handlers. Each event handler includes a list of actions. If the event handler is configured to handle the event, it acts on the event based on the configured actions—for example, updating a balance or starting a service. Each action can specify a function.

    The ejb-adapter plug-in can use either the round-robin algorithm or the primary/backup algorithm to send events from the SAE to the SRC VTAs. When you configure the ejb-adapter plug-in, you specify a comma-separated list of SRC VTA IP addresses or hostnames. When you use the round-robin algorithm, an outgoing event from the SAE is sent to each of the SRC VTAs specified in the comma-separated list until it is handled by one of the SRC VTAs. When you use the primary/backup algorithm, the first SRC VTA in the comma-separated list is the primary SRC VTA; all others are secondary SRC VTAs. All outgoing events from the SAE are forwarded to the primary SRC VTA until it becomes full or inaccessible. When the handling of an event fails in the primary SRC VTA, the event is sent to the secondary VTAs in a round-robin fashion until one of the secondary SRC VTAs handles the event. On successful handling of the event, the secondary SRC VTA is promoted and becomes the new primary SRC VTA.

    Priority

    When you configure an event handler, you need to specify the priority for evaluating and running the event handler. The priority is an integer where the smaller number has the higher priority. The event handler with the highest priority receives the event, determines whether the event’s type is the same as the event type of the event handler, and determines whether the event satisfies the condition of the event handler. When an event handler finishes processing an event, the next applicable event handler according to the priority of the event handler processes the event.

    Events

    Each SRC VTA event corresponds to one subscriber and contains some attributes. The SRC VTA supports the following event types:

    • Service and subscriber tracking events from the SAE; for example, start or stop tracking events.
    • Account update events triggered by updating database accounts.
    • Callback events triggered by an SRC VTA API call.

    Various events can be received by the SRC VTA from the SAE. Table 1 describes the events supported by the SRC VTA.

    Table 1: SRC VTA Event Types

    EventDescription

    account-update

    Database update event

    callback:callid

    External callback event for the specified call

    service-interim:service name

    Service interim–tracking event for the specified service

    service-start:service name

    Service start–tracking event for the specified service

    service-stop:service name

    Service stop–tracking event for the specified service

    user-interim

    User interim–tracking event

    user-start

    User start–tracking event

    user-stop

    User stop–tracking event

    The service-name is the name of any configured SRC service.

    To process an event, the event handler must be configured to handle the particular event type. You configure which events are handled by the event handler with the shared vta group name event-handler event-handler-name events events statement. Separate events with a comma. You can configure an event handler to handle multiple event types. If an event handler is configured to handle an event, it can pass that event to a sequence of actions.

    An example of an event is:

    service-start: QuotaInternet, callback: TerminateSession

    The SRC software supports wildcard characters to configure an event for the specified service in event handler.

    Event Attributes

    Each event carries attributes. Table 2 describes the types of attributes that are available for each type of event.

    Table 2: Event Attributes

    Event Type

    Available Attributes

    Service and subscriber tracking events from the SAE

    • Plug-in attributes, such as PA_SERVICE_NAME or PA_LOGIN_NAME, associated with an SAE plug-in event. For a list of SAE plug-in events, see Testing the SRC VTA Configuration Overview.
    • currentTime attribute—Time since January 1, 1970 UTC when the SRC VTA begins passing the event to the event handlers (events are queued in the event queue and then passed to the event handlers). The value is the number of milliseconds in the range 0–9223372036854775807.
    • subscriberId—Subscriber ID based on attributes of a service or a subscriber-tracking event. The subscriberId event attribute is a result of the calculation. It identifies the subscriber of the corresponding SRC VTA event.

    Account update events

    • old_status_accountname—The old status of the account.
    • new_status_accountname—Returns the new status of the specified account.
    • old_lastUpdateTime_accountname—Returns the old last update time of the account.
    • new_lastUpdateTime_accountname—Returns the new last update time of the account.
    • old_balance_accountname—Returns the old balance of the account.
    • new_balance_accountname—Returns the new balance of the specified account
    • currentTime—Time since January 1, 1970 UTC, when the SRC VTA begins passing the event to the event handlers (events are queued in the event queue and then passed to the event handlers). The value is the number of milliseconds in the range 0–9223372036854775807.
    • subscriberId—Subscriber ID based on attributes of a service or a subscriber-tracking event. The subscriberId event attribute is a result of the calculation. It identifies the subscriber of the corresponding SRC VTA event.

    Callback events

    • callId—When the callback event type is invoked the callId value is specified. The callId value is placed in to the event using this event attribute and then processed. If an event handler is configured to handle this event type, the actions specified for the event handler can invoke functions, which have access to the callId in this event attribute.
    • currentTime—Time since January 1, 1970 UTC, when the SRC VTA begins passing the event to the event handlers (events are queued in the event queue and then passed to the event handlers). The value is the number of milliseconds in the range 0–9223372036854775807.
    • subscriberId—Subscriber ID based on attributes of a service or a subscriber-tracking event. The subscriberId event attribute is a result of the calculation. It identifies the subscriber of the corresponding SRC VTA event.

    Glob Pattern

    Use glob pattern matching when you configure an event for the specified service in event handler. The pattern matching happens only when SRC VTA receives a new service event from the SAE. After the pattern matching, the service name related event handlers are evaluated and executed based on the priority.

    Use the following wildcard characters when you configure an event for the specified service in event-handler:

    • *—Matches any substring.
    • ?—Matches any single character.
    • [range]—Matches a single character in the specified range. Ranges can have the form a-z, abcd, 0-9 or A-Z.
    • [!range]—Matches a single character outside the specified character or range of characters.

    An example of an event for the specified service with a wildcard pattern:

    service-start: Int8192-Usage_[!1-3]

    Matches any service event that starts with Int8192-Usage_ and ends with a value other than 1, 2, or 3. In this case, the ‘does not match’ condition is checked because in this case the pattern begins with “!”.

    Table 3 lists some examples of events with wildcard pattern and conditions.

    Table 3: Wildcard Pattern and Conditions

    Wildcard Pattern

    Match Condition

    Does not Match Condition

    Int8192-Usage

    Int8192-Usage

    Int8192-VTA

    Int8192-Usage?3.3

    Int8192-Usage_3.3

    Int8192-Usage13.3

    Int8192-Usage-3.3

    Int8192-Usage3.3

    Int8192-Usage_[0-3%]

    Int8192-Usage_1

    Int8192-Usage_%

    Int8192-Usage_6

    Int8192-Usage_[1-47a-f]

    Int8192-Usage_2

    Int8192-Usage_7

    Int8192-Usage_c

    Int8192-Usage_6

    Int8192-Usage_g

    Int8192-Usage_C

    Int8192-Usage_[!a-c]

    Int8192-Usage_d

    Int8192-Usage_1

    Int8192-Usage_a

    Int8192-Usage_b

    Int8192-Usage_[!1-3]

    Int8192-Usage_6

    Int8192-Usage_4

    Int8192-Usage_2

    Int8192-Usage_1

    Guidelines for Using Glob Pattern in an Event Handler

    Keep in mind the following considerations when using a wildcard pattern to configure service name related event in event-handler:

    1. Glob matches are case sensitive.
    2. A minor change in wildcard pattern may match unexpected events.
    3. Must be aware of wildcard pattern and choose a wise configuration.

    Follow these guidelines when using wildcard pattern:

    1. Enclose patterns in double quotes.

      For example:

      root@c5bng-src10# set RecordUsage events "service-start:Quota[2-3]"
    2. Verify the VTA information logs after you configure a wildcard pattern in the VTA event handler and confirm that the event handlers are loaded as expected.
    3. It is advised to use the same wildcard pattern throughout the event configuration, when you use a wildcard character for a service name in event-handler.

      For example:

      In GetQuota eventhandler configuration, if you use “service-start:Video-*” wildcard pattern for matching all the corresponding events and you want to match the same set of services in NoQuota eventhandler configuration, you must use the same “service-start:Video-*” wildcard pattern.

    4. When you use the event name with a wildcard pattern which is also the service name, both the service name and the wildcard pattern matching the service name are considered for processing.

      For Example:

      For the “service-interim:Sample[1-6]Test” event, the wildcard matches service names such as Sample[1-6]Test (which is a part of the event), Sample1Test, Sample2Test, Sample3Test, Sample4Test, Sample5Test, and Sample6Test.

    5. When you specify the priority for evaluating and running an event handler, you must set different priorities for different event handlers. The event gets dropped when it has more than one event handler with same priority.

    Condition

    Each event handler evaluates conditions to determine whether it should handle the event. You specify the condition as a script written in the JavaScript programming language that must return one of the following values:

    • True—Event handler should handle the event.
    • False—Event handler should not handle the event.

    If the condition is met, the SRC VTA performs the corresponding actions based on the event attributes. An action invokes a function and provides the parameters required by that function to the db-engine processor. If no condition is specified, true is returned as the value. If a referenced attribute does not exist in the event, the referenced attribute’s value is null. Following is an example condition:

    var newBalance=<balance_BoughtQuota>+<balance_PeriodicQuota>; if(<old_balance_PeriodicQuota>==null) <old_balance_PeriodicQuota>=<balance_PeriodicQuota>; if(<old_balance_BoughtQuota>==null) <old_balance_BoughtQuota>=<balance_BoughtQuota>; return <old_balance_PeriodicQuota>+<old_balance_BoughtQuota><=0&&newBalance>0;

    Note: In any condition or other JavaScript script, event attributes are referred to by enclosing them in angle < > brackets.

    Actions

    When you configure an event handler, you specify actions that the event handler executes in response to an event; for example, updating an account balance, starting a service, or stopping a service. An action is performed only if the event matches the specified event type and condition you configure for the event handler. An action can invoke functions provided by any processor.

    Note: We recommend that when you configure event handlers and their actions, you ensure that for any given event, all database operations are performed before any other operations that have permanent effects. This is because if a database error occurs—for example, due to normal contention for database records between different event threads—the SRC VTA rolls back the current database transaction (no changes are made to the database) and then restarts processing the event. If the event performs some other operation other than database operations before such an error, such as start a service, then that other operation is performed again when the event is reprocessed following the error.

    Modified: 2014-12-09