As an Amazon Associate I earn from qualifying purchases.

Voice Translation Rules : Examples

Updated:  4/14/2011

Voice translation rules have tripped up many an engineer, especially when troubleshooting an existing router that you may not have installed.  In those situations, it can be easy to misunderstand the subtleties of voice translation rules when quickly reviewing a production configuration.

So, by popular demand, this post will serve as a collection of many examples showing various methods of using voice translation rules.  Check back periodically, as the number of examples on this page will grow quickly over time.  As always, I'd love to have comments and suggestions for scenarios that should be included and explained.

In case you need to review the syntax of a voice translation rule, please review this earlier post that goes over syntax, including wildcards, number slicing and valid characters (and their meanings).

Applying Voice Translation-Rules

In order to apply a voice translation-rule, you must apply it to a voice translation-profile.  Voice translation-profiles can then be applied in a number of ways to dial-peers and voice ports.

See a quick example below, or this very comprehensive document for much greater detail.

voice translation-rule 1
  rule 1 /212/ /9/

voice translation-profile myprofile
  translate calling 1

dial-peer voice 10 pots
  translation-profile outgoing myprofile

Basic Match and Replace

example 1.1

In this example, only the first occurrence of the match-pattern will be changed to the replace-pattern.
 
    voice translation-rule number
     rule precedence /match-pattern/ /replace-pattern/

    voice translation-rule 1
     rule 1 /123/ /890/  

    router#test voice translation-rule 1 123
    Matched with rule 1
    Original number: 123    Translated number: 890

    router#test voice translation-rule 1 1234
    Matched with rule 1
    Original number: 1234   Translated number: 8904

    router#test voice translation-rule 1 1123
    Matched with rule 1
    Original number: 1123   Translated number: 1890

    router#test voice translation-rule 1 1123123
    Matched with rule 1
    Original number: 1123123  Translated number: 1890123

example 1.2

In this example, the match-pattern will be changed to the replace-pattern only when it occurs at the beginning of a number.  This is indicated by the leading "^" in the match-pattern.

    voice translation-rule 1
     rule 1 /^123/ /890

    router#test voice translation-rule 1 123
    Matched with rule 1
    Original number: 123    Translated number: 890

    router#test voice translation-rule 1 1234
    Matched with rule 1
    Original number: 1234   Translated number: 8904

    router#test voice translation-rule 1 1234123
    Matched with rule 1
    Original number: 1234123   Translated number: 8904123

    router#test voice translation-rule 1 1123
    No match.  "123" does not occur at beginning.

example 1.3

In this example, the match-pattern will be changed to the replace-pattern only when it occurs at the end of a number.  This is indicated by the trailing "$" in the match-pattern.

    voice translation-rule 1
     rule 1 /123$/ /890

    router#test voice translation-rule 1 123
    Matched with rule 1
    Original number: 123    Translated number: 890

    router#test voice translation-rule 1 1234
    No match.  "123" does not occur at the end of the number.

    router#test voice translation-rule 1 1234123
    Matched with rule 1
    Original number: 1234123   Translated number: 1234890

    router#test voice translation-rule 1 1123
    Matched with rule 1
    Original number: 1123   Translated number: 1890

example 1.4

In this example, the match-pattern will be changed to the replace-pattern only when it matches exactly.  This is indicated by using both the leading "^" and the trailing "$" in the match-pattern which has the combined effect of saying "match the pattern that both begins AND ends within the number".

    voice translation-rule 1
     rule 1 /^123$/ /890

    router#test voice translation-rule 1 123
    Matched with rule 1
    Original number: 123    Translated number: 890

    router#test voice translation-rule 1 1234
    No match.  "123" does not occur at the end of the number.

    router#test voice translation-rule 1 1123
    No match.  "123" does not occur at the beginning.

Using Wildcards

example 2.1

