OL98: Working With User-defined Fields in Solutions

ID: Q185050

The information in this article applies to:

Microsoft Outlook 98

SUMMARY

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. Unlike most other database- related software, Microsoft Outlook 98 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 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

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 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, 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. 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 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 &lt;folder name&gt;."

   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 &lt;folder name&gt;."

   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 more information about one-off items, please see the following article in the Microsoft Knowledge Base:
Q181266 OL98: 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.

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:
Q180981 OL98: 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 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. 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 the Microsoft fee-based consulting line at (800) 936-5200. For more information about the support options available from Microsoft, please see the following page on the World Wide Web:

http://www.microsoft.com/support/supportnet/refguide/

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 folder under your existing, default Contacts folder.

Create a Folder for the Contacts

Select the Contacts folder.

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.

Select the new Customers folder and open a new Contact form.

On the Tools menu, point to Form, and click Design This Form.

Click the (P.2) tab of the form. The Field Chooser displays automatically since this form page is modifiable.

On the Field Chooser, click New. In the Name box, type Pet Type and click OK, leaving the Type and Format as Text.

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.

Drag both fields to the (P.2) tab of the form. The page automatically is unhidden when controls are added to the page.

On the Form menu, click Rename Page, type Pet Info, and click OK.

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.

Close the item and don't save changes.

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.

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 add fields to the view so that it's easier to monitor Outlook field behavior.

Change the folder view to Phone List.

Drag all the fields off the column heading except the Icon, Attachments and FileAs fields.

Right-click the File As column heading, and click Field Chooser.

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.

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.

Close the Field Chooser and adjust the width of your columns as needed.

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

On the File menu, point to New and click Contact.

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.

On the File menu, point to New and click Contact.

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.

On the File menu, point to New and click Contact to open a new contact item based on the custom form.

On the Tools menu, point to Forms, and click Design This Form.

Click the Pet Info page. The Field Chooser displays automatically.

In the Field Chooser, click New, and type Neutered as the name of the new field. Select Yes/No in the Type list, leave the Format as Icon, and click OK.

Drag the new field from the Field Chooser to the form page. Outlook automatically creates a check box control for the Yes/No field.

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.

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.

Right-click the File As column heading, and click Field Chooser.

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 as the Format "MM/dd/yy." Click OK.

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

On the File menu, point to New and click Contact to open a new contact item based on the custom form.

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 unselected.

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:

Q182274 OL98: How to Update Existing Items to Use a New Custom Form

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 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

Select the Contacts folder.

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.

Click one of the contacts in the Customers folder to select it.

Press CTRL+A to select the 3 Contacts in the folder.

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:

The property Pet Type is unknown.

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.

REFERENCES

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

Q180826 OL98: Resources for Custom Forms and Programming

Q182349 OL98: Questions About Custom Forms and Outlook Solutions

Q181266 OL98: Working with Form Definitions and One-Off Forms

Additional query words: OutSol OutSol98 98

Keywords : FmsProb PgmHowto
Version : WINDOWS:98
Platform : WINDOWS
Issue type : kbhowto