Configuring the VTA to Manage Database Accounts

[Contents] [Prev] [Next] [Index] [Report an Error] [No Frames]

SDX 6.4.x Application Library Guide > Configuring the VTA with VTA Configuration Manager > Configuring the VTA to Manage Database Accounts
Configuring the VTA to Manage Database Accounts
The VTA uses the database engine processor to update database accounts. The database engine processor works as a proxy to a database. It can calculate usage, update account balances, get account and active service session data, and set initial balances of subscriber accounts. You can also use it to dynamically adjust interim accounting intervals based on a service or based on a subscriber's remaining resources and use of the network for that service.

The database engine processor consists of account update scripts, subscriber accounts, service accounts, and actions.

To configure the database engine processor:

In the VTA Configuration Manager navigation pane, select Edit.

Under Current Configuration, select Processors.

A list of processors appears.
Click Enable to enable the processor and display the configuration page for the database engine processor, or click Database Engine Processor.

The Database Engine Processor screen appears.
You can enable or disable the processor and perform the following tasks:

Configuring Scripts That Update Accounts

Configuring the VTA to Manage Subscriber Accounts

Configuring a Usage Metric for Service Accounts

Configuring an Interim Accounting Interval for Service Accounts

Configuring Actions for the Database Engine Processor

Configuring Scripts That Update Accounts

You can set up scripts to update balances in the accounts from which the usage of a service is charged and update accounts by assigning values to variables for the account balances.

You can create or delete account update scripts:
To add a script, click Add Account Update Script, enter a name for the script in the Add Account Update Script field that appears, and click Create.

To delete a script, click Delete next to the script that you want to delete.
Account Update Script Name

Name of the script.

Value—Name of a script

Default—No value

Account Update Script Content

JavaScript program that updates a subscriber's account. The script can refer to the attribute name of any attributes in the event being processed.

Value—Fields of an account can be updated by assigning values to the following parameters:

balance_<accountName>—Values written to this parameter are put in the balance field of the account.

status_<accountName>—Values written to this parameter are put in the status field of the account.

lastUpdateTime_<accountName>—Values written to this parameter are put in the last_update_time field of the account.

Example—<balance_PeriodicQuota>=<balance_PeriodicQuota>-\ <currentUsage>;<lastUpdateTime_PeriodicQuota>=<currentTime>;

Configuring the VTA to Manage Subscriber Accounts

A subscriber account is a record of credit and debit entries in the database that track a subscriber's use of a particular network resource.

You configure subscriber accounts in the Database Engine Account section of the Database Engine Processor configuration page. For example:
You can create, delete, or modify accounts:

To add an account, enter a name for the account in the New Database Engine Account field, and click Create.

To delete an account, click Delete next to the account that you want to delete.

To modify an account, select the account that you want to modify.

If you create or modify an account, the account configuration screen appears.

Initial Balance

Initial balance for the subscriber account.

Value—Integer in the range -9223372036854775807 through 9223372036854775807

Default—No value

Initial Status

Initial status for the subscriber account.

Value—Text string

Example—active

Configuring a Usage Metric for Service Accounts

You configure VTA service accounts in the Database Engine Service section of the Database Engine Processor configuration page. For example:
You can create, delete, or modify accounts:

To add an account, enter a name for the account in the New Database Engine Service field, and click Create.

To delete an account, click Delete next to the account that you want to delete.

To modify an account, select the account that you want to modify.

If you create or modify an account, the account configuration screen appears.
New Database Engine Service

Name of the service account.

Value—Text string

Default—No value

Usage Metric

Formula that calculates usage based on an accounting event for the specified service. The formula is in the form of a JavaScript program, and it can specify variables. For information about these variables, see Defining a Formula for Determining Network Resource Usage.

Example—return (<upStreamBytes>+<downStreamBytes>-(<upStreamPackets>+
<downStreamPackets>)*20)/2;

Default—No value

Defining a Formula for Determining Network Resource Usage

In the Usage Metric box, you define a formula that determines the use of network resources for a service. Each service in a VTA can use a different formula. You can configure the VTA software to evaluate this formula for every accounting event it receives from the SAE for each quota service. It can then debit the result from the accounts. Use the variables described in this section to define the formula.

downStreamBytes

Amount of data that the subscriber downloaded from the network since the last accounting event.

Value—Number of bytes in the range 0-9223372036854775807

