How to work with user-defined fields in solutions in Outlook 2002

This article was previously published under Q290656
This article has been archived. It is offered "as is" and will no longer be updated.
For a Microsoft Outlook 98 version of this article, see 185050.
For a Microsoft Outlook 97 version of this article, see 183352.
For a Microsoft Outlook 2000 version of this article, see 201438.
SUMMARY
This article discusses considerations solution developers should take intoaccount when planning, implementing, and deploying a solution usingOutlook custom forms and user-defined fields. Unlike most other database-related software, Outlook can store different sets of user-defined fields in different items in a folder. While this means that itemsin a folder are very flexible "containers" for storing data, it also meansthat developers need to be aware of how this flexibility may impact anOutlook-based solution.

MORE INFORMATION

Overview of Outlook Standard and User-Defined Fields

In a database program such as Microsoft Access, fields are defined at the"table level," meaning that once you add a field to a table of data, thefield will exist in all records in the table. Outlook items are likerecords in a database, and Outlook folders are conceptually equivalent toa table or flat-file database. This database analogy breaks down when youconsider how Outlook and Microsoft Exchange implement the concept offields, or properties.

In Exchange, items in a folder can have any set of fields. It isup to the application to determine the "field schema" for items in afolder. Outlook has separate field schemas for each of the different predefined items such as Contacts, Appointments, Tasks, and such. Each ofthese items has a set of standard fields specific to that type of item.Note that some fields exist in more than one type of item, such as theStart field in Appointments and Journal entries, and some fields exist in all items, like Mileage and Billing Information.

In addition to the standard fields that Outlook makes available for eachtype of item, Outlook allows you to create user-defined, or custom fieldsto store additional information with an item. While these user-definedfields serve the same purpose as the standard fields, you typically usethem in a different manner. The most important difference between standardfields and user-defined fields is that standard fields are always availablewhen working with a particular type of item, but this is not necessarilytrue when working with user-defined fields. User-defined fields can existin:

  • Folders, so that you can use fields in folder-related scenarios such as using the Field Chooser to add custom fields to a table view.
  • Items, so that data can be stored in the fields.
  • Published forms, so that new items you create based on the custom form will "inherit" the user-defined fields.
In most cases, Outlook will replicate user-defined fields between itemsand folders on-the-fly, and this is usually transparent to most users ofOutlook. However, if you are creating a solution, it is usually importantto ensure consistency so that the solution works in all possible scenarios.

This article will discuss Outlook behavior in various circumstances toassist you in understanding where fields exist, how Outlook creates themon-the-fly, and how you can determine where the fields actually are soyou can determine how user-defined fields may be impacting your solution.

Adding User-Defined Fields

When you use the Field Chooser to create a field, either while in a viewor while in design mode of a form, the field will be added to the folder.If you are in form design mode and then drag the field onto the form, thefield will be added to the item and Outlook will automatically create acontrol and bind the field to the control.

If you are in form design mode and right-click a control to access itsproperties, you can create a new user-defined field by clicking the Newbutton on the Value tab of the Properties dialog box. Creating a field inthis manner will result in the new field being added to both the item andthe folder.

Fields can also be introduced into a folder solution by copying or movingan item from another folder into the solution folder. Fields can alsobe introduced if you programmatically create fields on-the-fly or as partof a solution to import items into a folder.

It is important to keep in mind that there are scenarios that can causeuser-defined fields to not exist in one or more of the three locations,and this can adversely affect a solution.

The following table summarizes Outlook behavior when creating newuser-defined fields.

   Action                                             Field added to   ------                                             --------------   Using New button on Field Chooser in a view        Folder   New button on Field Chooser in form design mode    Folder   Dragging field from Field Chooser to form          Item   Using New button in the Properties dialog box      Item and folder   of a control when binding the control to a field				

Deleting User-Defined Fields

Use the following table to determine how to delete a field that exists inthe following locations:

   To delete   field from     Do this   ----------     -------   Folder         Use the Field Chooser and set the list to show                  "User-defined fields in <folder name>."   Item           Use the All Fields tab of the item.   Form           Create a new item based on the existing custom form,                  delete the field using the All Fields tab of the form,                  and republish the form.				

Determining Where Fields Exist

