Expanded Repository Access and Some SVN Changes

What is SVN and what are you talking about? FreePBX keeps all of it’s source in our [url=/trac/browser]Revision Control System[/url] as does any properly run software project whether it is Open Source or not. For FreePBX, we use the Subversion SVN system. The purpose of such a system is to easily manage changes and releases, recover from mistakes, experiment with new functionality, etc.

The previous SVN repository allowed write access to be granted to a user to either the entire repository or none of it. Everyone can read it. This restriction has been a limiting factor in our ability to accommodate new developers who may not be ready to have access to the entire system but we may want to give them access to a particular subsection, experimental branch, etc.

Today we are announcing changes to the SVN repository that will allow such access. As part of that change, we created a new section of the repository for Contributed Modules to FreePBX. These modules have not yet or will not become part of the primary project but are available for all to access and for the authors to maintain. This is great news for both contributors and the users who are interested in getting access to these modules. You will no longer have to go looking for that tarball stored away in ticket XYZ and we will now be able to give individual contributors access to their own modules so that they can maintain them and provide visibility of changes and fixes just like you have with the rest of FreePBX. We are excited about this new capability which is just one more step in our [url=/freepbx-development]Open Source Development Philosophy[/url] to allow expanded access and community involvement in this great project!

If you have previously pulled code directly from SVN (with the [i]svn co[/i] command), then you should visit the [url=/support/documentation/installation/upgrading-your-system#svn]Installing From SVN[/url] instructions which will describe how you can [i]switch[/i] your current SVN copy to point to the new URL location using the [i]svn switch –relocate[/i] svn command.

For normal every day use and and access to the Module Admin Online Access within FreePBX, there is no change. Everything will continue to run as always. If you have previously contributed a module or have been hosting your own module and would like to get it in the repository you can either contact one of the developers (look for us in the #freepbx-dev IRC channel) or just [url=/trac/newticket]open a module submission ticket[/url] and either attach the tarball or give us a link where we can get it and add it to the repository. We will then provide you with access to it so that you can maintain it properly.

Follow Me or VmX Locater™ – Which One is for You?

Some people like to have all calls follow them and ring all
their phones. Others may prefer to not be bothered by every call; if the caller
really needs them now, they would like an option but prefer to have voicemail
handle the less urgent matters.
FreePBX offers two different features that are designed for these scenarios, Follow Me and VmX Locater. But why choose between the two when you can have the
best of both worlds?

Making Follow Me and
VmX Locater Work Together

These two powerful features are designed to work together so
you can have the ultimate solution for your personal needs. Instead of choosing
one or the other, why not have the caller choose what they want: leave
voicemail now, or try to locate you?

Let’s describe some behaviors that we would like to achieve
and then go about showing you how easy it is to configure this scenario.

Desired Call Flow

  • When a
    Caller calls and we are not in the office, we would like to send them to
    the voicemail system and present the unavailable
    greeting along with options to locate us if desired. If we are on the
    phone we would like them sent to the busy
    greeting and not present any options but voicemail. (If we had chosen to
    take the call, we would have done so on our Multi-Line or Call Waiting
    enabled phone.)
  • In the
    unavailable case, we instruct
    the caller that they may leave us a message now, or if urgent, they can
    have the system try to find us by pressing 1.
  • If the
    caller does not consider this urgent, they leave a message and are done.
  • If the
    caller considers this urgent, they choose option 1 and are sent to the Follow Me setup.
  • The Follow Me configuration attempts to
    find you. If not successful then it returns to voicemail, this time to the
    busy greeting where they no
    longer have an option to keep trying to find you. In your busy message you indicate you are
    not reachable at this time and they must leave voicemail or try you later.

Let’s walk through the steps required to enable this very
powerful and easy to configure setup. First we configure the user’s unavailable and busy greetings in voicemail. Next we enable VmX Locater for this user and create their Follow Me feature. Lastly, we configure our user’s VmX Locater and Follow Me settings from the User Portal (ARI).

Create the Messages

Let’s begin. Here are a couple of examples for the Unavailable and Busy messages:


“I am not able to get
the phone right now. You can leave me a message after the beep or if this is
urgent, you can press 1 now to have the system try to find me. If it can not
find me you will be returned here to leave me a message”


“I am either on
another line or not reachable at this time. Please leave me a message after the

Enable the Features
in FreePBX

Now that we have the two messages, we will set out to
configure what was described above. The flow chart in Figure 1 describes our
desired behavior.

Follow Me / VmX Call Flow


Figure 1

We must first enable both the Follow Me and VmX Locater
features in FreePBX. Navigate to the desired extension/user GUI screen and
enable the VmX Locater feature. We
will use extension 200 in our example. You will need both Voicemail Status Enabled and VmX Locater™
as shown in Figure 2.

Enable VmX Locater

Figure 2

The rest will be done in the ARI User Portal. Before going there,
we will also create the initial Follow Me
feature as shown in Figure 3. So while you are in the Extension/User GUI, click
on the Add Follow Me Settings (or Edit Follow Me Settings if one already
exists). You are taken to a screen similar to Figure 3.

Follow Me Setup

Figure 3

The important things to set here are the desired Ring Strategy and the Destination if not answered. (These can
not be set in the User Portal) Our favorite Ring Strategy is the RingallV2-prim which you can read more
about in one of our past articles here. To accomplish the goals we have set,
you will want to choose the Voicemail
<200> John Smith (busy) Destination
. We will configure the remaining
settings in the User Portal.

Configure the
Features in the User Portal (ARI)

With these features setup, we (or the user) move to the ARI User
Portal to finish. (Since you probably do not want to give normal user’s access
to FreePBX if you care about the integrity of your phone system.)

Log into the User Portal Recording Interface. (This is the
Recordings tab at the top of the FreePBX Screen, or navigate to it
directly). Next choose Follow Me on the Left navigation
section. Figure 4 shows what we have chosen to configure.

Follow Me ARI User Portal Configuration

Figure 4

We have chosen the following configurations:


Unchecked – which means that phone calls will not
automatically be sent to our Follow Me
setup. This makes it only accessible through the VmX Locater.

Follow Me List:

We list the numbers that we want in our Follow Me list. Note that we must include our own extension if we
want it rung as well. Also note, there is no ‘#’ required at the end of an
external number. The system figures this out by itself.

Ring First For:

We like the initial ring time. This is not really necessary
in the example we are describing but makes it more convenient if you like to
switch back and forth between using Follow
directly or only through the VmX Locater. You can leave it at 0 if it
does not apply to you.

Ring Follow Me List

Make sure this time is long enough for the user to answer their
cell phone and press 1 to confirm the call if using confirmation.

Use Confirmation:

Checking this box will assure that all calls sent to an
outside line (vs. internal FreePBX extensions) will require the user to confirm
the call by pressing 1. This keeps calls from dropping into cell phone
voicemail, answering machines or other undesired landing spots.

That provides our desired Follow Me configuration. We must now setup the VmX Locater configuration to. Choose the VmX™ Locater menu option and you will be presented with a screen as
shown in Figure 5.

VmX Locater ARI User Portal Configuration

Figure 5

We have configured the options as follows:

Use When:

By checking unavailable
but not busy we are configuring the
system as drawn in Figure 1. If the phone is busy, or the caller has already
flowed through the Follow Me process
and was sent to the busy destination
if no answer then you do not want them to be able to choose to keep trying your
Follow Me.

Voicemail Instructions:

This is a personal preference. If checked the caller will be
presented with the standard voicemail system instructions concerning leaving a
message, reviewing their message, etc. after playing your greetings. Un-checking
this box will disable that system message.

Press 0:

If you have a personal assistant or alternative choice for
what to do when people press 0, you can uncheck this box and provide the number
here. Otherwise the system default for zero-ing out of voicemail will be used.

Press 1:

Checking the Send to
is what does our magic and makes sure that this option gets sent
to Follow Me even though we had
disabled it in the previous section.

Press 2:

If you really want to complicate your caller’s lives you can
present them with yet another option and put a number in for option 2. Some
people also choose to use this option but not “announce” that it is available. We’ll leave it to the reader’s
imagination of how they may choose to use this option. (And for those of you who
like to look under the hood, there are also options 3-9 that can be programmed
but are not exposed in the GUI.)


That is all there is to it. You can now go back and review
Figure 1 to see the call flow that is presented to callers when they try to
reach you. Both voicemail messages are recorded in the Voicemail system by the
user as they would always do so. The Follow-Me
and VmX Locater configurations are
controlled by the user in their ARI User Portal once created and enabled by the
Administrator. They can then easily manage their own configuration, whether
they choose the one described here or other preferences.

We hope this has been another useful addition to our
Technical Corner. We will will return to the Under the Hood series in our next article.

FreePBX Devices and Users Under the Hood

FreePBX is often referred to as a GUI to manage Asterisk
configuration files. This misconception leads to confusion when Asterisk knowledgeable
users begin to dig into a FreePBX system and find so many things that look
foreign or different from what they are used to.

FreePBX is a sophisticated PBX Framework that transforms a
LAMPA System (Linux, Apache, MySQL, PHP, Asterisk) into a world class PBX.
Asterisk is a great tool just as PHP or gcc are great interpreters and
compilers. But without sophisticated business logic and data structures they
will not do a lot for you. FreePBX provides this application layer on top of the
LAMPA foundation to deliver this. This next series of articles will take a walk
through the different components of FreePBX and discuss how and why things are
done the way they are.

We will briefly step up to a birds eye view of the system
and then spend the rest of this week’s article exploring what is up with all
these FreePBX Users (AMPUSER) vs. devices vs. extensions.


Figure 1

Figure 1 illustrates an architectural view of the overall
system. We will defer the long architectural discussion for another day and
focus in on some of the FreePBX Core Dialplan Objects and a minor discussion on
one of the FreePBX Core Application Library components used by these FreePBX


Figure 2

Figure 2 highlights the AMPUSER and DEVICES Astdb objects that we will be talking about
for the rest of this article.

If you are familiar with Asterisk, you may likely equate a
phone’s extension with an extension number in some Asterisk context that is
directly associated with a specific Endpoint, for example a SIP phone.. An example may look like:

[internal] exten => 2002,1,Dial(sip/2002,${RINGTIME},${DIALOPTIONS})
exten => 2002,2,Voicemail(2002)

This is where FreePBX takes a diversion and separates this
extension into at least 3 chunks of information.

  • FreePBX
    User (AMPUSER)

This is the user, identified by
their internal extension number.

  • FreePBX
    Device (DEVICE)

This is the FreePBX Device number
that is uniquely associated with some physical Endpoint such as a SIP phone,
zap FXS channel, etc.

  • Endpoint

This is the actual Endpoint
configuration. In the case of a SIP End Point this would be the information
written into sip_additional.conf for example, and ultimately the Endpoint’s
provisioning file or nonvolatile memory.

If you are like the majority of users, you are only familiar
with the Extension GUI page for configuring an extension. Under the hood
everything is always running in what is referred to as the deviceanduser mode. In this mode, FreePBX extensions are actually separated into
the FreePBX user and the specific devices that a user can be attached to. This
allows a single user to have multiple devices with the same phone number. It also
allows a single device to be used by multiple users in a hot desk style
environment, where a user logs into the device resulting in it becoming their

and AMPUSER Objects

As shown in Figure 2 FreePBX uses objects stored in the
native Asterisk database, Astdb, to manage many of its internal features and
in this case, the FreePBX Users and Devices.


Each EndPoint, regardless of the technology type, is stored
in a unique FreePBX Device object. This is one of the simpler objects currently
containing 4 vital fields:


How to contact the associated Endpoint. E.g. SIP/2212


A device can be fixed
or adhoc. A fixed device is
permanently assigned to a single user. An adhoc device is available to be
logged into by different users such as the hot desk example.


The user that a fixed device is assigned to, or the user that
an adhoc device is currently assigned to.


The CallerID associated with this device, vs. with a user,
to be used when a call is placed on an emergency route. This allows a physical
device to supply a CallerID associated with its physical location vs. a user’s
CallerID which may be from a different country.

This DEVICE object provides the bridge between the specific
technology (e.g. Endpoint SIP/2212) and the user that is currently associated
with that device. It also provides an insulation layer that allows a different
End Point to be easily substituted for another without any change to the rest
of the system.

If your particular device is 320, you can see the details of
that device by going to the Asterisk CLI and typing database show DEVICE/320.

End Point Identity

The Device information is fine for the FreePBX system to
contact the device, however FreePBX needs a way to associate an End Point with
a Device when the End Point is initiating the call. This is done by configuring
the CallerID of the End Point to the Device number. For SIP, IAX and Zap
devices, this is automatically handled by FreePBX. If you configure a SIP
extension or device, you should see the resulting callerid = device <num> in the sip_additional.conf
configuration, for example.

FreePBX User

Since FreePBX grew up in its youth as AMP (Asterisk
Management Portal), it still possesses much of its heritage under the hood with
naming conventions. The AMPUSER object represents the FreePBX user and can
contain a wealth of information about that user depending on which modules and
features may be enabled for them. The AMPUSER object associates a
user/extension with its corresponding device(s) at any point in time.

Some of the core attributes of the AMPUSER object are:


The Display Name associated with this user, used for
internal calling only.


The extension number to be displayed with this user on
internal calls. Usually the same as the user’s number unless they are
masquerading their internal caller id.


CallerID information (“Name” <num>) to be used for
external calls (usually to the PSTN)


All devices that are currently associated with this user. For example, if the user had devices 1320 and 2722 then the entry would be "1320&2722"


A password this user would use to logon to an adhoc device


Number of seconds to ring this user before failing over to
voicemail or Call Forward Unavailable. (Set to 0 when using the system default.)


The voicemail context of this user, or novm if no voicemail


Recording settings whether or not to automatically record
inbound/outbound calls or disallow them, or allow On Demand recording.

These fields provide the vitals to manage the given FreePBX
user/extension and associate it with any number of devices. There are many
other attributes that control features such as FollowMe or VmX Locater™ and
others. If your particular user/extension number is 320 you can see all these
settings by typing database show AMPUSER/320
at the CLI.

Many core functions and AGI scripts depend on this
information to make the PBX function and deliver the rich set of features that
are provided. We will look at one in particular to understand how the link is
made when an Endpoint originates a call.


When the End Point makes a call, it appears in FreePBX
within the proper context that is configured with just its configured CallerID,
that of the DEVICE previously discussed. In order to associate that device with
the proper user, one of the first things that is done in the
dialplan is to call Macro(user-callerid).
One of the main things that this function does is to lookup the current
identify of this End Point and associate it with the configured user’s identity
(proper CallerID, etc.) so that the normal channel variables are properly
configured. Doing this assures the proper internal and outbound CallerIDs are
used and any other configurations for this user are known.

Calling a user’s

There is a bit more involved when you call a user which is
beyond the scope of this part of our tour since it can involve many steps
depending on what features the user may have enabled. At the basic level,
calling a user results in FreePBX looking up all the associated devices that
are defined in the user’s AMPUSER object. It then rings all of the associated
End Points for those devices by looking up the dial field in each of those DEVICE objects.


We’ll wrap up this week and try to pick this up soon by
exploring other corners under the FreePBX hood to see how more of the system
works. We hope you find this interesting and useful. Tell us what you think or
what other parts of the system you may wish to hear more about next.