The Outlook Object Model

The Outlook object model is a collection of objects that lets you work with Outlook components in VBA code. There are two ways you can get information about the Outlook object model: through the object model diagram in Help and through the Object Browser.

Viewing the Outlook Object Model Diagram

Curiously, it is much more difficult to view the Outlook object model than the Word object model—you won’t find it by searching on “object model” in Help, as with Word. To locate the diagram in Office 2000, follow these steps:

1. Open Help from the main Outlook window, and click on the Contents page.

2. Select the Advanced Customization book.

3. Select the Microsoft Outlook Visual Basic Reference book.

4. Select the Microsoft Outlook Objects topic.

For Office XP, follow these steps:

1. Open Help from the main Outlook window, and click on the Contents page.

2. Select the Forms and Programming Information book.

3. Select the Outlook VBA Language Reference book.

4. Select the Microsoft Outlook Visual Basic Reference book.

5. Select the Microsoft Outlook Object Model topic.

For Office 2003, follow these steps:

1. Open Help from the main Outlook window, and click the Table of Contents link.

2. Select the Microsoft Outlook Visual Basic Reference book.

3. Select the Microsoft Outlook Object Model topic.

The object model diagram is shown in Figure 12.2.

Figure 12.2

You won’t see familiar Outlook items such as contacts, tasks, or appointments in the object model, and you will see strange objects such as the NameSpace object and the Explorers and Inspectors collections.

However, you can work with Outlook items in VBA code—you just need to know how to get at them, by working down the branches of the object model, as described in the next section.

In addition to the object model diagram in Help, you can also use the Object Browser (opened by F2 in the Visual Basic window). Select Outlook in the unlabeled Libraries selector, and then select the Outlook component you want to examine in the Classes list. Its properties, methods, and events are displayed in the Members list, as shown for the AppointmentItem object in Figure 12.3.

Figure 12.3

More than other Office components, the names of Outlook fields (properties) are often significantly different from the field names that appear in the Outlook interface, for example in the Field Chooser. Additionally, there are some highly useful properties that don’t appear in the Field Chooser at all; you can only work with them in Visual Basic for Applications (VBA) or Visual Basic Script (VBS) code. To avoid confusion, in this chapter, I will use the term field for properties of objects (and other Outlook components) as they appear in the interface, and property when working in VBA code.

Important

Since Office 2000, Outlook uses two dialects of Visual Basic: VBS for code behind forms, and VBAfor application-wide programming.

The Outlook Field Chooser is shown in Figure 12.4.

Figure 12.4

If you examine the fields shown on the first page of the Frequently-used fields section of the Field Chooser and try to locate their corresponding properties in the Object Browser, you may not find them—at least not under the same names. There are two problems: (1) Different names for fields and their corresponding properties, and (2) some selections in the Field Chooser don’t represent properties at all, but collections (Attachment represents the Attachments collection, and Contacts represents the Links collection). The table below shows how the fields shown in Figure 12.4 match up to property names.

Field Name	Property or Collection Name
Assistant’s Phone	AssistantTelephoneNumber
Attachment	Attachments (collection)
Business Address	BusinessAddress
Business Fax	BusinessFaxNumber
Business Home Page	BusinessHomePage
Business Phone	BusinessTelephoneNumber
Business Phone 2	Business2TelephoneNumber
Callback	CallbackTelephoneNumber
Car Phone	CarTelephoneNumber
Categories	Categories (an enumerated property)
Company	CompanyName
Company Main Phone	CompanyMainTelephoneNumber
Contacts	Links (collection)

For a full listing of Outlook ContactItem fields and their corresponding properties, see my white paper on Outlook Fields and Properties, which can be downloaded from the Downloads page of my Web site, www.helenfeddema.com.

The Basic Automation Commands

To initiate an Automation session for working with Outlook, you need to create an Automation object representing the Outlook Application object, which is at the top of the Outlook object model. This can be done with either the CreateObject or GetObject function. CreateObject creates a new instance of Outlook, while GetObject uses an existing instance of Outlook. To avoid creating extra Outlook instances, I like to use the GetObject function initially, with a fallback to CreateObject in a procedure’s error handler, so that an existing instance of Outlook will be used, if there is one, and a new instance will be created if it is needed.

While you can use the GetObject function to create an instance of (say) an Outlook folder, I find it more useful to create a Outlook application object that can then be used for all Automation work with Outlook, since most Automation code needs to work with properties and methods of the Application object itself, and the NameSpace object on the next level down, as well as with the properties and methods of lower-level objects such as the MAPIFolder and ContactItem objects. The syntax for setting a reference to an existing instance of Outlook, using the GetObject function, is:

 Set gappOutlook = GetObject(, "Outlook.Application") 

If this line of code fails (because Outlook is not running), error 429 occurs, and the following error handler then runs a line of code using the CreateObject function to create a new instance of Outlook and resumes running the code after the GetObject line.

 If Err.Number = 429 Then    ‘Outlook is not running; open Outlook with CreateObject.    Set gappOutlook = CreateObject("Outlook.Application")    Resume Next Else    MsgBox "Error No: " & Err.Number & "; Description: "    Resume ErrorHandlerExit End If 

Using the gappOutlook variable, you can access any of the objects in the Outlook object model to work with folders and items of various types. The code samples in the “Exporting Data from Access to Outlook Items” and “Importing Data from Outlook Items to Access” sections in this chapter (and the Outlook Data Exchange sample database) all use the gappOutlook variable as the starting point for working with various components of the Outlook object model.

Unlike Word, Outlook has no macro recorder, so unfortunately, you can’t record a macro to get a shortcut to the syntax needed for various Outlook actions.

NameSpaces and Other Oddly Named Objects

If you are unfamiliar with the Outlook object model, you will probably be puzzled at the names of its major objects, which don’t correspond to what you see in the interface. The strangest ones are the NameSpace object, which represents the data stored in Outlook folders; the Inspector object, representing the window in which an Outlook item (such as a contact or mail message) is displayed; and the Explorer object, representing a pane in which the contents of a folder are displayed, such as the Tasks folder (when you open Outlook in the interface, you are looking at an Explorer).

These three high-level objects, in addition to the Application object itself, are used to get at the other Outlook components you need to work with, such as folders and items. To work with a folder, for example, you must first set a reference to the Outlook Application object, then the NameSpace object, and then you can retrieve one of the default local folders using the GetDefaultFolder method, or a custom folder by referencing it as a member of the top-level Folders collection, or some folder underneath that folder (note that the singular of Folders in VBA code is not Folder, as you would expect, but MAPIFolder).

Syntax for Referencing Outlook Objects

The following code segments show how to set a reference to various types of Outlook folders and items, in different situations, as described in comments in the following code. The appOutlook variable would only be needed if you haven’t declared a global gappOutlook variable in the Declarations section of a standard module, which is the technique I use in the sample databases for this chapter.

    Dim appOutlook As Outlook.Application    Dim nms As Outlook.NameSpace    Dim flds As Outlook.Folders    Dim fld As Outlook.MAPIFolder    Dim exp As Outlook.Explorer    Dim ins As Outlook.Inspector 

Declare this variable as Object so it can be used for any type of item. This is useful when iterating through a folder that may contain several different sorts of items (such as a contacts folder containing both contact items and distribution lists).

    Dim itm As Object 

Declare these variables as specific item types.

    Dim msg As Outlook.MailItem    Dim con As Outlook.ContactItem    Set nms = gappOutlook.GetNamespace("MAPI")    Set flds = nms.Folders("Personal Folders").Folders 

Set a reference to the default local Contacts folder.

    Set fld = nms.GetDefaultFolder(olFolderContacts) 

Set a reference to a folder called Custom Contacts under the top-level Personal Folders folder’s Folders collection (via the previously set flds variable).

    Set fld = flds("Custom Contacts") 

