mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-31 02:37:10 +00:00
ce004fbf1f
I still need to set up tests to make sure my examples are completely correct, but I ran out of time tonight and felt that they at least would give an idea as to how to use calendaring. I will try to test the examples and do some cleanup on the docs tomorrow night. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@197926 65c4cc65-6c06-0410-ace0-fbb531ad65f3
207 lines
8.2 KiB
TeX
207 lines
8.2 KiB
TeX
\section{Introduction}
|
|
|
|
The Asterisk Calendaring API aims to be a generic interface for integrating
|
|
Asterisk with various calendaring technologies. The goal is to be able to
|
|
support reading and writing of calendar events as well as allowing notification
|
|
of pending events through the Asterisk dialplan.
|
|
|
|
There are three calendaring modules that ship with Asterisk that provide support
|
|
for iCalendar, CalDAV, and Microsoft Exchange Server calendars. All three
|
|
modules support event notification. Both CalDAV and Exchange support reading
|
|
and writing calendars, while iCalendar is a read-only format.
|
|
|
|
\section{Configuring Asterisk Calendaring}
|
|
|
|
All asterisk calendaring modules are configured through calender.conf. Each
|
|
calendar module can define its own set of required parameters in addition to the
|
|
parameters available to all calendar types. An effort has been made to keep all
|
|
options the same in all calendaring modules, but some options will diverge over
|
|
time as features are added to each module.
|
|
|
|
An example calendar.conf might look like:
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[calendar_joe]
|
|
type = ical
|
|
url = https://example.com/home/jdoe/Calendar
|
|
user = jdoe
|
|
secret = mysecret
|
|
refresh = 15
|
|
timeframe = 600
|
|
autoreminder = 10
|
|
channel = SIP/joe
|
|
context = calendar_event_notify
|
|
extension = s
|
|
waittime = 30
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
\subsection{Module-independent settings}
|
|
|
|
The settings related to calendar event notification are handled by the core
|
|
calendaring API. These settings are:
|
|
\begin{description}
|
|
\item[autoreminder] This allows the overriding of any alarms that may or may not
|
|
be set for a calendar event. It is specified in minutes.
|
|
\item[refresh] How often to refresh the calendar data; specified in minutes.
|
|
\item[timeframe] How far into the future each calendar refresh should look. This
|
|
is the amount of data that will be visible to queries from the dialplan. This
|
|
setting should always be greater than or equal to the refresh setting or events
|
|
may be missed. It is specified in minutes.
|
|
\item[channel] The channel that should be used for making the notification
|
|
attempt.
|
|
\item[waittime] How long to wait, in seconds, for the channel to answer a notification
|
|
attempt.
|
|
\end{description}
|
|
|
|
There are two ways to specify how to handle a notification. One option is
|
|
providing a context and extension, while the other is providing an application
|
|
and the arguments to that application. One (and only one) of these options
|
|
should be provided.
|
|
|
|
\begin{description}
|
|
\item[context] The context of the extension to connect to the notification
|
|
channel
|
|
\item[extension] The extension to connect to the notification. Note that the
|
|
priority will always be 1.
|
|
\end{description}
|
|
|
|
or
|
|
|
|
\begin{description}
|
|
\item[app] The dialplan application to execute upon the answer of a notification
|
|
\item[appdata] The data to pass to the notification dialplan application
|
|
\end{description}
|
|
|
|
\subsection{Module-dependent settings}
|
|
|
|
Connection-related options are specific to each module. Currently, all modules
|
|
take a url, user, and secret for configuration and no other module-specific
|
|
settings have been implemented. At this time, no support for HTTP redirects has
|
|
been implemented, so it is important to specify the correct URL--paying attention
|
|
to any trailing slashes that may be necessary.
|
|
|
|
\section{Dialplan functions}
|
|
\subsection{Read functions}
|
|
|
|
The simplest dialplan query is the CALENDAR\_BUSY query. It takes a single
|
|
option, the name of the calendar defined, and returns "1" for busy (including
|
|
tentatively busy) and "0" for not busy.
|
|
|
|
For more information about a calendar event, a combination of CALENDAR\_QUERY
|
|
and CALENDAR\_QUERY\_RESULT is used. CALENDAR\_QUERY takes the calendar name
|
|
and optionally a start and end time in "unix time" (seconds from unix epoch). It
|
|
returns an id that can be passed to CALENDAR\_QUERY\_RESULT along with a field
|
|
name to return the data in that field. If multiple events are returned in the
|
|
query, the number of the event in the list can be specified as well. The available
|
|
fields to return are:
|
|
\begin{description}
|
|
\item[summary] A short summary of the event
|
|
\item[description] The full description of the event
|
|
\item[organizer] Who organized the event
|
|
\item[location] Where the event is located
|
|
\item[calendar] The name of the calendar from calendar.conf
|
|
\item[uid] The unique identifier associated with the event
|
|
\item[start] The start of the event in seconds since Unix epoch
|
|
\item[end] The end of the event in seconds since Unix epoch
|
|
\item[busystate] The busy state 0=Free, 1=Tentative, 2=Busy
|
|
\item[attendees] A comma separated list of attendees as stored in the event and
|
|
may include prefixes such as "mailto:".
|
|
\end{description}
|
|
|
|
When an event notification is sent to the dial plan, the CALENDAR\_EVENT
|
|
function may be used to return the information about the event that is causing
|
|
the notification. The fields that can be returned are the same as those from
|
|
CALENDAR\_QUERY\_RESULT.
|
|
\subsection{Write functions}
|
|
|
|
To write an event to a calendar, the CALENDAR\_WRITE function is used. This
|
|
function takes a calendar name and also uses the same fields as
|
|
CALENDAR\_QUERY\_RESULT. As a write function, it takes a set of comma-separated
|
|
values that are in the same order as the specified fields. For example:
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
CALENDAR_WRITE(mycalendar,summary,organizer,start,end,busystate)=
|
|
"My event","mailto:jdoe@example.com",228383580,228383640,1)
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
\section{Dialplan Examples}
|
|
\subsection{Office hours}
|
|
A common business PBX scenario is would be executing dialplan logic based on
|
|
when the business is open and the phones staffed. If the business is closed for
|
|
holidays, it is sometimes desirable to play a message to the caller stating why
|
|
the business is closed.
|
|
|
|
The standard way to do this in asterisk has been doing a series of GotoIfTime
|
|
statements or time-based include statements. Either way can be tedious and
|
|
requires someone with access to edit asterisk config files.
|
|
|
|
With calendaring, the adminstrator only needs to set up a calendar that contains
|
|
the various holidays or even recurring events specifying the office hours. A
|
|
custom greeting filename could even be contained in the description field for
|
|
playback. For example:
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[incoming]
|
|
exten => 5555551212,1,Answer
|
|
exten => 5555551212,n,GotoIf(${CALENDAR_BUSY(officehours)}?closed:attendant,s,1)
|
|
exten => 5555551212,n(closed),Set(id=${CALENDAR_QUERY(office,${EPOCH},${EPOCH})})
|
|
exten => 5555551212,n,Set(soundfile=${CALENDAR_QUERY_RESULT(${id},description)})
|
|
exten => 5555551212,n,Playback($[${ISNULL(soundfile)} ? generic-closed :: ${soundfile}])
|
|
exten => 5555551212,n,Hangup
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
\subsection{Meeting reminders}
|
|
One useful application of Asterisk Calendaring is the ability to execute
|
|
dialplan logic based on an event notification. Most calendaring technologies
|
|
allow a user to set an alarm for an event. If these alarms are set on a calendar
|
|
that Asterisk is monitoring and the calendar is set up for event notification
|
|
via calendar.conf, then Asterisk will execute notify the specified channel at
|
|
the time of the alarm. If an overrided notification time is set with the
|
|
autoreminder setting, then the notification would happen at that time instead.
|
|
|
|
The following example demonstrates the set up for a simple event notification
|
|
that plays back a generic message followed by the time of the upcoming meeting.
|
|
calendar.conf.
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[calendar_joe]
|
|
type = ical
|
|
url = https://example.com/home/jdoe/Calendar
|
|
user = jdoe
|
|
secret = mysecret
|
|
refresh = 15
|
|
timeframe = 600
|
|
autoreminder = 10
|
|
channel = SIP/joe
|
|
context = calendar_event_notify
|
|
extension = s
|
|
waittime = 30
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[calendar_event_notify]
|
|
exten => s,1,Answer
|
|
exten => s,n,Playback(you-have-a-meeting-at)
|
|
exten => s,n,SayUnixTime(${CALENDAR_EVENT(start)})
|
|
exten => s,n,Hangup
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
\subsection{Writing an event}
|
|
Both CalDAV and Exchange calendar servers support creating new events. The
|
|
following example demonstrates writing a log of a call to a calendar.
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
[incoming]
|
|
exten => 6000,1,Set(start=${EPOCH})
|
|
exten => 6000,n,Dial(SIP/joe)
|
|
exten => h,1,Set(end=${EPOCH})
|
|
exten => h,n,Set(CALENDAR_WRITE(calendar_joe,summary,start,end)=Call from ${CALLERID(all)},${start},${end})
|
|
\end{verbatim}
|
|
\end{astlisting}
|