downStreamPackets

Number of data packets that the subscriber downloaded from the network since the last accounting event.

Value—Integer in the range 0-9223372036854775807

Guidelines—Do not use downStreamPackets in a usage formula and maxUsageRate in the interim interval formula for the same service at the same time.

interimTime

Time since the last accounting event.

Value—Number of seconds in the range 0-2147483647

Guidelines—Generally, this value equals the interim accounting interval; however, it may exceed the interim accounting interval if an accounting event is lost. Similarly, the value may be less than the interim accounting interval if a stop event occurs in the middle of an accounting interval.

upStreamBytes

Amount of data that the subscriber uploaded to the network since the last accounting event.

Value—Number of bytes in the range 0-9223372036854775807

upStreamPackets

Number of data packets that the subscriber uploaded to the network since the last accounting event.

Value—Integer in the range 0-9223372036854775807

Guidelines—Do not use upStreamPackets in a usage formula and maxUsageRate in the interim interval formula for the same service at the same time.

Sample Formulas for Usage Metrics

Table 35 provides examples of usage formulas.
 Table 35:  Examples of Formulas That Calculate Use of Network Resources 

 Formula
 Description
 Function

 return <upStreamBytes> + <downStreamBytes> 

 Number of bytes sent and received by the subscriber. 

 Tracks volume of data that the subscriber transfers.


 return 2*<upStreamBytes> + <downStreamBytes> 

 Twice the number of sent bytes plus the number of received bytes.

 Allows higher charges for subscribers who are operating servers.


 return <interimTime> 

 Time the subscriber is connected.

 Tracks time that the subscriber connects rather than volume of data transfer.


 return <downStreamBytes>/<interimTime>

 Rate of downstream data transfer.

 Allows higher charges for higher transfer rates.


 QuotaInternet formula:
 return <upStreamBytes> + <downStreamBytes>- (<upStreamPackets> + <downStreamPackets>)*20
 QuotaLocal formula:
 return (<upStreamBytes> + <downStreamBytes>- (<upStreamPackets> + <downStreamPackets>)*20)/2

 Formulas for separate, complementary services in a single VTA.
 The following expression returns the total number of bytes in the IP headers of packets uploaded and downloaded by the service, and as such is not subscriber data. It is not counted as usage.
 (<upStreamPackets>+
<downStreamPackets>)*20 

 Provides support for two services: QuotaInternet for Internet service and QuotaLocal for local service. 
 Allows higher charges for Internet service than for local service. By allocating a fixed usage limit for both services to each subscriber, encourages subscribers to access local resources due to decreased cost.
 



 
Configuring an Interim Accounting Interval for Service Accounts

You configure VTA service accounts in the Database Engine Service section of the Database Engine Processor configuration page. For example:
You can create, delete, or modify accounts:

To add an account, enter a name for the account in the New Database Engine Service field, and click Create.

To delete an account, click Delete next to the account that you want to delete.

To modify an account, select the account that you want to modify.

If you create or modify an account, the account configuration screen appears.
New Database Engine Service

Name of the service account.

Value—Text string

Default—No value

Interim Interval

Defines a formula to dynamically adjust the interim accounting interval for each service based on the subscriber's remaining resources and use of the network for that service.

Returns a value from a JavaScript program (interim metric script) that calculates the interim interval for the specified service.

Value—The JavaScript program can specify variables. For more information about these variables, see Adjusting the Interim Accounting Interval for a Service.

Property name—InterimInterval.<serviceName>

Adjusting the Interim Accounting Interval for a Service

In the Interim Interval box, you define a formula to dynamically adjust the interim accounting interval for each service based on the subscriber's remaining resources and use of the network for that service. Each service in the VTA can use a different formula. You can configure the VTA software to evaluate the formula to obtain the accounting intervals. Depending on the result, the VTA performs the following functions:

If the result is zero, the VTA disables interim accounting.

If the result is a negative number, the VTA does not change the interim accounting interval.

If the result is a positive number, the VTA changes the interim accounting interval to this value.

The variables are categorized as:

Current service—Provides session data of the service for the current service-tracking event.

Other service—Provides service session usage information for another subscriber service for the current service-tracking event. For example, if a subscriber has two quota services, QuotaLocal and QuotaInternet, the interim formula for QuotaLocal can provide usage information to QuotaInternet.

Account balance—Provides the balance in the account.

