RALs

RALs is a standalone subsystem within CGRateS designed to handle two major tasks: Rating and Accounting. It is accessed via CGRateS RPC APIs.

Rating

Rating is the process responsible to attach costs to events.

The costs are calculated based on the input data defined within TariffPlans in the following sections:

RatingProfile

Binds the event via a fixed number of fields to a predefined RatingPlan. Configured via the following parameters:

Tenant: The tenant on the platform (one can see the tenant as partition ID). Matched from event or inherited from JSON configuration.
Category: Freeform field used to “categorize” the event. Matched from event or inherited from JSON configuration.
Subject: Rating subject matched from the event. In most of the cases this equals with the Account using the service.
ActivationTime: Date and time when the profile becomes active. There is no match before this date.
RatingPlanID: Identifier of the RatingPlan assigned to the event.
FallbackSubjects: List of rating subjects which will be searched in order in case of missing rates in case of defined RatingPlan. This list is only considered at first level of iteration (not considering FallbackSubjects within interations).

Note

One RatingProfile entry is composed out of a unique combination of Tenant + Category + Subject.

RatingPlan

Groups together rates per destination and relates them to event timing. Configured via the following parameters:

ID: The tag uniquely idenfying each RatingPlan. There can be multiple entries grouped by the same ID.
DestinationRatesID: The identifier of the DestinationRate set.
TimingID: The itentifier of the Timing profile.
Weight: Priority of matching rule (DestinationRatesID*+*TimingID). Higher value equals higher priority.

DestinationRate

Groups together destination with rate profiles and assigns them some properties used in the rating process. Configured via the following parameters:

ID

The tag uniquely idenfying each DestinationRate profile. There can be multiple entries grouped by the same ID.

DestinationsID

The identifier of the Destination profile.

RatesID

The identifier of the Rate profile.

RoundingMethod

Method used to round during float operations. Possible values:

*up: Upsize towards next integer value (ie: 0.11 -> 0.2)
*middle: Round at middle towards next integer value (ie: 0.11 -> 0.1, 0.16 -> 0.2)
*down: Downsize towards next integer (ie: 0.19 -> 0.1).

RoundingDecimals

Number of decimals after the comma to use when rounding floats.

MaxCost

Maximum cost threshold for an event or session.

MaxCostStrategy

The strategy used once the maximum cost is reached. Can be one of following options:

*free: Anything above MaxCost is not charged
*disconnect: The session is disconnected forcefully.

Destination

Groups list of prefixes under one Destination profile. Configured via the following parameters:

ID: The tag uniquely idenfying each Destination profile. There can be multiple entries grouped by the same ID.
Prefix: One prefix entry (can be also full destination string).

Rate

A Rate profile will contain all the individual rates applied for a matching event/session on a time interval. Configured via the following parameters:

ID: The tag uniquely idenfying each Rate profile. There can be multiple entries grouped by the same ID.
ConnectFee: One time charge applying when the session is opened.
Rate: The rate applied for one rating increment.
RateUnit: The unit raported to the usage received.
RateIncrement: Splits the usage received into smaller increments.
GroupIntervalStart: Activates the rate at specific usage within the event.

Timing

A Timing profile is giving time awarness to an event. Configured via the following parameters:

ID: The tag uniquely idenfying each Timing profile.
Years: List of years to match within the event. Defaults to the catch-all meta: *any.
Months: List of months to match within the event. Defaults to the catch-all meta: *any.
MonthDays: List of month days to match within the event. Defaults to the catch-all meta: *any.
WeekDays: List of week days to match within the event as integer values. Special case for Sunday which matches for both 0 and 7.
Time: The exact time to match (mostly as time start). Defined in the format: hh:mm:ss

Note

Due to optimization, CGRateS encapsulates and stores the rating information into just three objects: Destinations, RatingProfiles and RatingPlan (composed out of RatingPlan, DestinationRate, Rate and Timing objects).

Accounting

Accounting is the process of charging an Account on it’s Balances. The amount of charges is decided by either internal configuration of each Balance or calculated by Rating.

Account

Is the central unit of the Accounting. It contains the following fields:

Tenant: The tenant to whom the account belogs.
ID: The Account identifier which should be unique within a tenant. This should match with the event’s Account field.
BalanceMap: The pool of Balances indexed by type.
UnitCounters: Usage counters which are set out of thresholds defined in ActionTriggers
AllowNegative: Allows authorization independent on credit available.
UpdateTime: Set on each update in DataDB.
Disabled: Marks the account as disabled, making it invisible to charging.

Balance

Is the unit container (wallet/bundle) of the Account. There can be unlimited number of Balances within one Account, groupped by their type.

The following BalanceTypes are supported:

*voice: Coupled with voice calls, represents nanosecond units.
*data: Coupled with data sessions, represents units of data (virtual units).
*sms: Coupled with SMS events, represents number of SMS units.
*mms: Coupled with MMS events, represents number of MMS units.
*generic: Matching all types of events after specific ones, representing generic units (i.e., for each x *voice minutes, y *sms units, and z *data units will have their respective usage)
*monetary: Matching all types of events after specific ones, representing monetary units (can be interpreted as virtual currency).

A Balance is made of the following fields:

Uuid

Unique identifier within the system (unique hash generated for each Balance).

ID

Idendificator configurable by the administrator. It is unique within an Account.

Value

The Balance’s value.

ExpirationDate

The expiration time of this Balance

Weight

Used to prioritize matching balances for an event. The higher the Weight, the more priority for the Balance.

DestinationIDs

List of Destination profiles this Balance will match for, considering event’s Destination field.

RatingSubject

The rating subject this balance will use when calculating the cost.

This will match within RatingProfile. If the rating profile starts with character *, special cost will apply, without interogating Rating for it. The following metas are available:

*zero$xdur: A *zero followed by a duration will be the equivalent of 0 cost, charged in increments of x duration (ie: *zero1m.
*any: Points out to default (same as undefined). Defaults are set to *zero1s for voice and *zero1ns for everything else.

Categories

List of event Category fields this Balance will match for.

SharedGroup

Pointing towards a shared balance ID.

TimingIDs

List of Timing profiles this Balance will match for, considering event’s AnswerTime field.

Disabled

Makes the Balance invisible to charging.

Factors

Used in case of of *generic BalanceType to specify the conversion factors for different type of events.

Blocker

A blocking Balance will prevent processing further matching balances when empty.

ActionTrigger

Is a mechanism to monitor Balance values during live operation and react on changes based on configured thresholds and actions.

An ActionTrigger is made of the following attributes:

ID

Identifier given by the administrator

UniqueID

Per threshold identifier

ThresholdType

Type of threshold configured. The following types are available:

*min_balance: Matches when the Balance value is smaller.
*max_balance: Matches when the Balance value is higher.
*balance_expired: Matches if Balance is expired.
*min_event_counter: Consider smaller aggregated values within event based on filters.
*max_event_counter: Consider higher aggregated values within event based on filters.
*min_balance_counter: Consider smaller Balance aggregated value based on filters.
*max_balance_counter: Consider higher Balance aggregated value based on filters.

ThresholdValue

The value of the threshold to match.

Recurrent

Execute ActionTrigger multiple times.

MinSleep

Sleep in between executes.

ExpirationDate

Time when the ActionTrigger will expire.

ActivationDate

Only consider the ActionTrigger starting with this time.

Balance

Filters selecting the balance/-s to monitor.

Weight

Priority in the chain. Higher values have more priority.

ActionsID

Action profile to call on match.

MinQueuedItems

Avoid false positives if the number of items hit is smaller than this.

Executed

Marks the ActionTrigger as executed.

LastExecutionTime

Time when the ActionTrigger was executed last.

Action

Actions are routines executed on demand (ie. by one of the three subsystems: SchedulerS, ThresholdS or ActionTriggers) or called by API by external scripts.

An *Action has the following parameters:

ID

ActionSet identifier.

ActionType

The type of action to execute. Can be one of the following:

*log

Creates an entry in the log (either syslog or stdout).

*reset_triggers

Reset the matching ActionTriggers

*cdrlog

Creates a CDR entry (used for example when automatically charging DIDs). The content of the generated CDR entry can be customized within a special template which can be passed in ExtraParameters of the Action.

*set_recurrent

Set the recurrent flag on the matching ActionTriggers.

*unset_recurrent

Unset the recurrent flag on the matching ActionTriggers.

*allow_negative

Set the AllowNegative flag on the Balance.

*deny_negative

Unset the AllowNegative flag on the Balance.

*reset_account

Re-init the Account by setting all of it’s Balance’s Value to 0 and re-initialize counters and ActionTriggers.

*topup_reset

Reset the Balance matching the filters to 0 and add the top-up value to it.

*topup

Add the value to the Balance matching the filters.

*debit_reset

Reset the Balance matching the filters to 0 and debit the value from it.

*debit

Debit the value from the Balance matching the filters.

*transfer_balance

Transfers units between accounts’ balances. It ensures both source and destination balances are of the same type and non-expired. Destination account and balance IDs, and optionally a reference value, are obtained from Action’s ExtraParameters {"DestinationAccountID":"","DestinationBalanceID":""}. If a reference value is specified, the transfer ensures the destination balance reaches this value. If the destination account is different from the source, it is locked during the transfer.

*reset_counters

Reset the Balance counters (used by ActionTriggers).

*enable_account

Unset the Account Disabled flag.

*disable_account

Set the Account Disabled flag.

*http_post

Post data over HTTP protocol to configured HTTP URL.

*http_post_async

Post data over HTTP protocol to configured HTTP URL without waiting for the feedback of the remote server.

*mail_async

Send data to configured email address in extra parameters.

*set_ddestinations

Update list of prefixes for destination ID starting with: *ddc out of StatS. Used in scenarios like autodiscovery of homezone prefixes.

*remove_account

Removes the matching account from the system.

*remove_balance

Removes the matching Balances out of the Account.

*set_balance

Set the matching balances.

*transfer_monetary_default

Transfer the value of the matching balances into the *default one.

*cgr_rpc

Call a CGRateS API over RPC connection. The API call will be defined as template within the ExtraParameters.

*alter_sessions

Processes the ExtraParameters field from the action to construct a request for the SessionSv1.AlterSessions API call. The ExtraParameters field format is expected as follows:

tenant

filters: separated by “&”.

limit, specifying the maximum number of sessions to alter.

APIOpts: set of key-value pairs (separated by “&”).

Event: set of key-value pairs (separated by “&”).

*force_disconnect_sessions

Processes the ExtraParameters field from the action to construct a request for the SessionSv1.ForceDisconnect API call. The ExtraParameters field format is expected as follows:

tenant

filters: separated by “&”.

limit, specifying the maximum number of sessions to disconnect.

APIOpts: set of key-value pairs (separated by “&”).

Event: set of key-value pairs (separated by “&”).

*export

Will send the event that triggered the action to be processed by EEs

*reset_threshold

Will reset the specified Threshold in the ExtraParameters field by writing inside it the Tenant:ID of the threshold.

*reset_stat_queue

Will reset the specified StatQueue in the ExtraParameters field by writing inside it the Tenant:ID of the StatQueue.

*topup_zero_negative

Set the the matching balances to topup value if they are negative.

*set_expiry

Set the ExpirationDate for the matching balances.

*publish_account

Publish the Account and each individual Balance to the ThresholdS.

*publish_balance

Publish the matching Balances to the ThresholdS.

*remove_session_costs

Removes entries from the StorDB.session_costs table. Additional filters can be specified within the ExtraParameters.

*remove_expired

Removes expired balances of type matching the filter.

*reset_account_cdr

Creates the account out of last CDR saved in StorDB matching the account details in the filter. The CDR should contain AccountSummary within it’s CostDetails.

*remote_set_account

When an event triggers the action, the event will be used to set an account from a remote server using the URL provided in the ExtraParameters field.

*dynamic_threshold

Processes the ExtraParameters field from the action to construct a Threshold profile The ExtraParameters field format is expected as follows:

Tenant

ID

FilterIDs: separated by “&”.

ActivationInterval: separated by “&”.

MaxHits

MinHits

MinSleep

Blocker

Weight

ActionIDs: separated by “&”.

Async

EeIDs: separated by “&”.

APIOpts: set of key-value pairs (separated by “&”).