Outbound Route Permissions

This module allows you to block access to certain routes from specified extensions. You can do bulk changes (for a range of extensions) on the module's main page, or you can individually change access to routes on each extension's page.

You can also pick a Default Destination if a call is denied (so you can send the caller to a recording, etc.). If you wish to use a different destination for denied calls in a particular situation, see the usage tip below.

Note that Asterisk is incapable of having two identical routes and trying to force calls to use the other route if one of them is banned by this module. It will not work. You must have unique outbound routes for the proper selection to work. N.B. Just having different trunk selections does NOT make the routes non-identical!

If you wish to emulate this functionality, you can use the 'Redirect' function. Any number you type in the 'Redirect' range will be PREPENDED to the number dialed, and the call will then be sent through the dialplan again (specifically, it will be sent back to the from-internal context). For example:

• Route 1: Zap/1 matches 0|.
• Route 2: Sip/Foo matches 1|.

If you wanted to stop extension 100 from using Zap/1 at all, and send all his calls through Sip/Foo, you would need to DENY 100 access to Route1, and create a NEW route, Route3:

• Route 3: Sip/Foo matches 9990|.

In the 'Redirect' field, type '999'. When extension 100 dials 0123456, they match Route 1. Route 1 FAILS, and then system invisibly changes the number dialed to be 9990123456 (note the '0' he dialled originally is preserved, and you then strip 9990 from the front in Route 3), which matches Route 3 and the call is then sent via Sip/Foo.

Redirect rules are only checked if the route is DENIED.

You can set a Default Destination if calls are denied. If you wish to use something other than the default in a specific instance, you can use a Redirect prefix and a Misc. Application. Example: set the redirect prefix to 000123, then create a Misc. Application and set the Feature Code to _000123. (note the underscore at the start and the period at the end of the Feature Code - both are necessary), then make the destination of the Misc. Application whatever you wish.

Caveats: If you already have a large dialplan, see How to increase the execution time and/or memory allowed for "orange bar" reloads - you may need to increase one or both of those values. Also, you probably should be running the SVN version of FreePBX (however, it appears to work with FreePBX 2.5.1.2).

The latest release can be found at:
http://www.freepbx.org/trac/browser/contributed_modules/release
(the filename is routepermissions-version.tgz)

Usage tips:

Apparently some users seem to be having problems because they don't understand that you need to have one route where the number called by the user is matched exactly. For example, if you want different groups of users to access different trunks whenever 1NXXNXXXXXX is called, you must have a route that has the pattern 1NXXNXXXXXX (or some acceptable variation - see next paragraph) in the Dial Patterns textbox, and that should be set to use the trunks that you want the majority of your users to be accessing. You allow access to that route for those users, then for the "exceptions" you disallow access to that route and (optionally) use a Redirect Prefix to redirect the call to another outbound route. What you cannot do is use is use a Redirect Prefix in front of the pattern on ALL your outbound routes. One route should contain a pattern that exactly matches whatever the caller dials. Then you can have other routes that include the same pattern, but with a Redirect Prefix.

Note that saying that the pattern must be matched exactly does not mean that you cannot add or strip digits in your primary route - it just means that one route must have a pattern that exactly matches what the user actually dials. So if your users dial 1NXXNXXXXXX but all of your providers only want to see the last ten digits, you could use 1|NXXNXXXXXX in your primary route, and then if you want to use a Redirect Prefix of 00009 with some extensions, you'd have another route with the pattern 000091|NXXNXXXXXX (note that in real-world use, it's probably better to strip the leading "1" at the trunk level, because different providers have different requirements. But this is just an example to clarify what is permissible).

Another point: When a call is denied and a prefix is prepended, the call is then sent back to the from-internal context, as if the user had dialed the call with the prefix prepended. While it's normally expected that the system will try to match the modified number using a route, so that the call will be sent out on a different trunk (or group of trunks) for that particular user, that doesn't necessarily have to be the case. Here's a trivial example:

Let's say you have to pay a charge for directory assistance calls. You have a route set up that handles nothing but directory assistance calls (matching 411, 1NXX5551212, and perhaps other patterns associated with the service). You have one user that refuses to look numbers up online or in the telephone directory, and has run up hundreds of dollars in directory assistance changes. You want to block his calls to directory assistance, but you also want to play a recording of the boss telling him that if he runs up one more cent in directory assistance charges he's fired!

So you block the calls and use a redirect prefix (I always suggest using redirect prefixes that start with several zeroes because generally speaking, no "normal" dialing pattern would ever start with more than about two zeroes). So let's say you make the redirect prefix 0000034733 (34733=FIRED on a phone keypad, it's just an example here). Now you create a Misc. Application and set the Feature Code to _0000034733. (note the underscore at the start and the period at the end - the underscore specifies that this is a pattern and the period that there will be additional digits after the prefix). Make the destination of the Misc. Application the Announcement that corresponds to the boss's recording.

