Helpdesk Application
Now that we know how to successfully log on to the Exchange Server, let's take a look at our first sample application, the Helpdesk application. The Helpdesk application is a web-based application that allows users to submit new help requests. Help technicians can, in turn, use their web browser to view and answer help requests as well as schedule meetings with the users to go on site to solve their problems. This application allows the technicians to use different views for the help tickets stored in the system so that they can quickly see who the ticket is from, when it was sent, and its status. (A help ticket for the Helpdesk application is shown in Figure 11-2.) When browsing help tickets, the technicians are presented with machine-configuration information from a Microsoft Access 97 database, making it easier for them to track down whether the issue is related to hardware, software, or a user error.
Figure 11-2 A help ticket in the Helpdesk application. This is the Dynamic HTML version of the application.
This application is the most complex of all the sample applications in this book, but the code for it is easy to follow and shows you how to use many of the objects in the CDO library. There are actually two versions of the application on the companion CD. The version you use depends on the web browser you want to target. One version implements a user interface for the helpdesk tickets by using Dynamic HTML (DHTML). The other version uses HTML tables. A screen from the non-DHTML version is shown in Figure 11-3.
Figure 11-3 The non-DHTML version of a help ticket.
Setting Up the Helpdesk Application
Before you can install the application, you must have a Windows NT 4.0 Server and a client with certain software installed. Table 11-1 outlines the installation requirements.
To use the Helpdesk application, you will need to have some e-mail users. You can either select currently set up e-mail users or add new ones using the Exchange Administrator program. Be sure to fill in the directory information for your users; this information should include their office locations, phone numbers, titles, and departments. The Helpdesk application dynamically retrieves this information using the CDO library. If the information is not available in the directory, the application will display the text "None specified" for these fields.
To install the application, copy the Helpdesk folder from the companion CD to your web server where you want to run the application. If you are going to use a browser that does not support DHTML, such as Internet Explorer 3.0, copy the three .asp files from the nondhtml subfolder to the Helpdesk folder, overwriting the current files. These files will replace the DHTML versions of the Helpdesk with the HTML versions.
Table 11-1 Installation Requirements for the Helpdesk Application
| Required Software | Installation Notes |
|---|---|
| Exchange Server 5.5 SP1 with Outlook Web Access | |
| IIS 3.0 or higher with Active Server Pages | IIS 4.0 is recommended. |
| CDO library (cdo.dll) CDO Rendering library (cdohtml.dll) | Exchange Server 5.5 SP1 installs CDO library 1.21 and CDO Rendering library 1.21. Outlook 98 installs CDO library 1.21. |
| ActiveX Data Objects | IIS 4.0 installs ADO 1.5. Visual Basic 6.0 installs ADO 2.0. For more information on ADO, consult http://www.microsoft. com/data/. |
| Access 97 (optional) | Install Access 97 if you want to utilize the database access feature. |
| For the client: A web browser Outlook 98 | For the web browser, Microsoft Internet Explorer 4.0 is recommended. You can run the client software on the same machine or on a separate machine. |
Start the IIS administration program. The user interface you see depends on what version of IIS you have. Create a virtual directory that points to the location where you copied the help desk files, and name the virtual directory helpdesk. Make sure you enable the Execute permissions option for the virtual directory or you will receive an HTTP error when attempting to access the application. You will be able to use the following URL to access your help desk: http://yourservername/helpdesk.
Included with the helpdesk files on the companion CD is a sample Access 97 database (smsdata.mdb) that allows the application to query for system information about the current user. To use this database, you must set up a system DSN for it on the server machine by using the ODBC Data Source Administrator in the Control Panel. Point the system DSN at the smsdata.mdb file, and name the DSN Helpdesk. Make sure that the read-only flag is unchecked for the smsdata.mdb file. Open smsdata.mdb in Access and edit the Userid fields for all three tables to reflect the display names of the users you have in Exchange.
NOTE
Files copied from CDs have their read-only flags set. When setting up the applications included with this book, be aware that you may need to clear this read-only flag after copying files from the companion CD.
Launch Microsoft Outlook. (You can launch it on any machine because you are going to create a public folder that will contain the help tickets for the application. The only requirement is that the Exchange Server with which the IIS server is communicating can access the public folder you create.) Create a new public folder under All Public Folders. Name the folder Helpdesk, and select Task Items as the default item type for the folder.
NOTE
You must install the Helpdesk folder under All Public Folders or the application will not work. If you cannot install the application there, you can modify the code contained in the Helpdesk application so that it looks for the folder in another location, or you can retrieve the folder by using its EntryID.
Among the helpdesk files, you will find a file named helpdesk.fdm. This file is a form definition file that will be used to import the correct fields needed by the Helpdesk application. In this case, the form is a Help Request task form with multiple custom fields.
To install the Help Request form, you need to import this file in to the Helpdesk public folder. To do this, right-click on the Helpdesk public folder and select Properties. Click on the Forms tab, and click Manage to display the Forms Manager, as shown in Figure 11-4.
In the Forms Manager dialog box, click Install to display the Open dialog box. Select the All Files option from the Files Of Type drop-down list so that Outlook does not search only for files with a .cfg extension. Locate and double-click on the helpdesk.fdm file to display the Form Properties dialog box. Click Cancel, and then click Close and OK. When you have the Helpdesk public folder selected, you should see a new option on the Actions menu named New Helpdesk Request.
You will need to create some views in the Outlook client so that these views are available to the web browser client. This is one of the powerful features of CDO. These views will include some of the custom fields from the Help Request form just installed. Using the Define Views dialog box and the information in Table 11-2, create the Helpdesk, From, and Status views for the Helpdesk public folder. (For information about creating views, see the section titled "Views" in Chapter 4.)
Figure 11-4 The Forms Manager dialog box.
Table 11-2 Information for Creating Helpdesk, From, and Status Views
| View Name | Type | Fields | Group By |
|---|---|---|---|
| Helpdesk | Table | Flag, From User (select from Help Request form) Received, Subject (select from All Mail Fields) | None |
| From | Table | Flag (select from Help Request form) Received, Subject (select from All Mail Fields) | From User, in ascending order |
| Status | Table | From User (select from Help Request form) Received, Subject (select from All Mail Fields) | Flag, in ascending order |
Using the Properties dialog box in Outlook for the Helpdesk public folder, set the permissions for your users. Give regular users who will submit help tickets Create Items permission. Give technicians who can submit, view, and resolve help tickets Create Items and Read Items permissions. Figure 11-5 shows a sample permissions setup for the Helpdesk folder. As you will see, the application checks the permissions of the current user for the Helpdesk folder to determine whether the user is a technician or just a regular user. If you do not give yourself at least Read Items permissions, you will not be able to see the menu option View Current Help Tickets in the Helpdesk application.
Figure 11-5 The Permissions tab of the Properties dialog box for the Helpdesk public folder. Regular users have Create Items permissions, and technicians have Create Items and Read Items permissions.
You're finished setting up the application. Try connecting your browser to http://yourservername/helpdesk to access the application.
Helpdesk CDO Session Considerations
You need to be aware of certain issues when building ASP-based applications with CDO, like the Helpdesk application. Recall from Chapter 8 that the ASP Session object, which is created when a new user connects to your web application, maintains the user state for web applications. ASP, in turn, runs the Session_OnStart subroutine in the Global.asa file. When a user's session times out or the user abandons the session, ASP runs the Session_OnEnd subroutine in the Global.asa file. This might seem simple enough, but the most common problem developers run into with CDO applications is not putting in the correct code in the Session_OnStart and Session_OnEnd subroutines in the Global.asa. If you do not put the correct code in these subroutines, you could get an ASP 0115 error, which indicates that a trappable error has occurred in an external object. Your ASP application will cease working until you restart the web server. To help you better understand what you need to do as a CDO developer, and to help you avoid this error in your application, let me explain in more detail exactly what happens when a user logs on and off an Exchange Server in a CDO ASP application. I'll do this by showing you the Global.asa file from the Helpdesk application:
<SCRIPT LANGUAGE=VBScript RUNAT=Server> Sub Application_OnStart On Error Resume Next Set objRenderApp = Server.CreateObject("AMHTML.Application") If Err = 0 Then Set Application("RenderApplication") = objRenderApp Else Application("startupFatal") = Err.Number Application("startupFatalDescription") = _ "Failed to create application object<br>" & _ Err.Description End If Application("hImp") = 0 'Load the configuration information from the Registry objRenderApp.LoadConfiguration 1, _ "HKEY_LOCAL_MACHINE\System\CurrentControlSet\" & _ "Services\MSExchangeWeb\Parameters" Application("ServerName") = objRenderApp.ConfigParameter("Server") Err.Clear End Sub Sub Application_OnEnd Set Application("RenderApplication") = Nothing End Sub Sub Session_OnStart On Error Resume Next 'This is a handle to the security context. 'It will be set to the correct value when a 'CDO session is created. Session("hImp") = 0 Set Session("AMSession") = Nothing End Sub 'While calling the Session_onEnd event, IIS doesn't call us in 'the right security context. 'Workaround: current security context is stored in Session 'object and then gets restored in Session_onEnd event handler. ' 'All CDO and CDO Rendering library objects stored in the 'Session object need to be explicitly set to Nothing between 'the two objRenderApp.Impersonate calls below Sub Session_OnEnd On Error Resume Next set objRenderApp = Application("RenderApplication") fRevert = FALSE hImp = Session("hImp") If Not IsEmpty(hImp) Then fRevert = objRenderApp.Impersonate(hImp) End If 'Do our cleanup. Set all CDO and CDOHTML objects inside 'the session to Nothing. 'The CDO session is a little special because we need to do 'the Logoff on it. Set objOMSession = Session("AMSession") If Not objOMSession Is Nothing Then Set Session("AMSession") = Nothing objOMSession.Logoff Set objOMSession = Nothing End If If (fRevert) Then objRenderApp.Impersonate(0) End If End Sub </SCRIPT> |
When the first user connects to the application, the Application_OnStart subroutine is run only once. As you can see in the code, the first step is to create a new CDO rendering application from the CDO Rendering library. The ProgID for the CDO rendering application is AMHTML.Application. The rendering application is stored in an application-level variable so that you avoid creating multiple AMHTML objects. Your application will perform better if you create the AMHTML object once and then use it throughout all user sessions.
NOTE
CDO was formerly named Active Messaging, so you will see both CDO and AM used throughout the CDO library. Consider any objects that are prefixed with AM to be CDO objects.
The Application_OnStart subroutine initializes some variables and then uses a method on the CDO rendering application object to retrieve the name of the Exchange Server from the web server's Registry. This method allows portability of the code. You don't have to hard-code the name of the Exchange Server; the Helpdesk application pulls the information from the Registry.
After the first user connects and Application_OnStart is finished running, ASP runs the Session_OnStart subroutine for all users. Session_OnStart clears a session variable named hImp. This hImp variable is a handle to the security context for the current user. Remember that when a user first browses a web page in IIS, she is running in the security context of the IUSR_servername account. While this account is useful for browsing web pages anonymously, it is not useful for accessing Exchange Server objects and information because it has no implicit permissions on Exchange Server objects. So when building an authenticated CDO application, you need to force IIS to challenge the current user for the user's Microsoft Windows NT credentials. IIS and CDO can use the Windows NT security context for that user to attempt a logon to the Exchange Server. The following code, taken from the Logon.inc file of the Helpdesk application, checks the HTTP variables to make sure that the current user is authenticated by the web server using the user's Windows NT credentials. In the Helpdesk application, this section of code is called by every ASP page, just in case the ASP session of the user has timed out.
Public Function BAuthenticateUser On Error Resume Next 'Response.Write( "In BAuthenticateUser<br>") BAuthenticateUser = False bstrAT = Request.ServerVariables("AUTH_TYPE") If InStr(1, "_BasicNTLM", bstrAT, vbTextCompare) < 2 Then Response.Buffer = TRUE Response.Status = ("401 Unauthorized") Response.AddHeader "WWW.Authenticate", "Basic" Response.End Else BAuthenticateUser = True End If End Function |
This function searches the AUTH_TYPE server variable to see whether either Basic or NTLM is contained anywhere in the string. If either is not, the user is unauthenticated and the script sends back a "401 Unauthorized" response and a header which will force the browser to challenge the user for credentials.
Once authenticated, the security context of the user must be saved as a Session variable. You must save this security context because IIS uses multiple threads of execution and you cannot be guaranteed that the thread that tries to destroy the session when the user logs off will be the same thread used to create the session. In the Session_OnEnd subroutine, the script checks to see whether hImp is not empty, implying it is a valid handle. If hImp is not empty, hImp is used to specify the Windows NT security context to impersonate. Once the CDO and CDO Rendering objects are set to Nothing and the session is logged off, the CDO Rendering application object reverts from the authenticated thread to the unauthenticated thread by calling the Impersonate method, with 0 as the parameter.
As we step through the Helpdesk application, you will see that every page in the application checks to see whether the ASP session, and therefore the CDO session, has been abandoned or has timed out. If the session has been abandoned or has timed out, the application redirects the user to the logon page so that he can restart his ASP and CDO sessions. Figure 11-6 shows the logon page.
Figure 11-6 The logon page for the Helpdesk application.
Logging On to the Helpdesk
You've seen that both the Global.asa and the Logon.inc files help to authenticate users and maintain sessions. We have not yet discussed, however, how you actually use the Logon method of the CDO Session object in the Helpdesk application to create a valid session with the Exchange Server. The Logon method must be called before you attempt to access any other CDO objects. The script that implements user logons is contained in the Logon.inc file, shown here:
<% 'logon.inc. VBScript methods to create and check an 'ActiveMessaging session '============================ 'ReportError ' '============================ Function ReportError( bstrContext) ReportError= False If Err.Number <> 0 Then Response.Write( "Error: " & bstrContext & " : " & _ Err.Number & ": " & Err.Description & "<br>") Err.Clear ReportError= True End If End Function '============================ 'BAuthenticateUser 'Ensures user is authenticated. Note that this implies that 'Basic authentication is enabled on the IIS server. '============================ Public Function BAuthenticateUser On Error Resume Next 'Response.Write( "In BAuthenticateUser<br>") BAuthenticateUser = False bstrAT = Request.ServerVariables("AUTH_TYPE") If InStr(1, "_BasicNTLM", bstrAT, vbTextCompare) < 2 Then Response.Buffer = TRUE Response.Status = ("401 Unauthorized") Response.AddHeader "WWW.Authenticate", "Basic" Response.End Else BAuthenticateUser = True End If End Function '============================ 'CheckAMSession ' 'Checks for and returns the AM session in the Session object. 'If not found, calls NoSession(). 'Call this before emitting any HTML or any redirects, 'authentication, etc. 'Returns True if session exists or can be created. '============================ Public Function CheckAMSession() On Error Resume Next 'Response.Write( "In GetSession<br>") Dim amSession CheckAMSession= False Set amSession= Session( "AMSession") If amSession Is Nothing Then NoSession amSession= Session( "AMSession") End If If Not amSession Is Nothing Then CheckAMSession= true End If End Function '============================ 'NoSession ' 'Called when the AM session cannot be found. 'Either creates a session or gets more info from the user. 'Returns only if the session was created. ' '============================ Sub NoSession() On Error Resume Next Dim bstrMailbox Dim bstrServer Dim bstrProfileInfo Dim objAMSession1 Dim objRenderApp Dim objInbox bstrServer = Application("ServerName") if Session("mailbox") is Nothing then bstrMailbox = Request.QueryString("Contact_Email") else bstrMailbox = Session("mailbox") end if 'Must be authenticated to successfully log on BAuthenticateUser Err.Clear Set objAMSession1 = Server.CreateObject("MAPI.Session") If Not ReportError( "create MAPI.Session") Then set objRenderApp = Application( "RenderApplication" ) 'Construct the ActiveMessaging profile from server 'and mailbox name bstrProfileInfo = bstrServer + vbLF + bstrMailbox Err.Clear objAMSession1.Logon "", "", False, True, 0, True, _ bstrProfileInfo If Not ReportError( "CDO Logon") Then 'To ensure that we are really logged on, we need to 'try retrieving 'some data Err.Clear Set objInbox = objAMSession1.Inbox 'If ReportError( "Get Inbox") Then 'The logon is no good. We'll do a little 'cleanup here. If err.number <> 0 then objAMSession1.Logoff Set objAMSession1 = Nothing %> <META HTTP-EQUIV="REFRESH" CONTENT="0; URL=email.asp"; TARGET="_top"> <% 'response.redirect "default.htm" End If 'This will be retrieved in CheckSession. 'Note that if the logon failed, this is set to 'Nothing'. Set Session("AMSession") = objAMSession1 'Need this to re-create the proper security context 'in Session_OnEnd. Session("hImp") = objRenderApp.ImpID End If 'objAMSession1.Logon End If 'Server.CreateObject() End Sub |
The first function called on every ASP page in the Helpdesk application is the CheckAMSession function, which checks to see whether the user already has a valid CDO Session object with the Exchange Server. If this function does not find a valid object, it calls the NoSession subroutine to log the user on to CDO.
In the NoSession subroutine, the variable bstrServer is set to the Exchange Server name, which is pulled from the Registry in the Global.asa file. (Again, retrieving the Exchange Server name from the Registry allows the portability of the code to any web server and any Exchange Server.) The script then checks to see whether the ASP Session variable named mailbox contains a valid mailbox alias name. If this variable is empty, the script attempts to grab the mailbox name from the URL that was passed to the web server by the logon screen of the application.
The BAuthenticateUser function is called to ensure that the user is logged on to Windows NT correctly before the code attempts the CDO Session Logon method. After the CDO object is created, its Logon method is called. The variable bstrProfileInfo is set so that CDO can dynamically create a profile for the user. The script calls the Logon method, and if that method returns no errors, the script tries to retrieve the Inbox for the user. You should follow similar steps in your applications because the Logon method can return successfully when called with dynamic profiles, even when the server or mailbox name is not valid. If you do not try to retrieve information from the server directly and assume the Session object is valid because the method returned successfully, you will run into many problems.
If the code cannot retrieve the user's Inbox successfully, the code logs off and redirects the user to the logon page. If the code can retrieve the Inbox, it stores the handle to the security context for this user in the hImp session variable.
Accessing Folders in the Helpdesk
You don't have much of a Helpdesk application if your users can't enter information and your technicians can't retrieve information. This Helpdesk application uses a public folder to store and retrieve information about ticket status. CDO provides access to public folders through its InfoStores collection, which contains all the different stores or databases that CDO can access. For example, with the InfoStores collection, you can access not only public folders and server-based mailboxes, but also personal folders stored in .pst files or offline replicated folders stored in .ost files. Of course, to enable CDO to access some of these infostores, you must run your CDO application on the client machine. Figure 11-7 shows the InfoStores collection with some of its child objects.
Figure 11-7 The InfoStores collection in CDO. This collection is used to access data stored in Exchange Server.
In the Helpdesk application, the InfoStores collection is used to find the public folder store. The following code from default.asp uses a For...Each statement to loop through the InfoStores collection and retrieve each store in the collection. Each store is checked to see whether the store name corresponds to the public folder store. If a corresponding store name is found, the For...Each statement is exited.
Set objInfoStoresColl = objOMSession.InfoStores for each objInfoStore in objInfoStoresColl If objInfoStore.Name = "Public Folders" Then exit for end if next |
Now that the application has the correct infostore, the correct set of folders needs to be accessed in that infostore. The InfoStore object in CDO has a RootFolder property that returns a Folder object representing the root of all the folders. For your mailbox and public folder stores, the RootFolder property returns a Folder object named IPM_Subtree. By using that Folder object, you can traverse through all folders in your mailbox or top-level public folders. However, note one caveat with this property: you cannot use the RootFolder property to access public folders if your application is running as a Windows NT service. Instead, you need to use the Fields collection on the InfoStores object with the specific property tag PR_IPM_PUBLIC_FOLDERS_ENTRYID (&H66310102). Once you retrieve the EntryID for the root public folder from the Fields collection, you can use the GetFolder method to actually retrieve the root Public Folder. (An EntryID is like a GUID in that it uniquely identifies the folder in the Exchange Server database.) After retrieving the root folder, you can then use the Folders collection of the root public folder to retrieve the root folder's subfolders. The following code, taken from default.asp, shows the GetFolder method in action. It retrieves the folders in the public folder tree, and then recurses the top-level folders as it searches for the Helpdesk folder.
'This is the EntryID for the root public folder bstrPublicRootID = objInfoStore.Fields.Item( &H66310102 ).Value Set myrootfolder = objOMSession.GetFolder(bstrPublicRootID, _ objInfoStore.ID) 'Now get the Folders collection below the root Set myfoldercollect = myrootfolder.Folders Set recursefolder = myfoldercollect.GetFirst() 'Recurse it until we get the folder we are looking for While recursefolder.Name <> "Helpdesk" Set recursefolder = myfoldercollect.GetNext() Wend set objFolder = recursefolder set Session("HelpdeskFolder") = recursefolder Session("InfoStoreID") = objInfoStore.ID |
Once the code finds the Helpdesk folder, it stores the CDO Folder object that corresponds to the Helpdesk folder as well as the unique identifier for the public folder InfoStore object because, from a performance standpoint, recursing the InfoStores and Folders collection in every ASP page in the Helpdesk application to find this information is expensive. Since we now have this information available across the entire session, the other pages use the Session object for the folder whenever access to the Helpdesk folder is required.
Implementing Helpdesk Folder Security
When a user logs on to the Helpdesk application, the options displayed depend on the user's folder permissions. For example, if a user accesses the application and she has only Create Items permission for the Helpdesk folder, the ASP will display only the Submit A Helpdesk Ticket and Logoff options, as shown in Figure 11-8. However, if a technician who has Read Items and Create Items permissions for the Helpdesk folder logs on to the application, the ASP will display an additional menu option—View Current Help Tickets, as shown in Figure 11-9.
Figure 11-8 The Helpdesk Menu page, where the user who has logged on has Create Items permissions for the Helpdesk folder.
This functionality is implemented in CDO by using the Fields collection on the Folder object. The Fields collection, a common collection across many of the objects in CDO, allows you to access specific properties stored for an object that CDO does not have an explicit object or property for. With the Fields collection, you can pass in a unique identifier that corresponds to the properties you want to retrieve. In the next section of Helpdesk code, which is from the default.asp file, we pass in the unique identifier for the MAPI property ActMsgPR_ACCESS (&H0FF4003), which contains a bitmask of flags corresponding to the user's permissions level for the current Folder object. The code then performs a logical AND on the returned value from the Fields collection by using the known bitmask of the MAPI_ACCESS_READ permission. If the result does not equal zero, the user can read items in the folder, and the ASP displays the View Current Help Tickets link in the helpdesk menu.
Figure 11-9 The Helpdesk Menu page, where the user logged on is a technician and has Create Items and Read Items permissions for the Helpdesk folder.
<h2>Please choose an option:</h2> <a href="default1.asp">Submit a helpdesk ticket</a><P> <% 'Check permissions on the folder to see whether the user has 'read access. If the user does, the user must be a technician, 'so display the ability to view help tickets. nAccess = objFolder.Fields.Item(ActMsgPR_ACCESS) bCanPost = nAccess And MAPI_ACCESS_READ If bCanPost <> 0 then %> <a href="render.asp">View current help tickets</a> <% end if %> <P> <a href="logoff.asp">Logoff</a> |
You can pass many types of identifiers to the Fields collection. The Helpdesk application does not use the CdoPR_CONTAINER_CLASS (&H3613001E) property, but I point it out to you because it demonstrates the type of information you can access through the Fields collection on CDO objects. It contains the message class of the default type of item contained in the folder. For example, if in Outlook you set the default item type for a Public Folder as contacts, the CdoPR_CONTAINER_CLASS property will contain IPF.Contact. How do you change the default item type in a folder programmatically through CDO? By using the Fields collection on a folder and this property, as shown in the next bit of sample code, the code changes the default item type of a folder to tasks. The code uses the InfoStores collection to retrieve the mailbox of the user. It then retrieves the root folder of the mailbox by using the RootFolder property. From that root folder, it retrieves the contacts folder in the mailbox. The next line of code uses the Fields collection on the folder to set a property that corresponds to the default item type for the folder. Finally, to make the default item-type change permanent, the Update method of the Folder object is called, committing the changes to the disk memory.
Set oStore = oSession.InfoStores("Mailbox - Thomas Rizzo (Exchange)") Set oFolder = oStore.RootFolder.Folders("Contacts") MsgBox "Before Update: " & oFolder.Fields(&H3613001E) oFolder.Fields(&H3613001E) = "IPF.Tasks" oFolder.Update MsgBox "After Update: " & oFolder.Fields(&H3613001E) |
NOTE
For the most complete list of the identifiers you can use with the Fields collection in your applications, refer to the cdo.chm on the companion CD. On the Contents tab, look under the Appendixes section for the MAPI Property Tags document.
Retrieving User Directory Information
If the user clicks on the Submit A Helpdesk Ticket option on the helpdesk menu, the file default1.asp is called. This ASP file displays a help request form, which is shown in Figure 11-10.
As you can see in Figure 11-10, some information about the user is already entered in the help request form. This information is dynamically pulled from the Exchange Server directory to help users save time when filling out requests. The enabling technology for this dynamic lookup involves primarily two CDO objects, the Recipient object and the AddressEntry object. A diagram illustrating the hierarchy of these two objects is shown in Figure 11-11.
Figure 11-10 The help request form allows users to post information to the Helpdesk application.
Figure 11-11 The Recipients collection and Recipient object in CDO.
The Recipient object represents a recipient of a message. You might be wondering why a Recipient object is used to retrieve directory information from Exchange Server. There are two primary reasons for this. The first is that CDO does not explicitly support querying for directory information without first retrieving the AddressEntry object for the desired user. The second is that adding the name of the user to a message as a Recipient, and then using the Resolve method of the Recipient object, is probably the easiest way to retrieve the AddressEntry object for a particular user. After resolving the name, you can call the AddressEntry property on the resolved Recipient object to retrieve the corresponding AddressEntry object. Just make sure you destroy the temporary objects you created for the Message and Recipient objects. The AddressEntries collection and AddressEntry object in CDO are shown in Figure 11-12.
Figure 11-12 The AddressEntries collection and AddressEntry object in CDO.
The AddressEntry object contains the directory and address information for a user in the Exchange Server system. You can use the built-in properties of this object to access the e-mail address information for a particular user, but to access directory information (department, office location, and phone number), you must use the Fields collection of the AddressEntry object with MAPI property tags. The code sample below, which is taken from default1.asp, shows you how the Helpdesk application implements directory lookup for users.
Set objmessage = objOMSession.Outbox.Messages.Add 'Create the recipient Set objonerecip = objmessage.Recipients.Add 'Retrieve the e-mail address from the previous HTML form objonerecip.Name = Session("mailbox") 'Resolve the name against the Exchange Server directory objonerecip.Resolve 'Get the address entry so that we can pull out template info Set myaddentry = objonerecip.AddressEntry Set myfields = myaddentry.Fields 'The numbers in parens are the hard-coded IDs for dept, title, etc. Set mydept = myfields.Item(974651422).value set mytitle = myfields.Item(974585886).value set myworkphone = myfields.Item(973602846).value set myoffice = myfields.Item(974716958).value if mydept = "" then mydept = "None specified" end if if mytitle = "" then mytitle = "None specified" end if if myworkphone = "" then myworkphone = "None specified" end if if myoffice = "" then myoffice = "None specified" end if set objmessage = Nothing set objonerecip = Nothing |
First this code adds a new message to the Outbox of the user by calling the Add method on the Outbox folder. Then the code adds a new Recipient object to the message. Since the ASP session contains the display name of the current user, this value is passed in as the Name property for the recipient. The code then calls the Resolve method on the Recipient object to make CDO check for ambiguous names in the directory. Once the user is resolved, the AddressEntry object for the user is retrieved using the AddressEntry property of the Recipient object.
From there, the Fields collection of the AddressEntry object is retrieved. The code then uses some MAPI property identifiers to retrieve specific information from the directory. If the information is unavailable in the directory, the code specifies that the value for the variables be "None specified". To make sure that the temporary Message and Recipient objects are released from memory, the code sets both objects to Nothing.
Posting Information in the Helpdesk
Once the user fills in the helpdesk ticket information, such as a problem description, the user clicks the Post Now button on the HTML form. The action of this HTML form sends the user information to another ASP file named posthelp.asp. Posthelp.asp uses the CDO library to post this information to the Helpdesk public folder by creating a new Message object in the folder. The hierarchy for the Message object and its parent collection the Messages collection is shown in Figure 11-13.
Figure 11-13 The Messages collection and Message object in CDO.
The Messages collection is accessed by calling the Messages property on a Folder object. The Messages collection consists of Message objects, which you can manipulate to change items in folders or to create new items. To add a new message to a folder, you use the Add method of the Messages collection—essentially, it adds a new item to the collection. The type of message created depends on which folder you are calling the Add method in. For example, if you call the Add method in your Inbox, CDO will return a new Message object. If you call the Add method in your Calendar folder, CDO will return a new AppointmentItem object.
After adding a new item to the collection, you can set the properties for the item and then call the Send or Update method, depending on the type of item you created. If you used the Add method in your Outbox, you would call the Send method, because e-mail messages are created in the Outbox. In the Helpdesk application, the script calls the Update method because the application does not e-mail new help tickets into the folder but rather posts them into the folder. The following script from posthelp.asp posts the information from the HTML form into the public folder:
set objFolder = Session("HelpdeskFolder") set recursefolder = objFolder 'Add a new message to the public folder Set oMessage = recursefolder.Messages.Add 'Set the message properties oMessage.Subject = Request("Subject") oMessage.Sent = True oMessage.Unread = True oMessage.TimeSent = Now oMessage.TimeReceived = Now oMessage.Type = "IPM.Task.Help Request" oMessage.Importance = Request("Priority") oMessage.Fields.Add "From User", 8, Request.Form("Contact_Email") oMessage.Fields.Add "Description", 8, Request("Description") oMessage.Fields.Add "Problem Type", 8, Request("Type") oMessage.Fields.Add "Product", 8, Request("Product") oMessage.Fields.Add "Phone", 8, Request("Phone") oMessage.Fields.Add "User Location", 8, Request("Location") oMessage.Fields.Add "Flag", 8, "Opened" 'Set the conversation properties oMessage.ConversationTopic = oMessage.Subject oMessage.ConversationIndex = objOMSession.CreateConversationIndex 'Post the message oMessage.Submitted = FALSE oMessage.Update Set oMessage = Nothing |
As you can see in the code, some properties on the new Message object, such as the Sent, Unread, TimeSent, TimeReceived, and Submitted properties, are explicitly set. These properties need to be set because when you post an item into a public folder as the Helpdesk does, the underlying messaging system does not set these properties for you. They must be set before calling the Update method on the Message object for posted items.
The Sent property is a Boolean that determines whether the message has been sent through the system. Since we are posting information directly into the folder, we need to set this property explicitly to True before calling the Update method. The Submitted property is also a Boolean that needs to be set to True before calling the Update method. The Submitted property determines whether the item has been submitted into the messaging subsystem.
The TimeReceived and TimeSent properties contain dates that tell the user when the message was received by the folder and when the user sent the messages. You should set both of these properties to the current date and time before posting the item into the folder. The easiest way to do this is assign them to the value returned by the Now function.
The Unread property is a Boolean that represents whether the current user has read the item. This property is not set for you automatically by CDO when posting an item to a public folder. For this reason, you must set this property to False before posting your item into the public folder.
Now that we have set the required properties to successfully post a message into a public folder, we can use some of the other properties on the Message object to implement the functionality of our application. Notice in the script that the Type property is set to IPM.Task.Help Request. The Type property corresponds to the message class of the item. By setting this property to a custom message class, Outlook and Outlook Web Access users can use a custom form that handles that message class to open up the item in the folder.
The Importance property in the script is set to the importance established by the user in the Priority drop-down list in the HTML form. This property has three possible values: CdoLow (0), CdoNormal (1), and CdoHigh (2). Setting Importance in CDO has the same effect as adding the exclamation point icon or the down arrow icon to an e-mail message in Outlook.
The Subject property is set to whatever the user types in the Problem text box of the helpdesk form. It is rendered as a hyperlink later in the application so that from their web browser, technicians can click on a specific problem and drill down to the specifics about the help ticket and the user who submitted it.
The Fields collection on the Message object is used in the script to add custom fields to the item programmatically—a powerful technique, because any items you create in CDO can use it. These custom properties, or fields, are then accessible from Outlook. Since the Exchange Server database is a semistructured database, you can even change or add new properties to the items in a folder without worrying about breaking a schema. This means that in your application, every item and its properties can hold different data. Your application can dynamically add new properties to items depending on the input of the user.
Semistructured DatabasesExchange Server is a semistructured database, as compared to Microsoft SQL Server, which is completely structured. With SQL Server, you need to define your schema before you can start adding data, and the schema is usually fixed. With Exchange Server, every message can be different. For example, one message might have 0 attachments and another might have 15 attachments. Exchange Server is designed to efficiently handle this varying data.
