Incredible PBX: Adding Google Calendars with Asterisk 1.8

One of the exciting new features in Asterisk 1.8 is external calendar integration including iCal, caldav, Microsoft Exchange, and ews. Hats off to Terry Wilson at Digium® for his great work on the calendaring API. Unfortunately, there hasn’t been much written about integrating the calendars into FreePBX®-based Asterisk® systems… until now. Because we’re all about free, our focus today will be Google Calendar integration, but we’ll provide you some links to get any of the other calendar types integrated into PBX in a Flash and Incredible PBX if that’s what floats your boat. In addition to being free, Google Calendar is one of the best calendaring apps on the planet. Its beauty lies in the incredible flexibility it provides for group scheduling and the sharing and transparent integration of dozens of calendars (both public and private) not to mention real-time updating with your favorite Android smartphones. Apple does much the same thing with iCal on the Mac and iPhone… for an annual fee.

The rainbow of colors you see in the left column of the screenshot above each represent a different calendar. All of the calendar entries from all of these calendars are integrated into the single calendar display on the right with a simple color scheme to identify where each calendar entry originated. As mentioned, these calendars can not only be from your friends and business associates, they also can be publicly available, read-only calendars for subject matter such as holidays, schedules of your favorite sports teams and rock bands, school calendars, etc. Take a look at iCalWorld to get a quick handle on what’s available. See also this Google resource.

The one bit of advice we would provide in setting up Google Calendar is don’t put all your eggs in one basket. Create separate calendars for different individuals and for different types of events. And don’t mix business with personal. Also keep internal business events separate from those that you might want to share with customers. Down the road, this facilitates sharing just the information of importance to different groups of friends and business associates. Bottom Line: Spend a little time thinking about organization of your calendars. It will pay off handsomely down the road.

Once you integrate Google Calendar into Incredible PBX, you can use it to alert you to upcoming appointments, to schedule and activate conference calls, and even to log the date, time, length, and recipient of all your outbound and/or incoming phone calls.

For today, we’ll get the software installed and functioning. And we’ll help you set up a simple reminder system based upon appointment entries in your Google Calendar. We’ll also give you some good reference materials so that you can experiment a bit on your own. In coming weeks, we’ll build a time slips system to keep track of all your phone calls.

Prerequisites. As mentioned, you’ll need a Gmail account as well as Asterisk 1.8 and PIAF-Purple with Incredible PBX 1.8 to follow along in today’s tutorial. All of the pieces are optional except for Asterisk 1.8 and a fairly current version of FreePBX, but we’ll leave that exercise for the pioneers. The script is licensed as GPL code so knock yourself out.

The Gotchas. Nothing is ever easy, is it? There always are a few surprises to worry about. Here’s the current short list for Asterisk Calendaring. When you schedule a meeting or appointment with Google Calendar, there is an option to set an alert to remind you of the meeting at any time you like on a per appointment basis. So, if you have a meeting 50 miles from home, you could set the alert for 90 minutes in advance while a meeting next door could be set with a 5 minute alert. All of that works fine in Google Calendar. Unfortunately, in Asterisk 1.8.4, there’s a math bug that subtracts the hour differential between your time zone and Greenwich Mean Time (GMT) from these alert times. If you happen to live in the GMT time zone, there’s no bug. However, those living on the East Coast of the U.S. will find their reminder calls arriving four hours too early. If you set an alert for 60 minutes before a scheduled meeting, Asterisk will call you 5 hours in advance. For our West Coast friends, it’s an 8 hour bug. Fortunately, the Asterisk Calendaring config file provides an option to override these alerts with a reminder call at a fixed number of minutes before each appointment. While it lacks the individual appointment flexibility to schedule alerts of different durations, it does work. So, for the time being, we’ll be using that.

