Using ColdFusion 8 with Microsoft Exchange Server
Modified
5 November 2007
Requirements
Prerequisite knowledge
Some familiarity with Microsoft Exchange and ColdFusion tag syntax is useful.
User level
Intermediate
Additional Requirements
Adobe ColdFusion 8
or
Adobe ColdFusion 9 beta
Microsoft Exchange Server
Microsoft Exchange Server is used by businesses for e-mail messaging, calendar scheduling, and contacts and tasks management. Adobe ColdFusion 8, with a new library of tags, gives you the ability to access, retrieve, create, and modify this information quickly, easily, and without having to learn Lightweight Data Access Protocol (LDAP).
This article uses the new cfexchange tags in Adobe ColdFusion 8 to demonstrate how to:
- Connect to an Exchange server
- Retrieve a list of folders from an Exchange user's mailbox
- Retrieve mail, contact, calendar, and task information
- Create contacts, calendar events, and tasks
- Modify existing contacts, calendar events, and tasks
Setting up Exchange Server
You might be wondering how and why you would want to use ColdFusion to work with a Microsoft Exchange Server. I'd like to explain a few scenarios which led me to my use of it.
One of the first applications that I developed was an intranet application that allowed employees to go online and schedule their yearly performance evaluation. The application showed the employee a list of available times from which he/she selected a time. The manager, who performs the evaluation then received an e-mail with the details and an attachment that the employee could open and import in his/her Outlook calendar. Each manager was responsible for maintaining his/her list of available time slots through a web interface I developed. Unfortunately, since few managers were comfortable with using anything outside of the Microsoft Office Suite, they would often send me a list of changes and ask me to edit the information in the application.
In another scenario (part of the public facing website for the same company), there was a page for prospective students to request information from the Education Department. This process simply output the person's request in an e-mail that was sent to the manager of the Education Department; oftentimes, however, the e-mail would get buried under other e-mails in the manager's inbox.
At the time, I remember thinking: "There has got to be an better way." Unfortunately, without navigating through the quagmire that is the Microsoft Exchange Server LDAP structure, there wasn't. However, with the release of ColdFusion 8, developers have a whole new set of tools which allow you to quickly, and easily interact with Microsoft Exchange Server. In this article I show you the code that I would have used to revise the applications described above with the new cfexchange tags in ColdFusion 8.
To communicate with your Exchange server using ColdFusion, you must make sure that your Exchange server is configured to allow access to ColdFusion by ensuring that the following conditions are met:
- The Exchange server, Exchange access, and Web-based Distributed Authoring and Versioning (WebDAV) are configured in the Internet Information Server (IIS). This is done on the server that is running Exchange.
- The Exchange server enables Outlook Web Access to all login users.
- If you are using HTTPS to log into your Exchange server, you must have a valid client certificate in the Java Runtime Environment (JRE) certificate store.
Connecting to an Exchange server
You can connect to an Exchange server with ColdFusion using two different types of connections: persistent and transient.
Persistent connections will remain open until they are explicitly closed. These connections enable you to use a single connection for multiple tasks, and save processing overhead from having to reopen connections for each interaction with the Exchange server.
Transient connections will only exist for the duration of the tag used to interact with the Exchange server. Transient connections can be used when you need to have access to the Exchange server for only one task or tag, such as retrieving a list of tasks.
Whether you're using persistent or transient connections, there is certain information you will need to connect to Exchange:
- The IP address or domain name of the Exchange server
- A username of a user with access to Exchange
- The user's password
- Optionally, a mailbox name to which you will connect
By default, ColdFusion will connect to the mailbox used by the user specified in the username attribute. If this user has been delegated access to another user's account, this account may be specified in the mailbox attribute.
The following example shows how you to use a persistent connection to retrieve a user's contacts:
<cfexchangeconnection action="open" connection="myExchangeConnection"
server="#serverName#"
username="#username#"
password="#password#" />
<cfexchangecontact action="get" name="myContacts" connection="myExchangeConnection" />
<cfexchangeconnection action="close" connection="myExchangeConnection" />
This example shows how you would use a transient connection to retrieve a user's contacts:
<cfexchangecontact action="get" name="myContacts"
server="#serverName#"
username="#username#"
password="#password#" />
Retrieving items from Exchange Server
For the scheduling application I discussed above, I first create the list of available times. As in the original application, the manager has the responsibility of maintaining the available times. However, with the revised code, the managers can use Outlook, a tool they are comfortable with and already use. For the examples shown here, let's assume each manager specifies his or her own available time by setting an appointment in Outlook and giving it a subject of "Evaluation-Open." Using ColdFusion 8, I can look at the manager's calendar and only display these items. When an employee schedules his or her evaluation, you change the subject text to "Evaluation – {employee Name}." For the purposes of this article, I have set the code samples to work only with appointments that fall between December 1, 2007 and December 15, 2007.
To retrieve calendar information from Exchange, use the cfexchangecalendar tag. In this particular case, you also need to use the cfexchangefilter tag because you only need retrieve certain appointments that fall between December 1, 2007 and December 15, 2007. Here is what the cfexchangecalendar code block would appear:
<cfexchangeconnection action="open" connection="myExchangeConnection"
server="#serverName#"
username="#username#"
password="#password#"
mailboxname="#mailbox#">
<cfexchangecalendar action="get" connection="myExchangeConnection" name="managerCalendar">
<cfexchangefilter name="startTime" from="12/1/2007" to="12/15/2007"/>
<cfexchangefilter name="subject" value="Evaluation-Open"/>
</cfexchangecalendar>
<cfexchangeconnection action="close"connection="myExchangeConnection">
Anytime you retrieve information from an Exchange server, regardless of which tag set is being used, a ColdFusion query object is returned. The different item types (contact, calendar, task and mail) return slightly different result sets. One column that is returned with every query object is UID. The UID of an item uniquely identifies the item within Exchange.
If you needed additional filters, you could simply add more cfexchangefilter tags as needed. It is important to note that when filtering, if multiple filter names are used, ColdFusion will retrieve items that match all filters. If you use more than one filter with the same name, ColdFusion will retrieve items that match only the last listed filter. The name of the filter must equal the name of one of the columns in the query object.
Creating and editing Exchange Server items
Once the employee chooses a date and time for their evaluation, you need to update the appointment to assign it to the employee. To accomplish this, you code an action="modify" attribute in the cfexchangecalendar tag.
Whenever you need to create or modify an Exchange item, you create a ColdFusion structure that contains the information you wish to create or edit. The keys of the structure match column names from the query object that is retrieved for whichever Exchange item you are working with. In this case, since you need to modify the subject of a calendar event, you also need to use the event and UID attributes of the cfexchangecalendar tag.
In the following example, I changed the subject of the event to "Evaluation - {employee name}" based on information that might be stored in the session scope and relates to the employee. I also set the reminder for the evaluation to one week before evaluation.
<cfscript>
newEval = StructNew();
newEval.subject = "Evaluation - #session.firstName# #session.lastName#";
newEval.reminder = 10080;
</cfscript>
<cfexchangeconnection action="open"
connection="myExchangeConnection"
server="#serverName#"
username="#username#"
password="#password#"
mailboxname="#mailbox#">
<cfexchangecalendar action="modify" connection="myExchangeConnection" event="#newEval#" uid="#form.evalUID" />
<cfexchangeconnection action="close" connection="myExchangeConnection">
To make sure all the necessary information is ready for the evaluation, let's create a task for the manager's administrative assistant so the employee's personnel file can be retrieved and ready for the evaluation.
<cfscript>
newTask = StructNew();
newTask.subject = "Retrieve personnel file for Bobby Smith";
newTask.dueDate = evalDate;
newTask.message = "Please pull personnel file for Bobby Smith";
newTask.reminderDate = DateAdd('h',-1,evalDate);
</cfscript>
<cfexchangetask action="create"
connection="myExchangeConnection"
username ="#user#"
password="#password#"
server="#serverName#"
task="#newTask#" />
As you can see, this example uses create for the action attribute of the cfexchangetask tag, as well as the connection attribute. The code also sets the due date for the task to be the same time as the evaluation, but sets the reminder to one hour before the evaluation. The code snippet also does away with the cfexchangeconnection tags and passes the server and user information in the cfexchangetask tag. For this example, the connection to Exchange Server is opened only for the duration of the of the cfexchangetask operation and then closed.
When you are creating or editing Exchange Server items, the attribute used to pass information to Exchange differs depending on the type of item being created or edited. As you have seen, you use the event and task attributes for Exchange Calendar and Task items respectively. When editing or creating an Exchange contact, you use the contact attribute.
The last thing you must do for scheduling the evaluation is to send an e-mail to the employee with the event details. To do this, you can still use the cfmail tag. While ColdFusion 8 has the ability to read e-mail in a user's Exchange mailbox, and even modify those items, such as marking mail items as being read, you cannot send e-mail using the cfexchange family of tags.
As I mentioned in the beginning of this article, there is another area where being able to easily create Exchange Server items could be used would be when prospective students request information from the Education Department. The most common issue here was that because the request was sent via an e-mail, it would oftentimes get buried under other items in the recipient's inbox. You can fix this problem easily by creating a task similarly to how you did above and by assigning the task to the education manager, for instance.
Often times, the education manager wanted to follow-up with the prospective student to see if there were any questions, or if there was anything else that was needed. To make this easier, you could create an Exchange Contact item and add it to the education manager's "Contacts" in the Microsoft Exchange Server.
<cfscript>
newContact.FirstName=Form.firstName;
newContact.Company=Form.company;
newContact.LastName=Form.lastName;
newContact.HomeAddress.Street=Form.street;
newContact.HomeAddress.City=Form.city;
newContact.HomeAddress.State=Form.state;
newContact.HomeAddress.Country=Form.country;
newContact.HomePhoneNumber=Form.HomePhone;
newContact.Email1=Form.email;
</cfscript>
<!--- Create the contact in Exchange --->
<cfexchangecontact action="create"
username ="#user1#"
password="#password1#"
server="#exchangeServerIP#"
contact="#newContact#"
result="theUID" />
Now, whenever a visitor to the site requests information from the education department, the education manager would have the person's contact information easily at hand. This type of functionality would also be very useful for organizations with a sales department. Each request for information could be turned into a Contact and potential lead for the sales department.
Where to go from here
I have only scratched the surface of what you can do using the cfexchange family of tags in ColdFusion 8. Using these tags and the cfmail tags, you could write an application that mimics the functionality of Outlook Web Access, but uses your company's or client's existing intranet or website layout. By giving developers an easy and powerful way to retrieve and manipulate Microsoft Exchange items, Adobe continues to show that ColdFusion is not only capable of running enterprise-level applications, but allows developers to create these applications faster than ever before. More information about all of the Exchange-related tags can be found in Adobe LiveDocs.
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License
Tutorials & Samples |
