Chapter 10. Digit Manipulation
You might encounter situations where you need to control the actual digits contained in the telephone numbers that enter or leave the gateway. You might need to add the area code to a call that is routed out of the public switched telephone network (PSTN), or remove a site code from an intracompany call, for instance. Digit manipulation encompasses adding, subtracting, and changing telephone numbers. You can manipulate calling numbers, called numbers, and redirecting numbers, in addition to the numbering plan and ISDN number type. You can use techniques that are applied to incoming or outgoing calls, or globally to all calls. You can manipulate telephone numbers before a dial peer is matched, or afterward.
In this chapter, you will learn
• Ways that a router applies digit manipulation
• Basic digit manipulation techniques, such as digit stripping, prefixing, and forwarding
• Number expansion
• Number translation
• Control of the calling line identification (CLID) number
• Ways to troubleshoot and verify the telephone number changes that are applied
Basic Digit Manipulation
Several different digit manipulation techniques exist, each of which controls telephone numbers in a different way and can be applied at specific points in the call flow. Table 10-1 summarizes the techniques covered in this chapter, where they are applied, and where their effect is felt.
Table 10-1. Digit Manipulation Techniques
You can perform digit manipulation only on H.323 and SIP gateways; on MGCP gateways, the call agent must perform any manipulation because it controls the calls. Cisco CallManager Express and routers that are using Survivable Remote Site Telephony (SRST) offer some additional manipulation options to those discussed in this chapter, such as dial plan patterns. CallManager Express techniques are beyond the scope of this book. Chapter 13, “SRST and MGCP Gateway Fallback,” discusses SRST digit manipulation in greater detail. You can also use Toolkit Command Language (Tcl) scripts to manipulate the called and calling numbers, as described in Chapter 15, “Using TCL Scripts and VoiceXML.”
Digit Stripping
VoIP dial peers transmit all digits in the called number by default; however, POTS dial peers remove, or strip, any outbound digits that explicitly match their destination pattern. For instance, given a destination pattern of 55512.. the called number transmitted to the PSTN would contain just the last two digits. The first five digits, 55512, would be stripped. Only explicitly matched digits are stripped. Given a destination pattern of 555[2-9].. and a digit string of 555422, only the 555 would be stripped. If all the digits in a called number are removed, the caller hears only a reorder tone.
Digit stripping is the default behavior of POTS dial peers. It can work to your advantage, as long as you understand its effect. For instance, if users dial 9 to reach an outside number, you would not want the number 9 sent to the PSTN as part of the called number. When you configure the destination pattern of a POTS dial peer as 9T, the 9 is matched, so it is stripped. The remaining digits are transmitted. However, suppose that you have a dial peer for an emergency number, such as 911 in the United States. In that case, you would not want any of those digits removed, so you must disable the default behavior for that dial peer.
You can disable digit stripping with the command no digit-strip under POTS dial-peer configuration mode. Re-enable it with the command digit-strip. The relevant command syntax is as follows:
dial-peer voice 1 pots
[no]digit-strip
Forward Digits
You can achieve more precise control over the number of digits in the called number that are transmitted to the PSTN with the following command, which applies only to POTS dial peers:
forward-digits [number | all | extra]
where
• number gives the number of digits to be forwarded.
• all means to forward all digits.
• extra tells the gateway to forward any digits that are longer than the length of the destination pattern.
This command lets you specify the exact number of digits to be forwarded. If the number of digits presented exceeds the number allowed, the rightmost digits are sent. One place this can be useful is when you must dial a code (such as 9) to reach an outside number, and there is an emergency situation. The previous section showed how to ensure that the entire emergency number (such as 911) is sent. In an emergency, a person might be confused about whether to dial the outside code. That is why dial peers are typically set up to match both the emergency number, and that number plus the code number. If the destination pattern of a dial peer is 9911, you should send only 911. You can use the forward-digits command to transmit only the last three digits, 911, to the PSTN.
The following examples show what digits are sent when you dial the number 111-222-3333 and use various options of the forward-digits command.
For this first case, the rightmost seven digits, 222-3333, are sent.
Miami(config)#dial-peer voice 111 pots
Miami(config-dial-peer)#destination-pattern 111222....
Miami(config-dial-peer)#forward-digits 7
With the configuration that follows, the entire number, 111-222-3333, is sent. This is an alternative to using the no digit-strip command shown in the previous section.
Miami(config)#dial-peer voice 111 pots
Miami(config-dial-peer)#destination-pattern 111222....
Miami(config-dial-peer)#forward-digits all
Finally, with the final configuration that follows, because the destination pattern is now six digits long and the dialed number is ten digits, the “extra” digits—3333—are sent.
Miami(config)#dial-peer voice 111 pots
Miami(config-dial-peer)#destination-pattern 111222
Miami(config-dial-peer)#forward-digits extra
Prefix Digits
In some cases, you might need to transmit more than the dialed digits of a called number. For example, perhaps a call that would normally go across your VoIP network needs to be rerouted through the PSTN, requiring the addition of the appropriate area code and prefix. Or, a destination pattern might specify the first six digits of the number, with wildcards for the other digits. By default, those six digits are stripped. You can use the prefix string command to replace some of those digits. This command is given under dial-peer configuration mode, and it is only for POTS dial peers. The prefixed string can be any number from 0 to 9 and a comma that inserts a one-second pause. The gateway prefixes digits after the outgoing dial peer is matched and after any digits are stripped, but before it sends out the call.
In Example 10-1, long-distance calls need to go to a particular carrier and must have a separate dial peer from external local calls. The destination pattern is 91 to capture long-distance traffic; however, the PSTN needs the number 1 transmitted as part of the called number to route the call properly. Thus, the prefix command is added to replace that digit.
Example 10-1. Prefixing Digits to an Outgoing Call
Miami(config)#dial-peer voice 91 pots
Miami(config-dial-peer)#destination-pattern 91T
Miami(config-dial-peer)#prefix 1
Miami(config-dial-peer)#port 1/0:23
When a user dials the outside long-distance number 9-1-111-222-3333, the digits are manipulated before being sent to the PSTN. The original digits 9 and 1 are stripped, and a 1 is prefixed to the remaining number. Thus, the PSTN receives the number 1-111-222-3333.
Number Expansion
Number expansion is another way to add digits to an outgoing called number; however, number expansion is applied to the gateway as a whole, and acts on all calls, not just those matching a designated dial peer. As with the previous three techniques, this manipulates only the called number. Number expansion manipulation occurs before any outbound dial peer is matched. Thus, you must configure outbound dial peers to match the expanded numbers, not the original ones.
The command for number expansion is num-exp original-number expanded-number, configured at global configuration mode. Although it is called number expansion, the manipulated number can contain fewer digits than the original, or it can contain more.
Example 10-2 shows two instances of number expansion configured. The first expands any four-number extension beginning with 1 to a seven-digit number beginning with 5551. The second changes any seven-digit number beginning with 5551 to a four-digit extension.
Example 10-2. Number Expansion
Miami(config)#num-exp 1... 5551...
Miami(config)#num-exp 5551... 1...
!
!Verifying the first number expansion
Miami#show dialplan number 1111
Macro Exp.: 5551111
!
!Verifying the second number expansion
Miami#show dialplan number 5551098
Macro Exp.: 1098
In the results of the show dialplan number command, notice that although the number entered in the command is the original number, the router looked for a match to the expanded number. The show dialplan number command is also useful for verifying that you have a dial peer to match the expanded number.
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:
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.
Example 10-3. Using a Basic Voice Translation Rule
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 matched—the numbers 1 and 5 in this example—are 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
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.
Example 10-4. Using Regular Expressions: Replacing Digits
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 number—instead, 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.
Example 10-5. Using Regular Expressions: Prefixing Digits
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.
Example 10-6. Using Regular Expressions: Deleting Digits
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 set—758.
• The expression 2 points to the second set. In the translated number, it is replaced with the contents of the second set—in 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.
Example 10-7. Using Regular Expressions: Digit Replacement Using Sets
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 set—758.
• 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 set—in 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.
Example 10-8. Using Regular Expressions: Changing the Call Type and Numbering Plan
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.
Example 10-9. Creating a 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.
Example 10-10. Testing and Debugging Voice Translation Rules
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.
Manipulating Caller ID
During an outgoing call, the CLID is sent as part of the call information. CLID information includes at least one calling party number. The CLID might also include a name, a second number, and redirecting number information. You can control the information sent at the CallManager, and you can configure the gateway to control the information that shows up on caller ID. Some companies prefer that the main corporate number is displayed, rather than the actual extension of the person calling, for instance. The receiver can use CLID information in many ways, such as to route emergency services calls, so you must take this into account if you manipulate the CLID.
CLID Commands
You can manipulate caller ID information by a set of clid commands. These commands allow you to remove or change the calling party information transmitted with a call, or send it but prevent it from being displayed. clid commands apply to specific dial peers when given under dial-peer configuration mode. They apply globally when given under the voice service voip configuration mode (available in Cisco IOS Software Release 12.4(4)T and later). Not all options are available when configuring CLID in this mode. The commands include the following (those available under voice service voip are noted):
• clid network-number number—Specifies the network number to be sent in the CLID information. It sets the presentation indicator to “Y” and the screening indicator to “network provided.” Available in both dial-peer and voice service voip configuration modes.
• clid second-number strip—Removes the original calling number from the H.225 source address field. You can also give this command on the same line as the clid network-number command. It is valid only if you have configured a network number.
• clid restrict—Transmits the calling party information but sets the presentation indicator to “N” so that it is not displayed to the called party.
• clid strip [name | pi-restrict [all]]—Removes the CLID number if just the clid strip command is given and sets the presentation indicator to “N.” It removes the CLID name if the name option is added. To remove both the name and number, you must enter both commands separately. The pi-restrict option causes the CLID number to be stripped only when you set the progress indicator to “restricted.” Adding the all keyword strips both the CLID number and name. The pi-restrict all option is available in both dial-peer and voice service voip configuration modes.
• clid substitute name—Substitutes the calling number for the display name. Available in both dial-peer and voice service voip configuration modes.
Station ID Commands
You can control the caller ID information that FXS and FXO ports send with the station-id [name | number] string command. Using either the name or number keywords also enables caller ID on that port. The station-id command is typically used on FXS voice ports that are attached to a phone or fax that might originate on-net calls. The information that you configure with this command shows up as the caller ID on the device connected to the remote FXS port. You might also use this command on an FXO port to supply caller ID information if that does not come from the central office, for example:
VoiceGW(config)#voice-port 1/0/0
VoiceGW(config-voiceport)#station-id name C.P. Ryan
VoiceGW(config-voiceport)#station-id number 1112223000
Order of Operation in Digit Manipulation
As you have seen, some digit manipulation techniques accomplish the same result. You can use all the various methods of digit manipulation on the same gateway, but it is not recommended and usually not needed. Choosing which technique to use is sometimes more of an art than a science. For instance, an emergency call to 911 routed out a POTS interface would have all of its digits stripped before tranmission, so the call would not go through. To remedy this, you could configure no digit-strip, or forward-digits 3, or prefix 911 on the dial peer. You could even configure a translation profile or number expansion to change the called number so that the digits 911 would be sent, although that would be the hardest way to do it.
The point at which you must perform the manipulation is also is a factor. If the digit manipulation should apply to all calls, or be done before a dial peer is matched, you can use one of the global techniques. If the manipulation will apply only to certain calls, you can configure it under the dial peers for those calls. Some techniques are specific to POTS or VoIP dial peers, so that might aid your decision.
Consistency is a major consideration if you have many gateways needing similar digit manipulations to manage. Pick a technique (or techniques, if necessary), and standardize on it. In general, stick to the simplest way of accomplishing what you want. This consistency makes the gateways easier to configure, easier to manage, easier to troubleshoot, and probably easier on the router.
A good understanding of how the different methods interact will help your decision making, and in troubleshooting problems, also. Figure 10-1 shows how a call flows through the router, and where each technique is applied.
Figure 10-1. Order of Operation in Digit Manipulation
A POTS call first comes in a voice port, is matched to an incoming dial peer, and then is matched to an outgoing dial peer. Rules that are assigned to the voice port are applied first, next any global number expansion, then those on the incoming dial peer, and lastly those on the outgoing dial peer. If a prefix command is under the dial peer, the translation is done first.
A VoIP call matches an incoming dial peer, then an outgoing dial peer, and possibly a POTS voice port. Globally assigned rules such as VoIP incoming translation profile and number expansion are executed first, then any rules on the incoming dial peer, and finally any rules on the outgoing dial peer. If a Tcl script is associated with a dial peer to manipulate the ANI or DNIS, the script runs after the dial peer is matched but before any translation profile associated with that dial peer.
Table 10-3 summarizes the order of operation for techniques discussed in this chapter.
Table 10-3. Digit Manipulation Techniques—Order of Operation
Troubleshooting Digit Manipulation
When you are troubleshooting digit manipulation, first verify the configuration. Test the digit manipulations as much as possible before deploying them in a live network. If they do not work as expected, check to make sure that they are correctly configured and that other rules do not interfere. Remember the order in which the router processes rules.
This chapter discussed several troubleshooting and verification commands, some of the most useful of which are as follows:
• test voice translation-rule rule-number phone-number—Shows the results of a translation rule, enabling you to test it to ensure that it does what you planned
• debug voice translation—Shows the translations happening
• show dialplan numbernumber—Verifies number expansion and which dial peers a phone number matches
• debug voip ccapi inout—Shows inbound and outbound dial peers being matched
• show num-exp[number]—Displays the number expansion rules configured
• show dial-peer voice [tag]—Displays any CLID, translation profiles, call blocking, disconnect cause, digit stripping, forwarding, or prefixing that is configured on the dial peer
• show voice translation-rule [number | sort [ascending|descending]]—Lists the translation rules that are configured on the router and all translation patterns configured for each one
• show voice translation-profile [name | sort [ascending|descending]]—Lists the translation profiles configured on the router and all translation rules associated with each one
• debug isdn q931—Shows the called and calling numbers sent out a PRI link for troubleshooting CLID commands
• csim start phone-number—Simulates a phone call from the router; can be used with debugs
Case Study
Figure 10-2 shows the Boise, Idaho office network. In this case study, the Boise office has the following telephone network requirements:
• The office has been experiencing spam faxes lately from one specific phone number, 410-111-2222. That number needs to be blocked incoming on the Boise PRI.
• The office has a small help desk staff that takes calls from the Miami, Florida office and the Lima, Peru office. Both locations call the same help desk number, 3-0150. (3 is a site code.) You need to route calls from Miami to the English-speaking group at 3-0148, and you need to route calls from Lima to the Spanish-speaking group at 3-0149. Both calls will go through the local PBX. The internal company numbers for Miami are 2-0100 through 2-0199. The internal numbers for Lima are 6-6200 through 6-6250.
• Caller ID should show only the main office number of 208-555-0100 for outgoing calls.
• Outgoing local PSTN calls should have the initial 9 stripped and ten digits sent to the PSTN.
Figure 10-2. Case Study Network
Example 10-11 shows the configuration that is necessary on the Boise router to block the spam faxes, route the help desk calls, change the caller ID, and send the appropriate called number to the PSTN.
Example 10-11. Digit Manipulation Case Study
!Configure the router to block calls from the fax spam number
!Create the rule to reject 410-111-2222
Boise(config)#voice translation-rule 410
Boise(cfg-translation-rule)#rule 1 reject /4101112222/
!
!Create a translation profile, and associate that rule with it
Boise(config)#voice translation-profile BlockFax
Boise(cfg-translation-profile)#translate calling 410
!
!Apply the translation profile to the dial peer, incoming. Specify a disconnect cause
Boise(config)#dial-peer voice 99 pots
Boise(config-dial-peer)#incoming called-number .
Boise(config-dial-peer)#call-block translation-profile incoming BlockFax
Boise(config-dial-peer)#call-block disconnect-cause incoming call-reject
Boise(config-dial-peer)#direct-inward-dial
!
!Configure the router to route help desk calls based on the ANI
!First create a rule that will be used to translate the DNIS on calls from Miami
Boise(config)#voice translation-rule 100
Boise(cfg-translation-rule)#rule 1 /(.*)/ /30148/
!
!Create a rule that will translate the DNIS on calls from Lima
Boise(cfg-translation-rule)#voice translation-rule 200
Boise(cfg-translation-rule)#rule 1 /(.*)/ /30149/
!
!Create translation profiles to translate the called numbers
Boise(config)#voice translation-profile Miami
Boise(cfg-translation-profile)#translate called 100
!
Boise(cfg-translation-profile)#voice translation-profile Lima
Boise(cfg-translation-profile)#translate called 200
!
!Apply the translation profiles to dial peers that will match the incoming ANI
Boise(config)#dial-peer voice 100 voip
Boise(config-dial-peer)#answer-address 221..
Boise(config-dial-peer)#translation-profile outgoing Miami
!
Boise(config-dial-peer)#dial-peer voice 200 voip
Boise(config-dial-peer)#answer-address 662[0-5].
Boise(config-dial-peer)#translation-profile outgoing Lima
!
!Create dial peers for the help desk numbers, pointing to the PBX
Boise(config)#dial-peer voice 30148 pots
Boise(config-dial-peer)#destination-pattern 30148
Boise(config-dial-peer)#port 0/0/0
!
Boise(config-dial-peer)#dial-peer voice 30149 pots
Boise(config-dial-peer)#destination-pattern 30149
Boise(config-dial-peer)#port 0/0/1
!
!Configure CLID to send only the main office number in calls to the PSTN
Boise(config-dial-peer)#dial-peer voice 9 pots
Boise(config-dial-peer)#clid network-number 2085550100 second-number strip
Boise(config-dial-peer)#destination-pattern 9T
Boise(config-dial-peer)#port 1/0:23
!
!On the same dial peer, allow exactly ten digits to be sent as called number
Boise(config-dial-peer)#forward-digits 10
Review Questions
1 Define digit manipulation.
2 Of the digit manipulation techniques digit stripping, digit forwarding, digit prefixing, number expansion, and CLID, which are executed after the outbound dial peer is matched but before the numbers are transmitted?
3 By default, POTS dial peers strip any outbound digits that explicitly match their destination pattern. What are two simple ways to prevent the router from stripping all the digits?
4 When is a number expansion executed, and how can you test its action?
5 Given the following voice translation rule, how would a dialed string of 913012345678 be translated?
/^(91)301(.......)/ /12/
6 Given the following voice translation rule, how would a dialed string of 913012345678 be translated?