Asterisk Calendar alerts also were supposed to be triggered only for events in which your Status has been set to Busy. A typical example would be a medical appointment. Instead, the alerts are generated for all calendar entries. So, if you’ve got 12 children and you’ve set all-day calendar entries to remind you of their birthdays each year, be forewarned that using your default Google Calendar will trigger a friendly reminder call at 11:50 p.m. on the night before each of your kids’ birthdays. Unless you and your spouse are both Night Owls, this might lead to some "WAF issues" if you get our drift. The workaround that we’ll implement today is to create a secondary appointments calendar and reserve it just to schedule meetings and appointments for which you wish to receive reminder calls at 10 minutes before each event. You can change the notification time to any fixed number of minutes desired. As we mentioned, one nice feature of Google Calendar is that entries on secondary calendars will automatically display on your main calendar. Just be sure to schedule the appointments on the correct calendar (we’ll show you how) if you want a reminder call.

Setting Up a Google Appointments Calendar. Before we get Asterisk configured for calendaring, let’s first set up your secondary Google appointments calendar. Log into the Gmail account that you either already use or will begin using for scheduling Calendar entries. Just click on the Calendar tab at the top of the screen and set up your default calendar if it doesn’t already exist. Once it’s set up, there will be a calendar list in the left margin under My Calendars. Just below your existing Calendar(s), there will be a Tasks entry, and below that will be an Add link to add a new calendar. Click on Add and fill in the main pieces of information as shown below. Use appointments for the name of the calendar and make sure you set the correct Time Zone for your hometown. Then save your entries by clicking the Create Calendar button.

Once you have created your new appointments calendar, we need one other piece of information to use it with Asterisk. Under My Calendars in the left margin, click on the down arrow beside appointments and choose Calendar Settings. That will bring up a form that looks like this:

The next to the last section of the form is entitled Calendar Address. You’ll see an entry to the right of the section title called Calender ID with a long alphanumeric string followed by @group.calendar.google.com. Write down the Calendar ID or copy it to clipboard. Don’t include @group.calendar.google.com! You can ignore the statement that the link is inoperative unless you make your calendar public. It actually works just fine with your Google credentials which we’ll configure as part of the Asterisk setup below.

Configuring Asterisk for Google Calendar Integration. PBX in a Flash and Incredible PBX come with most of the components you’ll need to get calendaring to work. However, there are a few missing pieces at the moment. These will require that Asterisk be recompiled, and we’ve built a little script to do all of it for you. Just log into your server as root and issue the following commands:

cd /root
wget http://incrediblepbx.com/setup-cal.sh
chmod +x setup-cal.sh
./setup-cal.sh

After you enter your Google credentials and Calendar ID, the script will temporarily shut down Asterisk, download the missing components for calendaring, recompile Asterisk, and customize the calendar setup with your Google credentials. Then the script will complete the setup and restart Asterisk. The whole process takes about 5 to 10 minutes.

Asterisk Calendar Configuration. Here are the pieces in the default Google Calendar config file that will be replaced with your personal settings:

[GoogleCalendar]
type = caldav
;url = https://www.google.com/calendar/dav/username@gmail.com/events/
url = https://www.google.com/calendar/dav/CalendarID@group.calendar.google.com/events/
user = username@gmail.com
secret = userpassword
refresh = 10
timeframe = 120
;
autoreminder = 10
;
channel = local/8005551212@from-internal
context = from-internal
extension = 225
waittime = 45


If you should ever need to make changes to these settings again, you’ll find the entries with your Google credentials at the end of the calendar.conf config file in /etc/asterisk. Remember to restart Asterisk after making any changes. The commented out URL entry is the one you’d use to access your main Google Calendar instead of the secondary appointments calendar we created above. If the GMT bug is ever fixed, this would be a step forward.

Extension 225 (C-A-L) is the extension that will be called to actually play back the reminder information. You’ll find this block of code at the top of extensions_custom.conf in the [from-internal-custom] context. You can make any adjustments you’d like. We simply set this up to give you a template to follow. As configured, the reminder will read you a summary, the starting time, location, and any description associated with each calendar entry. If you have a Cepstral voice in addition to Flite, just change the Flite entries to Swift. Then restart Asterisk: amportal restart.