Use the following table to determine where a field exists:

   To verify    fields are in      Do this   -------------      -------   Folder             Use the Field Chooser and set the list to show                      "User-defined fields in <folder name>"   Item               Use the All Fields tab of the item and set the list                      to show "User-defined fields in this item." Note                      that you may want to temporarily display this page                      of the form while you are developing the solution.   Form               Create a new item based on the existing custom form                      and then check the All Fields page of the form as                      above.				

What Can Go Wrong?

Here are some of the symptoms you may see when user-defined fields are not consistent in a folder-based solution.
  • Items become "one-offs" because fields are added to them on-the-fly. Typical symptoms include the size of the items increasing, the Message Class field of an item reverting back to the standard message class for that type of item, and the user receives the enable/disable macro virus warning when opening a one-off item.For additional information about one-off items, please see the following article in the Microsoft Knowledge Base:
    290657 OL2002: Working with Form Definitions and One-Off Forms
  • Specific aspects of the Outlook object model may fail because they are designed to expect fields to exist in a particular location. See the Programming Considerations section of this article for more details.
  • General programming logic problems and errors if your Automation orVBScript code assumes that fields exist in a particular place and theyare not there.

General Suggestions

Avoid Creating Items Until the Solution is Fully Finished.

Ideally, you should create a custom form that contains all of the user-defined fields that you need for the solution. When that is done, you can publish the form to the folder and all items that are created in thefolder will be based on the custom form and therefore inherit the user-defined fields. This scenario ensures that each user-defined field exists in all locations and therefore the solution has consistency.

If you create items for testing your solution as you develop it, youshould delete these items and create new ones if you add user-definedfields into the form.

If you must add fields into a folder solution after you created theitems, consider making sure all of the items get the new fields added tothem. You can do this either programmatically (Item.UserProperties.Add),or by displaying the items in a table view, adding the user-defined fieldto the view, temporarily adding a value into the field so that Outlookadds the field into the item on-the-fly, and then deleting the temporaryvalues.

Importing Items

If you will be importing data into a folder as items, you cannot createthe user-defined fields in the items using the Outlook Import/Exportutility. If you use the utility to import the items, consider creating aprocedure that will programmatically add all of the user-defined fields inthe item. Consider creating a procedure that will programmatically createand import all of the items. For additional information about programmatically importing items, click the article number below to view the article in the Microsoft Knowledge Base:
290658 OL2002: How to Programmatically Import Outlook Items from Access

Fields Added to an Item Only If They Have a Value

Be aware that under various circumstances you can see different behaviordepending on whether or not a field contains a value. For example, if youopen a new contact item and create a new user-defined field on the AllFields page of the form, the field will be added to the folder, but willnot be listed under "User-defined fields in this item" until you enter a value into the field. In other words, in scenarios where the fields exist in a folder but not an item, Outlook will automatically add the field to an item if the field is given a value. This can also commonly happen when entering data into a table view using the "in-cell editing" feature.

Copying or Moving Items

If you copy or move items from one folder to another, the user-definedfields in the items will be moved but the fields will not be associatedwith the new destination folder. Depending on what you are trying toaccomplish you can either make a copy of the entire folder instead ofmoving individual items, or you can use the Field Chooser to redefine theuser-defined fields in the new folder.

Programming Considerations

Find and Restrict Methods

You can use the Find or Restrict method in the Outlook object model to find all items in a folder that match certain criteria. For example, you may want to get all items where the OrderDate (a user-defined field) is sometime this year. For these methods to work the user-definedfield must exist in the folder, not just the items in the folder. You canuse the Field Chooser to create a new field to match the one you areworking with in code. You can also use the AddToFolderFields argument for the UserProperties.Add method to make sure that when you add a field into an item it is also added into the folder set of fields.

Save Items When Changing Field Values

If you write code to change a field value you must save the item via code(Item.Close 0). If you do not save the item, the value will not change and it may give you the impression that the field doesn't exist in the item or cause other unexpected behavior that may seem confusing.

Example Solution

Microsoft provides programming examples for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability and/or fitness for a particular purpose. This article assumes that you are familiar with the programming language being demonstrated and the tools used to create and debug procedures. Microsoft support professionals can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific needs.
If you have limited programming experience, you may want to contact a Microsoft Certified Partner or Microsoft Advisory Services. For more information, visit these Microsoft Web sites:

Microsoft Certified Partners - https://partner.microsoft.com/global/30000104

Microsoft Advisory Services - http://support.microsoft.com/gp/advisoryservice