Replace any number that is five digits in length that begins with "88" with the number "9999000".

    voice translation-rule 1
     rule 1 /^88.../ /9999000/

    router#test voice translation-rule 1 88222
    Matched with rule 1
    Original number: 88222    Translated number: 9999000

    router#test voice translation-rule 1 89123
    No Match.  The number does not begin with 88.

    router#test voice translation-rule 1 881234
    No Match.  The number contains too many digits.

    router#test voice translation-rule 1 8812
    No Match.  The number contains too few digits.

example 2.2

Replace any numbers with "9995000".  ".*" is a wildcard that includes all numbers, including null.

    voice translation-rule 2
     rule 1 /.*/ /9995000/

    router#test voice translation-rule 2 123
    Matched with rule 1
    Original number: 123    Translated number: 9995000

    router#test voice translation-rule 2 86573
    Matched with rule 1
    Original number: 86573  Translated number: 9995000

    router#test voice translation-rule 2 ""
    Matched with rule 1
    Original number: <NULL>  Translated number: 9995000

example 2.3

This example replaces all numbers, except null, with "9995000".  ".+" includes all numbers, except null.

    voice translation-rule 1
     rule 1 /.+/ /9995000/

    router#test voice translation-rule 1 89555
    Matched with rule 1
    Original number: 89555  Translated number: 9995000

    router#test voice translation-rule 1 212
    Matched with rule 1
    Original number: 212    Translated number: 9995000

    router#test voice translation-rule 1 ""
    No match.  <NULL> is not included in match pattern.

example 2.4

This example replaces any number that starts with a combination of eights with "999" instead of the eight(s).

    voice translation-rule 5
     rule 1 /^8+/ /999/

    router#test voice translation-rule 5 85551212
    Matched with rule 1
    Original number: 85551212   Translated number: 9995551212

    router#test voice translation-rule 5 885551212
    Matched with rule 1
    Original number: 885551212  Translated number: 9995551212

    router#test voice translation-rule 5 8885551212
    Matched with rule 1
    Original number: 888123456  Translated number: 9995551212

    router#test voice translation-rule 5 5551212  
    No match.  Number does not begin with eight.

example 2.5

Translate any number to null, including null.  The wildcard combination "^.*" matches all numbers, including null.  If you had wanted to match only null, you could have used "^$".

    voice translation-rule 1
     rule 1 /^.*/ / /

    router#test voice translation-rule 1 2001
    Matched with rule 1
    Original number: 2001     Translated number: <NULL>

    router#test voice translation-rule 1 5551212
    Matched with rule 1
    Original number: 5551212  Translated number: <NULL>

    router#test voice translation-rule 1 5551212
    Matched with rule 1
    Original number: <NULL>   Translated number: <NULL>

Number Slicing (and Dicing)

Voice translation rules have the ability to slice the number into smaller parts, manipulate each part individually and then put the number back together again.  This technique is called "number slicing".  It can appear very complicated and gives many engineers difficulty at first, but with some practice you will soon master the technique.

example 3.1

This example is meant to provide some explanation of a typical voice translation rule using number slicing at a higher level.  Consider the following rule:

    / (x\) y\ (z\) /  / a \1 \2 /  

  • Split the matched number into three sets of x, y, and z. 
  • The backward slash (\) indicates the where to slice up the number. 
  • The brackets () indicate which sets you want to reuse in the replacement pattern. 
  • The a represents additional digits to insert into the replacement number.

      Set 1 inherits the value of x.
      Set 2 inherits the value of z.
      Expression y is not reused.

The replacement number is a concatenated numberaxz

example 3.2

