cfexchangecalendar

Description

Creates, deletes, modifies, gets, and responds to Microsoft Exchange calendar events, and gets calendar event attachments.

History

ColdFusion 8: Added this tag.

Syntax

create  
<cfexchangecalendar 
    required  
    action = "create" 
    event = "#event information structure#" 
    optional  
    connection = "connection ID" 
    result = "variable for event UID"> 
 
delete  
<cfexchangecalendar 
    required  
    action = "delete" 
    uid = "event UID,event UID, ..." 
    optional  
    connection = "connection ID" 
    message = "string" 
    notify = "yes|no"> 
 
deleteAttachments  
<cfexchangecalendar 
    required  
    action = "deleteAttachments" 
    uid = "event UID" 
    optional  
    connection = "connection ID"> 
 
get  
<cfexchangecalendar 
    required  
    action = "get" 
    name = "query identifier" 
    optional  
    connection = "connection ID"> 
 
getAttachments  
<cfexchangecalendar 
    required  
    action = "getAttachments" 
    name = "query identifier" 
    uid = "event UID" 
    optional  
    attachmentPath = "directory path" 
    connection = "connection ID"> 
    generateUniqueFilenames = "no|yes" 
 
modify 
<cfexchangecalendar 
    required  
    action = "modify" 
    event = "#event information structure#" 
    uid = "event UID" 
    optional  
    connection = "connection ID"> 
 
respond 
<cfexchangecalendar 
    required  
    action = "respond" 
    responseType = "accept|decline|tentative" 
    uid = "event UID" 
    optional  
    connection = "connection ID" 
    message = "string"> 
    notify = "yes|no">
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.

Attributes

Attribute

Action

Req/Opt

Default

Description

action

N/A

Required

The action to take. Must be one of the following values:

  • create

  • delete

  • deleteAttachments

  • get

  • getAttachments

  • modify

  • respond

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.

Note: If you omit this attribute, ColdFusion does not save any attachments. If you specify a relative path, the path root is the ColdFusion temporary directory, which is returned by the GetTempDirectory function.

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.

event

create

modify

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.

For more information on the event structure, see Usage.

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

delete

respond

Optional

The text of an optional message to send in the response or deletion notification.

name

getAttachments

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

delete

respond

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:

  • accept

  • decline

  • tentative

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.

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.

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.

If you specify one or more attachments for a modify action, the specified attachments are added to any existing attachments; the pre-existing attachments are not deleted.

Categories

   

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:

  • high

  • normal

  • low.

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.

If you specify a date and time in this attribute and specify a YEARLYRecurrenceType with no other recurrence attributes, the event recurs yearly at the day and time specified in this attribute.

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 the Developing ColdFusion Applications.

Element

Type

Default

Description

RecurrenceType

all

DAILY

Used only if the structure has a yesIsRecurring element. Must be one of the following values:

  • DAILY

  • WEEKLY

  • MONTHLY

  • YEARLY

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:

  • MON

  • TUE

  • WED

  • THU

  • FRI

  • SAT

  • SUN

RecurrenceWeek

MONTHLY, YEARLY

 

The week of the month or year on which the event recurs.

The valid values are:

  • first

  • second

  • third

  • fourth

  • last

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 Optimizing transient files 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 meeting notices and requests in the Developing ColdFusion Applications.

Example

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.

<!--- Create a structure to hold the event information. ---> 
<!--- A self-submitting form for the event information ---> 
<!--- This example omits recurrence to keep the code relatively simple ---> 
<cfparam name="form.eventID" default="0"> 
 
