Description
Creates, deletes, modifies, gets, and responds to Microsoft Exchange calendar events, and gets calendar event attachments.
History
- ColdFusion (2023 release) Update 5: Added the attributes username, password, and server.
- ColdFusion (2018 release): Added the optional attribute timeZone for action="create".
- ColdFusion 11: Added three new optional attributes to the cfexchangecalendar tag for managing secondary calendars. These attributes are applicable for get and create actions only and valid for exchange server version starting from 2010. Secondary calendars can be specified in the exchangecalendar tag either using secondary calendar folder ID or using the calendar folder path
- ColdFusion 10: getUserAvailability, getRooms, getRoomsList
- Added the attribute serverVersion.
- Added the attribute serverVersion.
- ColdFusion 8: Added this tag.
Category
Syntax
<cfexchangecalendar timeZone="Time Zone for the event">
|
| Note: For all actions, see cfexchangeconnection for additional attributes that you use if you do not specify the connection attribute. If you omit the connection attribute, create a temporary connection by specifying cfexchangeconnection tag attributes in the cfexchangecalendar tag. In this case, ColdFusion closes the connection when the tag completes. For details, see the cfexchangeconnection tag open action. |
Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys. |
See also
cfexchangeconnection, cfexchangecontact, cfexchangefilter, cfexchangemail, cfexchangetask, Working with meetings and appointments in the Developing ColdFusion Applications
Attributes
Attribute |
Action |
Req/Opt |
Default |
Description |
|---|---|---|---|---|
action |
N/A |
Required |
|
The action to take. Must be one of the following values:
|
| username | all | Optional | The Exchange user ID. | |
| password | all | Optional | The password for accessing the Exchange server. |
|
| server | all | Optional | The IP address or URL of the server that is providing access to Exchange. | |
attachmentPath |
getAttachments |
Optional |
|
The filepath of the on-disk or in-memory directory in which to put the attachments. If an on-disk directory does not exist, ColdFusion creates it. |
attendees |
getUserAvailability |
Required |
|
Comma-separated list of all attendees. |
connection |
all |
Optional |
|
The name of the connection to the Exchange server, as specified in the cfexchangeconnection tag. If you omit this attribute, you must create a temporary connection by specifying cfexchangeconnection tag connection attributes in the cfexchangecalendar tag. |
dataRequestType |
getUserAvailability |
Required |
|
|
emailAddress |
getRooms |
Optional |
|
Defines the Simple Mail Transfer Protocol (SMTP) address of a mailbox user. |
endDate |
getUserAvailability |
Required |
|
A string that ColdFusion can interpret as a date-time value. |
event |
createmodify |
Required |
|
A reference to the structure that contains the event properties to be set or changed, and their values. Specify this attribute in number signs (#). The event attribute also supports the categories key. |
getOccurrence |
TrueFalse |
Optional |
|
If True, retrieves all occurrences of a recurring event between specified startDate and EndDate values and also, any single events. You can not use cfExchangeFilter tag if you specify getOccurrence as True. |
generateUnique Filenames |
getAttachments |
Optional |
no |
A Boolean value that specifies whether to generate unique filenames if multiple attachments have the same filenames. If two or more attachments have the same filename and this option is yes, ColdFusion appends a number to the filename body (before the extension) of any conflicting filenames. Thus, if three attachments have the name myfile.txt, ColdFusion saves the attachments as myfile.txt, myfile1.txt, and myfile2.txt. |
message |
deleterespond |
Optional |
|
The text of an optional message to send in the response or deletion notification. |
name |
getAttachments getUserAvailability getRoomsListgetRooms |
Required |
|
The name of the ColdFusion query variable that contains the retrieved events or information about the attachments that were retrieved. For more information on the returned data, see Usage. |
notify |
deleterespond |
Optional |
true |
Boolean value that specifies whether to notify others of the changes made to the event. |
responseType |
respond |
Required |
|
Must be one of the following values:
|
result |
create |
Optional |
|
The name of a variable that contains the UID of the event that is created. You use the UID value in the uid attribute of actions other than create to identify the event to be acted on. |
serverVersion |
|
Optional |
2007 |
Specifies the Microsoft Exchange Server version. The values are:
|
startDate |
getUserAvailability |
Required |
|
A string that ColdFusion can interpret as a date-time value. |
uid |
delete getAttachments modify respond |
Required |
|
Case-sensitive Exchange UID value or values that uniquely identify the event or events on which to perform the action. For the delete action, this attribute can be a comma-delimited list of UID values. The deleteAttachments, getAttachments, modify, and respond actions allow only a single UID value. |
| folderid | Optional | Specify the calendar folder ID from which the calendar items need to be managed. If the folder ID is not a valid calendar, an error will be reported. | ||
| folderpath | Optional | Full path to the calendar folder in the mailbox store. Path delimiter also can be specified in the tag by using the pathdelimiter attribute. If both folderid and folderpath are not specified, cfexchangecalendar tag manages the default user calendar. If both folderid and folderpath are specfied, folderid will be considered. |
||
| pathdelimiter | Optional | / | Lets you specify the delimiter that is used to separate the folders in the folderpath attribute. |
Usage
The cfexchangecalendar tag manages calendar events on the Exchange server. Use the cfexchangecalendar to do the following actions:
- Create an appointment or meeting event. You can create all-day events.
- Delete one or more events.
- Get one or more events that conform to an optional set of filter specifications, such as the subject, sender or recipient ID, time received, and so on.
- Get the attachments for a specific event.
- Modify an existing event.
Respond to an event.
To use this tag, you must have a connection to an Exchange server. If you are using multiple tags that interact with the Exchange server, such as if you are creating several contact records, use the cfexchangeconnection tag to create a persistent connection. Then specify the connection identifier in each cfexchangecalendar tag, or in any other ColdFusion Exchange tag, if you are also accessing tasks, contacts, or mail. Doing this eliminates the overhead of creating and closing the connection for each tag. Alternatively, you can create a temporary connection that lasts only for the time that ColdFusion processes the single cfexchangecalendar tag. To do this, specify the connection attributes directly in the cfexchangecontact tag. For details on the connection attributes, see the cfexchangeconnection tag.Note: To create an Exchange calendar appointment, create a calendar event and do not specify any required or optional attendees.
The create action
When you specify the create action, the event attribute must specify a structure that contains the information that defines the events. The structure can have the following entries:
Element |
Default |
Description |
|---|---|---|
AllDayEvent |
no |
A Boolean value that indicates whether this is an all-day event. |
Attachments |
|
One or more paths to the files to send as attachments. Separate filepaths with semicolons (;) for Windows, and colons (:) for UNIX and Linux. Paths to the attachments must be absolute. |
Categories |
|
A comma-delimited list of categories. The filter searches for events that match all the categories in the list. |
Duration |
|
The duration of the event in minutes. |
EndTime |
|
The end time of the event, in any valid ColdFusion date-time format. |
Importance |
normal |
One of the following values:
|
IsRecurring |
A Boolean value that indicates whether this event repeats. If yes, specify a RecurrenceType element and elements to specify the recurrence details. For information on the recurrence fields, see the next table. |
|
Location |
|
A string that specifies the location of the event. |
Message |
|
A string that contains a message about the event. The string can include HTML formatting. |
OptionalAttendees |
|
A comma-delimited list of mail IDs. |
Organizer |
|
A string that specifies the name of the meeting organizer. |
Reminder |
|
The time, in minutes before the event, at which to display a reminder message. |
RequiredAttendees |
|
A comma-delimited list of mail IDs. |
Resources |
|
A comma-delimited list of mail IDs for Exchange scheduling resources, such as conference rooms and display equipment. |
Sensitivity |
The valid values are normal, company-confidential, personal, and private. |
|
StartTime |
|
The start time of the event, in any valid ColdFusion date-time format. |
Subject |
|
A string that describes the event subject. |
The following table lists the elements that you use to specify the event recurrence if you set the IsRecurring field to a yes value. For a detailed description of how to specify event recurrence, see Specifying Calendar recurrence in Working with meetings and appointments in the Developing ColdFusion Applications.
Element |
Type |
Default |
Description |
|---|---|---|---|
RecurrenceType |
all |
DAILY |
Used only if the structure has a yes IsRecurring element. Must be one of the following values:
|
RecurrenceNoEndDate |
all |
yes |
Boolean value; if yes, the event recurs until you change or delete the event. Cannot be used with RecurrenceCount or RecurrenceEndDate. |
RecurrenceCount |
all |
|
The number of times the event recurs. Cannot be used with RecurrenceEndDate or RecurrenceNoEndDate. |
RecurrenceEndDate |
all |
|
The date of the last recurrence. Cannot be used with RecurrenceCount or RecurrenceNoEndDate. |
RecurrenceFrequency |
DAILY, WEEKLY, MONTHLY |
1 |
The frequency of the recurrence in days, weeks, or months, depending on the type. For example, for DAILY recurrence, a RecurrenceFrequency of 3 schedules the event every three days. |
RecurEveryWeekDay |
DAILY |
|
The recurrence of the event on every week day, but not on Saturday or Sunday. Cannot be used with RecurrenceFrequency. |
RecurrenceDays |
WEEKLY |
|
The day or days of the week on which the event occurs. Must be one or more of the following values in a comma-delimited list :MON , TUE, WED, THU, FRI, SAT, {{SUN}}If you omit this field for a weekly recurrence, the event recurs on the day of the week that corresponds to the specified start date. |
RecurrenceDay |
MONTHLY, YEARLY |
|
The day of the week on which the event occurs. Must be one of the following values:
|
RecurrenceWeek |
MONTHLY, YEARLY |
|
The week of the month or year on which the event recurs. The valid values are:
|
RecurrenceMonth |
YEARLY |
|
The month of the year on which the event recurs. The valid values are JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, and DEC. |
The delete action
When you specify the delete action, specify a uid attribute with a comma-delimited list of one or more Exchange UIDs that identify the events to delete. Use the get action, with an appropriate filter expression, to determine the UID values to specify.
If all UIDs that you specify are invalid, the cfexchangecalendar tag generates an error. If at least one UID is valid, the tag ignores any invalid UIDs and deletes the items specified by the valid UID.
The get action
When you specify the get action, use child cfexchangefilter tags to specify the messages to get. For detailed information on filters, see cfexchangefilter.
When the tag completes processing, the query object specified by the name attribute contains one record for each retrieved message. Each record has the following columns:
AllDayEvent |
Duration |
EndTime |
From |
HasAttachment |
HtmlMessage |
Importance |
IsRecurring |
Location |
Message |
OptionalAttendees |
Organizer |
Reminder |
RequiredAttendees |
Resources |
Sensitivity |
StartTime |
Subject |
UID |
Categories |
The following table describes the From, HtmlMessage, Message, and UID fields. For detailed information on the other fields, see the table in the create action description.
Column |
Description |
|---|---|
From |
The Exchange ID of the person who created the event. |
HtmlMessage |
An HTML-formatted version of the message about the event. |
Message |
A plain-text version of the message about the event. |
UID |
The Exchange unique identifier for the mail event. Use this value to identify the event in the delete, getAttachments, and modify actions. |
The getAttachments action
When you use the getAttachments action, specify a single UID and a name attribute. The cfexchangecalendar tag populates a query object with the specified name. Each record has the following information about an attachment to the event specified by the UID:
Column |
Description |
|---|---|
attachmentFileName |
The filename of the attachment. |
attachmentFilePath |
The absolute path of the attachment file on the server. If you omit the attachmentPath attribute, this column contains the empty string. |
CID |
The content-ID of the attachment. Typically used in HTML img tags to embed images in a message. |
mimeType |
The MIME type of the attachment, such as text/html. |
isMessage |
A Boolean value that specifies whether the attachment is a message. |
size |
The attachment size in bytes. |
The tag places the attachments in the directory specified by the attachmentPath attribute. If you omit the attachmentPath attribute, ColdFusion does not get any attachments, it gets the information about the attachments. This lets you determine the event's attachments without incurring the overhead of getting the attachment files .Use the following syntax to specify an in-memory attachmentPath directory. In-memory files are not written to disk and speed processing of transient data.
attachmentpath = "ram:///path" |
The path can include multiple directories, for example ram:///petStore/orders/messageAttachments. Create all directories in the path before you specify the file. For more information on using in-memory files, see Working with in-memory files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
The getAttachments action works only if authentication for EWS (Exchange Web Services) is set to basic in the server setup of Exchange. IWA (Integrated Windows Authentication) is not supported.
The modify action
When you specify the modify action, you select the event to modify by specifying a uid attribute with single event UID; multiple UIDs are not allowed. You populate the event structure with only the fields that you are changing. For a detailed description of the fields and their valid values, see the table in the create action.
If an event has attachments and you specify attachments when you modify the event, the new attachments are added to the previous attachments; they do not replace them. Use the deleteAttachments action to remove any attachments.
The respond action
You use the respond action to respond to a meeting notification that you received by using the cfexchangemail tag. A meeting does not appear in your calendar, and cannot be accessed by using the cfexchangecalendar tag, until you respond to the mail message and accept or tentatively accept the request.
When you specify the respond action, specify the UID, from the notification mail message, of the event to which you are responding. Also specify the response type; that is, whether you are accepting, rejecting, or tentatively accepting the event. You can optionally specify a message to include in the response and set a flag whether to notify the creator of the event of your response. For detailed information on using the respond action, see Working with meetings and appointments in the Developing ColdFusion Applications.
Suggestions struct values
Struct values |
Description |
|---|---|
date |
Suggested day for the meeting. |
quality |
The quality of the suggested day, if Excellent, Good, Fair or Poor. |
TimeSuggestion |
An array of struct that contains the following values:
|
Values of the struct attendeeavailability
Struct values |
Description |
|---|---|
CalendarEvent |
A struct that contains the following values:
|
mergedFreeBusyStatus |
An array of struct that contains status. The status can be
|
viewType |
The free/busy view type retrieved for the attendee. It can have the following values:
|
workingHours |
A struct that contains the following details:
|
Exchange UID value
For all the cfexchangecalendar actions, the value of the attribute uid is as follows:
- If exchangeServerVersion is set to 2003 or 2007: The uid indicates the ID of the appointment in the mailbox of the organizer.
- If exchangeServerVersion is set to 2010: The uid indicates the ID of the received appointment in the mailbox of the attendee.
In the case of interaction with Microsoft Exchange server 2003 or 2007, whenever an appointment is created, the UID of the organizer can be used by the attendee for any operation such as responding, deleting, or getting attachments. In the case of Microsoft Exchange server 2010, the behavior is different. If attendees have to perform appointment-related actions, they have to first search for the appointment in their mailbox and then use the UID of that appointment.
Example 1
The following example lets you create, and then modify a calendar event. When you first submit the form, ColdFusion creates the calendar event and redisplays the form with the data you entered. Accept the event before you modify the form and resubmit it. When you submit the form a second time, ColdFusion sends the modification information. For more information, see Working with meetings and appointments in the Developing ColdFusion Applications.
This example resends all the event data (to limit the example length), but you could change the example so that it only sends modified data.
<!--- A self-submitting form for the event information ---> |
Example 2
The following example shows how you can get UserAvailability action:Application.cfm
<cfset todayDate = #Now()#> |
Availability.cfm
action="open" |
The following example shows how you can use the actions getRooms and getRoomList.
action="open" |
Example 3
Creating and getting an appointment in a secondary calendar using the folderId attribute:
|
Creating and getting an appointment in a secondary calendar using the folderpath attribute:
<cfexchangeconnection action="open" connection="conn1" server="<server hostname/IP>" username="<username>" password="<password>" serverversion="2010" protocol="<protocol>" > |
Example with username and password
<cfscript>
eventStruct = structnew();
eventStruct.AllDayEvent = "yes";
eventStruct.Importance = "low";
eventstruct.RequiredAttendees = "user@example.com";
eventstruct.Subject = "This is any subject " & rand("CFMX_COMPAT" );
eventStruct.StartTime = now();
</cfscript>
<cfexchangecalendar
action="create"
username ="user1"
password="password"
server="exchangeServerIP"
serverversion="version"
protocol="protocol"
event="eventStruct"
result="theUID" />
<cfscript>sleep(1000);</cfscript>
<cfexchangeCalendar action="get" username ="user1"
password="password"
server="exchangeServerIP"
serverversion="version"
protocol="protocol" name="getEvent">
<CFExchangeFilter name="subject" value="calendar">
</cfexchangeCalendar>
<cfset myArray = ArrayNew(1)>
<cfloop query="getEvent">
<cfset temp = ArrayAppend(myArray, "UID")>
</cfloop>
<cfset myList = ArrayToList(myArray, ",")>
<cfset myLen = ListLen(myList)>
<cfoutput query="getEvent">
<cfif getEvent.subject contains "calendar">
<cfexchangeCalendar action="delete"
username ="user1"
password="password"
server="exchangeServerIP"
serverversion="version"
protocol="protocol"
uid="myList">
Successful!<br>
</cfif>
</cfoutput>