OL97: Working With User-defined Fields in Solutions

Unlike most other database-related software packages, Microsoft Outlook 97 can store different sets of user-defined fields in different items in a folder. While this means that items in a folder are very flexible "containers" for storing data, it also means that developers need to be aware of how this flexibility may impact an Outlook-based solution. This article discusses considerations solution developers should take into account when planning, implementing, and deploying, a solution using Outlook custom forms and user-defined fields.

This article contains the following topics:

• Overview of Outlook Standard and User-Defined Fields
• Adding User-Defined Fields
• Deleting User-Defined Fields
• Determining Where Fields Exist
• What Can Go Wrong?
• General Suggestions
• Programming Considerations
• Example Solution

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, the field will exist in all records in the table. Outlook items are like records in a database, and Outlook folders are conceptually equivalent to a table or flat-file database. But this database analogy breaks down when you consider how Outlook and Microsoft Exchange implement the concept of fields, or properties.

In Microsoft Exchange, items in a folder can have any set of fields. It is up to the application to determine the "field schema" for items in a folder. Outlook has separate field schemas for each of the different pre- defined items such as Contacts, Appointments, Tasks, and such. Each of these 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, like the Start 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 each type of item, Outlook allows you to create user-defined, or custom fields to store additional information with an item. While these user-defined fields serve the same purpose as the standard fields, you typically use them in a different manner. The most important difference between standard fields and user-defined fields is that standard fields are always available when working with a particular type of item, but this is not necessarily true when working with user-defined fields. User-defined fields can exist in:

• 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 items and folders on-the-fly, and this is usually transparent to most users of Outlook. However, if you are creating a solution it is usually important to ensure consistency so that the solution works in all possible scenarios. This article will discuss Outlook behavior in various circumstances to assist you in understanding where fields exist, how Outlook creates them on- the-fly, and how you can determine where the fields actually are so that you 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 view or 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, the field will then be added to item and Outlook will automatically create a control and bind the field to the control.

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

Fields can also be introduced into a folder solution by copying or moving an item from another folder into the solution's folder. Or, they can also be introduced if you programmatically create fields on-the-fly or as part of a solution to import items into a folder.

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

The follow table summarizes Outlook behavior when creating new user-defined fields:

Deleting User-Defined Fields

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

Determining Where Fields Exist

Use the following table to determine where a field exists:

What Can Go Wrong?

