1.4.4 Routing plan

The routing plan’s role is to associate routes with prefixes. Each prefix is represented by a separate entry. Besides the prefix there are other properties which are applied during the call processing.

Multiple entries can share the same prefix if they differ in any of the other routing properties. 

Note: The Calls routing/Routing plan menu is for calls only, for SMS there is a separate plan under SMS routing menu.

When a call request comes to voipswitch, first it is checked if there are Routing plan rules defined in the client’s account. If so, the dialed number is modified and then passed to the Routing plan.

The Routing function looks for the best matching entry by comparing the modified dialed number with the prefixes defined in the Routing plan. When the match is found voipswitch will try to connect with the associated route.

During the process voipswitch checks if there is any common codec in the client and destination allowed codecs sets. If not, then the entry is considered as no match and the routing function looks further for the next matching prefix. If transcoding is enabled for client its codec set is extended by those supported by the transcoding module.

Another property which is checked during the lookup is time span. It defines at what hours and on what days of the week a route is active. If not active at the moment a call is made the routing function will skip this entry.

When the proper route is found the softswitch checks the routing properties defined in the Routing plan. Click on a particular entry to see the detailed view.

Defining a route per prefix

The key property for each dialing plan entry is the prefix. It is a string of characters to which the dialed number is compared. The prefix has to consist of minimum 1 and maximum 40 characters.

Another property is the route type. Depending on the chosen route type the other settings in the dialing plan entry may change.

When adding a new entry the dialog window will present the mandatory settings depending on the selected route type.

Destinations

The route types defined in the Calls routing menu include gateways, registrars, lookups, enum servers and the callback routes. When the Gateway route type is selected the drop down list will allow to pick one of the gateways defined in Calls Routing/Gateways menu.

Similarly, when the Registrar type is selected you can choose from the list of registrars added earlier in Calls routing/Registrars menu.

These two route types refer to the SIP endpoints and therefore the next important setting is the proxy mode.

Independent signalling and media proxy - origination and termination endpoints do not see each other; VoipSwitch connects independently with each endpoint then conferences them together.