Current Service Variables

Use the variables described in this section to define a formula for the current service.

lastInterimTime

Last interim time interval.

Value—Number of seconds in the range 1-2147483647

sessionLength

Length of the current session.

Value—Number of seconds in the range 0-2147483647; value is 0 when the VTA is calculating the interim time of start events. For other events, value is set by the PA_SESSION_TIME attribute.

maxUsageRate

Maximum rate at which the subscriber can use network resources according to the formula described in Table 36.

Value—Integer in the range 0-9223372036854775807

Guidelines—This formula corresponds to the usage formula for the same service as the interim formula.

The maxUsageRate variable is calculated for a service by means of the following values for the variables in the corresponding usage formula:

upStreamBytes=PA_UPSTREAM_BANDWIDTH

downStreamBytes=PA_DOWNSTREAM_BANDWIDTH

interimTime=lastInterimTime

upStreamPackets=0

downStreamPackets=0

If you use the parameters upStreamPackets (PA_IN_PACKETS) and downStreamPackets (PA_OUT_PACKETS) in the usage formula and at the same time maxUsageRate in the interim interval formula, the maxUsageRate is not accurate, because the values for maximum upStreamPackets and downStreamPackets are unknown.

averageUsageRate

Average rate at which the subscriber is consuming volume in units per second. The unit can be a value such as dollars, bytes, or packets. The type of unit depends on the value specified in the formula. Measurement begins when the service starts.

Value—Integer in the range 0-9223372036854775807; the value is 0 when the VTA is calculating the interim time of start events.

For other events, the value is the usage formula divided by PA_SESSION_TIME. The usage formula is calculated from PA_IN_PACKETS, PA_OUT_PACKETS, PA_OUT_OCTETS, PA_IN_OCTETS, and PA_SESSION_TIME.

latestUsageRate

Rate of service usage since the last usage report.

Value—Integer in the range 0-9223372036854775807; the value is 0 when the VTA is calculating the interim time of start events.

The value is calculated by using the result of the usage formula divided by the length of the service session since the previous usage report for the same service.

Other Service Variables

Use the variables described in this section to define a formula for another service.

System requirements to calculate service usage, in the form of the averageUsageRate and the sessionLength variables, can affect system performance. Using a longer interim interval means that there are fewer interim events to process, which requires fewer system resources.

averageUsageRate_<serviceName>

Average rate at which the service is consuming volume in units per second. The unit can be a value such as dollars, bytes, or packets. The type of unit depends on the value specified in the formula. Measurement begins when the service starts.

Value—Integer in the range 0-9223372036854775807; the value is 0 when the VTA is calculating the interim time of start events.

Guidelines—Service names can contain alphanumeric characters and dashes (-).

sessionLength_<serviceName>

Length of a service session for the service.

Value—Integer in the range 0-2147483647; the value is 0 when the VTA is calculating the interim time of start events.

Guidelines—Service names can contain alphanumeric characters and dashes (-).

Account Balance Variable

Balance information can be provided from each of the subscriber's accounts.

balance_<accountName>

Balance for the specified account before the new usage value is applied.

Value—Integer in the range 0-9223372036854775807

Example—balance_PeriodicQuota refers to the balance for the PeriodicQuota account.

Table 36 provides examples of formulas to dynamically adjust the interim accounting interval for a service.
 Table 36:  Examples of Interim Accounting Interval 

 Formula
 Description

 return 900

 Accounting interval is fixed at 900 seconds (15 minutes).


 return (<balance_Periodic> + <balance_Bought>) /<maxUsageRate> 

 Minimum time required for the subscriber to empty the periodic and bought accounts.


 return <sessionLength> >= 60*15 ? (<balance_Periodic> + <balance_Bought>) /<averageUsageRate>/2 : 
(<balance_Periodic> + <balance_Bought>) /<maxUsageRate> 

 Half the time required for the subscriber to empty the accounts at the current average rate, or the minimum time if the session is shorter than 15 minutes.
 Because the average rate may not be representative early in the session, check when the account is half empty. 



 
Configuring Actions for the Database Engine Processor

You can configure actions that the database engine processor performs on events. For example, you can set up an action to calculate usage in a service-tracking event by using the usage metric that you configured for a service.

To configure actions for the database engine processors:

In the VTA Configuration Manager navigation pane, select Edit.

Under Current Configuration, select Actions.