For more information about the support options that are available and about how to contact Microsoft, visit the following Microsoft Web site:http://support.microsoft.com/default.aspx?scid=fh;EN-US;CNTACTMSThe following is a lengthy series of steps that creates a sample folder-based solution. The scenario is that you work at a veterinary hospital and want to keep track of customers and the pets they own. To do this, create a new Customers subfolder in your default Contacts folder.

Create a Folder for the Contacts

  1. Select the Contacts folder.
  2. Right-click the Contacts folder and on the shortcut menu, click New Folder. In the Name box type, Customers and in the Folder Contains List, click to select Contact Items. Click OK.

Create and Publish a Simple Custom Contact Form

The initial form will keep track of the customer's pet names and types.
  1. Select the new Customers folder and open a new Contact form.
  2. On the Tools menu, point to Form, and click Design This Form.
  3. Click the (P.2) tab of the form. The Field Chooser displays automatically since this form page is modifiable.
  4. On the Field Chooser, click New. In the Name box, type Pet Type and click OK, leaving the Type and Format as Text.
  5. On the Field Chooser, click New again. In the Name box, type Pet Name and click OK, again leaving the Type and Format as Text.
  6. Drag both fields to the (P.2) tab of the form. The page automatically is unhidden when controls are added to the page.
  7. On the Form menu, click Rename Page, type Pet Info, and click OK.
  8. On the Tools menu, point to Forms, and click Publish Form As. In the Form Name box, type Customer. In the Display Name box, type Pet Information. Verify the form is set to be published in the Customers folder, and click Publish.
  9. Close the item and don't save changes.
  10. Right-click the Customers folder and click Properties. In "When posting to this folder," click to select the Pet Information form and click OK. It is now the default form for the folder.
In the previous steps, when the Field Chooser created the two new fields,they were only added to the folder. When the fields were dragged from theField Chooser to the form, Outlook then propagated the fields to the item.Since the item was published as a form, the fields also now exist in thepublished form.

There are no existing items in the folder because we just createdit; we now have the fields existing in the folder and in the form. Becauseall new items will be based on the published form, all items will alsohave the two user-defined fields. This is an ideal scenario, because theuser-defined fields will now exist in every possible location when working in this folder.

Set the View for the Folder

The following steps will set up a table view and add fields to theview so that it's easier to monitor Outlook field behavior.

  1. Change the folder view to Phone List.
  2. Drag all the fields off the column heading except the Icon, Attachments, and FileAs fields.
  3. Right-click the File As column heading, and click Field Chooser.
  4. Set the list at the top of the Field Chooser to show "User-defined fields in folder." Drag the Pet name and Pet Type fields to the top of the column headings to add them to the view.
  5. Set the list at the top of the Field Chooser to show All Contact Fields. Drag the Message Class and Size fields to the column headings to add them to the view.

    NOTE: These two fields are being added for illustrative purposes. Itis often advisable to display these fields when developing a folder solution.
  6. Close the Field Chooser and adjust the width of your columns as needed.
  7. Right-click below the column headings, and click Other Settings. In the Rows section, make sure Allow In-cell Editing is enabled, and click OK.

Create Two Contact Items for Customers

  1. On the File menu, point to New and click Contact.
  2. Type Alan Adams as the Full Name, then click the Pet Info page and type Fido for the Pet Name and Dog for the Pet Type. Click Save and Close.
  3. On the File menu, point to New and click Contact.
  4. Type Bob Barry as the Full Name, then click the Pet Info page and type Kit for the Pet Name and Cat for the Pet Type. Click Save and Close.
At this point the two user-defined fields are in the published form, inthe folder, and in the two items that were just created in the folder.

Add an Additional Field to the Published Form

Add an additional field to track whether or not each pet has been neutered.
  1. On the File menu, point to New and click Contact to open a new contact item based on the custom form.
  2. On the Tools menu, point to Forms, and click Design This Form.
  3. Click the Pet Info page. The Field Chooser displays automatically.
  4. In the Field Chooser, click New, and type Neutered as the name of the new field. Click to select Yes/No in the Type list, leave the Format as Icon, and click OK.
  5. Drag the new field from the Field Chooser to the form page. Outlook automatically creates a check box control for the Yes/No field.
  6. On the Tools menu, point to Forms, and click Publish Form. Select Pet Information in the item list to populate the Display Name and Form Name boxes, and click Publish.
  7. Close the item and don't save changes.
