Voice Translation Rules and Profiles

You can accomplish more precise, granular manipulation using voice translation profiles, which contain voice translation rules. The techniques that were previously discussed can alter only the called number, or dialed number identification service (DNIS), digits. Translation profiles are much more powerful. They can change both the DNIS and the calling number, or automatic number identification (ANI), digits plus the redirecting number. With translation profiles you can adjust the numbering type and plan, reject unwanted calls based on a rule match, and remove specific digits (such as hyphens).

Note

A legacy technique called translation rules (without the voice) can manipulate ANI and DNIS numbers. This technique is still supported, but the recommended method is to use voice translation rules and voice translation profiles.

Using voice translation profiles for digit manipulation requires three steps:

Step 1.	Create one or more voice translation rules and a prioritized list of translations associated with each rule. A maximum of 128 rules is supported, with 15 translations per rule.
Step 2.	Create one or more voice translation profiles and associate the translation rules to the profile. You can define up to 1000 profiles, each with its own unique name. Within the profile, you can apply one voice translation rule to calling numbers, one to called numbers, and one to redirected called numbers.
Step 3.	Apply the voice translation profile to all VoIP calls globally, a dial peer, a voice port, a trunk group, a source IP group, or an interface.

Creating Voice Translation Rules

To create a voice translation rule, use the command voice translation-rule tag in global configuration mode. Then create an ordered list of one or more rules with the following command:

[View full width]

rule precedence /match pattern/ /replace pattern/ [type {match-type replace-type} [plan {match-type replace-type}]]

You can enter rules in any order; the precedence value determines the order in which the rules are executed. You can configure up to 15 rules.

A basic voice translation rule replaces one group of digits with another. Each group is delineated with // (frontslash) characters. In Example 10-3, voice translation Rule 1 replaces 111 with 222, and 333 with 444. A test of the translations shows that they are carried out as specified.

Boise(config)#voice translation-rule 1
Boise(cfg-translation-rule)#rule 1 /111/ /222/
Boise(cfg-translation-rule)#rule 2 /333/ /444/

Boise#test voice translation-rule 1 111
Matched with rule 1
Original number: 111 Translated number: 222
Original number type: none Translated number type: none
Original number plan: none Translated number plan: none

Boise#test voice translation-rule 1 13335
Matched with rule 2
Original number: 13335 Translated number: 14445
Original number type: none Translated number type: none
Original number plan: none Translated number plan: none

 

When the number 1335 is tested, notice that the number patterns are translated no matter where they appear in the string. Notice also that any digits that are not expressly matchedthe numbers 1 and 5 in this exampleare simply carried through. For more precise control, you can use some special characters and wildcards to build regular expressions, as shown in the next section.

Building Regular Expressions

A regular expression is a text-parsing tool that combines a string of literal characters and special characters, called metacharacters. Voice translation rules can use regular expressions to find matches in the digit strings, and replace a match with a different string. Table 10-2 lists some commonly used special characters and their meaning.

Table 10-2. Regular Expression Special Characters

Character	Meaning
.	Matches any single character
[]	Matches one number within the brackets; for example, the expression [234] would match either 2, 3, or 4
[^]	Matches a number except one within the bracket
-	Indicates a range of numbers when used within brackets
^	When used before a string, denotes the beginning of a string
$	Denotes the end of a string
*	Matches 0 or more occurrences of the previous expression
+	Matches 1 or more occurrences of the previous expression
?	Matches 0 or 1 occurrence of the previous expression (use Ctrl-v ? to enter in the IOS)
()	Groups digits into sets
	Changes the meaning of the following character
&	Brings all the matched digits into the replacement string

Previously in Example 10-3, the string 333 was matched even when it was in the middle of the list. If you wanted to match 333 only when it appeared at the beginning of a string, you could use the caret character:

rule 2 /^333/ /444/

To match a string containing only 333, add the dollar sign at the end and the caret at the beginning:

rule 2 /^333$/ /444/

 

Using Regular Expressions When Rerouting a Call over the PSTN

The real power of regular expressions comes from using them in more complex ways. One common use is when intrasite calls that would normally traverse an IP WAN must be rerouted over the PSTN. You must remove any private numbering, such as site codes, from the called number and format it for use on the PSTN.

In Example 10-4, a company has two locations in Maryland, USA. One has a site code of 758, and the other has a site code of 759. The remainder of intrasite the number is the last seven digits of the actual phone number. In the national numbering plan, the area code for both locations is 410. To route intraoffice calls to these locations over the PSTN, you must substitute the long-distance code and area code for the site code. In this example, the first four numbers are translated to 1410, but the rest of the number is left untouched.

