Skip to main content
Biamp Systems

XML Files for Number Normalization Rules with Tesira VoIP & Lync

Note: This is a draft article. It is still in the process of being written, and therefore may not be complete or 100% accurate. Please keep this in mind while reading and using the information in this article. We should be done soon!

This article describes/explains...

XML file process to add Normalization Rules for E.164 Dial Plans in Lync

The purpose of this document is to assist in implementing the requirements for dialed Number Normalization Rules in Tesira VoIP when required by a customer's Lync environment. 

At this phase the technicians will have coordinated with their customers on providing the normalization rules that  are to be added to the Tesira VoIP configuration as defined here in our customer facing documentation.

At this stage we are now going to work with the technician to finalize their configuration. This will require the following steps:

  1. Create a bsip000000000000.xml file with Tesira VoIP normalization rules defined
  2. Load the VoIP card with the bsip000000000000.xml file via TFTP server
  3. Test the normalization rules individually to validate they are dialing as expected

Create a bsip000000000000.xml file with Tesira normalization rules defined

Requires modifying our stock template file to add customer's normalization rules

Using the attached bsip000000000000 file we will modify this file to match the customer's normalization rules.

To do this you will use the program XML notepad which can be downloaded from Microsoft- here

Once the file is opened inside of XML notepad you will see the following:

 

There are two lines on the VoIP card- Each line allows for four lines of rules, with 80 characters per line, total of 320 characters allowed. Line 1 will be defined by rules 11/12/13/14 and line 2 by rules 21/22/23/24

Tesira VoIP shall use one or more vertical bars to separate rules.  If users just need a number pattern and translation rule, the separator isn’t needed.

For example: 

^(\d{4})$:+1425555$1|^5(\d{4})$::+1425555$1||^(\d{7})$:::+1425$1

Using the customer's provided Normalization rules we will need to add these to the XML file on the appropriate line to define the rules for the VoIP card.

Here are some basic rules as example.

The table below gives some examples and explanations about the rules.

Use case

Number pattern

Translation

Example

Translates 4-digit extensions

^(\d{4})$

+1503718$1

1234 is translated to +15037181234

Translates 5-digit extensions starting 5

^5(\d{4})$

+1503718$1

51234 is translated to +15037181234

Translates 7-digit numbers

^(\d{7})$

+1503$1

7189238 is translated to +15037189238

Translates 10-digit numbers

^(\d{10})$

+1$1

5037189238 is translated to +15037189238

Translates numbers with long distance prefixes

^1(\d{10})$

+$1

15037189238 is translated to +5037189238

Translates numbers with international prefixes

^011(\d*)$

+$1

011915037189238 is translated to +915037189238

Translates 0 to an operator

^0$

+15037180100

0 is translated to +15037180100

Translates numbers with prefixes

^5678(\d{4})$

+1503718$1

56781234 is translated to +15037181234

Here is a completed file using the dial plan normalization rule examples:

 

.NET framework as regular expression

 

Tesira VoIP shall follow .Net framework regular expression to create matching rules and is a subset of .Net framework regular expression.  Users can create multiple number pattern and translation rules.  The number pattern and translation rules shall be separated by one or more colons. For example, ^(\d{4})$:+1503718$1 and ^(\d{4})$::+1503718$1 shall be identical. The number pattern and translation rule must be present as a pair. If users dial a number 9238, the number will match the pattern mentioned in the example, Tesira VoIP will follow the designated translation rule and translate the dialed number to +15037189238 and send it to its server. This spec doesn’t want to become a tutorial for regex.

The below gives some basic information:

  • \d - Matches any decimal digit
  • ^ - The match must start at the beginning of the string
  • $ - The match must occur at the end of the string
  • (subexpression) - subexpression
  • {n} - Matches the previous element exactly n times
  • $number - the substring matched by group number

Subexpression definitions

 

A parenthesis - (subexpression) constructs an expression group or subexpression.

Users must construct the expression specifying what we want to match and translate.  In phone number normalization application, we don’t allow for the use of more than a single subexpression. The $1 in the translation rule is the first matched subexpression result. The matched sub-expression result will be translated accordingly.  If no match is found, the number will stay as is.

 

  • If a rule ^5(\d{4})$:+1503718$1 is configured and users dial 51234, this number will match the pattern, the matched subexpression result is 1234, a.k.a., $1. The translated number is +15037181234. The point to be made here is that only matched subexpression will be taken care and translated. If users dial 41234, the number won’t match this pattern.
  • If a rule ^(\d{4})$:+1503718$1 is configured and users dial 1234, this number will match the pattern, the matched subexpression result is 1234 ($1). The translated number is +15037181234.

 

No Subexpression is defined

 

Users may not create a subexpression. In this case, the matched sub-expression result sign ($1) must not be present in the translation rule. If the dialed number matches the pattern, the number will be translated to the number in the translation rule exactly.

 

  • If a rule ^654321$:+15037181234 and users dial 654321, this number will match the pattern. The translated number is +15037181234. The point to be made here is that only matched subexpression will be taken care and translated. If users dial 41234, the number won’t match this pattern.

Loading a VoIP card with the XML file via TFTP (Static Provisioning method)

This procedure can be performed locally from the a PC directly to the VoIP card, however to Perform this you will need to download a TFTP freeware and install to the local machine.

To avoid networking issues using the customer network for this procedure it is recommended to perform this process over a direct connection from the VoIP card directly to the PC using static IP settings. This streamlines the host of network variables that could interfere with the file transfer. Though this file transfer technically could be performed on a customer network  supporting TFTP,  the process of using static IP addressing with connectivity directly connected between devices would be the most controlled method for this single use case deployment.