In this example, the number of 55866 will be replaced with 85566 using number slicing.  While this could be accomplished using a simpler rule, it serves our purposes here to demonstrate number slicing.  Note that "^" and "$" are used to designate that the match pattern must exist at both the beginning and end of a number (essentially an explicit match). 

         voice translation-rule 1
     rule 1 /^\(55\)8\(66\)$/ /8\1\2/

     Set 1: 55
     Set 2: 66
    Ignore: 8

    router#test voice translation-rule 1 55866
    Matched with rule 1
    Original number: 55866    Translated number: 85566

    router#test voice translation-rule 1 12345
    No match.  The match pattern is not satisfied. 

    router#test voice translation-rule 1 55867
    No match.  The match pattern is not satisfied.

    router#test voice translation-rule 1 55466
    No match.  The match pattern is not satisfied.

Manipulating Number Type and Plan

When interfacing with different telcos around the world, you will find that all are not created equally.  Some will require that calls be send with a specific numbering plan for the type of call to be handled correctly.  Using voice translation rules, the plan or type can be manipulated as required or the call can be blocked.  

example 4.1

If a number starts with "4" and the type is "national", the rule adds "99" as a prefix. If the type is "international", the rule adds "999" as the prefix.  This simulates the scenario in which the telco requires an access code when placing an national or international call.

    voice translation-rule 1
     rule 1 /^4/ /994/ type national national
     rule 2 /^4/ /9994/ type international international
    router#test voice translation-rule 1 442195555 type national
    Matched with rule 1
    Original number: 442195555              Translated number: 99442195555
    Original number type: national          Translated number type: national
    Original number plan: none              Translated number plan: none
       
    router#test voice translation-rule 1 442195555 type international
    Matched with rule 2
    Original number: 442195555              Translated number: 999442195555
    Original number type: international     Translated number type: international
    Original number plan: none              Translated number plan: none



    router#test voice translation-rule 1 842195555 type international
    No Match.  Does not begin with "4".


example 4.2

This rule simply matches any four-digit number that starts with "8" and adds the number "04421955" as a prefix while stripping the "8", and sets the plan to "isdn" and the type to "national".

    voice translation-rule 1
     rule 1 /^8\(...$\)/ /04421955\1/ type unknown national plan unknown isdn
    router#test voice translation-rule 1 8150 type unknown plan unknown
    Matched with rule 1
    Original number: 8150                  Translated number: 04421955150
    Original number type: unknown          Translated number type: national
    Original number plan: unknown          Translated number plan: isdn



    router#test voice translation-rule 1 6150 type unknown plan unknown
   
No Match.  Does not begin with 8.


    router#test voice translation-rule 1 81501 type unknown plan unknown
   
No Match.  Does not contain the correct number of digits (4).  

Blocking Calls

Rejecting or blocking calls can easily be done with voice translation-rules.  Add the reject keyword to the syntax as shown in these examples.  The call must match the match-prefix in order to be dropped. 


example 5.1 

Rejects all calls starting with "900".

    rule 1 reject /^900/

    router#test voice translation-rule 10 8005551212
    No Match.  Does not begin with 900.

    router#test voice translation-rule 10 9005551212
     Call blocked by rule 1


Special Cases

This section contains examples that show strategies to accomplish very common digit manipulation requirements.

example 6.1

This is a very useful translation rule that will strip off all but the last 4 digits.  Note that digits that will be retained must be enclosed in () within the match pattern.

    rule 1 /^.*\(....\)/ /\1/

    router#test voice translation-rule 1 5551212
    Matched with rule 1
    Original number: 5551212       Translated number: 1212

    router#test voice translation-rule 1 2125551212
    Matched with rule 1
    Original number: 2125551212       Translated number: 1212

Suggestions Welcome  

If you have a suggestion or example that should be included - please let me know!  I'll give you credit and link back to your blog, website or twitter - your choice!

More Information

Voice Translations in Cisco IOS Gateways  This is an 18-page PDF that goes into great detail about many types of translation rules, and how to apply them in different situations.  Highly recommended!

