Managing Accounts in CGRateS with cgr-console

Managing Accounts in CGRateS with cgr-console

In a previous post I discussed the different ways to interact with CGRateS whilst it was running. Here I shall give some specific examples of using the cgr-console command to manage accounts and balances.

To add a new account to the system, you can use the account_set command, as shown in this example:

cgr> account_set Tenant="ssl_lab" Account="12345"
"OK"

This will set an account “12345” in the Tenant “ssl_lab”.

Note that the Tenant parameter is required for most commands. The tenant capability allows you to partition CGRateS so that, for instance, you could have segregated setups for different resellers without having to run multiple instances.

To see the account you just created, use the accounts command:

cgr> accounts Tenant="ssl_lab"
[
 {
  "ID": "ssl_lab:12345",
  "BalanceMap": {},
  "UnitCounters": {},
  "ActionTriggers": [],
  "AllowNegative": false,
  "Disabled": false
 }
]

To remove an account, use the account_remove command:

cgr> account_remove Tenant="ssl_lab" Account="12345"
"OK"
cgr> accounts Tenant="ssl_lab"
[]

Setting an account balance can be done using the balance_set command, for example:

cgr> account_set Tenant="ssl_lab" Account="12345"
"OK"
cgr> balance_set Tenant="ssl_lab" Account="12345" BalanceType="*monetary" BalanceId="MainBalance" Value=20
"OK"
cgr> accounts Tenant="ssl_lab"
[
 {
  "ID": "ssl_lab:12345",
  "BalanceMap": {
   "*monetary": [
    {
     "Uuid": "0d5a56c1-18e4-4e55-b53d-c851b77a9da4",
     "ID": "MainBalance",
     "Value": 20,
     "Directions": {},
     "ExpirationDate": "0001-01-01T00:00:00Z",
     "Weight": 0,
     "DestinationIDs": {},
     "RatingSubject": "",
     "Categories": {},
     "SharedGroups": {},
     "Timings": [],
     "TimingIDs": {},
     "Disabled": false,
     "Factor": {},
     "Blocker": false
    }
   ]
  },
  "UnitCounters": {},
  "ActionTriggers": [],
  "AllowNegative": false,
  "Disabled": false
 }
]

Note that you will need to provide either a BalanceId or a BalanceUUID. This is because every account can have multiple balances, and in ID of some sort is required to differentiate between them.

In practice it’s usually better to provide a BalanceID using some sort of reference name or ID identifying it’s use. In this case, CGRateS will automatically create the BalanceUUID as in the example above. If you don’t provide a BalanceId, CGRateS will leave this blank. Of course, you can provide both BalanceID and BalancUUID if you wish.

The balance_set command allows only a single balance to be added to an account. If you want multiple balances on an account, you can use the balance_add command. Here’s an example of how you might use this:

cgr> balance_add Tenant="ssl_lab" Account="12345" BalanceType="*minutes" BalanceId="Bundle1" Value=30
"OK"
cgr> accounts Tenant="ssl_lab"
[
 {
  "ID": "ssl_lab:12345",
  "BalanceMap": {
   "*minutes": [
    {
     "Uuid": "742d7e80-d7c4-4860-a134-a97dd8bdc4f1",
     "ID": "Bundle1",
     "Value": 30,
     "Directions": {},
     "ExpirationDate": "0001-01-01T00:00:00Z",
     "Weight": 0,
     "DestinationIDs": {},
     "RatingSubject": "",
     "Categories": {},
     "SharedGroups": {},
     "Timings": [],
     "TimingIDs": {},
     "Disabled": false,
     "Factor": {},
     "Blocker": false
    }
   ],
   "*monetary": [
    {
     "Uuid": "0d5a56c1-18e4-4e55-b53d-c851b77a9da4",
     "ID": "MainBalance",
     "Value": 20,
     "Directions": {},
     "ExpirationDate": "0001-01-01T00:00:00Z",
     "Weight": 0,
     "DestinationIDs": {},
     "RatingSubject": "",
     "Categories": {},
     "SharedGroups": {},
     "Timings": [],
     "TimingIDs": {},
     "Disabled": false,
     "Factor": {},
     "Blocker": false
    }
   ]
  },
  "UnitCounters": {},
  "ActionTriggers": [],
  "AllowNegative": false,
  "Disabled": false
 }
]

Here I have added a new balance called “Bundle1” which has 30 units. Note that, in this case, I specified the BalanceType to be “*minutes”. The previous balance “MainBalance” had a BalanceType of “*monetary” (which is actually the default if not specified). The balance type is used during rating to steer how the balance is consumed. CGRates knows about the following balance types:

  • monetary
  • sms
  • internet
  • internet_time
  • minutes.

(CGRateS constants are specified with a leading asterisk in the commands).

This capability can be used to support different pools of credit for each customer/subscriber which are consumed in different ways.

The example above gives a fairly typical example of a customer who has a main balance (“MainBalance”) which is decremented as they make phone calls. This is a monetary figure as it directly relates to how much money they have topped their account up with (or how much they owe for post-paid customers with negative balances), and the balance will be decremented based on the calculated rate of any phone calls they make, which can vary by destination, time of day, etc.

At the same time, this customer has a balance called “Bundle1” which is of type “minutes”. This could represent a special bundle that they have purchased or have been rewarded which gives them a set number of minutes of calling, for instance to a specific destination. This balance is decremented based on usage, and is independent of the calling rate.

Any specific bundle can be “topped up” by using bundle_add to add balance to a specified existing balance, using the associated BundleID or BundleUUID:

cgr> balance_add Tenant="ssl_lab" Account="12345" BalanceType="*minutes" BalanceId="Bundle1" Value=30
"OK"
cgr> accounts Tenant="ssl_lab"
[
 {
  "ID": "ssl_lab:12345",
  "BalanceMap": {
   "*minutes": [
    {
     "Uuid": "742d7e80-d7c4-4860-a134-a97dd8bdc4f1",
     "ID": "Bundle1",
     "Value": 60,
     "Directions": {},
     "ExpirationDate": "0001-01-01T00:00:00Z",
     "Weight": 0,
     "DestinationIDs": {},
     "RatingSubject": "",
     "Categories": {},
     "SharedGroups": {},
     "Timings": [],
     "TimingIDs": {},
     "Disabled": false,
     "Factor": {},
     "Blocker": false
    }
   ],
   "*monetary": [
    {
     "Uuid": "0d5a56c1-18e4-4e55-b53d-c851b77a9da4",
     "ID": "MainBalance",
     "Value": 20,
     "Directions": {},
     "ExpirationDate": "0001-01-01T00:00:00Z",
     "Weight": 0,
     "DestinationIDs": {},
     "RatingSubject": "",
     "Categories": {},
     "SharedGroups": {},
     "Timings": [],
     "TimingIDs": {},
     "Disabled": false,
     "Factor": {},
     "Blocker": false
    }
   ]
  },
  "UnitCounters": {},
  "ActionTriggers": [],
  "AllowNegative": false,
  "Disabled": false
 }
]

Note that, if you specify a non-existant BundleID or BundleUUID, CGRateS will add a new and separate balance.

Also it is not possible for a balance to have multiple types within it. If you attempt to use balance_add to add credit of a different type to an exist balance, CGRateS will create a new and entirely separate balance.

So, when adding credit to an existing balance, make sure you get the correct parameters.

Leave a Reply

Your email address will not be published. Required fields are marked *