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.


 
New Vitelity Special. Vitelity has generously offered a new discount for PBX in a Flash users. You now can get an almost half-price DID and 60 free minutes from our special Vitelity sign-up link. If you’re seeking the best flexibility in choosing an area code and phone number plus the lowest entry level pricing plus high quality calls, then Vitelity is the hands-down winner. Vitelity provides Tier A DID inbound service in over 3,000 rate centers throughout the US and Canada. And, when you use our special link to sign up, the Nerd Vittles and PBX in a Flash projects get a few shekels down the road while you get an incredible signup deal as well. The going rate for Vitelity’s DID service is $7.95 a month which includes up to 4,000 incoming minutes on two simultaneous channels with terminations priced at 1.45¢ per minute. Not any more! For PBX in a Flash users, here’s a deal you can’t (and shouldn’t) refuse! Sign up now, and you can purchase a Tier A DID with unlimited incoming calls for just $3.99 a month and you get a free hour of outbound calling to test out their call quality. To check availability of local numbers and tiers of service from Vitelity, click here. Do not use this link to order your DIDs, or you won’t get the special pricing! After the free hour of outbound calling, Vitelity’s rate is just 1.44¢ per minute for outbound calls in the U.S. There is a $35 prepay when you sign up. This covers future usage and any balance is fully refundable if you decide to discontinue service with Vitelity.
 


Some Recent Nerd Vittles Articles of Interest…

Be Sociable, Share!

2 Responses to “Incredible PBX: Adding Google Calendars with Asterisk 1.8”

  1. Terry Wilson says:

    Re: “Asterisk Calendar alerts also were supposed to be triggered only for events in which your Status has been set to Busy.”

    Actually, they are supposed to fire for events where you aren’t busy, if there is a notification set. Since the notification is being overridden on all events to work around the timezone bug, all events have notification set. It should be possible to have the notification dialplan that is executed check ${CALENDAR_BUSY(calendarname)} before sending out the notification if you only want notification calls to come out when you are busy.

    The real fix is for me to fix the timezone bug. :-) I wasn’t aware of it.

    [WM: Thanks, Terry. Great suggestion! The only problem would be that, doing this in the dialplan, would mean the reminder call still rings in but the called party would get an immediate hangup when the dialplan detects that the calendar isn't busy. Still not ideal if it's in the middle of the night.]

  2. Geert Jansen says:

    You can fix the time zone issue easily by modifying the res_calendar_icalendar.c
    file and running make, make install from asterisk src directory.

    find: /* XXX Technically you can check RELATED to see if the event fires from the END of the event

    then cange the line
    event->alarm = icaltime_as_timet_with_zone(tmp, utc);

    into:
    event->alarm = icaltime_as_timet_with_zone(tmp, icaltime_get_timezone(start));

    Then you have your alarms in place!

    Geert

Ringbinder theme by Themocracy