Sample Five

In my opinion, voice translation rules are one of the most powerful tools available with the H.323 feature set on IOS. This also includes CME since it is basically an H.323 gateway with some additional functionality. With the voice translation rules, you can do away with the need for num-expansion and also with CME you don’t need to use the potentially problematic dialplan-pattern. What I will do for the purposes of this document is to present some of the most common scenarios for translation rule usage and how they apply.

Translating 10-Digit DID to 4-Digit Extension

Probably one of the most common uses of translation-rules is taking a 10-digit DID number coming from the PSTN and breaking it down into a 4-digit extension. For our purposes, the DID coming into the system is 214-555-3XXX and the extension is 3XXX. Here’s what you will need to do for this task:

voice translation-rule 1
  rule 1 /^214555\(3...\)$/ /\1/

Ok, let’s stop there for a second and cover what we have just entered. The first line just states that you are starting a translation-rule and the tag for that rule is 1. That 1 has no relation to the 1 in the second line of “rule 1″. All of the rules inside a voice translation rule are processed sequentially and once a match is made the rule processing stops.

The first / simply signifies that you are starting the section where you will try and match a portion of the dial-string.

The ^ tells the system that the number that comes after it that it is matching MUST be at the start of the string. If you don’t have that in there, then it will match wherever it sees it (for instance, if you have a number of 01134521455530011 it would start matching at the 214).

The 214555 is simply the first digits that it will match. Take note, that anything matched by the system will automatically be discarded unless otherwise specified.