Boise(config)#voice translation-rule 2
Boise(cfg-translation-rule)#rule 1 /^75[89](.*)/ /14101/
Boise#
Boise#test voice translation-rule 2 7591234567
Matched with rule 1
Original number: 7591234567 Translated number: 14101234567

 

To understand a regular expression, break it into its component parts and decipher each part individually. Breaking the match portion of Rule 1 into its component parts:

• ^75 are literal characters. The caret (^) designates the beginning of a string. This only matches a string that begins with a 7 and is followed by a 5.
• [89] matches a literal character 8 or 9. The brackets tell the router to match just one of the numbers that the expression contains.
• In (.*), the backslashes change the parentheses from literal characters to set-delimiters. The characters within the set are .*, which matches any character that is repeated zero or more times.

The following list breaks down the replacement portion of the rule into its component parts:

• 1410 replaces the initial literal characters.
• In the 1 part of the expression, the backslash changes the meaning of the digit 1. It is no longer a literal numberinstead, it points to the first set in the matching part of the rule. The first set is (.*). Thus, any digits matching that set are inserted after 1410.

Instead of replacing site codes, your gateway might need to add digits when it reroutes an intrasite call to the PSTN. One way it can do this is to create multiple dial peers, each with a destination pattern of a remote site, and then prefix digits. If PSTN calls to multiple locations will go out the same PRI, the gateway can accomplish this more efficiently by using a set of voice translation rules grouped under one translation profile. For instance, suppose that your company uses seven-digit dialing between three internal sites over your MPLS WAN. One site is local to you, but your phone company uses ten-digit dialing locally. The other two sites are long distance. You would need to add three additional digits to the called number for the local site, and the appropriate long-distance and area codes for the other sites. The original seven digits must remain unchanged.

Example 10-5 shows the voice translation rules to accomplish this for three sites in the United States. Numbers in the local site begin with 789, with an area code of 410. Numbers in one remote site begin with 123, with an area code of 212, and the other site begins with 456 with an area code of 617. The long-distance code is 1. Also shown in the example is the translation rules grouped under a voice translation profile; this could then be applied to the POTS dial peer pointing to the PRI. The section "Creating Voice Translation Profiles," later in this chapter, covers voice translation profiles in greater detail.

VoiceGW(config)#voice translation-rule 15
VoiceGW(cfg-translation-rule)#rule 1 /^789/ /410&/
VoiceGW(cfg-translation-rule)#rule 2 /^123/ /1212&/
VoiceGW(cfg-translation-rule)#rule 3 /^456/ /1617&/
!
VoiceGW(config)#voice translation-profile TO-PSTN
VoiceGW(cfg-translation-profile)#translate called 15
!
VoiceGW#test voice translation-rule 15 7891234
Matched with rule 1
Original number: 7891234 Translated number: 4107891234
Original number type: none Translated number type: none
Original number plan: none Translated number plan: none

VoiceGW#test voice translation-rule 15 1234567
Matched with rule 2
Original number: 1234567 Translated number: 12121234567
Original number type: none Translated number type: none
Original number plan: none Translated number plan: none

VoiceGW#test voice translation-rule 15 4561111
Matched with rule 3
Original number: 4561111 Translated number: 16174561111
Original number type: none Translated number type: none
Original number plan: none Translated number plan: none

 

Breaking the match portion of Rule 1 into its component parts:

• ^789 designates the literal characters 789 at the beginning of the string. This matches any string, of any number of digits, that begins with 789 so it will match the entire seven-digit called number.

Breaking the replacement portion of Rule 1 into its component parts:

• 410 tells the router to place the digits 410 at the beginning of the replacement string.
• & (ampersand) pulls all the matched digits into the replacement string.

The logic behind the other two rules is the same as Rule 1.

Using Regular Expressions to Delete Specific Digits

One of the company locations in Maryland, USA has a legacy PBX with a few users connected to it. Users in other company sites dial a site code of 758 to reach this location, and then a seven-digit number. The seven-digit number for PBX users begins with 4445. The PBX was programmed to expect to receive an incoming called number consisting of the site code and the last four digits of the phone number. So you must keep the site code, remove the next three digits (444), and keep the last four digits.

In Example 10-6, voice translation rule 3 accomplishes this by making the site code one set, and the last four numbers another set, but leaving the middle string of 444 out of any sets. It then tells the router to create a string consisting only of the two sets.

