How to work with user-defined fields in solutions in Outlook 2000 (201438)

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, 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. This database analogy breaks down when you consider how Outlook and Microsoft Exchange implement the concept of fields, or properties.

In 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 predefined 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, such as 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 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 be added to the 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 folder. Fields 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 following table summarizes Outlook behavior when creating new user-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 in the 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:

  207896 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

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 the folder 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, 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 you created the 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.

Importing 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 additional information about programmatically importing items, 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. 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. 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. This includes, but is not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and with the tools that are used to create and to debug procedures. Microsoft support engineers 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 requirements. 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 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 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.

There are no existing items in the folder because we just created it; we now have the fields existing in the folder and in the form. Because 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, because 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 add 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. 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. It is 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, 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. 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 published form. Even though the two existing items 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 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 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 add an additional field for the neutering date but not use the 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 form or 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 Date column, 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 form definition of this item doesn't match that of the published form. Notice the 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 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 an Exchange public folder to share them, but instead of making a copy of the folder you want 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 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 this folder, 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 those pet owners who have dogs. Be sure to reference the Outlook object library first.

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: Now go back to the Customers2 folder and display the Field Chooser. Create a 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.