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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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