Here are some of the symptoms you can experience 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 items 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 more information about one-off items, please see the following article in the Microsoft Knowledge Base:
  176567  (http://support.microsoft.com/kb/176567/EN-US/ ) OL97: 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 or VBScript code assumes that fields exist in a particular place and they are not there.

General Suggestions

• Try to 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. Then you would publish the form into the folder and then all items that are created in the folder would 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, you should delete these items and create new ones if you add user-defined fields into the form.

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

• When you import items

If you will be importing data into a folder as items, you cannot create the user-defined fields in the items using the Outlook import/export utility. If you use the utility to import the items, consider creating a procedure that will programmatically add all of the user-defined fields in the item. Consider creating a procedure that will programmatically create and import all of the items.

For more information about programmatically adding fields to an item, please see the following article in the Microsoft Knowledge Base:

• Fields added to an item only if they have a value

Be aware that under various circumstances you can see different behavior depending on whether or not a field contains a value. For example, if you open a new contact item and create a new user-defined field on the All Fields page of the form, the field will be added to the folder, but will not 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-defined fields in the items will be moved, but the fields will not be associated with the new destination folder. Depending on what you are trying to accomplish, you can either make a copy of the entire folder instead of moving individual items, or you can use the Field Chooser to redefine the user-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. In order for these methods to work the user-defined field must exist in the folder, not just the items in the folder. You can use the Field Chooser to create a new field to match the one you are working with in code. Or you can 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 the Microsoft fee-based consulting line at (800) 936-5200. For more information about Microsoft Certified Partners, please visit the following Microsoft Web site: For more information about the support options that are available and about how to contact Microsoft, visit the following Microsoft Web site: The 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 have. To do this, create a new Customers folder under your existing, 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 Create Subfolder. 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, click Design Outlook Form.
3. Click the (P.2) tab of the form. The Field Chooser should be displayed 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. Note the page is automatically unhidden since controls have been added to the page.
7. On the Form menu, click Rename Page and rename the page "Pet Info".
8. On the Tools menu, click Design Outlook Form to switch out of design mode.
9. On the File menu, click Publish Form As. In the Form Name box, type Customer. Verify the form is set to be published in the Customers folder, and click Publish.
10. Close the item and don't save changes.
11. Right-click the Customers folder and click Properties. In "When posting to this folder, use", click to select the Customer 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 the Field 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 the published form.

Because there are no existing items in the folder, since we just created it, we now have the fields existing in the folder and in the form. Since all new items will be based on the published form, all items will also have the two user-defined fields. This is an ideal scenario, since the user- 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 adds some fields to the view 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. On the View menu, 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. Have the Field Chooser display 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, and it is often advisable to display these fields when developing a folder solution.
6. Adjust the width of the columns as necessary.
7. On the View menu, click Format View. In the Rows box, make sure that Allow In-cell Editing is enabled, and click OK.

Create Two Contact Items for Customers

1. Click the first toolbar button to open a new contact.
2. Type Alan Adams as the name, then click the Pet Info page and type Fido for the pet name and "Dog" for the pet type. Save and Close the item.
3. Click the first toolbar button to open a new contact.
4. Type Bob Barry as the name, then click the Pet Info page and type Kit for the pet name and "Cat" for the pet type. Save and Close the item.

At this point the two user-defined fields are in the published form, in the 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. Click the first toolbar button to open a new contact item based on the custom form.
2. On the Tools menu, click Design Outlook Form.
3. Click the Pet Info page and the Field Chooser should be displayed.
4. In the Field Chooser, click New... and type Neutered for the name of the new field. Set the Type to Yes/No, leave the Format as Icon, and then click OK.
5. Drag the new field from the Field Chooser to the form page. Outlook will automatically create a check box control for the Yes/No field.
6. On the File menu, click Publish Form As. Use the default settings 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 published form. Even though the two existing items that were created earlier were never directly exposed to the Neutered field, they are linked to the published form definition so the Neutered field is treated as if it actually exists in the item. To verify this, open the contact item for Alan Adams. Click the All Fields page of the form and then set the list to show "User-defined fields in item." Note that all three user-defined fields are listed as being in the item and then close the item.

Note that in the view the two items do not have a box next to them. This indicates that the fields are not actually in the item but are coming from the published form. This visual discrepancy may make it appear as though the fields are not part of the item and while technically they are not, for practical purposes they are available.

Add an Additional Field to the Folder

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

1. Make sure the Field Chooser is displayed in the table view.
2. Click New... in the Field Chooser and type Neuter Date for the name of the new field, set the Type to Date/Time, and set the Format as MM/DD/YY. Click OK.
3. Drag the Neuter Date field into the view column header.

The field has now been added to the folder, but does not exist in the published form or in either of the two items in the folder.

Create a Third Contact Item

1. Click the first toolbar button to create a new item.
2. Enter "Ozzie OneOff" as the name, then click the Pet Info page and enter "Otto" for the pet name and "Ostrich" for the pet type. Leave the Neutered check box unselected.
3. Close and save the item.

Now set a value for the Neuter Date in this new item. In the Neutered column, click in the blank area for Ozzie OneOff and enter a date. After the date is entered, press TAB to have Outlook store the value in the field. Because a value was entered 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 form definition of this item doesn't match that of the published form. Notice the size of the item has increased and that the Message Class field has reverted to IPM.Contact. This is now 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 more information about the Message Class field and how to change it, please see the following article in the Microsoft Knowledge Base: Now assume you wish to copy the contacts into a Microsoft Exchange public folder to share them, but instead of making a copy of the folder you decide to create a new folder and drag the contacts into it. In these steps we'll use a standard folder instead of an actual public folder.

Create a new folder for the Contacts

1. Right-click the Contacts folder and on the shortut menu, click Create Subfolder.
2. Set the name of the folder to Customers2, make sure the folder is set to contain contacts, and click OK.
3. In the Customers folder, click one of the contacts to select it.
4. Press CTRL+A to select the 3 contacts in the folder.
5. On the Edit menu, click Copy To Folder, select the Customers2 folder, and then click OK.

The three contacts are now copied into the second folder, but the user- defined fields are not defined in the folder.

Set up a Programming Example

Now try to use the following VB or VBA automation code to retrieve those pet owners who have dogs. Make sure to reference the Outlook object library first. You will receive a run-time error: Now go back to the Customers2 folder and display the Field Chooser. Create a new field called "Pet Type" of type text. This will add this user-defined field to the set of fields available for the folder. If you then try the above code again, it will work and not return an error.

For more information about creating solutions with Microsoft Outlook 97, please see the following articles in the Microsoft Knowledge Base: