LCR or FusionPBX/CoolPBX Manual

The LCR for FusionPBX is an in-app for FusionPBX/CoolPBX that will allow you to not only add fault tolerance in your termination routes (outgoing calls) but to prioritize the routing (usually by cost). This software is not open-source yet, there is a campaign for that purpose.

• Basic system admin skills,
• FusionPBX 4.4, 5.x or CoolPBX 1.0,
• PostgreSQL 9.3+ or MariaDB 10.1+
• PHP 7+

1. Install FusionPBX or CoolPBX (this manual doesn't cover this part),
2. Install phpbolt (please go to https://phpbolt.com/ for detailed directions)
3. Check out the repository (TBD) by typing: git clone ....
4. Go to your FusionPBX/CoolPBX deployment, click under Advanced->Upgrade and check Schema, Menu Defaults and Permissions Default. Click on the execute button and wait.
5. Go to your FusionPBX/CoolPBX deployment, click under Advanced->Group Manager and click on  SuperAdmin permissions link. Look for the lcr_* permissions and make sure they are all checked on.
6. Log out and log in.
7. Log via SSH to your server, and go to the LUA APP script directory, usually /usr/share/freeswich/scripts/app, then do a symlink of the Lua scripts the LCR app comes with.  For example (change it according to your system):
   cd /usr/share/freeswitch/scrpts/app
   ln -s /var/www/CoolPBX/app/lcr/resources/install/scripts/app/lcr/

If you are upgrading, execute steps 3, 4, 5, and 6.

 Because this software is not Open source (yet),  you must get a license. The software will write two files at the root of your FusionPBX/CoolPBX deployment, one with .key and the other with .req extensions. Contact OKay INC (or myself directly) and send me the .req file. The name of the file is important.

Make sure both .key and .req files exist.

You will get a free one-month license (only once) for evaluation purposes. If you are interested in more time, you will have to make a 300 CAD minimum donation, and you will get a reward of one unlimited license. You can see this as a one-time purchase, but legally speaking it is a donation.

What happens if I don't renew the License?

The same as if you don't have a license, the software turns into a read-only mode. In terms of LCR, this wouldn't be a big deal, but today's economy makes termination carriers update their pricing list often, meaning that your system, at some point, won't have accurate information and it will send a call through the not cheapest route.

What is the Status of the Campaign? What will happen when its Goal is reached?

The status of the campaign can be monitored here (TBD).

When the campaign is over, we will upload the unencrypted source code in the public GIT repository, you will just have to do a git pull.

LCR for FusionPBX introduces the concept of Carrier. A carrier can be seen as a set of services with specific properties.

Each carrier is linked to one or more gateways.

Each carrier is linked to its buying pricing list.

Other concepts this software uses:

 

Go to the LCR menu, and click on the + button to add your first carrier.

Where:

• The name is just human-readable. The name must not have any spaces.
• The number of channels is the number of simultaneous calls this carrier allows. Those carriers who claim to be unlimited lie about that. There is always a number, they may not know it. If you don't know this number place a reasonable number of simultaneous calls you have been able to route in the past. This number is used for pricing calculations (if you plan to use the Billing for FusionPBX/CoolPBX app).
• The priority specifies the weight a carrier must have. This number is absolute. Zero means maximum priority. If you do not plan to take advantage of this feature, leave a 4, this way you will have space for changes. This parameter forces the selection of first the carriers with the lowest value regardless of their pricing.
• Since the COVID pandemic, many carriers have gotten creative on how to surcharge for their services. The cancellation ratio is a perfect example. If your carrier surcharges you because of an excess of cancelling calls, this parameter will help you to avoid surcharges. Use 100 if your carrier doesn't bill or this; for example, if your carrier surcharges you if 10%+ of your calls are cancelled, set a 90.
• By definition, a short call is any call whose length is less than 6 seconds. Many carriers surcharge because of this. If your carrier is short-call friendly (aka call center), set this to false. This will help the LCR to decide if it should put a carrier within the selection pool depending on your calling behaviours.
• Some carriers can not transmit faxes. If you are having issues transmitting faxes, use the fax-enabled label. It will tell the LCR to take to this specific carrier when it detects it is being used to send out a fax
• The tags label is to tag your carriers. This allows you to split the traffic depending on the values you put there. Tags are one-word and comma-delimited.
• Enable this carrier if you want it to be used or not.

Click on the Save button when you are finished. You are still not done.

Linking your Gateway to your Carrier

Edit your new carrier, you will see more options. You must already have configured your gateways. This manual doesn't cover that part since this is a native part of FusionPBX/CoolPBX and it is not a specific LCR capability.

Click on the + button on the Carrier Gateways section.

You will get a linking page like this.

Where:

• The prefix dropbox will have your configured gateways. Select the one that belongs to this carrier. If you need to add a prefix, click on the triangle after selecting the carrier and append it.
• The suffix box is there in case your carrier asks for any. Usually, this is blank.
• The priority is useful to use one specific gateway from one carrier before another. For example, some carriers have POPs across the globe, so it is wise to give priority to those who are closer to you.
• The codec box accepts the codecs (comma-delimited) of the codecs that this carrier will accept. Usually, this has a blank value. If you need this, beware that your FreeSWITCH must have transcoding enabled.
• The enable box allows you to use this specific gateway.

Adding Your First Buying Rate

 Click on the + close to the LCR Buying price label. You will see the following screen.

Where:

• The origination digits box is used when some carriers apply different rates to the same destination based on the source. This is very common in some European carriers, where they have different rates if the caller ID number comes from outside Europe. If you are not using this feature, keep it blank.
• The digits box is what you need to fill in to specify the destination. Please note that LCR uses the best possible match. This means that if you have one rate with digits = 1, and a second rate with digits = 1613, if you call 1613XXXXXXX the 1613 rate will apply, but if you call 1514XXXXXXX, the 1 rate will apply instead.
• The call direction dropbox is always set to outbound. Inbound and local values are meant or very special use cases we won't cover here.
• The rate box specifies how much this carrier is billing you per minute. Please specify the currency. Multi-currency capabilities are only available if the Billing for FusionPBX/CoolPBX is installed. This box is also described as the talking rate in some places.
• The connection rate box specifies how much the carrier is billing you per minute when it connects. Usually, this value is the same as the rate box.
• The connect increment and talking increment are specified in seconds. They specify when to charge the connection rate and when to charge the talking rate. For more details about the relationship between these values, please read the article about charges in telecom in this blog.
• The intrastate and intralata boxes are only needed if your carrier gives you these specific values. Leave them blank if you don't have these values.
• Lead strip and trial strip boxes specify the number of characters it should strip before routing. Usually, this is blank.
• Prefix and suffix boxes are used to pre-append and append a string to the destination number before routing. Usually, this is blank. If your carrier requires a prefix or suffix to route, don't use this box. Set that value in the Carrier-gateway section.
• The starting date and ending date boxes specify the dates the rates are valid. These values are compared against the local time of your server.
• The quality, reliability and CID boxes are not used. They will be in future versions.
• The enable box allows the current rate to be eligible.
• The description box is for a human tag.

Mass Rate Importing

Please use a CSV file with the following headers:

• description,
• digits,
• connect_increment, if not specified then it will be the same as talk_increment
• talk_increment,
• rate,
• connect_rate, if not specified then it will be the same as the rate
• intrastate_rate, if not specified then it will be the same as rate. Only useful for the USA.
• intralata_rate, if not specified then it will be the same as rate. Only useful for the USA.
• currency, [3 chars]
• lcr_direction, [inbound, outbound, internal]
• date_start [optional, if not specified then current date and time]
• date_end [optional, if not specified then it will be 2099-12-31 06:50:00]
• lcr_profile [use default if you do not know what to do, check lcr.conf.xml]
• lead_strip,
• trial_strip,
• prefix,
• suffix, and
• random

Numbers must use a dot as a decimal point. Strings must use double quotes (").

Note: the import script is very memory-hungry, it is recommended to split your CSV file.

FusionPBX/CoolPBX usually bridges the outgoing call with a dialplan similar to this:

bridge sofia/gateway/40bc4ebd-1124-4e84-965e-11df899629db/$1

Change that line to:

lua app.lua lcr $1

Please take in mind that $1 is just an example. You should modify it accordingly. 

 You can configure the following default settings.

Category: LCR

Subcategory	Type	Default Value	Description
debug	boolean	false	Turns on debug messages in all PHP code.

 

 The LCR software has some variables that can be configured on the LUA config scripts (FusionPBX 4.4 or CoolPBX 1) or passed through the dial plans before calling the LUA script.

Dialplan Variable	Local LUA variable	Default Value	Description
lcr_billing	lcr.billing	false	Tell the LCR if it is going to perform Billing support tasks.
lcr_diverion	lcr.diversion	false	Tell the LCR to use the information from the Diversion for FusionPBX/CoolPBX to set up a dynamic Diversion header.
lcr_nanp	lcr.nanp	true	Tell the LCR to use INTRALATA rates if the calls come and go within the USA.
lcr_nanp_method	lcr.nanp_method	local_area	Tell the LCR what method to use. Currently, only local_area is valid.
lcr_anti_cancel_caller_id_number	lcr.anti_cancel_caller_id_number	false	Tell the LCR to use stats of the cancellation ratio using the caller ID number as a factor.
lcr_anti_cancel_callee_id_number	lcr.anti_cancel_callee_id_number	false	Tell the LCR to use stats of the cancellation ratio using the callee ID number as a factor.
lcr_anti_cancel_accountcode	lcr.anti_cancel_accountcode	false	Tell the LCR to use stats of the cancellation ratio using the accountcode number as a factor.
lcr_anti_cancel_evaluation_period	lcr.anti_cancel_evaluation_period	30 (days)	Tell the LCR to examine the CDR and use the last N days to calculate the cancellation ratio.
lcr_skip_carrier_uuids			Tell the LCR to exclude these specific carriers.
lcr_short_call_friendly		false	Tell the LCR to see whether to only use call-friendly carriers or not.
lcr_tag			Tell the LCR to only select carriers that have that specific tag.

1.  The LCR is not routing. What do I check?
   LCR by default looks for the best match, if it does not find anything it is because there is no match. The most common reason is the notation you are using. LCR should have the rates including the international code: 1613 for the Ottawa region, 1514 for Montreal, and 5255 for Mexico City (just to name some). If your users are dialing 10 digits instead of 11 (missing the leading one for North America), you should implement diaplans to prefix it and send 1613XXXYYYY instead of 613XXXYYYY. Same with international codes, if your users dial 0115255XXXXYYYY, you should configure dialpans to strip the 011 and send 5255XXXXYYYY to the LCR.
   
   
2. My LCR routes, but it is very slow. What's the problem?
   There are multiple causes and most of them database related.
   If you have many carriers with huge rate lists (let's say you have more than 100k records in your v_lcr table), it is very likely your database needs more memory to void excessive I/O.
   Another reason could be a lack of proper indexing. FusionPBX/CoolPBX creates some basic indexing, but it may not be enough on huge datasets.
   If you are a FusionPBX user, you may be missing Memcached and mod_memcached. Install them, the LUA part of the LCR takes advantage of it.
   
   
3. My termination carrier offers me two kinds of routes. How do I input that?
   Create one carrier per route kind. Let's say CarrierA-R1, and CarrierA-R2 and input each rating list into each carrier. 
   
   
4. I am offering my customers Value routes and Premium routes. How do I tell the LCR to use some routes depending on the service?
   Edit all your carriers and in the tags textbox input a tag to identify what service kind it belongs. If you already have a tag there, use a comma. Then on the dialpan, set the lcr_tag variable to the right tag.
   
   
5. How do I see what decision the LCR took?
   You can use fs_cli to see the actual routing decision or you can later review the CDR details and look for all the lcr_* variables.