10 comments:

  1. if you want to try VTR's try this http://www.redsack.com/blogs/translation.aspx

    ReplyDelete
  2. Can you share more examples for Blocking / reject rules? Especially the international ones, like one I have shown below:

    rule 1 reject /^901153/ type international plan any

    ReplyDelete
  3. That's a great idea! I'll add some more uses for blocking in the near future.

    ReplyDelete
  4. My situation is a little different. I am trying to figure out how to PERMIT calling numbers, based on ANI information, as opposed to blocking. I though maybe I could block on a negative result instead of permitting on a positive match, but I don't see where that is supported. Essentially I need a white-list, not a black-list. By default all calling numbers are blocked, EXCEPT for the ones I allow. I guess its something like an ANI ACL. Is that even possible? Oh, and to make things even more interesting, the "white-list" will probably need to reside on an ACS type external repository. First action will be to ask it if 555-1212 is allowed. If not, terminate the call. If it is, then begin a standard PPP CHAP session setup.

    ReplyDelete
  5. Interesting scenario! First, I don't know of an ACS-type method of doing this, but I'll instead focus on the Cisco IOS gateway portion of the question.

    As for the IOS gateway call blocking, check out this link: https://supportforums.cisco.com/docs/DOC-2907

    I've not tested the config snippet below (and please let me know if you do) - but this may accomplish the "white list" portion of your requirements:

    !
    ! Permit only calls from specific numbers
    !
    voice translation-rule 1
    rule 1 /5551212/ /5551212/
    rule 2 reject /.*/
    !
    voice translation-profile allow_certain_ani
    translate calling 1
    !
    dial-peer 1 pots
    direct-inward-dial
    translation-profile incoming allow_certain_ani

    ReplyDelete
  6. this is some great stuff Dan!

    Greetz,
    Mohamed from Holland

    ReplyDelete
  7. Awesome post Dan,

    What about dealing with calling other networked phone systems? as in calling other sites via a calling code ie 6788 xxxx

    ReplyDelete
  8. Hi All,
    I have CCM with extention number 19100-19900. i need to add 4 line phone call with line 1 connect to GSM modem with operator A, line 2 connect to GSM modem with operator B and so on till 4 line with different mobile operator. when users make a call to external number, they should not know which line they use, but I must make sure that their call will be out from port that contain same operator with destination number. i have cisco 8925 router with 4 FXO as h323 gateway that it's FXO ports connect to each GSM modem.
    Here are mobile operator prefix :
    operator A : 0815
    Operator B : 0856
    Operator C : 0899
    Operator D : PSTN (0XXX-XXXXXX)
    the goal is, user should dial direct number and CCM/voice gateway will choose appropriate port
    need your advise, is this possible to implement ? can you make me note, thanks

    ReplyDelete
    Replies
    1. My apologies for the slow reply. First, let me start by saying that I'm not familiar with using GSM modems, but I assume the same principles will apply here.

      The FXO ports can placed in a common trunkgroup to facilitate outbound calls via a dial-peer. The dial-peer will send calls to the trunkgroup and the trunkgroup will select an available FXO to make the outbound call.

      If you are trying to make the outbound "CALLING NUMBER" be the operators, so that they will get the return call themselves, it will depend upon the LEC and the service type. For example, class POTS lines will not allow this, however, some (if not most) PRI circuits will.

      Assuming the GSM service provider will allow it, you'd do this using a unique external phone mask in CUCM for each operator's phone device. If the GSM service provider does not allow the CALLING NUMBER to be altered, it will default to the one assigned to the GSM modem [FXO port] that is selected by the trunkgroup.

      voice-port 0/1/0
      trunk-group GSM
      !
      voice-port 0/1/1
      trunk-group GSM
      !
      voice-port 0/1/2
      trunk-group GSM
      !
      voice-port 0/1/3
      trunk-group GSM
      !
      dial-peer voice 150 pots
      trunkgroup GSM
      description Long Distance Dialing
      destination-pattern 1[2-9]..[2-9]......
      forward-digits all
      !

      Delete