Boise(config)#voice translation-rule 3
Boise(cfg-translation-rule)#rule 1 /^(758)444(5...)$/ /12/
!
Boise#test voice translation-rule 1 7584445111
Matched with rule 1
Original number: 7584445111 Translated number: 7585111

 

Breaking the match portion of this rule into its component parts

• ^(758) creates a set that contains the string 758 at the beginning of the digit string. The caret designates the beginning of a string, and the backslashes change the meaning of the parenthesis from literal characters to set delimiters.
• 444 designates three literal number fours
• The last four digits are grouped into a second set with (5...). This set matches any four digits at the end of the string, if they begin with the number 5. The end of the string is designated with the character $.

Breaking the replacement part of the rule into its component parts

• In the expression 1, the backslash changes the number 1 from a literal character. In the translated number, it is replaced with the contents of the first set758.
• The expression 2 points to the second set. In the translated number, it is replaced with the contents of the second setin this example, the string 5111.

Using Regular Expressions with Sets and Replacement Digits

Notice that in Example 10-6, the middle string of 444 is not included in the replacement pattern. Suppose that the rule is changed to include a replacement for that string, as shown in Example 10-7. Now the translated number matches those three fours and replaces them with three sevens.

Boise(config)#voice translation-rule 4
Boise(cfg-translation-rule)#rule 1 /^(758)444(5...)$/ /17772/
Boise#test voice translation-rule 4 7584445111
Matched with rule 1
Original number: 7584445111 Translated number: 7587775111

 

Breaking the match portion of this rule into its component parts

• ^(758) creates a set that contains the string 758 at the beginning of the digit string. The caret designates the beginning of a string, and the backslashes change the meaning of the parenthesis from literal characters to set delimiters.
• 444 designates three literal number fours.
• The last four digits are grouped into a second set with (5...). This set matches any four digits at the end of the string, if they begin with the number 5. The end of the string is designated with the character $.

The replacement part of this equation can look confusing because there is no visual break between its three components, so it is important to understand how the router interprets it. Breaking the replacement part of the rule into its component parts

• In the expression 1, the backslash changes the number 1 from a literal character. In the translated number, it is replaced with the contents of the first set758.
• The next three digits, 777, are a literal replacement for 444.
• The expression 2 points to the second set. In the translated number, it is replaced with the contents of the second setin this example, the string 5111.

Using Regular Expressions to Change the Call Type or Numbering Plan

You can also match and replace the type of call, such as national or international, and the numbering plan, such as ISDN or national. For instance, the commands in Example 10-8 replace the string 011 with 1 and change the call type from international to national.

[View full width]

Boise(config)#voice translation-rule 4 Boise(cfg-translation-rule)#rule 1 /^011/ /1/ type international national plan isdn national ! Boise#test voice translation-rule 4 0115551212 type international plan isdn Matched with rule 1 Original number: 0115551212 Translated number: 15551212 Original number type: international Translated number type: national Original number plan: isdn Translated number plan: national  

In this example, the match and replacement expressions follow a slightly different pattern. This expression has three components:

• In the first component, /^011/ /1/, the number 011 at the beginning of the string is replaced with the number 1.
• The second component, type international national, replaces the numbering type international with national.
• The third component, plan isdn national, replaces a numbering plan of isdn with a national numbering plan.

For a call to be matched by a rule, it must fulfill all the conditions. In this case, the call must begin with 011, have a type value of international, and have a plan value of isdn. If any of these values is not matched, this rule will not process the call.

Creating Voice Translation Profiles

Voice translation rules are associated with voice translation profiles. Using a voice translation profile gives you flexibility and scalability by allowing the use of multiple voice translation rules. You can apply voice translation rules to called numbers, calling numbers, and redirected numbers in the same profile. A voice translation profile is typically associated with a dial peer, a voice port, a trunk group, or all VoIP calls globally.

Create a translation profile and enter profile configuration mode with the command voice translation-profile name. Then specify what type of number will be translated, and the rule to apply to that number. Example 10-9 shows a sample translation profile.

Boise(config)#voice translation-profile TEST
Boise(cfg-translation-profile)#translate ?
 called Translation rule for the called-number
 calling Translation rule for the calling-number
 redirect-called Translation rule for the redirect-number
!
Boise(cfg-translation-profile)#translate called 2
Boise(cfg-translation-profile)#translate calling 3
Boise(cfg-translation-profile)#translate redirect-called 1

 

In Example 10-9, translation Rule 2 is applied to called numbers, translation Rule 3 is applied to calling numbers, and translation Rule 1 is applied to redirecting numbers. You can apply the same translation rule to each type of number, if appropriate.

