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 Actions Overview

    Actions are executed by event handlers in response to an event. For example, the action may update an account balance, start a service, or stop a service. You configure what action the event handler takes in response to an event when you configure an event handler. An action is performed only if an event matches the event type and condition specified in the event handler configuration. An action can invoke functions provided by any processor.

    An action can update event attributes or add new attributes to an event for subsequent processing of the same event by subsequent actions in the same event handler, or in subsequent event handlers.

    You define an action with the edit shared vta group name action action-name configuration statement. You refer to a previously defined action when you configure an event handler. Event handlers can refer to multiple actions. To configure an event handler to use a particular action, specify it as follows:

    [edit shared vta group name event-handler name]user@host# set actions actions

    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.

    When you configure an action, you specify the following options:

    • Function—The function that the action invokes
    • Parameter—The parameters and corresponding values to be passed to the function
    • On-error—What the event handler does in response to an error

    Functions are variables that an action invokes, for example, to update database accounts. The function takes as input the configured parameters, the event, and the event context (which may include values created by previously executed actions). The SRC VTA provides a set of available functions. Each function takes a different set of input parameters. Table 1 describes the available SRC VTA functions and their associated input parameters.

    Table 1: SRC VTA Functions and Input Parameters

    Function NameDescriptionInput Parameters

    db-engine-calculate-interim

    Calculates the interim interval in the service-tracking event by using the interim interval function for the service, as defined with the shared vta group name processor db-engine service name interim-interval-function configuration statement. This function adds the following attribute to the event after the function is executed:

    • interimInterval—Interim interval of the service

    None

    db-engine-calculate-usage

    Calculates usage in the service-tracking event by using the usage metric function for the service, as defined with the shared vta group name processor db-engine service name usage-metric-function configuration statement. This function adds the following attributes to the event after the function is executed:

    • currentUsage—Usage since the previous usage report
    • interimTime—Session length since the previous usage report

    None

    db-engine-get-accounts

    Retrieves account data for the corresponding subscriber for the event. Data for multiple accounts is retrieved; accounts are identified by the accountName suffix. Accounts are defined with the shared vta group name processor db-engine account name configuration statement, where the account name corresponds to the _accountName suffix. Subsequent event handlers of the event can use the retrieved data. This function adds the following attributes to the event after the function is executed:

    • balance_accountName—Balance for the account.
    • lastUpdateTime_accountName—Last update time in milliseconds since January 1, 1970 UTC for the account.
    • status_accountName—Status of the account.

    None

    db-engine-terminate-session

    Closes active SRC VTA sessions (for the subscriber for which the event occurred) that have a status of Start or Interim. It does not stop the corresponding services in the SAE. You can use this function to stop a session at the end of a billing period. Usage data collected after the SRC VTA session is stopped is stored in new SRC VTA session records.

    None

    db-engine-update-accounts

    Runs an account update script that changes the account balances of the corresponding subscriber for the event. Scripts are defined with the shared vta group name processor db-engine account-update-script name configuration statement. The predefined script name is used as input to this function. This function adds the following attributes to the event after the function is executed:

    • balance_accountName—Balance for the account after it is updated.
    • lastUpdateTime_accountName—Last update time in milliseconds since January 1, 1970 UTC for the account after it is updated.
    • status_accountName—Status of the account after it is updated.

    script-name—Name of the account update script defined in the db-engine processor.

    mailer-send

    Sends e-mail notifications when certain events occur. You can specify that e-mail notifications be sent to anyone, for example, subscribers, system administrators, or an automated billing system.

    • recipient—Destination e-mail address
    • from—Source e-mail address
    • subject—Subject of the e-mail
    • text—Content of the e-mail

    sae-set-interim-interval

    Sets the interim accounting interval for the service session identified in the event to be the value of the interimInterval attribute currently found in the event. Before this function is called, the db-engine-calculate-interim function of the db-engine processor must be called in order to place the interimInterval attribute into the event.

    current-subscriber-only—Specifies whether the function is applied only to the subscriber identified in the event or to all subscribers who have the same subscriber ID.

    • Set to true to apply the function to the current subscriber only. If you do not set this parameter, true is the default behavior.
    • Set to false to apply the function to all subscribers who have the same subscriber ID.

    sae-set-service-timeout

    Sets the service session timeout for the service session identified in the event.

    • subscription-name—Name of the subscription in the format serviceName%subscriptionId. Default subscriptions have the same name as the service. This parameter is optional when a service-tracking event is being processed. If %subscriptionId is omitted, the default subscription is assumed.
    • session-name—Name of the service session. This parameter is ignored if a service-tracking event is being processed and the subscription name is omitted. In this case, the session name from the service-tracking event is used. If this parameter is omitted, the default service session is used.
    • session-timeout—Length of the service session timeout in seconds. If the session timeout is set to 0, the service session is stopped immediately. When the session timeout expires, the service session is stopped.
    • current-subscriber-only—Specifies whether the function is applied only to the subscriber identified in the event or to all subscribers who have the same subscriber ID.
      • Set to true to apply the function to the current subscriber only. If you do not set this parameter, true is the default behavior.
      • Set to false to apply the function to all subscribers who have the same subscriber ID.

    sae-set-user-timeout

    Sets the subscriber session timeout of the subscriber identified in the event.

    • session-timeout—Length of the subscriber session timeout in seconds. If the session timeout is set to 0, the subscriber session is stopped immediately. When the session timeout expires, the subscriber is logged out.
    • current-subscriber-only—Specifies whether the function is applied only to the subscriber identified in the event or to all subscribers who have the same subscriber ID.
      • Set to true to apply the function to the current subscriber only. If you do not set this parameter, true is the default behavior.
      • Set to false to apply the function to all subscribers who have the same subscriber ID.

    sae-start-service

    Starts the specified service subscription.

    • subscription-name—Name of the subscription in the format serviceName%subscriptionId. Default subscriptions have the same name as the service. This parameter is optional when a service-tracking event is being processed. If %subscriptionId is omitted, the default subscription is assumed.
    • session-timeout—Length of the service session timeout in seconds. When the session timeout expires, the service session is stopped.
    • session-name—Name of the service session. If this parameter is omitted, the default service session is used.
    • current-subscriber-only—Specifies whether the function is applied only to the subscriber identified in the event or to all subscribers who have the same subscriber ID.
      • Set to true to apply the function to the current subscriber only. If you do not set this parameter, true is the default behavior.
      • Set to false to apply the function to all subscribers who have the same subscriber ID.
    • substitution—Policy parameter substitution to use when starting the service. This is specified as substitution name value value. If this parameter is omitted, the service is started without substitutions.
    • persistent—Specifies whether a service session is persistent. If you use the SRC VTA to activate a service with the persistent option, this service is subsequently activated by the SAE every time the subscriber connects to the network. This option provides efficiency because the SRC VTA does not need to make a decision to activate the service on subsequent logins and because some applications can more efficiently activate a group of services at login.
      • Set to true to cause the session to be persistent.
      • Set to false to specify that the session is not persistent and the service is activated or deactivated only for the current subscriber session.

    sae-stop-service

    Stops the specified subscription to the specified service.

    • subscription-name—Name of the subscription in the format serviceName%subscriptionId. Default subscriptions have the same name as the service. This parameter is optional when a service-tracking event is being processed. If %subscriptionId is omitted, the default subscription is assumed.
    • session-name—Name of the service session. If the subscriptionName parameter is omitted, this parameter is ignored. If this parameter is omitted, the default service session is used.
    • reason—Reason for the termination. When the service is stopped, the termination cause can be sent to the billing system so it can differentiate between service stops. If this parameter is omitted, no termination cause is provided to the billing system. Specify an integer that identifies the termination cause. Possible values are defined in RFC 2866—RADIUS Accounting (June 2000).
    • current-subscriber-only—Specifies whether the function is applied only to the subscriber identified in the event or to all subscribers who have the same subscriber ID.

      • Set to true to apply the function to the current subscriber only. If you do not set this parameter, true is the default behavior.
      • Set to false to apply the function to all subscribers who have the same subscriber ID.
    • persistent—Specifies whether a service session is persistent.
      • Set to true to cause the session to be persistent.
      • Set to false to specify that the session is not persistent and the service is deactivated only for the subscriber identified in the event.

    scripts-run-external-script

    Executes an external script that is present on the local SRC file system, as previously defined with the shared vta group name processor scripts external-script name configuration statement.

    • script-name—Name of an external script previously defined with the shared vta group name processor scripts external-script name configuration statement.
    • name—Any other parameters the script expects to receive as previously defined under the shared vta group name processor scripts external-script name parameters configuration statement. These parameters are entered as name/value pairs.

    scripts-run-javascript

    Executes a script written in the JavaScript programming language that you previously defined by using the shared vta group name processor scripts javascript name configuration statement.

    • script-name—Name of a script written in the JavaScript programming language that you previously defined by using the shared vta group name processor scripts javascript name configuration statement.

    Any parameters referenced in the script itself are taken from the event and passed to the function automatically.

    On Error

    For each action, you must specify what the event handler does if an error occurs; you specify this with the on-error option. If an error occurs, the event handler can do one of the following:

    • Abort-event-processing—Stop processing the current event.
    • Go-to-next-action—Continue with the next action, if any, in the same event handler.
    • Go-to-next-event-handler—Skip any remaining actions in the current event handler and proceed to the next event handler (if any).

    Published: 2014-06-19