diff --git a/docs/apicalls.rst b/docs/apicalls.rst index 29bf0d2a3..92c328303 100644 --- a/docs/apicalls.rst +++ b/docs/apicalls.rst @@ -1,17 +1,17 @@ -Api Calls +API Calls ======== The general API usage of the CGRateS involves creating a CallDescriptor structure sending it to the balancer via JSON/GOB RPC and getting a response from the balancer in form of a CallCost structure or a numeric value for requested information. CallDescriptor structure ------------------------ - - Direction, TOR, Tener, Subject, DestinationPrefix string - - TimeStart, TimeEnd time.Time + - Direction, TOR, Tenant, Subject, Account, DestinationPrefix string + - TimeStart, TimeEnd Time - Amount float64 Direction - The direction of the call (inbound or aoutbound) + The direction of the call (inbound or outbound) TOR Type Of Record, used to differentiate between various type of records -Tener +Tenant Customer Identification used for multi tenant databases Subject Subject for this query @@ -24,6 +24,9 @@ TimeStart, TimeEnd Amount The amount requested in various API calls (e.g. DebitSMS amount) +The **Subject** field is used usually used to identify both the client in the detailed cost list and the user in the balances database. When there is some additional info added to the subject for the call price list then the **Account** attribute is used to specify the balance for the client. For example: the subject can be rif:from:ha or rif:form:mu and for both we would use the rif account. + + CallCost structure ------------------ - TOR int diff --git a/docs/importing.rst b/docs/importing.rst index 975ad2c6e..35cce529a 100644 --- a/docs/importing.rst +++ b/docs/importing.rst @@ -1,6 +1,7 @@ -.. _`data-importing`: +.. _data-importing: + Data importing -============= +============== For importing the data into CGRateS database we are using cvs files. The import process can be started as many times it is desired with one ore more csv files and the existing values are overwritten. If the -flush option is used then the database is cleaned before importing.For more details see the cgr-loader tool from the tutorial chapter. @@ -32,7 +33,7 @@ RatesFallbackSubject RatesTimingTag Forwards to a tag described in the rates timing file to be used for this profile. ActivationTime - Multiple rates timings/prices can be created for one profile with different activation times. When a call is made the appropriate profile(s) will be used to rate the call. + Multiple rates timings/prices can be created for one profile with different activation times. When a call is made the appropriate profile(s) will be used to rate the call. So future prices can be defined here and the activation time can be set as appropriate. Rates timing ~~~~~~~~~~~~ @@ -54,7 +55,7 @@ RatesTag TimingTag The timing tag described in the timing file Weight - If multiple timings cab be applied to a call the one with the lower weight wins. + If multiple timings cab be applied to a call the one with the lower weight wins. An example here can be the Christmas day: we can have a special timing for this day but the regular day of the week timing can also be applied to this day. The weight will differentiate between the two timings. Rates @@ -88,13 +89,13 @@ Describes the time periods that have different rates attached to them. +-----------------+--------+-----------+-----------+----------+ | Tag | Months | MonthDays | WeekDays | StartTime| +=================+========+===========+===========+==========+ -| WORKDAYS | *all | *all | 1;2;3;4;5 | 00:00:00 | +| WORKDAYS | \*all | \*all | 1;2;3;4;5 | 00:00:00 | +-----------------+--------+-----------+-----------+----------+ -| WEEKENDS | *all | *all | 6,7 | 00:00:00 | +| WEEKENDS | \*all | \*all | 6,7 | 00:00:00 | +-----------------+--------+-----------+-----------+----------+ -| DAILY_SAME_TIME | *all | *all | *all | *now | +| DAILY_SAME_TIME | \*all | \*all | \*all | \*now | +-----------------+--------+-----------+-----------+----------+ -| ONE_TIME_RUN | *none | *none | *none | *now | +| ONE_TIME_RUN | \*none | \*none | \*none | \*now | +-----------------+--------+-----------+-----------+----------+ Tag @@ -106,7 +107,7 @@ MonthDays WeekDays Integers from 1=Monday to 7=Sunday separated by semicolons (;) specifying the week days for this time period. StartTime - The start time for this time period. *now will be replaced with the time of the data importing. + The start time for this time period. \*now will be replaced with the time of the data importing. Destinations ~~~~~~~~~~~~ @@ -133,13 +134,7 @@ Describes the actions to be applied to the clients/users accounts. There are two The accounts hold the various balances and counters to activate the triggered actions for each the client. -Balance types are: - MONETARY - SMS - The integer number of SMSeses - INTERNET - INTERNET_TIME - MINUTES +Balance types are: MONETARY, SMS, INTERNET, INTERNET_TIME, MINUTES. +------------+---------+-----------+------------------+------------------+ |Tenant | Account | Direction | ActionTimingsTag | ActionTriggersTag| @@ -167,9 +162,9 @@ For each account there are counters that record the activity on various balances +------------------+------------+----------------+----------------+------------+--------+ | Tag | BalanceTag | ThresholdValue | DestinationTag | ActionsTag | Weight | +==================+============+================+================+============+========+ -| STANDARD_TRIGGER | MONETARY | 30 | *all | SOME_1 | 10 | +| STANDARD_TRIGGER | MONETARY | 30 | \*all | SOME_1 | 10 | +------------------+------------+----------------+----------------+------------+--------+ -| STANDARD_TRIGGER | SMS | 30 | *all | SOME_2 | 10 | +| STANDARD_TRIGGER | SMS | 30 | \*all | SOME_2 | 10 | +------------------+------------+----------------+----------------+------------+--------+ Tag @@ -211,7 +206,7 @@ Actions +--------+-------------+------------+-------+----------------+-----------+------------+---------------+--------+ | Tag | Action | BalanceTag | Units | DestinationTag | PriceType | PriceValue | MinutesWeight | Weight | +========+=============+============+=======+================+===========+============+===============+========+ -| SOME | TOPUP_RESET | MONETARY | 10 | *all | | | | 10 | +| SOME | TOPUP_RESET | MONETARY | 10 | \*all | | | | 10 | +--------+-------------+------------+-------+----------------+-----------+------------+---------------+--------+ | SOME_1 | DEBIT | MINUTES | 10 | GERMANY_O2 | PERCENT | 25 | 10 | 10 | +--------+-------------+------------+-------+----------------+-----------+------------+---------------+--------+ diff --git a/docs/intro.rst b/docs/intro.rst index 330396770..0878138f4 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -42,21 +42,21 @@ The activation period is a structure describing different prices for a call on d :: - type Interval struct { - Month time.Month - MonthDay int - WeekDays []time.Weekday - StartTime, EndTime string // ##:##:## format - Ponder, ConnectFee, Price, BillingUnit float64 + Interval { + Months + MonthDays + WeekDays + StartTime, EndTime + Weight, ConnectFee, Price, BillingUnit } It specifies the Month, the MonthDay, the WeekDays and the StartTime and the EndTime when the Interval's Price is in effect. -For example the interval {"Month": 1, "WeekDays":[1,2,3,4,5]. "StartTime":"18:00:00", "Price":0.1, "BillingUnit": 1} specifies that the Price for the first month of each year from Monday to Friday starting 18:00 is 0.1 cents per second. Most structure elements are optional and they can be combined in any way it makes sense. If an element is omitted it means it is zero ore any. +For example the interval {"Month": [1], "WeekDays":[1,2,3,4,5]. "StartTime":"18:00:00", "Price":0.1, "BillingUnit": 1} specifies that the Price for the first month of each year from Monday to Friday starting 18:00 is 0.1 cents per second. Most structure elements are optional and they can be combined in any way it makes sense. If an element is omitted it means it is zero ore any. -The ConnectFee specifies the connection price for the call if this interval is the first one from the call and the Ponder will establishes which interval will set the price for a call segment if more then one applies to it. +The ConnectFee specifies the connection price for the call if this interval is the first one from the call and the Weight will establishes which interval will set the price for a call segment if more then one applies to it. -For example there is an interval defining price for the weekdays and another interval that defines a special holiday prices. As that holiday is also one of the regular weekdays than both intervals are applicable to a call made on that day so the interval with the greater Ponder will give the price for the call in question. If both intervals have the same Ponder than the interval with the smaller price wins. It is, however, a good practice to set the Ponder for the defined intervals. For more information see :ref:`data-importing`. +For example there is an interval defining price for the weekdays and another interval that defines a special holiday prices. As that holiday is also one of the regular weekdays than both intervals are applicable to a call made on that day so the interval with the smaller Weight will give the price for the call in question. If both intervals have the same Weight than the interval with the smaller price wins. It is, however, a good practice to set the Weight for the defined intervals. For more information see :ref:`data-importing`. So when there is a need to define new sets of prices just define new ActivationPeriods with the StartTime set to the moment when they become active. @@ -66,7 +66,7 @@ The other functions relay on a user budget structure to manage the different quo CGRateS provide api for adding/substracting user's money credit. The prepaid and postpaid are uniformly treated except that the prepaid is checked to be alway greater than zero and the postpaid is always lower than zero. -Both prepaid and postpaid can have a limited number of free SMS and Internet traffic per month and this budget is replenished at regular intervals conforming to user tariff plan or as the user buys more free SMS. +Both prepaid and postpaid can have a limited number of free SMS and Internet traffic per month and this budget is replenished at regular intervals conforming to user tariff plan or as the user buys more free SMS (for example). The free (or special price) minutes must be handled a little differently because usually they are grouped by specific destinations (e.g. national minutes, ore minutes in the same network). So they are grouped in buckets and when a call is made the engine checks all applicable buckets to consume minutes according to that call. diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 35b24a787..6f343a727 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -5,15 +5,17 @@ The general steps to get up and running with CGRateS are: #. Create CSV files containing the initial data for CGRateS, see :ref:`data-importing`. #. Load the data in the databases using the loader tool. -#. Start the balancer or rater and connect it to the call switch, see :ref:`running`. +#. Start the balancer or rater and connect it to the call switch, see Running_. #. Start one ore more raters. #. Make API calls to the balancer/rater or just let the session manager do the work. Instalation ----------- -**Using packages** +Using packages +~~~~~~~~~~~~~~ -**Using source** +Using source +~~~~~~~~~~~~ After the go environment is installed_ and setup_ just issue the following commands: :: @@ -32,7 +34,8 @@ Running There are only three main command to used with CGRateS: cgr-balancer - The cgr-balancer will open a JSON RPC server and an HTTP server ready for taking external requests. It will also open a rater server on witch the raters will register themselves when they start. +~~~~~~~~~~~~ +The cgr-balancer will open a JSON RPC server and an HTTP server ready for taking external requests. It will also open a rater server on witch the raters will register themselves when they start. :: rif@grace:~$ cgr-balancer --help @@ -46,7 +49,8 @@ cgr-balancer cgr-rater - The cgr-rater can be provided with the balancer server address and can be configured to listen to a specific interface and port. +~~~~~~~~~ +The cgr-rater can be provided with the balancer server address and can be configured to listen to a specific interface and port. :: rif@grace:~$ cgr-rater --help @@ -62,6 +66,7 @@ cgr-rater -standalone=false: start standalone server (no balancer) cgr-console +~~~~~~~~~~~ The cgr-console is a command line tool used to access the balancer (or the rater directly) to call all the API methods offered by CGRateS. :: @@ -77,12 +82,8 @@ cgr-console -ts="2012-02-09T00:00:00Z": Time start cgr-loader - The loader is the most configurable tool because it has options for each of the three supported databases (kyoto, redis and mongodb). - Apart from that multi-database options it is quite easy to be used. - The apfile, destfile, tpfile and ubfile parameters are for specifying the input json files. - The storage parameter specifies the database to be used and then the databases access information (host:port or file) has to be provided. +~~~~~~~~~~ - :Example: cgr-loader -storage=kyoto -kyotofile=storage.kch -apfile=activationperiods.json -destfile=destinations.json -tpfile=tariffplans.json -ubfile=userbudgets.json :: rif@grace:~$ cgr-loader --help @@ -105,32 +106,46 @@ cgr-loader -timings="Timings.csv": Timings file -weekdays="WeekDays.csv": Week days file +cgr-sessionmanager +~~~~~~~~~~~~~~~~~~ -rif@grace:~$ cgr-balancer --help -Usage of cgr-balancer: - -freeswitchpass="ClueCon": freeswitch address host:port - -freeswitchsrv="localhost:8021": freeswitch address host:port - -httpapiaddr="127.0.0.1:8000": Http API server address (localhost:2002) - -json=false: use JSON for RPC encoding - -jsonrpcaddr="127.0.0.1:2001": Json RPC server address (localhost:2001) - -rateraddr="127.0.0.1:2000": Rater server address (localhost:2000) +:: -rif@grace:~$ cgr-sessionmanager --help -Usage of cgr-sessionmanager: - -balancer="127.0.0.1:2000": balancer address host:port - -freeswitchpass="ClueCon": freeswitch address host:port - -freeswitchsrv="localhost:8021": freeswitch address host:port - -json=false: use JSON for RPC encoding - -redisdb=10: redis database number - -redissrv="127.0.0.1:6379": redis address host:port - -standalone=false: run standalone (run as a rater) + rif@grace:~$ cgr-sessionmanager --help + Usage of cgr-sessionmanager: + -balancer="127.0.0.1:2000": balancer address host:port + -freeswitchpass="ClueCon": freeswitch address host:port + -freeswitchsrv="localhost:8021": freeswitch address host:port + -json=false: use JSON for RPC encoding + -redisdb=10: redis database number + -redissrv="127.0.0.1:6379": redis address host:port + -standalone=false: run standalone (run as a rater) -rif@grace:~$ cgr-mediator --help -Usage of cgr-mediator: - -dbname="cgrates": The name of the database to connect to. - -freeswitchcdr="Master.csv": Freeswitch Master CSV CDR file. - -host="localhost": The host to connect to. Values that start with / are for unix domain sockets. - -password="": The user's password. - -port="5432": The port to bind to. - -resultfile="out.csv": Generated file containing CDR and price info. - -user="": The user to sign in as. \ No newline at end of file +cgr-mediator +~~~~~~~~~~~~ + +:: + + rif@grace:~$ cgr-mediator --help + Usage of cgr-mediator: + -dbname="cgrates": The name of the database to connect to. + -freeswitchcdr="Master.csv": Freeswitch Master CSV CDR file. + -host="localhost": The host to connect to. Values that start with / are for unix domain sockets. + -password="": The user's password. + -port="5432": The port to bind to. + -resultfile="out.csv": Generated file containing CDR and price info. + -user="": The user to sign in as. + +cgr-scheduler +~~~~~~~~~~~~~ + +:: + + rif@grace:~$ cgr-balancer --help + Usage of cgr-balancer: + -freeswitchpass="ClueCon": freeswitch address host:port + -freeswitchsrv="localhost:8021": freeswitch address host:port + -httpapiaddr="127.0.0.1:8000": Http API server address (localhost:2002) + -json=false: use JSON for RPC encoding + -jsonrpcaddr="127.0.0.1:2001": Json RPC server address (localhost:2001) + -rateraddr="127.0.0.1:2000": Rater server address (localhost:2000) \ No newline at end of file