cfexchangecalendar

Description

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

History

ColdFusion 8: Added this tag.

Category

Communications tags

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">

See also

cfexchangeconnection, cfexchangecontact,cfexchangefilter, cfexchangemail, cfexchangetask, Working with meetings and appointments in the Developing ColdFusion Applications

Attributes

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.

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:

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.

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:

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.

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:

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>