cfexchangetask

Description

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

Note: For all actions, see cfexchangeconnection for additional attributes that you use if you do not specify the connection attribute.

History

ColdFusion 8: Added this tag.

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" 
    generateUniqueFilenames = "no|yes"> 
 
modify 
<cfexchangetask 
    required 
    action = "modify"" 
    task = "#task information structure#" 
    uid = "task UID"> 
    optional 
    connection = "connection ID">
Note: If you omit the connection attribute, create a temporary connection by specifying cfexchangeconnection tag attributes in the cfexchangetask 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

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.

Attribute

Action

Req/Opt

Default

Description

action

all

Required

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

  • create

  • delete

  • deleteAttachments

  • get

  • getAttachments

  • modify

attachmentPat

getAttachments

Optional

The filepath of the directory in which to put the attachments. If the 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, create a temporary connection by specifying cfexchangeconnection tag connection attributes in the cfexchangetask tag.

generateUniqu

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.

name

get

getAttachments

Required

The name of the ColdFusion query variable that contains the returned task records or information about the attachments that were retrieved. For more information on the returned data, see Usage.

result

create

Optional

The name of a variable that contains the UID of the task that is created. You use this value in the uid attribute of other actions to identify the task to be acted on.

task

create

modify

Required

A reference to the structure that contains the task properties to be set or changed and their values. Specify this attribute in number signs (#).

For more information on the event structure, see Usage.

uid

delete

getAttachments

modify

Required

A case-sensitive Exchange UID value that uniquely identifies the tasks on which to perform the action. For the delete action, this attribute can be a comma-delimited list of UID values. The deleteAttachments, getAttachments, and modify actions allow only a single UID value.

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. Include only the fields that you are setting or changing.

Column

Description

ActualWork

A number in minutes. Cannot be less than zero.

Attachments

The pathnames of any attachments to include in the task. To specify multiple files, separate filepaths with semicolons (;) for Windows, and colons (:) for UNIX and Linux. Use absolute paths.

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

BillingInfo

A string.

Companies

A string.

DateCompleted

A string in a date format that is valid in ColdFusion.

If you omit this field and set the Status field to completed, or set the PercentCompleted field to 100, this value is set to the current date.

If you set this date, the Status value is set to Completed and the PercentCompleted field is set to 100.

DueDate

A string in a date format that is valid in ColdFusion.

Message

A string containing the task description.

Mileage

A string.

PercentCompleted

A number in the range 0–100.

If you set this field to 100, The following values are set:

  • The Status value is set to Completed.

  • If the DateCompleted value is or was not set, it is set to the current date.

If you set this value to a number with a value less than 100, the following values are set:

  • If Status field is or was set to Completed, the Status is set to In_Progress.

  • The DateCompleted value is cleared.

Priority

One of the following values:

  • low

  • normal

  • high

ReminderDate

A string in a date format that is valid in ColdFusion.

StartDate

A string in a date format that is valid in ColdFusion. When you create a task, the default value defaults is the current date.

Status

The following values are valid: Not_Started, In_Progress, Completed, Waiting, or Deferred.

If you omit this field and the PercentCompleted value is less than 100, the Status value it is set to In_Progress.

If you set this field to Completed, the following values are also set:

  • The PercentCompleted value is set to 100.

  • If the DateCompleted value is not set, it is set to the current date.

If you set this field to a value other than Completed, the following values are also set:

  • If the PercentCompleted field is or was 100, the PercentCompleted value is reset to 0.

  • The DateCompleted value is set to 0.

Subject

A String.

TotalWork

A number in minutes. Cannot be less than zero.

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 tasks.

  • 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, 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, 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, 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:

Column name

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

If you specify the modify action, the uid attribute must specify a single Exchange UID. The task structure must 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. 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#">