The \( is sort of like an escape sequence. If you see a ( or a ) then you will need to have a \ before it. What the \( and \) do together in this case is to split out a group of numbers that will be referenced later. In this case the numbers are 3 followed by any four digits.

The $ tells the system that the last number matched is the end of the dial-string to match. By using the ^ and the $ together you can ensure that you are matching exactly what you want to.

Next up is another / and this one tells the system that we’re done with the matching expression. It is then followed by another / and this time it means that we are starting with the replace string. In other words, everything between the first set of // will be replaced by everything in the second set of //.

The last thing that we need to cover on this one is the \1. The \ again is like an escape character and it says that what follows is not actually a number that we are putting in there but a group. In this case group 1. The easiest way to understand how it references a group is that in the match string, anything between a \( and a \) is a group. If you have more than one, then it just increments the number for each group. Since we only have one group in our match string \(3…\), the \1 puts 3… as the translated number.

We’re not done yet, let’s continue with configuration:

voice translation-profile DID
  translate called 1

Now we can talk about these next two lines. The first line just sets up a new profile called DID. You can call it whatever you want, just remember it is case sensitive. As I recommend with all variables, you should probably consider doing them all in caps or at least use a consistent naming convention across all variables.

The line translate called 1 tells the system to translate the called number with voice translation-rule 1 (referring to the unique translation rule tag that we discussed earlier).

The next step is to apply this translation-profile somewhere, and to do that you can do one of the following:

voice-port 0/0/0:23
  translation-profile incoming DID

OR

dial-peer voice 4444 pots
  incoming called-number .
  direct-inward-dial
  translation-profile incoming DID

I find that the first method is the easier of the two because if you, for some reason, have more than one inbound dial-peer then you need to remember to apply the translation-profile to each of the dial-peers you will use. With that in mind, the only line that needs to be addressed here is translation-profile incoming DID. The one thing about this command that has been known to trip people up is when to use incoming and when to use outgoing. The easiest way that I can think of to describe this is to look at it as the relationship of the call to the router. For instance, in out case the call is coming from the PSTN INTO the router, therefore it is incoming. If the call was going from the router OUT to the PSTN then it would be outgoing. With this command in place, you have officially completed translating the inbound 10-digit DID to a 4-digit extension.

Translating 4-Digit Extension to 10-Digit Caller ID

Ok, so this is kind of reverse of what we did before. Instead of making a large number into a smaller one, we need to make a small number into a larger one. For this section, I’ll put out all of the configuration at once and then cover the couple of lines that may need explanation.

voice translation-rule 2
  rule 1 /^\(3...\)$/ /214555\1/

voice translation-profile CALLID
  translate calling 2
voice-port 0/0/0:23
  translation-profile outgoing CALLID

You will notice that the second line of this configuration looks different than the previous example but that there aren’t really any different symbols than before. We still have a / signifying the beginning of a match string and a ^ saying that the string has to start with the next digit and then we have \( and \) specifying that there is a group that we will want to reference later, followed by a $ that says the string must end with the last character specified and a / ending the match string.

On the replace side of it, there is a / starting the replace string and then 214555, literally just digits that are put in place. Then a \1 to insert the first group from the match string (3… and that’s it. So this should take 3001 and translate it to 2145553001.

Next is the line ‘translate calling 2′. Pretty much the same here, except that we are translating the calling number instead of the called. Since this is to be used for caller ID, it needs to be calling because the phone on the phone system is the one that needs it’s caller id modified. The 2, just references the translation-rule 2 since we used 1 in the previous example (I’m assuming that all of these are on the same router).

Lastly, translation-profile outgoing CALLID is outgoing because the call is going from the router OUT to the PSTN. Remember, if we put this on a dial-peer instead of the voice-port then we need to add it to every outbound dial-peer that will send a call out that port.
Using Translations to Transfer a Call Directly to a CUE Mailbox

The next thing that we want to do is enable translations so that if a user can transfer a call directly to a user’s mailbox by dialing 5+Extension. In order to do this, we need a couple of different pieces than we have seen in the examples above. Here’s the configuration:

ephone-dn 40
  number 53...
  name Transfer to VM
  call-forward all 3600

voice translation-rule 3
  rule 1 /^5\(3...\)/ /\1/

voice translation-profile XTOVM
  translate redirect-called 3

dial-peer voice 3600 voip
  destination-pattern 3600
  session protocol sipv2
  session target ipv4:10.1.202.1
  codec g711ulaw
  no vad
  translation-profile outgoing XTOVM

We need to do the ephone-dn configuration so that when someone dials 53001, for instance, it will always be forwarded to the voicemail number and hit the voicemail dial-peer which, as you will see later, will call the translation-profile.

The voice translation-rule looks pretty much like the first example. There is a 5 before the extension and we are discarding it. The translation-profile looks a little different. When someone calls an extension and goes to Unity Express, it knows what mailbox to send it to by looking at the redirect number. Without the translation in place, the redirect number in this case would be 53001. That is the reason that we need to translate the redirect-called number.

Lastly, on the dial-peer that points to CUE (which we would need to access voicemail even if we weren’t doing the translation) we are calling the profile as an outgoing profile, again because the call is going OUT of the router and to the CUE.
Using Translations for Calls Coming from Gatekeepers

We’ve pretty much covered most of what I had planned on doing, but I wanted to do this one more section so that we could demonstrate a voice translation-rule with more than one rule. For our example, we will have a call coming from a gatekeeper. That call with have a tech-prefix as well as an international country code. For out example, three types of calls will need to be handled:

1. Calls to an internal number that are sent to the system as 2#5266123001 where 52 is the country code and 3001 is the extension.

2. Calls to an external local number that are sent to the system as 2#5266124923 where 52 is the country code and everything after the country code is what needs to be dialed for a local call (except the 9 for an outside line).

3. Calls to another country that are sent to the system as 2#38 and a variable string of digits. And we will assume that our outbound string to dial another country will be 900+country code+number.

In order to handle these three calls, your translations will look something like this:

voice translation-rule 4
  rule 1 /^2#526612\(3...\)$/ /\1/
  rule 2 /^2#52\(6612....\)$/ /9\1/
  rule 3 /^2#/ /900/

voice translation-profile FROMGK
  translate called 4
  dial-peer voice 4445 voip
  incoming called-number 2#T
  translation-profile incoming FROMGK

The actual rules are pretty similar to what we have seen before, we take a number and strip some digits off and in a couple cases add a couple back on. The most specific rule will always be on top because once it matches a rule, it stops searching. So you can see that the least specific (which just matches a string starting with 2#) is the lowest on the rule scale and will only be hit if the other two rules don’t match. One different thing about that last rule is that we aren’t matching the whole string. All that it looks for is 2#. We know that the calls from the gatekeeper all have an international code so if it doesn’t match our first rule (for internal calls) and our second rule (for local calls) that it has to be an international call, so we just replace the 2# with a 900 and leave the rest of the dial string alone.
Testing

Once you have your voice translation-rules built, you will want to make sure that you test them to ensure that they will work correctly. To do this, you will use the command: test voice translation-rule . Here’s an example of the command and the output that it creates:

test voice translation-rule 4 2#5266123001
Matched with rule 1
Original number: 2#5266123001 Translated number: 3001
Original number type: none Translated number type: none
Original number plan: none Translated number plan: none

You can see that our rule stripped off the 2#526612 and turned it into a station number of 3001.

There are several other things that you can use translation rules for, but for most of what you will need the above can easily be adapted to fit the situation. By using the principles covered in this document, you should be able to easily make them work where needed.