Digit Manipulation

There are various reasons to manipulate the digits dialed by the caller on a voice system. The most common reason is to allow both internal calls (from other extensions) and external calls from the PSTN (where a full E.164 phone number is delivered) to terminate directly on the user's phone without needing a receptionist to intercept and redirect the call.

Note

E.164 is an International Telecommunication Union (ITU) specification that describes international telephone dial plans. It specifies phone number attributes such as international dialing codes, regional (area) codes, and the minimum and maximum length of each field in the phone number. Voice systems use the E.164 specification to parse and interpret phone numbers. PSTN numbers are always fully qualified E.164 numbers, whereas extensions within your business typically aren't, because they are private numbers of local significance only.

Here are some other reasons to translate (or manipulate) digits:

• To allow IP phone users to call each other directly by extension, and also to access the PSTN
• To allow for site access codes in a multisite on-net dial plan and to strip these digits to extract the extension as soon as the destination site is reached
• To allow for variable-length external (off-net) dialing while maintaining fixed-length internal dialing
• To block calls to certain numbers
• To redirect calls to certain numbers

For example, suppose your employee, Grace, is at extension 3001, and her PSTN DID number is 444-555-3001. Without some form of digit manipulation or live intercept, a call incoming from the PSTN that dialed 444-555-3001 will not match the ephone-dn definition for Grace's phone, which contains only her extension, 3001. Therefore, a method is needed to translate the string 4445553001 to 3001.

Several Cisco IOS digit manipulation tools can translate phone numbers. The following are the most common:

• Dial peer commands
• Cisco CME dialplan-pattern command
• IOS translation rules

Dial Peer Commands

You can include several commands on a POTS dial peer to add, suppress, or substitute the digits forwarded to the PSTN trunk interface:

• destination-pattern
• digit-strip
• forward-digits
• prefix
• translate-outgoing
• translation-profile

Dial peer commands are handy if only small changes to the beginning or end of the dialed number are necessary, such as prefixing an area code, prefixing a CO designator (NXX) to an extension number, or forwarding only the last four digits of a longer number. The wildcard matching within the destination-pattern command automatically deletes the numbers explicitly matched. For example, when 5553001 is dialed and is matched by a dial peer that contains the command destination-pattern 555...., the default operation is to forward only the digits 3001.

Cisco IOS Translation Rules

For more extensive digit manipulation, such as a wholesale change of a number or substituting digits in the middle of a number, translation rules are much more powerful. Translation rules are regular expressions attached to the dial peer with the translation-profile command.

Like the other dial peer commands discussed in the preceding section, translation rules are a generic Cisco IOS feature that allows manipulation of called numbers, calling numbers, and number types. It can also be attached in such a way that it translates calls in only one direction, either incoming or outgoing.

Example 6-9 gives a configuration extract for a T1 PRI trunk, with translation profile to_261x attached for incoming calls (calls from the PSTN to the Cisco IOS PSTN gateway). Translation profile to_261x, in turn, references translation rule 23, which has ten rules specified. This CLI segment intercepts all calls incoming from the PSTN over this T1 PRI that contains a dialed number ending in the range 12610 to 12619. It does not matter what (or how many) numbers precede this range; for example, it could be 555-331-2610 or 551-2618. The numbers that match the rule (12610 to 12619) are translated pointblank to a completely unrelated number so that none of the original digits survive. To illustrate, if a call with a dialed number of 555-331-2610 arrives, it is translated to 32085, and an IP phone (or other dial peer) associated with that extension receives the call. A PSTN call with a dialed number of 551-2618 results in extension 79988 receiving the call.

Example 6-9. Translation Rules

Router#show running-config
voice translation-rule 23
 rule 1 /12611/ /37002/
 rule 2 /12612/ /37262/
 rule 3 /12613/ /37990/
 rule 4 /12614/ /57514/
 rule 5 /12615/ /30631/
 rule 6 /12616/ /50043/
 rule 7 /12617/ /28787/
 rule 8 /12618/ /79988/
 rule 9 /12619/ /68278/
 rule 10 /12610/ /32085/
