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 cfexchangefilter child tags. The code to get items from the Exchange server has the following pattern:

<cfexchange***  
        action="get"  
        name="results query object name" 
        connection information> 
    <cfexchangefilter  
            name="filter type" 
            value"filter value> 
    <cfexchangefilter  
            name="data/time filter type" 
            from="start date/time" 
            to="end date/time"> 
    . 
    . 
    . 
</cfexchange>

The following rules determine how you get items:

  • You can have zero or more cfexchangefilter tags.

    • 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 differentname attributes, ColdFusion gets all items that match all of the specified conditions.

    • If you specify multiple cfexchangefilter tags with identicalname 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.

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.

<cfset rightNow = Now()> 
<cfset lastWeek = DateAdd("d","-7", rightNow)> 
 
<cfexchangemail action="get" name="weeksMail" 
        username ="#user1#" password="#password1#" 
        server="#exchangeServerIP#"> 
    <cfexchangefilter name="FromID" value="adobe.com"> 
    <cfexchangefilter name="TimeSent" from="#lastWeek#" to="#rightNow#"> 
</cfexchangemail> 
 
<cfdump var="#weeksMail#">