Here is a custom made guide for using translation rules/profiles. I have explained the concepts of the rules/profiles and then given some common uses of them.
TRANSLATION RULES/PROFILES
========================
Translation rules/profiles can be used to modify the calling/called number.
There are 3 steps involved:
1. Create the master translation rule and sub rules.
2. Create the translation profile and associate a master rule to it.
3. Apply this translation profile to a dial peer or an interface.
Translation rules: These are created in the following format:
Voice translation-rule 1 <<<<Master rule 1
Rule 1 /9911/ /911/
Rule 2 /1234/ /7890/
Rule 1 and rule 2 under voice translation-rule 1 are sub-rules. For all intents and purposes, it is the Master rule which needs to be unique i.e. the “tag” of designating it as “master rule 1” means that there should not be any other rule with the same tag of “1”. Master rules can use any tag, as long as they are unique but sub rules will always begin at rule 1 and end at rule 15.
The “/” character that you see is called a delimiter which signals the start and end of the “match pattern” and the “replacement pattern”. Hence, in the examples given above, /9911/ and /1234/ are the match patterns. The replacement patterns are /911/ and /7890/. Hence, sub-rule 1 effectively means that if anyone dials 9911, it should be changed to 911 and then sent out. Rule 2 means that if anyone dials 1234, it should be changed to 7890 and then sent out.
Translation rules use wildcards and regular expressions. These have different meanings, some of which are given below:
^ -> This wildcard means “anything beginning with”
. -> Means a single dialed digit
* -> Means one or more instances of the previous character
/ -> As explained before, this is a delimiter
\ -> Means strip all the characters before this character.
(1234\) -> Place the characters within brackets in a set. This is a combination of () and \.
T -> A wildcard which means any number of digits.
Examples:
/^9…/ /1234/ -> Means any number beginning with 9 and followed by 3 digits should be replaced by 1234. Hence if you dial 9555, it will be changed to 1234.
/.*/ /2122/ -> Means any dialed number should be changed to 2122. Note that .* is a combination of 2 wildcards and combined they mean “any dialed digit”.
/^022\(…\)/ /2\1/ -> This wildcard requires some explanation. The (…\) in the match pattern means “any 3 dialed digits should be placed in a set, and it should be designated as Set 1”. The ^022\ means any number beginning with 022 should have 022 stripped off from it. Hence, taken together, the match pattern means “any number beginning with 022 and followed by 3 digits should have 022 stripped off from it and the remaining 3 digits taken as Set 1.”
In the replacement pattern, the \1 means place Set 1 over here. The 2 is a prefix to Set 1. Hence the replacement pattern means “keep set 1 as it is but prefix the number 2 before it and send the entire number out”.
Hence, if someone were to dial 022456, the 022 would be removed and 2456 would be sent out since we are prefixing the 2 before 456. Remember that there are multiple ways of getting the same end result. Use what works best for you.
TRANSLATION PROFILES
===================
A translation profile is nothing but a collection of master translation rules. The profile is created in the following way:
Voice translation-profile test
Translate called 1
Translate calling 2
This means:
Create a translation profile and call it test.
Look at master rule 1 and let the match pattern apply to the called number.
Look at master rule 2 and let the match pattern apply to the calling number.
An example:
Voice translation-rule 1
Rule 1 /^9\(…….\)/ /408555\1/
Voice translation-rule 2
Rule 1 /.*/ /9194251234/
Voice translation-profile test
Translate called 1
Translate calling 2
All this effectively means:
Under master rule 1, if there is any number that is beginning with a “9” and having 7 digits after it, strip the 9 off and place the 7 digits in Set 1. Prefix the 7 digits in set 1 with 408555 and send it out.
Under master rule 2, any number should be changed to 9194251234.
As is evident from the translation profile, the number being translated can be either the calling or the called number (there are more options, but we won’t get into those right now). Hence, in this scenario, we have let CME know that master rule 1 should be applied on the called number and master rule 2 should be applied on the calling number. Master rule 1 can be used if 7 digit dialing has been replaced by 10 digit dialing, but the users are still in the habit of dialing 7 digits and not 10. Master rule 2 is a common practice for outgoing caller ID.
APPLICATION OF TRANSLATION PROFILES
=============================
Translation profiles need to applied for them to take effect. This is perhaps the most important step of all since application of the translation profiles should be correct in order to achieve the desired results. 90% of the time, translation profiles are applied to either a dial peer or an interface. Examples are given below:
Dial-peer voice 100 voip
Translation-profile incoming test
Dial-peer voice 101 voip
Translation-profile outgoing test
Translation profiles can be applied in the incoming or the outgoing direction. This, along with the application of rules on the calling and called number serve as a powerful tool for digit manipulation. Permutations and combinations abound and to fully understand the use of translation rules/profiles one has to put them in use and learn through trial and error.
NOTE: You can create a rule and test it out before assigning it to a profile and applying it to an interface. The CLI command for that is “test voice translation-rule 1 XXXXXXX” where XXXXXXX is the number you want to test out.
A BRIEF EXPLANTION OF DIAL PEERS
============================
Dial peers are the brains of the phone system. A dial peer determines where should calls go and moreover, which dialed numbers to match. Digit manipulation can be done in dial peers through the use of translation rules/profiles. There are 2 types of dial peers which are generally used : Voip and pots. Perhaps these are best explained through examples:
Dial-peer voice 1 pots
Destination-pattern 91[2-9]..[2-9]……
Forward-digits 11
Port 0/1/0
Explanation:
A pots dial-peer is created through the command “dial-peer voice XX pots” where XX is a tag assigned to this dial peer. It doesn’t really matter what the tag is as long as it is unique. Pots dial peers are used when connecting to any analog interface. Examples are: FXO and FXS ports, T1 links. T1 might be digital, but for the VoIP phone system, it represent a traditional telephony system and hence is designated as a Pots connection.
The “destination-pattern” is responsible for matching dialed digits. This uses wildcards as well, although some of the wildcards are different from the ones used in translation rules. In the example above, [2-9] means any digit between 2 and 9. Hence, the string 91[2-9]..[2-9]…… represents 11 digit dialing in the United States. The number 9 is used for an outside dial tone, 1 representing a Long Distance number and the remaining 10 digits.
The pots dial peers strip off any explicitly matched digits. Hence, in this example, 9 and 1 are digits which have been matched explicitly but the remaining are wildcards. The phone system will strip off 9 and 1 from the number by default and send the remaining numbers out. We want to strip the initial “9” off since that is just an outside access code, but we don’t want to strip the “1” off since the Service Provider is looking for that 1 to route the call. Hence we put in the “forward-digits 11” command which means forward the last 11 digits. This means that it will send out everything except the 9 since it is forwarding the LAST 11 digits.
Finally, we come to the “port” command which tells the phone system which port should it send the call out through. Calls can be sent out through FXO, FXS and T1 lines and all these have ports designated to them. T1 lines have ports in the format 0/1/0:23 whereas FXO and FXS ports are in the format 0/1/0. This is essential to tell the phone system which port to send the call out through.
There are a number of options under the dial peer configuration, but this is what is used most of the time. Let’s get to voip dial peers:
Dial-peer voice 10 voip
Destination-pattern 9[2-9]..[2-9]……
Session target ipv4:<IP address>
Codec g711ulaw
Explanation:
A voip dial peer is created in a similar way to a pots dial peer, except for the “voip” keyword at the end of the dial-peer voice XX command. Rules for the destination-pattern remain the same, but a VoIP dial peer DOES NOT strip off any digits before sending the number out. Hence translation rules/profiles need to be applied in order to strip the digits off. A simple rule of thumb – anything that is not POTS will generally be voip.
A voip dial peer does not have a port command associated with it since it does not relate to a port in any way. Instead, voip dial peers use IP addresses to route calls and these are routed using the “session target ipv4:” command. DNS can also be used for this with the command “session target dns:”.
Voip dial peers have an option of hard-coding the codec in use. By default, the CME system will use G729 as the codec, but circumstances might require you to manipulate the codec under the dial peers. A classic case of changing the codec under the dial peers is when sending calls to Unity Express. Unity understands the following parameters:
1. SIP
2. A codec of g711ulaw
3. No VAD (Voice Activity Detection)’
To make a dial peer realize that it needs to use the SIP protocol, we use the command “session protocol sipv2”. To change the codec, we use “codec g711ulaw”. To turn off VAD, we use “no vad”.
SCENARIO:
Let’s discuss modifying the extension that is called i.e. we will configure incoming call routing:
Here are our ephone-dns:
Ephone-dn 1
Number 2000
Ephone-dn 2
Number 2001
Ephone-dn 3
Number 2002
We assume that the Provider has given us 3 DIDs – the numbers are 4805552000, 4805552010 and 4805552020. Here is the way a phone should ring when a call comes in:
4805552000 should ring extension 2000
4805552010 should ring extension 2001
4805552020 should ring extension 2002
Furthermore, we assume that the Provider is sending us the last 4 digits. Hence, the provider will send us 2000, 2010 and 2020.
Notice that for extension 2000, the last four digits match the digits that the Provider sends. Hence, we don’t need to apply translation rules/profiles for this.
For the 2010 and 2020 number, we apply the following translation:
Voice translation-rule 1
Rule 1 /2010/ /2001/
Rule 2 /2020/ /2002/
Voice translation-profile for_2001_2002
Translate called 1
Exit
Post this, we need to figure out which incoming dial-peer is getting hit. In most cases, this can be checked by the “debug voice ccapi inout” command and then running a search for “incoming dial-peer”. This will let us know the dial-peer that is getting hit and we apply the translation on that dial-peer as follows:
Dial-peer voice 100 pots
Incoming called-number .
Translation-profile incoming for_2001
Port 0/1/0:23
Remember that the translation rules will only come into effect if the correct dial peers are matched and the profile is placed on the same dial peer. Alternatively, the profile can be placed on the voice-port as well, but this will apply to the entire phone system. The command remains the same.
Depending on the number of digits sent by the Telco, we can modify the match pattern (i.e. the 2010 and 2020 portion) and have it ring the same extensions or any other extension that we choose.
(The best way to check how many digits are being sent by the Telco is to enable the “debug isdn q931” for a PRI and check the called number field)
FOR OUTGOING CALLER ID:
Let’s take the case where there are a total of ten DIDs given by the Service Provider (404-555-2000 to 404-555-2009). We want the last five DIDs to display their individual caller IDs but the rest of the DIDs should display the company number of 404-555-2000 while making an outgoing call. Here is the configuration:
Voice translation-rule 100
Rule 1 /\(200[56789]\)/ /404555\1/
Rule 2 /.*/ /4045552000/
Voice translation-profile outgoing_clid
Translate calling 100
voice-port 0/1/0:23
Translation-profile outgoing outgoing_clid
Explanation:
In rule 1, [56789] means any ONE of the numbers given within the brackets. Hence, this rule encompasses 2005, 2006, 2007, 2008 and 2009 (i.e. the last 5 DIDs). It is assumed that the internal extensions are in the 2000-2009 range and hence, by default, the caller ID sent will be the extension itself. Therefore, this rule places the entire extension in SET 1 and prefixes 404555 before sending it out.
Rule 2 will be matched if rule 1 is not matched and this effectively means that if any other extension dials out, the caller ID will be 4045552000.
Hence, our requirement of the last 5 DIDs sending their own number and the rest sending the company number is satisfied.