voice translation-profile to_261x
 translate called 23

controller T1 2/0
 framing esf
 linecode b8zs
 pri-group timeslots 1-24

interface Serial2/0:23
 no ip address
 no logging event link-status
 isdn switch-type primary-5ess
 isdn incoming-voice voice

voice-port 2/0:23
 echo-cancel coverage 64

dial-peer voice 1261 pots
 translation-profile incoming to_261x 
 incoming called-number 1261.
 direct-inward-dial
 port 2/0:23

The syntax for translation rules can be cryptic if you are unfamiliar with regular expressions. But it is a very powerful facility to manipulate digits, and it is not tied to Cisco CME, so you can use it on any Cisco IOS voice-enabled router.

Here are some considerations when using the Cisco IOS voice translation rules feature:

• It's a very powerful feature that can do almost any translation of digits required, but it can be obscure and, therefore, error-prone to those who are unfamiliar with it.
• Being a generic Cisco IOS feature, the feature's rules apply to all calls that traverse the router. It can be applied at a global level, dial peers, and ephone-dns (Cisco CME IP phones).
• The digits are manipulated before dial peer matching and call termination.
• Calling and/or called numbers can be manipulated on every call based on what is configured.
• The rules can be directionally applied to incoming or outgoing calls (or both).

When applying translation rules to ephone-dns, there is a side effect that if no rule is matched, an extra post-dial delay is incurred. As a workaround, create a dummy translation rule that acts as a pass-through. For example, if no rule is applied to extension-to-extension calls, and the extensions all start with five, add a rule that "translates" five to five, just to make sure that a rule is always matched, and the delay is not incurred.

Cisco CME dialplan-pattern Command

The Cisco CME dialplan-pattern command allows E.164 numbers to be mapped to extension numbers or, put another way, to extract the extension number from a longer DID number. The dialplan-pattern command does not actually translate the number (although the effect from a call routing point of view is the same). It instead creates multiple dial peers that allow different dialed numbers to terminate on the same phone.

The dialplan-pattern command can be used in some cases (calls to IP phones) to achieve the same call routing as can be achieved by using translation rules. Because these two features operate differently, you should think carefully about which method to use. If you use both methods, you should be clear about how these might interplay with each other to affect your call routing. The dialplan-pattern command is explained in more detail in Chapter 7, "Connecting Multiple Cisco CMEs with VoIP."

The CLI shown in Example 6-10 does the same mapping as the number translation discussed previously for employee Grace.

Example 6-10. Cisco CME dialplan-pattern Command

Router#show running-config
telephony-service
 load 7960-7940 P00303020214
 max-ephones 48
 max-dn 192
 ip source-address 10.1.3.1 port 2000
 system message CUE System 2691
 create cnf-files version-stamp 7960 Jul 15 2003 13:48:12
 dialplan-pattern 1 510395.... extension-length 4 
 voicemail 6800
 max-conferences 8
 web admin system name cue password cue
 dn-webedit
 time-webedit

Some considerations about using the Cisco CME dialplan-pattern feature include the following:

• It's an easy-to-use, user-friendly feature.
• It's a Cisco CME feature, so it applies only to calls to and from IP phones controlled by Cisco CME. It does not apply to calls from the PSTN gateway directly to the AA or voice mail pilot numbers. Therefore, if digit manipulation is needed on these calls, one of the other two methods must be used.
• The IP phone extension must have at least one digit in common with the original called number and be in the same sequence. (If the extension is completely different from the called number, or not in sequence, Cisco IOS translation rules must be used to manipulate the digits.)
• Like Cisco IOS translation rules, the digits are manipulated before dial peer matching and call termination.
• It manipulates the called number on a call to an IP phone and the calling number of a call from an IP phone. This operation is implicit and cannot be controlled or altered.
• The E.164 number patterns generated by the dialplan-pattern command can be registered to an H.323 gatekeeper or SIP proxy. Digit translations done with Cisco IOS translation rules are not registered to H.323 gatekeepers or SIP proxies.

PSTN Trunk Failover