Free application for this are:

Solarwinds free TFTP

TFTPD32

With one of the TFTP clients installed, the PC will now be able to act as the TFTP server for this transaction. Confirm you are running the 2.4 software and 2.4.4 beta firmware before proceeding.

  1. Create a folder on the desktop for the XML file to be located
  2. Place the XML file to the new folder on the desktop
  3. Open the TFTP software and point the TFTP directory location to the new folder location on the desktop where the XML file is located by going to the File and sekect configuration, from here you can assign the XML directory folder. Start the TFTP service.

 

 

  1. Next, confirm the IP address of the VoIP card. The VoIP card IP address needs to be in the same subnet (IP range) as  your PC and may need to be set statically to a temporary IP address during this configuration so that is the same subnet as the control and PC network. Once completed with loading the XML file the VoIP card network settings can be reset to DHCP or the customer provided static address. The goal here is to create an isolated network for the VoIP card and your PC to complete the TFTP process, if you have a small unmanaged network switch you could additionally place the Tesira Control NIC onto the same subnet and have it participate in the ad-hoc configuration network to streamline the process.
  2. Configure the VoIP card to run static TFTP provisioning, this will tell the card to retrieve and run the XML file from the TFTP server hosted at your PC' static IP address. Now set Tesira TFTP provisioning to your PC's IP address as shown below:

 

TFTP location settings can be found in the Properties Sheet of the VoIP Control Status Block.  They are located in the DSP Attributes tab under Network Provisioning Server.  

Static Configuration
  • Change the TFTP Server Mode to Static
  • Enter the static IP or Hostname in the popup window and click OK. 
  • You should see the static address in the Properties Sheet (See Below).

 

TFTP Static

Static TFTP Configuration

 

  1. Resend the updated configuration into the Tesira with TFTP provisioning enabled and defined as described previously.
  2. Set the PC hosting the TFTP server to the same LAN as the VoIP card.
  3. Disable the Windows Firewall from running
    1. Go to Control Panel
    2. Windows Firewall
    3. Choose "Turn Windows Firewall on off" From left side of the screen, and select Firewall Off option.
  4. Set the TFTP software to use the NIC for the server interface as defined in previous step.
  5. Unplug the VoIP card network connection, and reconnect it back to the PC (provisioning LAN) which will restart the VoIP card and initiate the card to pull the configuration file via TFTP
  6. Confirm using the TFTP logviewer on the TFTP client that the VoIP card received the XML file, you will see a completed indication in the log:
  7. Disable TFTP provisioning from the VoIP control status propeties
  8. Resend the Tesira configuration
  9. Re-apply original network and Firewall settings to PC, Tesria, and VoIP card.

Alternative TFTP (non-static provisioning) load using VoIP debug console via Telnet  

This method does not require static provisioning be enabled in the VoIP status DSP properties. In this case you will create a telnet session to the VoIP card and force it to take the file from the TFTP server location specified. The difference here is that the file name needs to be using voip.cfg not bsip000000000000.xml, previous notes on TFTP software and firewall rules apply.

There have been some cases where the automatic TFTP won’t function, in that case you can do an alternate method of sending the file manually- The caveat is that the file name for this method prefers to be called voip.cfg not bsip000000000000.xml

Step 1

To begin create a folder named biamp on your desktop to be the directory folder of the TFTP software, place the bsip00000000000.xml in that location and rename it to voip.cfg, using cmd prompt from the PC follow these steps to rename it without the .xml extension-

dir

cd desktop

cd biamp

dir

rename voip.cfg.xml voip.cfg

dir

This last dir will show you that the file is renamed voip.cfg

 

Step 2

From the telnet session to the card and remove the existing files voip.cfg  and bsip000000000000.xml if they exist:

cd c:/

dir

rm voip.cfg

rm bsip000000000000.xml

Confirm there are no files on the card by issuing the command dir

Now tell the VoIP card to grab the file from the IP address of the TFTP location, if this is ad-hoc that is your PC LAN IP address, make sure the TFTP server is using the address of the wired LAN NIC not the Wireless interface IP, in the example below it is using IP 10.206.196.20 for the IP address of the PC hosting the TFTP software:

getfile -h 10.206.196.20 voip.cfg

You should see that transaction go through on the VoIP card as well as on the TFTP client, to confirm the file is on the card you can open and read the file on the card issuing the following command:

cat voip.cfg
 

 

 

 

Considerations    

 

Make Sure that that the TFTP logviewer is indicating that the file was sent. You may see errors, or you may have wrong file name and the card will reject the file.

Disabling the TFTP from provisioning after this procedure has been successfully implemented will increase the boot time of the VoIP card as it will not need to look for a configuration file during reset.

Normalization rules can sometimes be truncated to simpler rules that cover multiple rules- In the case where the customer will be exceeding the 320 character limit it may be possible to modify their rules into more succinct rules that have the same results.

Future Versions of Tesira software will support the adding of normalization rules through the software and will allow for a total of 48 rules. This process will be temporary until version 2.6

The systems up until and including Lync that are able to use the existing SVC-2 dial plan without the (+) symbol work because of prefixes being added by Normalization Rules.

Phone number normalization is the process of translating number strings (dial strings) that are entered in various formats into a single standard format.

 

Final Testing

Once completed with the loading of the XML configuration, the final step is to test the normalization rules to make certain they are valid.

If the rules do not match the number dialed will fail, and the dialer will issue a "Forbidden" message. Further analysis of the rules will be needed to see if the XML file was created correctly or if the customer dial plan rules are not accurately matching what we are needing to dial.

 

 

 

Further reading

 

 

  • Was this article helpful?