Asterisk Calendar Test Drive. Asterisk keeps track of your scheduled events by checking your Google Calendar every 10 minutes. We recommend configuring reminders for calls 10 minutes before any scheduled event in the appointments calendar. What this means is you probably should never schedule an event expecting to get a reminder call if the event is less than about a half hour in the future. If you use a setting for the autoreminder time other than 10 minutes, this will obviously be different for you.

So let’s schedule an appointment for an hour from the current time. Click on the Calendar tab in Gmail. And then click on the down arrow beside the appointments calendar in the left column. Choose Create Event on this Calendar. You’ll get a form that looks like this. Click Save to store your new Calendar entry. Then go have a beer and wait for your call.

Where To Go From Here. We’ve just scratched the surface of what you can do with Asterisk 1.8 using Google Calendars. We recommend you now review the chapter in the new Asterisk Definitive Guide book that covers calendaring in some detail. It will give you a good handle on what’s possible. For a more technical discussion, take a look at this contribution from one of the PIAF Forum regulars. Amazing stuff! There’s also a good article in VoIP Today that’s worth a careful read. Be aware that, if you recompile Asterisk to add support for Microsoft Exchange, you probably will break the Google Calendar connection that we’ve outlined today. At least, we never have been able to get the two to coexist. If you have better luck, please post your results. The reason for the problem is that the Exchange connector depends upon neon-0.29 which is not yet part of CentOS 5.x. We’ll keep you posted on our progress. Enjoy!

Originally published: Monday, May 23, 2011

Changes in PBX in a Flash Distribution. In light of the events outlined in our recent Nerd Vittles article and the issues with Asterisk 1.8.4, the PIAF Dev Team has made some changes in our distribution methodology. As many of you know, PBX in a Flash is the only distribution that compiles Asterisk from source code during the install. This has provided us enormous flexibility to distribute new releases with the latest Asterisk code. Unfortunately, Asterisk 1.8 is still a work in progress to put it charitably. We also feel some responsibility to insulate our users from show-stopping Asterisk releases. Going forward, the plan is to reserve the PIAF-Purple default install for the most stable version of Asterisk 1.8. As of June 1, Asterisk 1.8.4.1 is the new PIAF-Purple default install. Other versions of Asterisk 1.8 (newer and older) will be available through a new configuration utility which now is incorporated into the PIAF 1.7.5.6.2 ISO.

Here’s how it works. Begin the install of a new PIAF system in the usual way by booting from your USB flash drive and pressing Enter to load the most current version of CentOS 5.6. When the CentOS install finishes, your system will reboot. Accept the license agreement, and choose the PIAF-Purple option to load the latest stable version of Asterisk 1.8. Or exit to the Linux CLI if you want a different version. Log into CentOS as root. Then issue a command like this: piafdl -p beta_1841 (loads Asterisk 1.8.4.1), piafdl -p 184 (loads Asterisk 1.8.4), piafdl -p 1833 (loads Asterisk 1.8.3.3), or piafdl -p 1832 (loads Asterisk 1.8.3.2). If there should ever be an outage on one of the PBX in a Flash mirrors, you can optionally choose a different mirror for the payload download by adding piafdl -c for the .com site, piafdl -d for the .org site, or piafdl -e for the .net site. Then add the payload switch, e.g. piafdl -c -p beta_1841.

Bottom Line: If you use the piafdl utility to choose a particular version of Asterisk 1.8, you are making a conscious decision to accept the consequences of your particular choice. We would have preferred implementation of a testing methodology at Digium before distribution of new Asterisk releases; however, that doesn’t appear to be in the cards. So, as new Asterisk 1.8 releases hit the street, they will be made available through the piafdl utility until such time as our PIAF Pioneers independently establish their reliability.

Need help with Asterisk? Visit the PBX in a Flash Forum.
Or Try the New, Free PBX in a Flash Conference Bridge.

whos.amung.us If you’re wondering what your fellow man is reading on Nerd Vittles these days, wonder no more. Visit our new whos.amung.us statistical web site and check out what’s happening. It’s a terrific resource both for us and for you.

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!
 

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.
 

Some Recent Nerd Vittles Articles of Interest…