Description

Creates, deletes, modifies, and gets Microsoft Exchange contact records, and gets contact record attachments.

History

ColdFusion 8: Added this tag.

Category

Communications tags

Syntax

create
<cfexchangecontact
    required
    action = "create"
    contact = "#contact information structure#"
    optional
    connection = "connection ID"
    result = "variable for contact UID">

delete
<cfexchangecontact
    required
    action = "delete"
    uid = "contact UID,contact UID, ..."
    optional
    connection = "connection ID">

deleteAttachments
<cfexchangecontact
    required
    action = "deleteAttachments"
    uid = "contact UID"
    optional
    connection = "connection ID">

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

getAttachments
<cfexchangecontact
    required
    action = "getAttachments"
    name = "query identifier"
    uid = "contact UID"
    optional
    attachmentPath = "directory path"
    connection = "connection ID"
    generateUniqueFilenames = "no|yes">

modify
<cfexchangecontact
    required
    action = "modify"
    contact = "#contact information structure#"
    uid = "contact UID"
    optional
    connection = "connection ID>"

See also

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

Attributes

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

All fields except the BusinessAddress, HomeAddress, and OtherAddress fields contain text; the three address fields must contain structures with the following text fields:

• Street
• City
• State
• Zip
• Country

The Attachments field must contain the pathnames of any attachments to include in the contact. To specify multiple files, separate filepaths with semicolons (;) for Windows, and colons (:) for UNIX and Linux. You must use absolute paths.

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

The Categories field can have a comma-delimited list of the contact's categories.

If you do not specify a DisplayAs field, Exchange sets the display name to FirstName, LastName.

Usage

The cfexchangecontact tag manages contact records on the Exchange server. Use the cfexchangecontact tag to perform the following actions:

• Create a contact.
• Delete one or more contacts.
• Get one or more contact 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 contact record.
• Modify an existing contact.

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, you should use the cfexchangeconnection tag to create a persistent connection. You then specify the connection identifier in each cfexchangecontact, or 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 cfexchangecontact tag. To do this, you specify the connection attributes directly in the cfexchangecontact tag. For details on the connection attributes, see the cfexchangeconnection  tag open action.

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 contacts 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 cfexchangecontact 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 contact. The query object has columns with the same names and data formats as the fields listed for the contact attribute structure, with the following changes:

• The query object has a Boolean HasAttachment column, and does not have an Attachments column. If the HasAttachment field is yes, use the getAttachments action to retrieve the attachments.
• The query object has an additional UID column with the unique identifier for the contact record in the Exchange server. Use this value in the uid attribute of the getAttachments, delete, and modify actions to identify the required record.
• The query object has an additional HtmlDescription column. The Description column has a plain-text version of the description, and the HtmlDescription 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 cfexchangecontact tag populates a query object with the specified name. Each record has the following information about an attachment to the contact specified by the UID:

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.

The modify action

If you specify the modify action, the uid attribute must specify a single Exchange UID. The contact structure must specify only the fields that you are changing. Any fields that you do not specify remain unchanged.

If a contact has attachments and you specify attachments when you modify the contact, 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 lets a user enter information in a form and creates a contact on the Exchange server with the information:

<!--- Create a structure to hold the contact information. --->
<cfset sContact="#StructNew()#">

<!--- A self-submitting form for the contact information --->
<cfform format="flash" width="550" height="460">
    <cfformitem type="html"><b>Name</b></cfformitem>
    <cfformgroup type="horizontal" label="">
        <cfinput type="text" label="First" name="firstName" width="200">
        <cfinput type="text" label="Last" name="lastName" width="200">
    </cfformgroup>
    <cfformgroup type="VBox">
        <cfformitem type="html"><b>Address</b></cfformitem>
        <cfinput type="text" label="Company" name="Company" width="435">
        <cfinput type="text" label="Street" name="street" width="435">
        <cfinput type="text" label="City" name="city" width="200">
        <cfselect name="state" label="State" width="100">
            <option value="CA">CA</option>
            <option value="MA">MA</option>
            <option value="WA">WA</option>
        </cfselect> 
        <cfinput type="text" label="Country" name="Country" width="200" Value="U.S.A.">
        <cfformitem type="html"><b>Phone</b></cfformitem>
        <cfinput type="text" validate="telephone" label="Business" name="businessPhone"
            width="200">
        <cfinput type="text" validate="telephone" label="Mobile" name="cellPhone"
            width="200">
        <cfinput type="text" validate="telephone" label="Fax" name="fax" width="200">
        <cfformitem type="html"><b>Email</b></cfformitem>
        <cfinput type="text" validate="email" name="email" width="200">
    </cfformgroup>

    <cfinput type="Submit" name="submit" value="Submit" >
</cfform> 


<!--- If a form was submitted, populate the contact structure from it. --->
<cfif isDefined("Form.Submit")>
    <cfscript>
        sContact.FirstName=Form.firstName;
        sContact.Company=Form.company;
        sContact.LastName=Form.lastName;
        sContact.BusinessAddress.Street=Form.street;
        sContact.BusinessAddress.City=Form.city;
        sContact.BusinessAddress.State=Form.state;
        sContact.BusinessAddress.Country=Form.country;
        sContact.BusinessPhoneNumber=Form.businessPhone;
        sContact.MobilePhoneNumber=Form.cellPhone;
        sContact.BusinessFax=Form.fax;
        sContact.Email1=Form.email;
    </cfscript>
    
    <!--- Create the contact in Exchange --->
    <cfexchangecontact action="create" 
        username ="#user1#"
        password="#password1#"
        server="#exchangeServerIP#"
        contact="#sContact#"
        result="theUID">
        
    <!--- Display a confirmation that the contact was added. --->
    <cfif isDefined("theUID")>
        <cfoutput>Contact Added. UID is#theUID#</cfoutput>
    </cfif>
</cfif>