Currently this is an unofficial module that must be manually installed. It can be downloaded from:
choosing the latest version of the customcontext module. The easiest way to install it is to dowload it to your desktop and then choose "Upload Modules" in FreePBX Module Admin and install the module.
Then in FreePBX, click on the Tools tab, Module Admin, and Custom Contexts, select Install, click on Process, and then the red bar to complete installation.
- Restrict access to certain outbound routes or feature codes by a particular extension or group of extensions.
- Give particular extension(s) priority access to certain outbound routes, such as a particular emergency route associated with their geographic location.
- Give certain outbound routes top priority for use during "free" or low cost calling periods, while making those same routes lower priority (or disallowing access entirely) during higher cost time periods.
- Disallow access to outbound routes (with possible exception of Emergency access) to certain (or all) extensions during particular time periods (don't let night cleaning crew make long distance calls, or disallow outgoing night calls from telephones in children's rooms, while still allowing emergency number calls).
- Allow two or more families/companies/organizations to use the same FreePBX box, while still allowing each to have access only to "their" outgoing routes and trunks.
- If you have a SIP provider that does not send DID (normally a pain to handle because you can't create a normal Inbound Route), set up a new custom context (call it idiot-provider), give them no access to anything (deny all), and then specify where you want their calls to go in the Failover Destination. Then put context=idiot-provider in that provider's trunk user details.
What This Module Is NOT Intended For
- This module is not intended to provide an alternative way to access code that is found in, or might normally be placed in extensions_custom.conf. You probably want the DialplanInjection module if that is what you are trying to achieve.
- It's also not intended to give you simplified access to existing features, applications, or destinations (e.g. from an IVR) - you probably want to use Misc. Applications and/or Misc. Destinations (or possibly a Custom Extension) for that.
Please be aware that if you you have installed both this module and HUDlite on the same system, HUDlite will allow users to bypass any restrictions placed upon them by this module. Therefore, restricted users should not be given access to HUDlite. Also, a savy user can bypass the system. As soon as they transfer a call, the current dialplan puts them in a new context which is effectively from-internal taking away any restrictions.
One feature which was a bit lacking in Asterisk/FreePBX was the ability to easily create multiple tenants.
This module creates custom contexts which can be used to allow limited access to dialplan applications.
Now allows for time restrictions on any dialplan access!
This can be very useful for multi-tenant systems.
Inbound routing can be done using DID or zap channel routing, this module allows for selective outbound routing.
House/public phones can be placed in a restricted context allowing them only internal calls.
Custom contexts can now be used as destinations. An IVR menu, Time Condition, etc. can now send a caller into a custom context. This feature requires FreePBX 2.2.0rc2 (or the latest SVN version if prior to the release of rc2)
(The following are the module author's comments, "I" refers to the module author, not the original creator of this wiki page).
A number of improvements have been made to freePbx to handle multiple tenants.
1) inbound routing based on zap channel - i used to have to hack it by putting each zap channel in its own context.
2) authtype = database allows for dividing extension ranges
the main problem for me was outbound routing...
I wanted some extensions to dial out one route, and others out another route.
I had to create a custom context for each, then place each in their own custom context, then include all of the contexts which they should have access to. This became a nuisance as each module added its own context to from-internal-additional which could not be included as it also contains outbound-allroutes.
The purpose of this module is to dynamically list all contexts included in any contexts you choose, and allow you to create custom contexts which can include any of these all without config editing.
As an added bonus, I added a select list to the devices/extensions page to allow you to easily select any of your custom contexts to place the device in.
Version 0.1.1 - Now has optional Time Groups which allows you to name a set of times to enable the user to not only deny or allow access to certain dialplan contexts, but to control access to each context by time, date or day also.
Version 0.1.2 - Changes
Bugfixes- deleted routes, etc. now are removed.
Context tests for spaces and illegal chars.
Moved admin to tools to reduce confusion.
Added option to allow entire internal dialplan. (Useful for time limit on everything)
Made description for outbound-allroutes clearer that allowing overrides to allow all routes.
Version 0.1.3 - Made it obvious when allowing one include may allow another entire context.
Version 0.2.0 - Added priority feature to allow the user to control in what order the allowed contexts are included.
Version 0.2.1 - Added Duplicate Context option to easily copy an entire set of rules.
Version 0.2.2 - bugfix
Version 0.3.0 - New Features:
Allow or Deny based on pattern matching.
Failover Destination (one for regular extension, one for failed feature codes)
Adjusted Gui, Duplicate context, now duplicates the description too.
Version 0.3.1 - New Features:
Now prompts on delete. After duplicate you are editing new context.
It is now possible to rename contexts.
Version 0.3.2 - New Features:
Optional PIN to protect failover destination.
Contexts can now be used as destinations. An IVR menu, Time Condition, etc. can now send a caller into a custom context.
Version 0.3.3 -
New Feature: Added Set All option to quickly allow/deny all.
Fixed bug which caused routes to be denied after rename/sort/or delete other route.
Version 0.3.4 -
Fix for compatibility issues with FreePBX version 22.214.171.124.
Installation of Beta version
Download the latest Beta version using the instructions in the first paragraph.
If you did not use the instructions for getting and installing the module using wget, then expand the .tgz file into the /var/www/html/admin/modules directory - it will create a new directory called customcontexts. Make sure the group and owner of that directory are asterisk and that the permissions match that of the other module subdirectories.
Browse to FreePBX, Tools | Module Administration. You should see an entry for Custom Contexts. Click on it, click install, then click process and the red bar as usual.
Most users will not need to do anything in the Custom Contexts Admin section (now found under the Tools tab) - that is for advanced users. When you "add" or "remove" contexts from the Admin, you are not really adding or removing anything, you are just telling the module where to find all of the includes to list. By default there are three includes which should be sufficient for most users: from-internal, from-internal-additional, and outbound-allroutes. So, skip the Custom Contexts Admin section until you feel comfortable making changes there.
The first thing that you will want to create is time groups, if you plan to use those. The reason for doing this first is so that they will become available in the drop down selections when you create your custom contexts. For each group you create, you can decide which times it should be available. You can define multiple times within one named group, and then each named group then becomes available along with allow/deny for each choice under a custom context (this will become clearer further down), so you can allow, deny, or choose your time group to allow only at specific times/dates/days.
One thing to bear in mind when creating time groups is that this module will not forcibly end calls in progress. So if, for example, you have "free" calling on a particular route from 9:00 PM to 7:00 AM, you probably don't want to set the end time right at 7:00 AM, because then someone could make a call at 6:59 and talk for several minutes into the non-free period.
Now, to actually create a Custom Context, you go to the Custom Contexts page, and add a context - note that the context name may NOT contain spaces. Then add a description (spaces are okay here) and submit.
We'll talk about Dial Rules later - in many cases you will want to leave the Dial Rules blank.
Once the context is created, you can edit it to allow or disallow the features and routes you want a particular extension (or group of extensions) to have access to. There is a "Set All" option to set all the features and routes to Allow or Deny - this is useful when you want to start out with all of the dropdowns in one state, so that you only need to change the exceptions. Then choose "Allow" or "Deny" for each application or route - for example, you may wish to allow all, except for the items you specifically wish to restrict (for example, you probably want to restrict ChanSpy and ZapBarge!). If you have created any time conditions, it will also be possible to select those, to allow a feature or route to be accessed only during certain times. If you have any Dial Rules, you can choose to "Allow Rules" (allow the feature or route only if a Dial Rules pattern is matched) or "Deny Rules" (deny the feature or route only if a Dial Rules pattern is matched).
Certain items are in bold red letters, such as "ENTIRE Basic Internal Dialplan" and "ALL OUTBOUND ROUTES." If you allow ALL OUTBOUND ROUTES, it will override the individual route selections in the following section. So if you want users of this context to have access to all outbound routes, you can just allow outbound-allroutes and ignore the individual route sections (leave them all set to "deny"). But if you want to select routes individually, then make sure that outbound-allroutes is set to "Deny". Of course, you could also use non-overlapping time conditions for outbound-allroutes and individual routes.
If you allow "ENTIRE Basic Internal Dialplan", then it overrides every other selection on the page. You would normally only use this with a time rule, to allow your unaltered dialplan to be used for a portion of the day. Allowing the "ENTIRE Basic Internal Dialplan" without using a time rule is usually pointless. If you want control over individual items, deny "ENTIRE Basic Internal Dialplan", and allow only what you want.
Associated with each item a "Priority" dropdown. All priorities are set to 50 by default (so you can easily make any item higher or lower in priority). The best use of these is in the Outbound Routes section - you WILL want to make sure that any Outbound Routes that you allow are ordered by priority, otherwise your outbound calls may not be routed as you expect. Normally you will want to mirror the priority of the existing routes - the easiest way to do that is add 50 to the number at the start of the route, so for example if you have a route called "outrt-001-Emergency" you could add 50 to the "001" and use 51 as the priority. But note that you do not have to mirror the default priority of routes, which could become useful in certain situations.
For example, let's suppose you have an emergency route that goes to a an emergency answering point in your local area, but you also have another emergency route that goes to an emergency answering point in a community where you have a remote office. You could create two emergency routes going to the two different answering points and let the one going to the local point be higher in priority normally, but create a custom context for your remote extensions and in that custom context, make their community's emergency answering point higher in priority.
One more note about priorities - you can hide the display of the priority dropdowns by clicking on "Hide Sort Option" at the top of any custom context page. BUT - if you click on the "Submit" button while you have the priorities hidden, all the priorities on that page will be reset to the default (50)! So use this option with care!!
Note: This option is no longer available as its purpose was to clean up the page when priorities were listed below each context. Now that the display was fixed, the "hide priorities" option was removed.
At the bottom of the page, you can select a Failover Destination and a Feature Code Failover Destination. The Failover Destination is used when the called number does not start with a * and does not match on any route, while the Feature Code Failover Destination is used when the called number begins with a * and does not match any feature code. Be careful here, because it's possible to send a caller to a destination that gives them access to destinations that you don't intend for them to be able to access. Either or both of the Failover Destinations can be PIN protected, that is, you can enter a numeric PIN to require authentication before continuing to the destination.
Regarding Dial Rules, these can be used when you want to further allow or restrict access based on the number dialed. For example, you could give an internal caller access to a particular route only if 911 was called, or if a local number was called, while restricting their ability to place other calls on the same route. It's also possible to use the | character to strip off initial digits. For example, if you had a dial plan that included something like 90210|1NXXNXXXXXX you could set an outbound route to "Allow Rules" and it would generally restrict access to that route, except for those callers that know that they must dial 90210 prior to the 1+area code+number.
Sometimes you will want to create a new custom context that is very similar to an existing custom context you have already created - perhaps you only want to modify one or two items in the new context. The easiest way to do that is to go into the existing context, then click on "Duplicate Context ..." at the top of the page. This will create a duplicate of the existing context that you can edit as you
Finally, you need to go to your Extensions page and select each extension for which you wish to use a custom context. On each individual extension page, you should now see a dropdown to allow you to select a custom context. This drop-down is simply a convenient way to fill in the correct context in the "context" textbox. When you click on a custom context, it replaces whatever is currently in the "context" textbox with your new selection - if you choose "Default", it resets the extension back to the default "from-internal" context. Don't forget to click "Submit", and then click the red bar when you are all finished making changes.
NOTE that if you disable or uninstall the Custom Contexts module, you MUST reset all the extensions back to the default "from-internal" context. If you delete a time group, anyone who had that time limitation becomes "Allow" with no time restrictions. If you add a new outbound route, by default that route is set as "Deny" in the Custom Contexts, so you should go into each context and set it to "Allow" (or use a time condition) where appropriate.
One more caveat. After you add an outbound route, it is not available until you reload.