Now, whenever he makes a call to directory assistance, the number he called will have the prefix prepened, and then the call will be sent back to from-internal where the Misc. Application will catch it. And note that you can use a Misc. Application in this way to send the call to almost any system destination. Coupled with a Misc. Destination, you could even reroute calls from a particular user to a particular number, to go to a different particular number. This potentially makes this module a very powerful tool in routing calls from a particular extension.

Here's another example: You can have speed dial codes that are specific to a group of extensions. For example, let's say you want to make 222 a universal speed dial on your system for the home telephone number of the department manager, but you have several departments, each with their own manager. You could make a Misc. Destination for each manager's home phone (with the manager's number in the "Dial" field), then make a Misc. Application for each (making the destination the Misc. Destination you just created), but in the Feature Code textbox use a unique prefix in front of the 222 (first manager would be 00001222, second would be 00002222, third would be 00003222, etc.).

Also create a "catch all" Misc. Application that goes to Terminate Call: Congestion, or to a "Sorry, you call cannot be completed" recording or something of that nature, and assign the Feature Code 0000000000 to it (this will only be used if a caller dials 222 from a phone that is not part of a department with a manager).

Then make a CUSTOM trunk with the following Custom Dial String (this is the only field you need to fill in): Local/0000000000@from-internal

After creating the trunk, create a new Outbound Route with 222 as the only entry in the Dial Patterns textbox, and select the Local/0000000000@from-internal trunk (created in the previous paragraph) as the only trunk choice for that route.

Finally, in the Outbound Route Permissions section of each extension's configuration page (for every extension that is part of a group with a manager that should be reachable by dialing 222), check "No" for the 222 Outbound Route, then enter the appropriate prefix of the correct manager in the Redirect Prefix text box (00001, 00002, 00003, etc.). Alternately, you can make bulk changes to entire groups of extensions at once from the Outbound Route Permissions page. Now, when a user in a department dials 222, the call to the "222" route will be disallowed, but the correct prefix will be prepended and then the call will flow through the Misc. Application/Misc. Destination pair and call out to the appropriate manager. Should someone dial 222 from a phone not part of a department, use of the Outbound Route will be allowed (unless you simply disallow it and don't specify a redirect prefix), but it will go to the Custom Trunk which will send it to the "catch all" Misc Application.

Why it doesn't work when you try to use the same dial pattern in two different routes:

Some people try to make two routes that contain identical dial patterns and wonder why the second route in never used, even when access to the first is denied.

Perhaps it will help if I explain it this way. When you place a call, irregardless of what you may or may not have done in routepermissions, Asterisk goes through your routes one by one and tries to match the number called to the patterns in your routes. It stops searching on the FIRST match it finds, and that's it - under no circumstances will it look at any other route once it's found a match. Only AFTER it has found a match (actually, only after it's already sent the call to a trunk) does it check to see if the user has permission to use that route. If yes, the call goes through, but if no, the call stops dead in its tracks (and if you haven't supplied a redirect prefix, it goes to the default destination).

Let's say you have a second route with identical dial patterns as the first. Your outbound calls will never use it, no matter what you do. Remember: Asterisk stops searching on the FIRST match, and it doesn't check to see if the user is allowed to use the route until AFTER it's made that match.

So that's the point of the redirect prefix. Let's say your first route has the pattern 1NXXNXXXXXX (not something I'd recommend unless you want to allow some really high-cost calls to the Caribbean, but it's just an example here). If in your second route you also put 1NXXNXXXXXX, that pattern will never be matched. It HAS to be unique. So what I might do is instead use something like 0001|1NXXNXXXXXX for the second route. Then when you deny access to that first route, you put the 0001 prefix in the "redirect" text entry box. Now let's say you make a call to 1-800-555-1212 from an "alternate route" extension:

● User dials 1-800-555-1212

● 18005551212 is sent to from-internal context which begins looking for a match on the number in the route dial patterns.

● A match for 18005551212 is found in a route, the one and only route that will ever be used for the number 18005551212.

● The call is then sent to the first trunk in the list associated with that route.

● One of the first things the trunk does is to determine if the user (identified by Caller ID number) is allowed to place calls via the route that the call just came from (which is still available in a variable). In this case it finds that no, the user is NOT allowed to place a call on this route, BUT that a redirect prefix of 0001 has been supplied

● The called number is then modified to be 000118005551212

● 000118005551212 is sent back to the from-internal context which begins looking for a match on that number in the route dial patterns.

● A match for 000118005551212 is found in a route (hopefully NOT the same one that would match 18005551212), the one and only route that will ever be used for the number 000118005551212.

● Because of the bar character in the dial pattern, the digits 0001 are removed from the called number - note that at this point the route has already been selected - so the number again becomes 18005551212 before being passed to the trunk.

● The call is then sent to the first trunk in the list associated with that route.

● One of the first things the trunk does is to determine if the user (identified by Caller ID number) is allowed to place calls via the route that the call just came from (which is still available in a variable). In this case it finds that yes, the user IS allowed to place a call on this route.

● The call then goes out the selected trunk - or if that trunk is busy, it will try any other trunks associated with that route.

I hope that helps you understand why you can't use the same pattern in two different routes and expect it to work. You must use a redirect prefix on at least one of the patterns so that it will be recognized as unique.