signalling proxy and media proxy - the signaling and media will still be passed through VoipSwitch as in the first rule. The difference between this option and the previous one is that the call setup received from the client is sent to the target gateway. So the two endpoints can use more codecs if they both support them (even if VoipSwitch doesn't support it). Also, information coming from a client is forwarded directly to the termination gateway.

signalling proxy - only signalling information are passed through the switch. Media packages are sent directly between endpoints.

Internal users

Another route type option is Retail client which is used for sending calls to the users defined in the Retail clients menu. They represent SIP endpoints which register to voipswitch as to SIP registrar. When this route type is chosen a two new options appear:

• User lookup
• Specific user

User lookup will make the routing function to look for a client record in the clientsshared table. The route is found if the login equals the dialed number.

Note: It is important to note that the dialed number at this point is already modified according to the Routing rules defined in the Routing plan entry, General tab.

For example if the dialed number is 390123456 and the Routing plan rules are 390-> then the number after the transformation will become 123456 as the 390-> means that 390 is to be removed.  If there is a retail client with login 123456 the routing function will find it and check if it is currently registered to voipswitch. If the client is registered the voipswitch will try to send a call to its IP address and port.

In the case when a client is offline the system checks if there is a PUSH token for that client, if so a PUSH message is sent. If there is no response from the called endpoint the next step is to proceed with the Answering rules, unless the Disable answering rules option in the Special properties is on. In fact, the Answering rules are checked before call is sent to the user as there can be a Do not disturb action defined. 

If the number is not found among all logins from the clientsshared the voipswitch returns appropriate internal error.

Another option is to map the dialed number to a particular user. To do so choose the Retail client under the Route type and

under a Route field enter the login to make the system send all calls coming to the number defined in the Prefix field to that user.

If the entry’s prefix is too broad (too few characters) then all calls beginning with that prefix will be directed to the same client.

If you want to assign for example a DID number to the user you should enter the exact phone number as the prefix and then enter the login under the Route field.

Remember about the Routing plan rules modification options which change the number before its matching login is looked up for.

Voipbox scenarios

Next route type is Voipbox. When selected, two additional properties are shown:

• Languages
• Scenario

Their values are passed to Voipbox application which then proceeds with selected scenario in given language. Voipbox scenarios can be used for various services for example voicemail, calling cards, balance announcements, top up account and many other.

When this route type is selected there is one additional setting in the Connection properties namely Send media before connect. When ticked, the voipswitch will send the media coming from Voipbox to the originating endpoint before the 200 OK, i.e. before the call is established.

Prefix based overflow

The routing function finds the best matching prefix. If a call cannot be completed through that route the routing function tries next matching prefix – which is the best matching from the other matching prefixes excluding the one which failed.

For example you can add two routes, one with prefix 4860 and the other with prefix 48. A call to number 486002334455 will be first routed through the more detailed prefix 4860. If for some reason the route returns an error the system will attempt the next route with more general prefix 48. An example is when you are connected to a carrier that offers you termination to whole country (48 prefix is for Poland) but for some particular mobile prefixes you have cheaper termination through another carrier. In that case you accept higher cost when the preferred route (cheaper carrier) cannot complete the call.

Priorities

When there are two or more routes for the same prefix you need to use priorities. Priority 0 is the highest one. Next routes should have higher numbers.

When you add a new entry with a prefix that already exists you must choose the priority.

The routes with the same prefix are shown as one row in green color.

The priorities are important when for example you have a main route and a backup one. The main will have the 0 (highest) priority while the backup route will have 1 priority.

The priority based failover can be combined with the call overflow to routes with less matching (shorter) prefixes. For example:

48 priority 0 gateway A

48 priority 1 gateway B

4 priority 0 gateway A

4 priority 1 gateway A

This routing combines two independent failover groups.  The voipswitch looks for the best matching entry for the dialed number. Let’s assume it is Poland. The system tries first gateway A, if for some reasons it will fail the system will call gateway B which is the lower priority entry for the same prefix 48. If the second route also fails the system will check the routes of the higher level – for the prefix 4. The order is determined by the priorities for the prefix 4 and again we have two routes here with priorities 0 and 1.

Load sharing

Load sharing allows to distribute calls among multiple routes of any type. Each route belonging to the load balancing group has a property that defines the share, in percent, that will be sent through it.

Setting the load sharing requires two steps. For example if you have two gateways – gw1 and gw2 for prefix 44 first you need to add an entry for gw1. Then add a new route for the same prefix in the new route window, choose a gateway route type and from the list of destinations pick the gw2. Then click Save button.

Set the Balance sharing for each gateway by setting the percentage of the share for each gateway. The sum of the shares must equal 100%.

Entries for the same prefix grouped in a Balance sharing are shown in green color. 

Voipswitch draws a route using a probabilistic procedure with weights which ensures the correct distribution of calls over time.

The load sharing groups can be put in hierarchical order for example:

prefix 48 priority 0 25% A
prefix 48 priority 0 75% B
prefix 4 priority 0 50% E
prefix 4 priority 0 50% F

First two routes are for prefix 48 so first a call will be sent through either A or B. The probability weight make the system tends to choose the B route more often so it will cover 75% of the total calls.

If a call to A or B fails the system will look for a next available route which is this example is a load sharing group with prefix 4. As the destinations E and F have the equal share 50% each, the voipswitch will draw between them and send the call to either E or F.  Each of the two load sharing groups are treated separately, i.e. number of calls made through A or B does not influence the distribution for E and F.

Time span

Each routing plan entry can have a time span set which defines on which days of a week (From day, To day) and between what hours (From hour, To hour) the particular route is active and can be used. The entries which are not active at the moment when a call arrives are skipped.

This could be useful when some carriers offer cheaper rates at given periods only. Beyond the periods you may want to use other carrier.  

Time intervals which include midnight, e.g. 22:00 (10 PM) - 06:00 (6 AM), must be set as two separated entries in the dialing plan: first 22:00 - 24:00 and second 00:00 - 06:00. This is necessary for VoipSwitch to interpret the information properly.

Headers modification

FROM header parameters manipulation

Caller ID and Display name – allows for modification these two parameters which are in the FROM header in SIP requests. The header describes the initiator of the request. It consists of the SIP URI for example 1234@mydomain.com, which is the client login (user) and domain or IP of the server, and optionally the display name which carries a friendly name for example Peter. 

FROM: “Peter” sip:1234@mydomain.com;

Voipswitch enables modification of the user part of the SIP URI and the Display name. Click on the extended menu button on the right. A new window will appear which allows for changing the prefix, adding suffix and controlling the length of the parameter.

Dialed number manipulation

The dialed number specify the recipient of the request. Despite the used name it does not have to be a number, just any string that is the user identifier – the user part of the SIP URI. This parameter is carried in the TO header and the request line of SIP request.

Retail client route type

There is a distinction in handling this field depending on the route type. If the route type is a Retail client (a user) then the SIP URI in both request line and TO is the URI taken from the Contact header of the REGISTER packet of that user. Even if you call a number, for example 223344 which is mapped to a retail client e.g. user1 the request line and TO will be replaced with the SIP URI from registration and which is most likely user1@domain.com

If you set the dialed number rules in the routing plan the behavior of the voipswitch will change. Instead of sending the SIP URI from Contact, the original TO and request line parameter, in this case 223344 will be modified according to the defined rules and send in such form to the endpoint.

Other route types

For other route types the dialed number will be always changed according to the rules and then sent further in both TO and request line.

Field rules – advanced header manipulations

Besides the dialed number manipulation and FROM manipulation where you can use only simple transformations there is also an Advanced header manipulation which allows for modifications of any of the SIP headers coming in an INVITE request. Different rules can be applied per routing plan entry, changing the selected header or headers before the new INVITE is composed and sent to the destination route. The rules can program the system to change the order of the particular header parameters, remove some parameters or replace them with parameters from other headers of the same INVITE.

Header definitions

First you have to define which of the headers should be modified and associate them with a regular expression which will be used to split the header string into smaller parts (groups).

The definitions are stored in the fields_definitions table in voipswitch schema. The regular expressions are stored in the regex column and the output variables in the tokens.

By default there are field’s definitions for the following headers:

P-Asserted-Identity

Remote-Party-ID

From

The From header can have two forms From: or f:  which is reflected in the field name - From;f.

The list can be extended by adding new field definitions. To do so you need to work directly on the database.

When an INVITE request comes in the voipswitch checks the header names and compare with the ones defined in the field_name. If there is a definition for a particular header the voipswitch executes the associated regular expression and splits the header string into parts (groups) and copy them to the variables from the tokens column.

The general expression to split a SIP header into groups is 

For example P-Asserted-Identity header is composed of 3 parts: paid1, paid2, paid3.

For example:
P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@vovida.org>

paid1 is "Cullen Jennings"
paid2 is fluffy
paid3 is fluffy@vovida.org

Another example is the expression below which splits the header into 5 groups:

Each parenthesis in the expression marks a single group so consecutive groups are:

Those groups are respectively tagged by the tokens, in this case they are paid1, paid2, paid3, paid4, paid5.

When you apply the above regular expression to the P-Asserted-Identity field:

as a result you will get the following groups:

1. paid1:

1. paid2:

1. paid3:

1. paid4:

1. paid5:

A new regular expression can be validated using the following tool  http://www.regexplanet.com/simple/index.html.

Adding/modifying the rules in the database

The following example query allows to modify the table entry with id=3 by changing the regex and tokens values.

The query below shows how to add a new record to the table.

The Field_type value should always be set to 0.

Using header rules in the routing plan

Field (Advanced header manipulation) rules can be applied through the routing plan. A rule or rules can be set separately per each route. In the advanced tab there is Advanced header manipulation text area where the fields rules can be defined.
The variables (tokens) can be used with a t[token] syntax.

The following example shows a proper syntax of a field rule entry:

Before sending the INVITE request to the destination route, voipswitch composes new P-Asserted-Identity header according to the rule set. The variables in the rule above are replaced with the actual values. Variables can be part of the same header, in this example it is paid1 and paid3, or be part of another header which has been decomposed to tokens, like fm3 which is part of FROM header.

If one or more of the tokens used in a rule are not available (i.e. the parsing procedure did not return the relevant part) the whole rule will not be applied, in effect the header will not be modified. To avoid this situation you can use an OR operator. The operator allows to create compound rules. For example multiples rules for the same header can be connected with OR. If the first rule fails the one after the first OR will be executed.   

Adding parameters

You can add new parameters to the header like in the example below. They have to be separated by semicolon.

Remote-Party-ID header is extended by party=calling, privacy=off, screen=yes parameters.

Because the Remote-Party-ID mechanism doesn't have an RFC status, it is recommended to use the P-Asserted-Identity instead.

Modifying Caller ID (CLI)

It is often necessary to modify the CLI of a call before it is sent to external network. Internally we may use Display Name part of the FROM header which purpose is to carry a user friendly name. While it is usually supported by VoIP devices the Display Name is often ignored by the PSTN carriers. Instead the Display Name they will show the user part of the SIP URI as the CLI. If the user part is not a number the CLI will not be presented.

Changing the FROM User part with Display Name

Below is an example FROM header:

    From: "48656328746" <sip:karbtom2@37.28.157.2>;tag=086aaf12405f466fbf0f19f99ataga30

The header is decomposed to the following tokens:

    t[fm1]  = "48656328746"

    t[fm2]  = 48656328746

    t[fm3]  = karbtom2@37.28.157.2

    t[fm4]  = karbtom2

    t[fm5]  = 37.28.157.2

In order to copy the Display Name to the user part of the SIP URI we have to put the following rule into the Advanced header manipulation field in a Routing plan entry:

    From: t[fm1] <sip:t[fm2]@t[fm5]>

Adding display name

If there is no Display Name we may want to use the user part from the SIP URI.  Below is an example FROM header:

    From: <sip:karbtom2@37.28.157.2>;tag=086aaf12405f466fbf0f19f99ataga30

Tokens:

    t[fm1]  = (empty)

    t[fm2]  = (empty)

    t[fm3]  = karbtom2@37.28.157.2

    t[fm4]  = karbtom2

    t[fm5]  = 37.28.157.2

Put the following rule in the Advanced header manipulation field:

    From: "t[fm4]" <sip:t[fm3]>

Combining two rules

If you want both of the rules use the following syntax:

 From: t[fm1] <sip:t[fm2]@t[fm5]> OR "t[fm4]" <sip:t[fm3]>

 If the fm1 token is null (missing Display Name) the first rule fail and the second one will be applied.

Non-standard SIP headers

By default voipswitch does not forward non-standard headers like:
P-Asserted-Identity or Remote-Party-ID. 

If you want them to be passed to destination create a rule, for eample:

P-Asserted-Identity:sip:t[paid3]

For Remote-Party-ID you can either create a rule or, if the destination is of gateway type, tick on the Send Remote-Party-ID checkbox in the gateway definition.

To define field rules using a non-standard field, e.g. to define the From using the P-Asserted-Identity, the softswitch has to be forced to forward the non-standard headers first. This can be achieved building the non-standard field before the desired one.

Extended field definitions list

The below query adds three additional headers – Contact, Diversion and To (t).

Other routing properties

Other routing properties are grouped under the special properties option.

Prefix disabled – the routing plan entry with this checkbox ticked will not be included in the list of routes

Do not jump – the failover procedure will stop on this route, will not proceed further if a call fails. The client (caller) will receive an error response

Disable Answering rules – available only for Retail client route type. When a call fails the system ends the call without processing the Answering rules of the called client.

Calls limit - a decimal value which sets the maximum number of calls connected and/or connecting through a route. When Calls limit is set to 0, there is no limit, any other value means the number of calls is limited.

Importing/exporting routing plan

The Routing plan can be imported from a CSV file prepared beforehand. Click on the New button and then in the menu choose the Import function. A new window will appear allowing for picking a file.

The easiest way to make sure that the format is correct is to export a sample file first (click on More/Export) and build a new file on the basis of that file.

The file format is as in the below example.

Note: The tech_prefix values have to be put in quotation marks.

Route types and ID route

When a file is prepared manually you need to know the IDs of route types and particular routes IDs. These information are stored in the database. Below is a reference showing which tables store information on a given route type.

The routing plan can be exported to a CSV file. Click on More button then Export.

In the popup window choose  use download option or Show details.

LCR based on cost tariffs

Least Cost Routing is a possibility to choose the routing of outbound traffic based on cost. It can be done manually, that you periodically (monthly, weekly or even daily) choose between routes from different carriers for destinations across the world. That process can be also automated by a software function that checks the cost rates assigned to the carriers and modify the routing plan accordingly.

In voipswitch the LCR function is based on groups of entries for the same prefix, each with different priority and pointing to different carrier. Each of the carriers has to have the cost tariff assigned. The LCR function runs periodically and modify the priorities so that the cheapest route for the given prefix is set as first (0 priority), then goes the more expensive and so forth until the most expensive one which is set as last route.

Groups of entries with the same prefix but different priorities are marked as failover groups.

Note: the LCR cannot be activated for the groups with Load Sharing. A group must be of the Failover type.

Note: The LCR works only for the destinations of type gateway. Moreover each gateway has to have a cost tariff assigned.

To enable LCR for all or some of the entries from the group extent the failover group to see all the covered entries, then tick the checkboxes on the left for these entries which should be controlled by the LCR function.

A confirmation window will appear followed by the summary report.

If we press on Show details, we will see a detailed report:

Now the entries in the Routing Plan are shown with the green ON icon in the LCR column.

When a cost tariff for any of the gateways included in the LCR changes you should run the LCR set up function which updates the priorities. Click on More button then Check LCR. A new window will appear where you can put the prefix or prefix ranges for which the LCR function will compare the cost rates. You can leave this field empty, in this case the LCR will be checked for all prefixes.

Next window shows the changes in priorities which came out as a result of the LCR set up function. You can see the “old priorities” and next to it the proposed order. You will receive informations about the prefix that are missing in destination tariff.

Routing based on CLI

Voipswitch allows for specifying different routes depending on the CLI of the calling user. It is useful if you want to send all calls coming from certain network only, for example from a certain mobile operator, to a different carrier than the other traffic.

The CLI based routing function combines the CLI with the dialed number and passes the output string as the dialed number to the routing procedure.

The function can be used for wholesale and retail type of clients.

Below example shows how to modify the dialed number used further in the routing procedure.

In the Dialing rules field enter the following instruction:

It will add to the dialed number the first 3 digits from the caller id and then append 22. The result will be processed by the routing procedure.

Some more example below:

TO DO - VSM4-40 - Getting issue details... STATUS

Generator

The generator creates new routing plan entries based on the defined destinations - Gateways and Registrars, and their cost tariffs.

This tool is very useful when you want to add a new carrier which supports various destinations (countries or areas). In that case you would have to add entries for all interesting prefixes one by one manually. Using the generator you need to define the routing properties only once and then they will be copied for all entries for that gateway. The prefixes for the entries will be taken from the cost tariff assigned to the gateway. The procedure can be executed for a single carrier or several carriers in one run.

To start the process click on the Generate button in the Routing plan screen.

In the window you can select either standard or LCR based generation.

Standard generation

The next window lets you choose the destinations which will be included in the newly created routing plan. Only those with assigned tariffs will be shown here. 

Clicking Next will open a window where you can set routing properties for each of the selected destinations. The properties will be used for creating new entries in the Routing Plan.

The next window allows to select prefixes from the cost tariffs for which new Routing plan’s entries will be added.

You can choose to use all prefixes from the tariff or use expressions which filter the required prefixes and allow to specify particular prefixes or their whole ranges. Below are some examples:

• "501*" returns all prefixes starting with "501" such as "501103103"
• "#{44-46}32*" is the same as the three expressions: "#4432*", "#4532*", "#4632*"
• asterisk * - allows using broader queries returning prefixes starting with the given characters, e.g: 48* - returns all prefixes starting with 48, such as 48, 482, 485, 4822 etc.
• braces symbols {} - allows searching for a range, e.g: 44{0-2} returns prefixes: 440, 441, 442; when combined with the asterisk symbol * it will match any variations of these 3 prefixes.

Note: When some prefixes are results of more than one expression, the prefix will be added only once.

When adding new expression click on the Search button to test and see the results. Then click Add to add the expression to the list of all expressions which will be used to build the whole result set.

Next screen presents three options specifying the behavior when there is already an entry for the same pair of the prefix and the destination.

The generator can simply create a new entry with the same prefix and destination – still some of the settings may differ. Another option let it just skip this prefix. The last option updates the existing entry and copies the route settings defined in the generator.

Before commencing the action there is a summary window showing the following numbers:

• Number of destinations selected for dialing plan creation
• Number of prefixes (defined by expressions or not) which will be created for each destination
• Number of dialing plans, which is a product of the multiplication Number of destinations and Number of prefixes and describes the total number of dialing plan routes for creation

If all agrees click the Generate button.