A list of actions appears. For example:
To add an action, enter a name for the action in the New Quota VTA Actions field, and click Create.

The action configuration screen appears.
Select DBEngine in the Processor field, and click Save. (If DBEngine does not appear in the drop-down list, enable the database engine processor.)

An expanded configuration screen for the action appears.
Edit the action fields.

See Action Fields for the Database Engine Processor.

If you are finished configuring the VTA, save the configuration to a directory or local file.

See Saving VTA Configurations to a Directory or Local File.

Action Fields for the Database Engine Processor

In VTA Configuration Manager, you can edit the following fields in the Quota VTA Actions screen.

Processor

Processor for which you are configuring the action.

Value—DBengine

Default—No value

Function

Function calls that the database engine processor invokes. These functions are variables that you can use to update database accounts.

Value

CalculateInterim—Calculates the interim interval in the service-tracking event by using the interim interval configured for the service. It has no parameters. It adds the following attribute to the event after the function is executed:

interimInterval—Interim interval of the service

CalculateUsage—Calculates usage in the service-tracking event by using the the usage metric configured for the service. It has no parameters. It adds the following attributes to the event after the function is executed:

currentUsage—Usage since the previous usage report

sessionSinceLastReport—Session length since the previous usage report

GetAccounts—Gets account data for the corresponding subscriber for the event. Subsequent event handlers of the event can use the retrieved data. It has no parameters. It 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.

TerminateSession—Closes active VTA sessions 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 service at the end of a billing period. Usage data collected after the VTA session is stopped is stored in new VTA session records.

UpdateAccounts—Runs an account update script that changes the account balances of the corresponding subscriber for the event. It 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.

Default—No value

Parameter Name

Parameters to pass to the function.

Value

Event attribute name; the event attribute name is replaced by the attribute's value wherever it appears.

For the UpdateAccounts function, you can configure the following parameter:

scriptName—Name of the account update script defined in the database engine processor

Example—ScriptName

Parameter Content

Values for the parameters.

Value

For the scriptName parameter—Name of the account update script defined in the database engine processor

Example—DebitQuotaUsage

Abort On Error

Disables or enables and sets the processing in response to an error.

Value

Break—Stop processing the current event.

Continue—Continue with the next action, if any, in the same event handler.

Next Event Handler—Continue with the next event handler (if any).

Default—No value

Formula	Description	Function
return <upStreamBytes> + <downStreamBytes>	Number of bytes sent and received by the subscriber.	Tracks volume of data that the subscriber transfers.
return 2*<upStreamBytes> + <downStreamBytes>	Twice the number of sent bytes plus the number of received bytes.	Allows higher charges for subscribers who are operating servers.
return <interimTime>	Time the subscriber is connected.	Tracks time that the subscriber connects rather than volume of data transfer.
return <downStreamBytes>/<interimTime>	Rate of downstream data transfer.	Allows higher charges for higher transfer rates.
QuotaInternet formula: return <upStreamBytes> + <downStreamBytes>- (<upStreamPackets> + <downStreamPackets>)20 QuotaLocal formula: return (<upStreamBytes> + <downStreamBytes>- (<upStreamPackets> + <downStreamPackets>)20)/2	Formulas for separate, complementary services in a single VTA. The following expression returns the total number of bytes in the IP headers of packets uploaded and downloaded by the service, and as such is not subscriber data. It is not counted as usage. (<upStreamPackets>+ <downStreamPackets>)*20	Provides support for two services: QuotaInternet for Internet service and QuotaLocal for local service. Allows higher charges for Internet service than for local service. By allocating a fixed usage limit for both services to each subscriber, encourages subscribers to access local resources due to decreased cost.

Formula	Description
return 900	Accounting interval is fixed at 900 seconds (15 minutes).
return (<balance_Periodic> + <balance_Bought>) /<maxUsageRate>	Minimum time required for the subscriber to empty the periodic and bought accounts.
return <sessionLength> >= 60*15 ? (<balance_Periodic> + <balance_Bought>) /<averageUsageRate>/2 : (<balance_Periodic> + <balance_Bought>) /<maxUsageRate>	Half the time required for the subscriber to empty the accounts at the current average rate, or the minimum time if the session is shorter than 15 minutes. Because the average rate may not be representative early in the session, check when the account is half empty.

[Contents] [Prev] [Next] [Index] [Report an Error] [No Frames]