Getting Exchange items and attachments

You can get calendar events, contacts, mail messages, and tasks from the Exchange server. You can also get attachments to these items. 
Getting an exchange item and its attachments can require multiple operations.

• To get mail that is not directly in the Inbox, specify the path from the root of the mailbox to the mail folder, and you can get items from only a single mail folder at a time. You can use the cfexchangeconnection tag to get the names, paths, and sizes of all folders in a mailbox, and can use the results to iterate over the folders.
• To get an attachment to an item, you must first get the item, and then use the item UID to get its attachments.

• If an Exchange item contains a message with inline images, the images are available as attachments. You can get the attachments, use the attachment CID to locate the image in the message, and display the image inline.

  Note: The getattachment action does not always populate the CID field for HTML mail that contains inline attachments, such as images. This problem occurs because some Exchange clients do not always set the CID values if the attachments are sent inline.

   

Getting and using folder names

To get the names of folders in the mailbox, or the subfolders of a particular folder, use the cfexchangeconnection tag with the getSubfolders action. This action returns a query with a row for each subfolder. The query has three columns:

• folder name
• full path from the mailbox to the folder, including the Inbox
• folder size, in bytes
  You can specify the folder whose subfolders you are getting and whether to recursively get all levels of subfolders.
  You can use a folder path from the getSubfolders action in the cfexchangemail tag folder attribute to specify the folder that contains the mail message that requires action. If you do not specify a folder, the cfexchangemail tag searches only the top level of the Inbox for the message on which to act. 
  To perform operations on mail from multiple folders, including getting mail items or attachments, you can loop over the entries in the query returned by the getSubfolders action, as the following example shows. This example generates a report of all declined meeting messages in the Inbox and all its subfolders.

Getting items

You get one or more events, contacts, mail messages, or tasks from the Exchange server by using a cfexchangecalendar, cfexchangecontact, cfexchangemail, or cfexchangetask tag, respectively, and specifying an action attribute value of get. ColdFusion returns the items in a query object that you specify in the name attribute. You determine the items to get by specifying selection conditions in {{cfexchange}}filter child tags. The code to get items from the Exchange server has the following pattern:

The following rules determine how you get items:

• You can have zero or more cfexchangefiltertags.
  • If you do not specify a maxrows field in the structure specified by the name attribute, ColdFusion gets a maximum of 100 items. To get more items, specify a maxrows field value greater than 100.
  • If you specify multiple cfexchangefilter tags with different name attributes, ColdFusion gets all items that match all of the specified conditions.
  • If you specify multiple cfexchangefilter tags with identical name attributes ColdFusion gets the items that match only the last tag with the duplicate name attribute.
• The name attributes correspond to field names in the Exchange item records. The valid values for the name attributes depend on the type of item you are getting. For detailed lists of the valid values, see the corresponding tag references in the CFML Reference.
• If the name attribute specifies a field that takes text or numeric information, you use the value attribute to specify the condition.
• If the name attribute specifies a field that takes a date, time, or date and time, you use the from and to attributes to specify the range. You can omit one of these attributes to specify an open-ended range, such as all dates up to and including December 1, 2007.
• Date ranges are inclusive. The selected items include ones with the specified to or from dates.
• You cannot use the empty string as a value attribute to search for an empty value. To find entries where a particular field has an empty value, get all entries and use a query of queries to filter the results to include only entries where the field is empty.
• In fields that take text strings such as Message and or Subject, ColdFusion returns items that contain the exact phrase that you specify in the value attribute.
• When you use the cfexchangemail tag, ColdFusion gets only items a single folder. If you include a filter for a folder, ColdFusion gets items that are directly in the Inbox only and does not search any subfolders. For an example of getting information from multiple folders, see Getting and using folder names above.
  When ColdFusion gets the results, it creates the query object specified in the name attribute, if it does not exist, and populates each row with a single item such as a mail message. The query columns depend on the type of item. For example, a mail message has FromID and ToID fields, and a contact has FirstName and LastName fields. For detailed information on the returned structures, see the corresponding tag in the CFML Reference.
  The query results for all types of items have two columns:

• A UID column with the unique ID of the item. You use this value to specify the item when you delete, modify, or (for calendar entries) respond to it. You also use the UID value to get the item attachments.
• A HasAttachments column with a Boolean value specifying whether the item has any attachments. If this field is true, you can use the getAttachments action to get the attachments.
  The following example gets the mail messages that were sent during the last week to the docuser1 user from any e-mail address that includes adobe.com. To keep this code short, the example uses the cfdump tag to show the results.

Getting item attachments

To get the attachments to an Exchange contact, event, message, or task, use a ColdFusion Exchange tag with a getAttachments action. Also specify the following information in the tag:

• The UID of the message that contains the attachment or attachments.
• The name of the query to hold the information about the returned attachments. When the tag completes processing, the query object contains one record for each retrieved attachment. The query has six columns that contain the filename, complete path to the saved attachment file, MIME type, file size, CID value (or an empty string) and an indicator that shows whether the attachment is a message.
• The path where the attachment is saved. (If you omit the path, ColdFusion does not get the attachments, but does get the information about the attachments.)
• Optionally, whether to create unique filenames by appending numbers to the names when two or more attachments have the same names. (The default is to not create unique filenames.)
  The following ColdFusion Exchange tag gets all attachments to the message identified by the theUID variable, saves them in the C:/temp/cf_files/attachments directory, and stores information about the attachments in the attachInfo structure:

To get message attachments, you must have the UID of the message and know that the message has attachments. Use a ColdFusion Exchange tag, such as cfexchangemail, with the get action to determine this information. When the tag completes processing, the query specified by the name attribute includes the following columns:

• The HasAttachments field is true if a message has one or more attachments
• The UID field contains the Exchange UID of the item. The exact UID format depends on the type of item; event, contact, message, or task.
  You can use these fields in your decision logic that determines whether to get attachments for a message and determines the message UID.
  The following example gets the attachments to all mail messages from docuser2 in the last week. It places each message���s attachments in a directory whose name is the hexadecimal part of the message UID. For each message with attachments, the application reports subject and date of the message, followed by a table listing the message���s attachments. The table includes the attachment name, MIME type, and size. 
  Notice that if a message has multiple attachments with the same name, the attachment information query always lists the attachments with their original, duplicate names, even if you specify generateUniqueFilenames="true". The generateUniqueFilenames attribute only affects the names of the files on disk. The attachmentFilePath column of the attachment information structure does have the unique filenames, however.

Displaying images inline

If an HTML message includes inline images, the Exchange server saves the images as attachments. Take the following steps to display the images in the retrieved message:

1. Use cfexchangemail tag get action to get the mail message.
2. Use cfexchangemail tag getattachments action to get the message attachments. Specify the UID of the mail message you got in the previous step. Also specify an attachmentPath attribute value that is under your web root, so that you can access the saved files by using a URL.
3. Search through the HTMLMessage field text that you got in step 1 and find the image items. Get the CID (content ID) value for each image.
4. Search the attachments query that you got in step 1. For each row with a CID column value that you got in step 3, get the corresponding attachmentFilePath column value.
5. Replace every img tag src attribute value with the attachmentFilePath field value that corresponds to the cid value.
6. Display the resulting HTML.
   The following example shows how to display a message with an inline image by retrieving the image from the attachments.