User Guide Cancel

cfexchangecontact

Last updated on May 30, 2024 | Also applies to ColdFusion

ColdFusion

Open app

CFML Reference User Guide
ColdFusion functions
ColdFusion Tags
1. ColdFusion tag summary
2. ColdFusion tags by category
  1. Application framework tags
    1. cfapplication
    2. cfassociate
    3. cferror
    4. cfimport
    5. cfinterface
    6. cflock
    7. cfscript
    8. cfthread
  2. Communications tags
  3. Database manipulation tags
  4. Data output tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcol
    5. cfcontent
    6. cfdocument
    7. cfdocumentitem
    8. cfdocumentsection
    9. cfflush
    10. cfheader
    11. cflog
    12. cfoutput
    13. cfpresentation
    14. cfpresentationslide
    15. cfpresenter
    16. cfprocessingdirective
    17. cfprint
    18. cfreport
    19. cfreportparam
    20. cfsilent
    21. cftable
  5. Debugging tags
    1. cfdump
    2. cftimer
    3. cftrace
  6. Exception handling tags
    1. cfcatch
    2. cferror
    3. cffinally
    4. cfrethrow
    5. cfthrow
    6. cftry
  7. Extensibility tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcollection
    5. cfcomponent
    6. cfexecute
    7. cfftp
    8. function
    9. cfindex
    10. cfinterface
    11. cfinvoke
    12. cfinvokeargument
    13. cfobject
    14. cfproperty
    15. cfreport
    16. cfreportparam
    17. cfreturn
    18. cfsearch
    19. cfsharepoint
    20. cfspreadsheet
    21. cfwddx
    22. cfxml
  8. File management tags
    1. cfdirectory
    2. cffile
    3. cffileupload
    4. cfftp
    5. cfzip
    6. cfzipparam
  9. Flow-control tags
    1. cfabort
    2. cfbreak
    3. cfcase
    4. cfcontinue
    5. cfdefaultcase
    6. cfelse
    7. cfelseif
    8. cfexecute
    9. cfexit
    10. cfif
    11. cfinclude
    12. cflocation
    13. cfloop
    14. cfrethrow
    15. cfswitch
    16. cfthrow
    17. cftry
  10. Forms tags
    1. cfapplet
    2. cfcalendar
    3. cffileupload
    4. cfform
    5. cfformgroup
    6. cfformitem
    7. cfgrid
    8. cfgridcolumn
    9. cfgridrow
    10. cfgridupdate
    11. cfinput
    12. cfpdf
    13. cfpdfform
    14. cfpdfformparam
    15. cfpdfparam
    16. cfpdfsubform
    17. cfselect
    18. cfslider
    19. cftextarea
    20. cftree
    21. cftreeitem
  11. Internet Protocol tags
    1. cfajaximport
    2. cfajaxproxy
    3. cfftp
    4. cffeed
    5. cfimap
    6. cfhttp
    7. cfhttpparam
    8. cfldap
    9. cfmail
    10. cfmailparam
    11. cfmailpart
    12. cfpop
    13. cfsprydataset
  12. Page processing tags
    1. cfcache
    2. cfcontent
    3. cfflush
    4. cfheader
    5. cfhtmlhead
    6. cfinclude
    7. cfprocessingdirective
    8. cfsetting
    9. cfsilent
  13. Security tags
  14. Variable manipulation tags
    1. cfcookie
    2. cfdump
    3. cfparam
    4. cfregistry
    5. cfsavecontent
    6. cfschedule
    7. cfset
    8. cfsetting
  15. Other tags
    1. cfimage
    2. cflog
    3. cfregistry
3. Tags a-b
4. Tags c
  1. cfcache
  2. cfcalendar
  3. cfcase
  4. cfcatch
  5. cfchart
  6. cfchartdata
  7. cfchartseries
  8. cfclient
  9. cfclientsettings
  10. cfcol
  11. cfcollection
  12. cfcomponent
  13. cfcontent
  14. cfcontinue
  15. cfcookie
  16. Tags d-e
5. Tags f
6. Tags g-h
  1. cfgraph
  2. cfgraphdata
  3. cfgrid
  4. cfgridcolumn
  5. cfgridrow
  6. cfgridupdate
  7. cfheader
  8. cfhtmlhead
  9. cfhtmltopdf
  10. cfhtmltopdfitem
  11. cfhttp
  12. cfhttpparam
7. Tags i
  1. cfif
  2. cfimage
  3. cfimap
  4. cfimapfilter
  5. cfimpersonate
  6. cfimport
  7. cfinclude
  8. cfindex
  9. cfinput
  10. cfinsert
  11. cfinterface
  12. cfinvoke
  13. cfinvokeargument
8. Tags j-l
9. Tags m-o
10. Tags p-q
  1. cfparam
  2. cfpdf
  3. cfpdfform
  4. cfpdfformparam
  5. cfpdfparam
  6. cfpdfsubform
  7. cfpod
  8. cfpop
  9. cfpresentation
  10. cfpresentationslide
  11. cfpresenter
  12. cfprint
  13. cfprocessingdirective
  14. cfprocparam
  15. cfprocresult
  16. cfprogressbar
  17. cfproperty
  18. cfquery
  19. cfqueryparam
11. Tags r-s
  1. cfregistry
  2. cfreport
  3. cfreportparam
  4. cfrethrow
  5. cfreturn
  6. cfsavecontent
  7. cfschedule
  8. cfscript
  9. cfsearch
  10. cfselect
  11. cfservlet
  12. cfservletparam
  13. cfset
  14. cfsetting
  15. cfsharepoint
  16. cfsilent
  17. cfslider
  18. cfspreadsheet
  19. cfsprydataset
  20. cfstoredproc
  21. cfswitch