Applying Voice Translation Profiles

After you create a voice translation profile, you can assign it to a dial peer, a voice port, a trunk group, or all VoIP calls globally. Where the voice translation profile is applied affects the matching of inbound and outbound dial peers. A profile that is applied to a voice port is carried out before the inbound dial peer is matched. A profile that is applied to an inbound dial peer is carried out before the outbound dial peer is matched. A profile that is applied to an outbound dial peer is carried out before the call is transmitted. Be sure to take this into consideration when placing your voice profiles and configuring your dial peers.

• To assign to a dial peer Use the command translation-profile [incoming | outgoing] name in dial-peer configuration mode. A dial peer can have one incoming and one outgoing translation profile, as the following configuration demonstrates:

  Boise(config)#dial-peer voice 4 voip
  Boise(config-dial-peer)#translation-profile incoming TEST
  Boise(config-dial-peer)#translation-profile outgoing TEST
  

• To assign to a voice port Use the command translation-profile [incoming | outgoing] name in voice-port configuration mode. A voice port can have one incoming and one outgoing translation profile. Inbound profiles are executed before the incoming dial peer is matched. If the port is a member of a trunk group, the profile that you apply to the port overrides any profile that you apply to the trunk group. The following configuration demonstrates assigning a voice translation profile to a voice port:

  Boise(config)#voice-port 2/0:23
  Boise(config-voiceport)#translation-profile incoming TEST
  

• To assign to a trunk group You use the same command to assign a voice translation profile to a trunk group that you use to assign a dial peer or voice port: translation-profile [incoming | outgoing] name. All members of the trunk group inherit the voice translation profile, unless a different one is explicitly applied to a port or dial peer in the group. The command is given in trunk-group configuration mode, as the following configuration shows:

  Boise(config)#trunk group 1
  Boise(config-trunk-group)#translation-profile incoming TEST
  

• To assign to all VoIP calls globally To associate a voice translation profile with all incoming VoIP calls, use the global command voip-incoming translation-profile name, as the following configuration demonstrates:

  Boise(config)#voip-incoming translation-profile TEST
  

Blocking Calls Using Voice Translation Rules and Profiles

You can also use voice translation rules and profiles to block incoming calls, either for a specific number or all calls matching a specific dial peer. To do this, first create a voice translation rule with the reject keyword. This rule blocks any incoming calls from phone number 410-111-2222:

Boise(config)#voice translation-rule 410
Boise(cfg-translation-rule)#rule 1 reject /4101112222/

Next, create a translation profile, and assign that rule to it:

Boise(config)#voice translation-profile BLOCK
Boise(cfg-translation-profile)#translate calling 410

Finally, apply the translation profile to the appropriate dial peer(s) with the command call-block translation-profile incoming name. When the call is blocked, a reason code is sent to the caller. You can control that message with the call-block disconnect-cause command, as shown here:

Boise(config)#dial-peer voice 99 pots
Boise(config-dial-peer)#call-block translation-profile incoming BLOCK
Boise(config-dial-peer)#call-block disconnect-cause incoming call-reject

 

Testing Voice Translation Rules

Because number translations can get complex, testing your translations before putting them into production is crucial. The easiest way to test is with the test voice translation-rule rule-number digit-string command. (Output from this command is shown in Examples 10-3 through 10-8.) To see the translations in action, enter debug voice translation before giving this command. This command shows whether the number is matched or not, and what is replaced. Example 10-10 shows the combination of testing the voice translation rule with debugging voice translation. The debug output shows that there was a successful substitution, the original number, the pattern that was matched, the replacement pattern, and the translated number.

[View full width]

Boise(config)#voice translation-rule 4 Boise(cfg-translation-rule)#rule 1 /^(22)444(5...)$/ /17772/ Boise(cfg-translation-rule)#^Z Boise#test voice translation-rule 4 224445678 Matched with rule 1 Original number: 224445678 Translated number: 227775678 Original number type: none Translated number type: none Original number plan: none Translated number plan: none Boise# *Mar 1 03:42:08.636: sed_subst: Successful substitution; pattern=224445678 matchPattern=^(22)444(5...)$ replacePattern=17772 replaced pattern=227775678 *Mar 1 03:42:08.640: regxrule_subst_num_type: Match Type = none, Replace Type = none Input Type = none *Mar 1 03:42:08.640: regxrule_subst_num_plan: Match Plan = none, Replace Plan = none Input Plan = none  

The commands show voice translation-rule and show voice translation-profile help verify the configuration.