Set a reference to a custom public folder.

    Set flds = nms.Folders("Public Folders").Folders    Set fld = flds("All Public Folders").Folders("Custom Folder") 

Set a reference to the currently open folder, via the active Explorer.

    Set exp = gappOutlook.ActiveExplorer    Set fld = exp.CurrentFolder 

Test whether the current folder is a Contacts folder.

    If fld.DefaultItemType <> olContactItem Then       MsgBox "This folder is not a Contacts folder; canceling"       GoTo ErrorHandlerExit    End If 

Set a reference to the currently open item, via the active Inspector.

    Set ins = gappOutlook.ActiveInspector    Set itm = ins.CurrentItem 

Test whether the open item is a mail message and set a mail message variable to it if so; this allows you to use IntelliSense to select specific MailItem properties.

    If itm.Class = olMail Then       Set msg = itm    End If 

Set a reference to the contact whose name is “Helen Feddema.”

    Set fld = nms.GetDefaultFolder(olFolderContacts)    Set con = fld.Items("Helen Feddema") 

Set a reference to a built-in Outlook item property.

 strFullName = con.FullName 

Set a reference to a custom Outlook item property.

 blnCustomer = con.UserProperties("Customer") 

Referencing Outlook Items in the Interface and in Code

Microsoft has chosen to use the word “Note” to reference different item types (a mail message’s message class and a Note in the interface), and to give items confusingly different names in code than they have in the user interface (a Journal item has a message class of Activity). Here is a table that will help you find the correct syntax for referencing an object in different situations.

Interface Name	Object Model Name	Message Class
Contact	ContactItem	IPM.Contact
Task	TaskItem	IPM.Task
Mail Message	MailItem	IPM.Note
Appointment	AppointmentItem	IPM.Appointment
Journal Entry	JournalItem	IPM.Activity
Note	NoteItem	IPM.StickyNote

Additionally, there are named constants (listed in the table below) that reference the standard Outlook items, which can be used as arguments for various methods in VBA code.

Interface Name	OlItemType Enum	OlObjectClass Enum
Contact	olContactItem	olContact
Task	olTaskItem	olTask
Mail Message	olMailItem	olMail
Appointment	olAppointmentItem	olAppointment
Journal Entry	olJournalItem	olJournal
Note	olNoteItem	olNote

Constants from the OlItemType enum are used in determining what type of item you are dealing with. Those in the OlObjectClassEnum (a much larger group) are used in determining what type of object you are dealing with. For example, if you wanted to determine whether an item in a folder is a mail message, you would check whether its Class property is olMail. To determine whether a folder is a Contacts folder, you would check whether the value of its Class property is olContact. The OlItemType constants are used to create new items of specific types, using the Application object’s CreateItem method.

The Outlook-Exchange Wizard

Access has a way to import from Outlook items or set up linked tables. If you select File|Get External Data|Import, and select the Outlook() or Exchange() selection in the Files of type selector, then select a profile, the Import Exchange/Outlook Wizard opens, as shown in Figure 12.5.

Figure 12.5

However, if you proceed through the steps of this Wizard, you will end up with a table that may not be very useful. Here is what you will get for the main Outlook item types:

• Contacts. A limited selection of standard fields is imported; it may be sufficient for many purposes.

• Tasks. You get the correct number of records, but Subject, Start Date, Due Date, and in fact all fields for which a table field is created, are blank. This is no use at all.

• Appointments. The table has Subject and Notes, but omits Start Time and End Time. This is not much use.

• Mail messages. The table has Subject, To, and Body. It omits attachments, except for noting that the message has one. This may be useful, if you don’t care about attachments.

See the tables in the Outlook Data Exchange database with the otbl tag for examples of what you get when you use this Wizard. Because of its inadequacies, you will do better to write VBA code to import data from Outlook, as described in the “Importing Data from Outlook Items to Access” section of this chapter.