SupplierS

SupplierS is a standalone subsystem within CGRateS responsible to compute a list of suppliers which can be used for a specific event received to process. It is accessed via CGRateS RPC APIs.

As most of the other subsystems, it is performance oriented, stored inside DataDB but cached inside the cgr-engine process. Caching can be done dynamically/on-demand or at start-time/precached and it is configurable within cache section in the JSON configuration.

Processing logic

When a new Event is received, SupplierS will pass it to FilterS in order to find all SupplierProfiles matching the Event.

As a result of the selection process we will get a single SupplierProfile matching the Event, is active at the EventTime and has a higher priority than the other matching SupplierProfiles.

Depending on the Strategy defined in the SupplierProfile, further steps will be taken (ie: query cost, stats, ordering) for each of the individual SupplierIDs defined within the SupplierProfile.

APIs logic

GetSupplierProfilesForEvent

Given the Event it will return a list of ordered SupplierProfiles matching at the EventTime.

This API is useful to test configurations.

GetSuppliers

Will return a list of Suppliers from within a SupplierProfile ordered based on Strategy.

Parameters

SupplierS

SupplierS is the CGRateS component responsible for handling the SupplierProfiles.

It is configured within suppliers section from JSON configuration via the following parameters:

enabled
Will enable starting of the service. Possible values: <true|false>.
indexed_selects
Enable profile matching exclusively on indexes. If not enabled, the SupplierProfiles are checked one by one which for a larger number can slow down the processing time. Possible values: <true|false>.
string_indexed_fields
Query string indexes based only on these fields for faster processing. If commented out, each field from the event will be checked against indexes. If defined as empty list, no fields will be checked.
prefix_indexed_fields
Query prefix indexes based only on these fields for faster processing. If defined as empty list, no fields will be checked.
nested_fields
Applied when all event fields are checked against indexes, and decides whether subfields are also checked.
attributes_conns
Connections to AttributeS for altering events before supplier queries. If undefined, fields modifications are disabled.
resources_conns
Connections to ResourceS for *res sorting, empty to disable functionality.
stats_conns
Connections to StatS for *stats sorting, empty to disable stats functionality.
default_ratio
Default ratio used in case of *load strategy

SupplierProfile

Contains the configuration for a set of suppliers which will be returned in case of match. Following fields can be defined:

Tenant
The tenant on the platform (one can see the tenant as partition ID).
ID
The profile identificator.
FilterIDs
List of FilterProfileIDs which should match in order to consider the profile matching the event.
ActivationInterval
The time interval when this profile becomes active. If undefined, the profile is always active. Other options are start time, end time or both.
Sorting

Sorting strategy applied when ordering the individual Suppliers defined bellow. Possible values are:

*weight
Classic method of statically sorting the suppliers based on their priority.
*lc

LeastCost will sort the suppliers based on their cost (lowest cost will have higher priority). If two suppliers will be identical as cost, their Weight will influence the sorting further. If AccountIDs will be specified, bundles can be also used during cost calculation, the only condition is that the bundles should cover complete usage.

The following fields are mandatory for cost calculation: Account/Subject, Destination, SetupTime. Usage is optional and if present in event, it will be used for the cost calculation.

*hc

HighestCost will sort the suppliers based on their cost(higher cost will have higher priority). If two suppliers will be identical as cost, their Weight will influence the sorting further.

The following fields are mandatory for cost calculation: Account/Subject, Destination, SetupTime. Usage is optional and if present in event, it will be used for the cost calculation.

*qos
QualityOfService strategy will sort the suppliers based on their stats. It takes the StatIDs to check from the supplier StatIDs definition. The metrics used as part of sorting are to be defined in SortingParameters field bellow. If Stats are missing the metrics defined in SortingParameters defaults for those will be populated for order (10000000 as PDD and -1 for the rest).
*reas
ResourceAscendentSorter will sort the suppliers based on their resource usage, lowest usage giving higher priority. The resources will be queried for each supplier based on it’s ResourceIDs field and the final usage for each supplier will be given by the sum of all the resource usages queried.
*reds
ResourceDescendentSorter will sort the suppliers based on their resource usage, highest usage giving higher priority. The resources will be queried for each supplier based on it’s ResourceIDs field and the final usage for each supplier will be given by the sum of all the resource usages queried.
*load

LoadDistribution will sort the suppliers based on their load. An important parameter is the *ratio which is defined as supplierID:Ratio within the SortingParameters. If no supplierID is present within SortingParameters, the system will look for *default or fallback in the configuration to default_ratio within JSON configuration. The *ratio will specify the probability to get traffic on a Supplier, the higher the *ratio more chances will a Supplier get for traffic.

The load will be calculated out of the StatIDs parameter of each Supplier. It is possible to also specify there directly the metric being used in the format StatID:MetricID. If only StatID is instead specified, all metrics will be summed to get the final value.

SortingParameters

Will define additional parameters for each strategy. Following extra parameters are available(based on strategy):

*qos
List of metrics to be used for sorting in order of importance.
Weight
Priority in case of multiple SupplierProfiles matching an Event. Higher Weight will have more priority.
Suppliers
List of Supplier objects which are part of this SupplierProfile

Supplier

The Supplier represents one supplier within the SupplierProfile. Following parameters are defined for it:

ID
Supplier ID, will be returned via APIs. Should be known on the remote side and match some business logic (ie: gateway id or directly an IP address).
FilterIDs
List of FilterProfileIDs which should match in order to consider the Supplier in use/active.
AccountIDs
List of account IDs which should be checked in case of some strategies (ie: *lc, *hc).
RatingPlanIDs
List of RatingPlanIDs which should be checked in case of some strategies (ie: *lc, *hc).
ResourceIDs
List of ResourceIDs which should be checked in case of some strategies (ie: *reas or *reds).
StatIDs
List of StatIDs which should be checked in case of some strategies (ie: qos or *load). Can also be defined as *StatID:MetricID.
Weight
Used for sorting in some strategies (ie: *weight, *lc or *hc).
Blocker
No more suppliers are provided after this one.
SupplierParameters
Container which is trasparently passed to the remote client to be used in it’s own logic (ie: gateway prefix stripping or other gateway parameters).

Use cases

  • Calculate LCR directly by querying APIs (GetSuppliers).
  • LCR system together with Kamailio dispatcher module where the SupplierID whithin CGRateS will be used as dispatcher set within Kamailio.
  • LCR system together with OpenSIPS drouting module where the SupplierID whithin CGRateS will be used as drouting carrier id.
  • LCR system together with FreeSWITCH or Asterisk where the SupplierID whithin CGRateS will be used as gateway ID within the dialplan of FreesWITCH or Asterisk.