Cisco voice translation rules: syntax, examples and testing
A voice translation rule changes a called or calling number on a Cisco gateway. Most rules that fail do so for one reason: the pattern syntax is not the one people expect.
The three parts
- The rule set holds numbered rules. Each rule has a match pattern and a replacement, both between slashes.
- The profile says which rule set applies to the called number and which to the calling number.
- The dial-peer (or trunk group, or voice port) applies the profile to incoming or outgoing calls.
voice translation-rule 1
rule 1 /^9\(.*\)/ /\1/
!
voice translation-profile STRIP-9
translate called 1
!
dial-peer voice 100 voip
translation-profile outgoing STRIP-9The pattern syntax
| Character | Meaning |
|---|---|
^ | Start of the number |
$ | End of the number |
. | Any one character |
[2-9] | Any one character in the range |
* | The previous item, zero or more times |
+ | The previous item, one or more times |
\( \) | A group to keep. Use it in the replacement as \1, \2 |
\ | Treat the next character literally |
The group syntax is the trap. Parentheses must be written with a backslash. Plain parentheses are treated as literal characters, so the rule looks correct and never matches a real number.
Worked examples
- Remove a leading 9:
rule 1 /^9\(.*\)/ /\1/ - Add +1 to a ten-digit number:
rule 1 /^\([2-9].........\)$/ /+1\1/ - Keep the last four digits:
rule 1 /^.*\(....\)$/ /\1/ - Replace a four-digit extension range with a full number:
rule 1 /^5\(...\)$/ /+14085555\1/
What catches people out
- Only the matched part is replaced.
/^9/ //removes the 9 and leaves the rest. Without anchors, a pattern can match in the middle of a number. - The first matching rule wins. Rules are tried in numeric order. Put the most specific rule first.
- Direction matters. An incoming profile runs before the outbound dial-peer is chosen, so it changes which dial-peer matches. An outgoing profile runs after.
- The plus sign has two meanings. In a pattern it is a repeat. To match a literal plus at the start of a number, write
\+.
Test before you apply
The gateway will run a rule against a number without placing a call:
test voice translation-rule 1 914085551212The output shows the matched rule and the translated number, or tells you that no rule matched.
Test with the number exactly as it arrives, including any plus sign or prefix. Read it from a debug, not from memory.
Where Workbench helps
Voice Translation Rule Builder asks what you want done to the number, writes the rule with the correct group syntax, and tests it against numbers you supply using the same matching the gateway uses.