To communicate with an Exchange server, establish a connection with the server. The connection can use the HTTP protocol or the HTTPS protocol. By default, ColdFusion connects to the mailbox that belongs to the login user name, but you can also connect to any mailbox whose owner has delegated access rights to the login user name. You can also access the server by using a proxy host.
Note: To establish any connection, the Exchange server must grant the login user Outlook web access. For information on how to enable this access, see Enabling Outlook web access below. |
Connections to the server can be persistent or transient:
- A persistent connection lasts until you explicitly close it. Persistent connections let you use a single connection for multiple tasks, which saves the processing overhead of opening and closing a separate connection for each interaction with the Exchange server.
- A transient connection lasts for the duration of the tag that interacts with the Exchange server. Transient connections are a useful technique on ColdFusion pages where you only have to access the Exchange server for a single tag; for example, where you only get a set of contacts.
Enabling access to the Exchange server
To enable access to the Exchange server, ensure the following:
- The Exchange server, Exchange access, and WebDav access are configured in IIS.
- The Exchange server enables Outlook web access to all login users.
- If you are using HTTPS to log into the exchange server, you have a valid client certificate in the JRE certificate store.
Ensure that IIS is configured for access to the Exchange server
- Open the IIS manager from the Administrative Tools control panel on the machine where the Exchange server is installed.
- Expand the Web Sites node in the tree on the left pane. If you see Exchange there, the web application is configured for Exchange. If you do not see it, follow the Microsoft instructions for configuring Exchange in the website
- Click the Web Service Extension node in the tree on the left pane. The right pane shows Web Service Extensions and their status. Make sure that Microsoft Exchange Server and WebDav entries are both allowed. If either entry is prohibited, select it and click the Allow button.
Enabling Outlook web access
To establish any connection, the Exchange server must grant the login user Outlook web access.
Check and grant web access
- In the Exchange administrator, open Administrative Tools > Active Directory Users and Computers > your domain name > users.
- Right-click the user whose ID you use to establish connections.
- Select the Exchange Features tab.
- In the Protocols section, enable the Outlook Web Access entry if it is disabled.
Enabling HTTPS access to the Exchange server
To enable HTTPS access from ColdFusion to the Exchange server you must
- Enable SSL on the Exchange server system
- Ensure that the JRE certificate store has a valid client certificate
Enabling SSL on the Exchange server system
Use the following steps to enable SSL on the Exchange server system:
- On the system where the Exchange server is installed, open the IIS manager from the Administrative Tools control panel.
- In the tree on the left pane, expand the Web Sites node,
- Right-click Exchange and ExchWeb in the expanded list and open the Web Site Properties dialog, then click the Directory Security tab.
- In the Secure Communications section, click Edit to open the Secure Communications dialog. Select the Require secure channel (SSL) option, click OK, and click Apply.
As an alternative to steps 3 and 4, you could do the following: Right-click Default Web Site. In Secure Communications->Edit, check the Require secure channel (SSL) option, click OK, and Click Apply. Select the nodes (for example Exchange) for which to enable SSL.
Enabling HTTPS access on the ColdFusion server
To use HTTPS to access the exchange server, you must have a valid client certificate in the JRE certificate store. If a known authority did not issue the certificate on the Exchange server, install a certificate. The Java certificate store already contains certificates from some authorities.
You can ask your system administrator to give you a certificate that you can install on the ColdFusion server, or you can do the following:
- Open Outlook Web Access in Internet Explorer and go to File->Properties.
- Click the certificates button.
- Click the Details tab and the 'Copy To File' button on the tab. Then follow the wizard options to save the certificate.
To install the certificate, run the following command using keytool.exe, which is in the jre\bin folder:
keytool.exe -importcert -file <path_to_certificate_file> -keystore ..\lib\security\cacerts |
Note: The keytool.exe program requires you to enter a password. The default password is changeit. |
Using persistent connections
To open a persistent connection, you use the cfexchangeconnection tag and specify the open action, the server IP address or URL, the user name, and the name of the connection (which you use in subsequent tags to specify the connection). You typically also specify a password, and can specify several other attributes, including a proxy host or a delegate mailbox ID. For details, see cfexchangeconnection in the CFML Reference.
Persistent connections use HTTP or HTTPS protocol with the keepAlive property set to true. As a result, the connections do not automatically close at the end of an HTTP request or ColdFusion page. Close the connection when you are done using it. If you do not, ColdFusion retains the connection until an inactivity time-out period elapses, after which, ColdFusion recovers the connection resources.
Note: You can store a connection in a persistent scope, such as the Application scope, and reuse it on multiple pages. However, you get no advantage by doing so, because the connections are lightweight and you get no substantial performance gain if you use a persistent scope. |
The following example opens a connection, gets all mail sent from spamsource.com, and deletes the messages from the Exchange server:
<cfexchangeConnection |
Using transient connections
Transient connections last only as long as the tag that uses them takes to complete processing. To create a transient connection, you specify the connection directly in your action tag (such as cfexchangetask) by using the same attributes as you do in the cfexchangeconnection tag (except for the connection name).
The following example uses a transient connection to create a single task:
<!--- Create a structure with the task fields. ---> |
Accessing delegated accounts
In Exchange, one user can grant, or delegate, another user access rights to their account. Users can delegate reviewer (read-only), author (read/write), or editor (read-write-delete) rights to any combination of the calendar, contacts, Inbox, or task list.
Note: You cannot use ColdFusion to delegate access rights. |
To access the delegator's account as a delegated user, specify the following information:
- Specify the delegated user's user name and password in the username and password attributes.
- Specify the mailbox name of the account that you are accessing in the mailboxName attribute.
You can access the account in a cfexchangeconnection tag that opens a persistent connection, or in a ColdFusion Exchange tag that uses a transient connection.
For example, if access rights to the docuser3 account are delegated to docuser4, you can use the cfexchangeconnection tag as in the following example to open a connection to the docuser3 account by using docuser4's credentials:
<cfexchangeconnection action="open" |
You can use this connection for any activities that docuser3 has delegated to docuser4. If docuser3, for example, has only delegated reviewer rights to the calendar, you can use this connection only with the cfexchangecalendar tag with get and getAttachments attributes.