12. Tags t
  1. cftable
  2. cftextarea
  3. cftextinput
  4. cfthread
  5. cfthrow
  6. cftimer
  7. cftooltip
  8. cftrace
  9. cftransaction
  10. cftree
  11. cftreeitem
  12. cftry
13. Tags u-z
  1. cfupdate
  2. cfwddx
  3. cfwebsocket
  4. cfwindow
  5. cfxml
  6. cfzip
  7. cfzipparam
CFML Reference
1. Reserved words and variables
2. Ajax JavaScript functions
3. ColdFusion ActionScript functions
4. ColdFusion mobile functions
5. Application.cfc reference
6. Script functions implemented as CFCs
7. ColdFusion Flash Form style reference
8. ColdFusion event gateway reference
9. ColdFusion C++ CFX Reference
10. ColdFusion Java CFX reference
11. WDDX JavaScript Objects
Cloud services

Description

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

History

ColdFusion (2023 release) Update 5: Added the attributes username, password, and server.
ColdFusion 10: Added the attribute serverVersion.
ColdFusion 8: Added this tag.

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

Note: If you omit the connection attribute, create a temporary connection by specifying cfexchangeconnection tag attributes in the cfexchangecontact 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

Attribute	Action	Req/Opt	Default	Description
action	N/A	Required		The action to take. Must be one of the following values: create delete deleteAttachments get getAttachments modify
username	all	Optional		The Exchange user ID.
password	all	Optional		The password for accessing the Exchange server.
server	all	Optional		The IP address or URL of the server that is providing access to Exchange.
attachmentPath	getAttachments	Optional		The absolute 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.
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 open action attributes in the cfexchangecontact tag.
contact	createmodify	Required		A reference to the structure that contains the contact properties to be set or changed and their values. Specify this attribute in number signs (#). For more information on the event structure, see Usage.
generateUniqueFilenames	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	getgetAttachments	Required		The name of the ColdFusion query variable that contains the returned contact 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 contact that is created. Use this value in the uid attribute of other actions to identify the contact to be acted on.
serverVersion		Optional	2007	Specifies the Microsoft Exchange Server version. The values are: 2003 2007 2010 If you do not specify the details, 2007 is taken by default. The value you specify overrides the value that you specify at the application level.
uid	getAttachmentsdeletemodify	Required		A case-sensitive Exchange UID value that uniquely identifies the contacts 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 contact attribute must specify a structure that contains information that defines the events. The structure can have the following elements. Include only the elements that you are setting or changing.

Assistant	Attachments	BusinessAddress	BusinessFax
BusinessPhoneNumber	Categories	Company	Department
Description	DisplayAs	Email1	Email2
Email3	FirstName	HomeAddress	HomePhoneNumber
JobTitle	LastName	MailingAddressType	Manager
MiddleName	MobilePhoneNumber	NickName	Office
OtherAddress	OtherPhoneNumber	Pager	Profession
SpouseName	WebPage

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

attachmentPath attribute

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:///filepath"

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

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 specifying 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 Working with in-memory files in Optimizing ColdFusion applications 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 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. 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:

<cfset sContact="#StructNew()#">


<cfform format="flash" width="550" height="460">
<cfformitem type="html">Name</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">Address</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">Phone</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">Email</cfformitem>
<cfinput type="text" validate="email" name="email" width="200">
</cfformgroup>

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


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


<cfexchangecontact action="create"
username ="#user1#"
password="#password1#"
server="#exchangeServerIP#"
contact="#sContact#"
result="theUID">


<cfif isDefined("theUID")>
<cfoutput>Contact Added. UID is#theUID#</cfoutput>
</cfif>
</cfif>

Example with username and password

<cfscript>

	domain = "exchange.com"
	contact.email1 = "john@example.comm"
	contact.FirstName="John"
	contact.Company="Adobe"
</cfscript>
<cfexchangecontact action="create" 
	  	username = "user1"  <!--- sample --->
		password = "password1"
		mailboxname ="user1"
		server = "exchangeServerIP"
		serverversion="version"
		protocol="protocol"
		contact = "contact"
		result = "contactUID"
		> 

	<!--- multiple filters  --->		
<cfexchangecontact action="get" 
		name="qContacts" 
		username="user1" 
		password="Password1" 
		server="exchangeServerIP" 
		serverversion="version" 
		protocol="protocol" 
		mailboxname="user1">
				
    <cfexchangefilter name="email1" value=contact.email1>
    <cfexchangefilter name="company" value=contact.Company>	
    <cfexchangefilter name="FirstName" value=contact.FirstName>
</cfexchangecontact>
	<cfoutput>Number of records returned: qContacts.RecordCount<br></cfoutput>
	<cfoutput>email1: qContacts.email1</cfoutput><br>

	<!--- one filters  --->		
	<cfexchangecontact action="get" 
		name="qContacts" 
		username="user1" 
		password="Password1" 
		server="exchangeServerIP" 
		serverversion="version" 
		protocol="protocol" 
		mailboxname="user1">
				
		<cfexchangefilter name="FirstName" value=contact.FirstName>
	</cfexchangecontact>
	<!--- 	<cfdump var=qContacts> --->
	
	<cfoutput>Number of records returned: qContacts.RecordCount<br></cfoutput>
	<cfoutput>FirstName: qContacts.FirstName</cfoutput><br>

<cfexchangecontact action="get" 
		name="qContacts" 
		username="user1" 
		password="Password1" 
		server="exchangeServerIP" 
		serverversion="version" 
		protocol="protocol" 
		mailboxname="user1">
				
		<cfexchangefilter name="email1" value="nosuchentiy@adobe.com">
</cfexchangecontact>
	
<cfoutput>Number of records returned: qContacts.RecordCount<br></cfoutput>

Get help faster and easier

New user?