<!--- If the form was submitted, populate the event structure from it. ---> 
<cfif isDefined("Form.Submit")> 
        <cfscript> 
        sEvent.AllDayEvent="no"; 
        sEvent=StructNew(); 
        sEvent.Subject=Form.subject; 
        if (IsDefined("Form.allDay")) { 
            sEvent.AllDayEvent="yes"; 
            sEvent.StartTime=createDateTime(Year(Form.date), Month(Form.date), 
                Day(Form.date), 8, 0, 0); 
        } 
        else { 
            sEvent.StartTime=createDateTime(Year(Form.date), Month(Form.date), 
                Day(Form.date), Hour(Form.startTime), Minute(Form.startTime), 0); 
            sEvent.EndTime=createDateTime(Year(Form.date), Month(Form.date), 
                Day(Form.date), Hour(Form.endTime), Minute(Form.endTime), 0); 
        } 
        sEvent.Location=Form.location; 
        sEvent.RequiredAttendees=Form.requiredAttendees; 
        sEvent.OptionalAttendees=Form.optionalAttendees; 
        //sEvent.Resources=Form.resources; 
        if (Form.reminder NEQ "") { 
            sEvent.Reminder=Form.reminder; 
        } 
        else { 
            sEvent.Reminder=0; 
        } 
        sEvent.Importance=Form.importance; 
        sEvent.Sensitivity=Form.sensitivity; 
        sEvent.message=Form.Message; 
    </cfscript> 
     
    <!--- If this is the first time the form is being submitted  
            Create a new event. ---> 
    <cfif form.eventID EQ 0> 
    <!--- Create the event in Exchange ---> 
        <cfexchangecalendar action="create"  
            username ="#user1#" 
            password="#password1#" 
            server="#exchangeServerIP#" 
            event="#sEvent#" 
            result="theUID"> 
        <!--- Output the UID of the new event. --->     
        <cfif isDefined("theUID")>         
            <cfoutput>Event Added. UID is#theUID#</cfoutput> 
            <cfset Form.eventID = theUID > 
        </cfif> 
    <cfelse>          
    <!--- The form is being resubmitted with new data, so update the event. --->     
        <cfexchangecalendar action="modify"  
            username ="#user1#" 
            password="#password1#" 
            server="#exchangeServerIP#" 
            event="#sEvent#" 
            uid="#Form.eventID#"> 
        <cfoutput>Event ID #Form.eventID# Updated.</cfoutput> 
 
    </cfif> 
</cfif> 
 
<cfform format="xml" preservedata="yes" style="width:500" height="600"> 
    <cfinput type="text" label="Subject" name="subject" style="width:435"><br /> 
    <cfinput type="checkbox" label="All Day Event" name="allDay"> 
    <cfinput type="datefield" label="Date" name="date" validate="date" style="width:100"> 
    <cfinput type="text" label="Start Time" name="startTime" validate="time" 
        style="width:100"> 
    <cfinput type="text" label="End Time" name="endTime" validate="time" 
        style="width:100"><br /> 
    <cfinput type="text" label="Location" name="location" style="width:435"><br /> 
    <cfinput type="text" label="Required Attendees" name="requiredAttendees" 
        style="width:435"><br /> 
    <cfinput type="text" label="Optional Attendees" name="optionalAttendees" 
        style="width:435"><br /> 
    <cfinput type="text" label="Resources" name="resources" style="width:435"><br /> 
    <cfinput type="text" label="Reminder (minutes)" validate="integer" name="reminder" 
        style="width:200"> 
    <cfselect name="importance" label="Importance" style="width:100"> 
        <option value="normal">Normal</option> 
        <option value="high">High</option> 
        <option value="low">Low</option> 
    </cfselect>  
    <cfselect name="sensitivity" label="Sensitivity" style="width:100"> 
        <option value="normal">Normal</option> 
        <option value="company-confidential">Confidential</option> 
        <option value="personal">Personal</option> 
        <option value="private">Private</option> 
    </cfselect>  
    <cfinput type="textarea" label="Message" name="message" style="width:435; 
        height:100"> 
    <cfinput type="hidden" name="eventID" value="#Form.EventID#"> 
    <cfinput type="Submit" name="submit" value="Submit"> 
</cfform>