At this point the Neutered field exists in the folder and in the publishedform. Even though the two existing items created earlier were neverdirectly exposed to the Neutered field, they are linked to the publishedform definition, so the Neutered field is treated as if it actually existsin the item. To verify this, open the contact item for Alan Adams. Clickthe All Fields page of the form and then set the list to show"User-defined fields in this item." Note that all three user-defined fields are listed as being in the item and then close the item.

Note that in the Phone List view the two items do not have a box next tothem. This indicates that the fields are not actually in the item but arecoming from the published form. This visual discrepancy may make it appearas though the fields are not part of the item, and while technically theyare not, for practical purposes they are available.

Add an Additional Field to the Folder

Now you will add an additional field for the neutering date but not usethe published form to do so.

  1. Right-click the File As column heading, and click Field Chooser.
  2. Click New in the Field Chooser and type Neuter Date as the name of the new field, select Date/Time in the Type list, and select "MM/dd/yy" as the Format. Click OK.
  3. Drag the Neuter Date field into the view column header, and close the Field Chooser.
The field is added to the folder, but does not exist in the published formor in either of the two items in the folder.

Create a Third Contact Item

  1. On the File menu, point to New and click Contact to open a new contact item based on the custom form.
  2. Enter Ozzie OneOff as the Full Name, click the Pet Info page and enter Otto for the Pet Name and Ostrich for the Pet Type. Leave the Neutered check box cleared.
  3. Click Save and Close.
Now set a value for the Neuter Date in this new item. In the Neuter Datecolumn, click in the cell labeled None in the Ozzie OneOff row, and type a date. After you type the date, press TAB to have Outlook store the value in the field. Because you typed a value in the field in the table view and the field didn't actually exist in the item, Outlook added the field to the item on-the-fly. This created a one-off item since the formdefinition of this item doesn't match that of the published form. Noticethe size of the item increased and that the Message Class field reverted to IPM.Contact. This is no longer linked to the published form in the folder. Every time it is opened, it will use the internal form definition and ignore the published form.

NOTE: The item can be relinked to the published form by programmatically changing the Message Class back to IPM.Contact.Customer, but the size of the item will not be reduced. For additional information about the Message Class field and how to change it, click the article number below to view the article in the Microsoft Knowledge Base:
290659 OL2002: How to Update Existing Items to Use a New Custom Form
Now assume you wish to copy the contacts into an Exchange publicfolder to share them, but instead of making a copy of the folder you wantto create a new folder and drag the contacts into it. In these steps we'lluse a standard folder instead of an actual public folder.

Create a Folder for the Contacts

  1. Select the Contacts folder.
  2. Right-click the Contacts folder and on the shortcut menu, click New Folder. In the Name box type, Customers2 and in the Folder Contains list, click to select Contact Items. Click OK.
  3. Click one of the contacts in the Customers folder to select it.
  4. Press CTRL+A to select the three contacts in the folder.
  5. On the Edit menu, click Copy To Folder, select the Customers2 folder, and then click OK.
Click the Customers2 folder. The three contacts are now copied into thisfolder, but the user-defined fields are not defined in the folder.

Create a Programming Example

Use the following VB or VB Automation code to retrieve thosepet owners who have dogs. Be sure to reference the Outlook object libraryfirst.

Sub GetDogOwners()   Set ol = New Outlook.Application   Set olns = ol.GetNamespace("MAPI")   Set ContactFolder = olns.GetDefaultFolder(olFolderContacts)   Set MyFolder = ContactFolder.Folders("Customers2")   Set Customers = MyFolder.Items   Set DogCustomers = Customers.Restrict("[Pet Type] = 'Dog'")End Sub				

You will receive a run-time error:

The property Pet Type is unknown.
Now go back to the Customers2 folder and display the Field Chooser. Createa new field named Pet Type. Leave the Type and Format set as Text. This will add Pet Type as a user-defined field to the set of fields available for the folder. If you try the above code again, it does not return an error.
REFERENCES
For additional information about available resources and answersto commonly asked questions about Microsoft Outlook solutions, click the article number below to view the article in the Microsoft Knowledge Base:
287530 OL2002: Questions About Custom Forms and Outlook Solutions
OutSol OutSol2002
Properties

Article ID: 290656 - Last Review: 12/06/2015 00:53:06 - Revision: 3.5

Microsoft Outlook 2002 Standard Edition

  • kbnosurvey kbarchive kbforms kbprogramming kbhowto KB290656
Feedback