Description

Creates, deletes, modifies, and gets Microsoft Exchange tasks, and gets task attachments.

History

ColdFusion 8: Added this tag.

Category

Communications tags

Syntax

create
<cfexchangetask
    required
    action = "create"
    task = "#task information structure#" 
    optional
    connection = "connection ID"
    result = "variable for event UID">

delete
<cfexchangetask
    required
    action = "delete"
    uid = "task UID,task UID, ..."
    optional
    connection = "connection ID">

deleteAttachments
<cfexchangetask
    required
    action = "deleteAttachments"
    uid = "task UID"
    optional
    connection = "connection ID">

get
<cfexchangetask
    required
    action = "get"
    name = "query identifier"
    optional
    connection = "connection ID">

getAttachments
<cfexchangetask
    required
    action = "getAttachments"
    name = "query identifier"
    uid = "task UID"
    optional
    attachmentPath = "directory path"
    connection = "connection ID">

modify
<cfexchangetask
    required
    action = "modify""
    task = "#task information structure#"
    uid = "task UID">
    optional
    connection = "connection ID">

See also

cfexchangecalendar, cfexchangeconnection, cfexchangecontact, cfexchangefilter, cfexchangemail, "Interacting with Microsoft Exchange Servers" in the ColdFusion Developer's Guide.

Attributes

The following table provides detailed information about each attribute. It lists the attribute name, the actions (action attribute values) to which it apples, whether it is required or optional for those actions, and its default value, if any, and provides a detailed description of the attribute and its valid values.

When you specify the create or modify action, the task attribute must specify a structure that contains information that defines the events. The structure can have the following fields. You have to include only the fields that you are setting or changing.

Usage

The cfexchangetask tag manages task records on the Exchange server. Use the cfexchangetask tag to perform the following actions:

• Create a task.
• Delete one or more task.
• Get one or more task records that conform to an optional set of filter specifications, such as the last name, job title, or home phone number, and so on.
• Get the attachments for a specific task record.
• Modify an existing task

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 task records, you should use the cfexchangeconnection tag to create a persistent connection. You then specify the connection identifier in each cfexchangetask, or any other ColdFusion Exchange tag, if you are also accessing calendar entries, contacts, or mail. Doing this saves 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 cfexchangetask tag. To do this, you specify the connection attributes directly in the cfexchangetask tag. For details on the connection attributes, see the cfexchangeconnection  tag.

The delete action

When you specify the delete action, you must specify a uid attribute with a comma-delimited list of one or more Exchange UIDs that identify the tasks to delete. You can 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 cfexchangetask 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, the query object specified by the name attribute contains one record for each retrieved task. The query object has columns with the same names and data formats as the fields listed for the task attribute structure, with the following differences:

• The query object has a Boolean HasAttachment column, and does not have an Attachments column. If the HasAttachment field value is yes, use the getAttachments action to retrieve the attachments.
• The query object has an additional UID column with the unique identifier for the task in the Exchange server. You can use this value in the uid attribute of the getAttachments, delete, and modify actions to identify the required task.
• The query object has an additional HtmlMessage column. The Message column has a plain-text version of the task description, and the HtmlMessage column text includes the description's HTML formatting.

You use child cfexchangefilter tags to specify the messages to get. For detailed information, see cfexchangefilter.

The getAttachments action

When you use the getAttachments action, you must specify a single UID and a name attribute. The cfexchangetask tag populates a query object specified by the name attribute with the specified name. Each record has the following information about an attachment to the specified task:

If you omit the attachmentPath attribute, ColdFusion does not get any attachments; it gets only the information about the attachments. This lets you determine the event's attachments without incurring the overhead of getting the attachment files.

The modify action

If you specify the modify action, the uid attribute must specify a single Exchange UID. The task structure needs to specify only the fields that you are changing. Any fields that you do not specify remain unchanged. For a detailed description of the contents of the task structure, see the Attributes section.

If a task has attachments and you specify attachments when you modify the task, the new attachments are added to the previous attachments, and do not replace them. You must use the deleteAttachments action to remove any attachments.

Example

The following example uses a transient connection to create a single task:

<!--- Create a structure with the task fields --->
<cfscript>
    stask=StructNew();
    stask.Priority="high";
    stask.Status="Not_Started";
    stask.DueDate="3:00 PM 09/14/2007";
    stask.Subject="My New Task";
    stask.PercentCompleted=0;
    Message="Do this NOW!";
</cfscript>    

<!--- Create the task using a transient connection. --->
<cfexchangetask action="create" 
    username ="#user1#"
    password="#password1#"
    server="#exchangeServerIP#"
    task="#stask#"
    result="theUID">
    
<!--- display the UID to confirm that the action completed. --->
<cfdump var="#theUID#">