Microsoft KB Archive/176567

= OL97: Working with Form Definitions and One-Off Forms =

Article ID: 176567

Article Last Modified on 1/22/2007

-

APPLIES TO


 * Microsoft Outlook 97 Standard Edition

-



This article was previously published under Q176567



SUMMARY
This article discusses how custom forms are implemented in Microsoft Outlook 97 and provides suggestions for addressing unexpected symptoms you may experience when creating a solution based on Outlook 97 forms.

The following topics are covered in this article:
 * A "Typical" Custom Forms Solution
 * One-Off Forms
 * Standard Ways Forms Become One-Offs
 * Items One-Offed Unexpectedly
 * Additional Notes



MORE INFORMATION
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:

https://partner.microsoft.com/global/30000104

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

This article assumes a general working knowledge of Outlook 97 custom forms. For information on getting started with customizing Outlook, refer to the Microsoft Knowledge Base articles listed in the References section of this article.

NOTE: There is a distinction between the terms "items" and "forms." An item refers to a "record" of information (a group of fields) in a folder. A form is basically a "front end" for the item and does not typically contain any data. Instead, it is published in a folder or forms library for use with items in the folder.

When creating custom form solutions with Outlook 97, it is important to be able to recognize how Outlook is using your custom form in relation to the items in a folder.

A "Typical" Custom Forms Solution
If you want to create a custom contact form to replace the default Outlook contact form, you would typically follow these steps:


 * 1) Start with a new, default Contact item to use as the basis for your custom form.
 * 2) Customize the form to suit your needs.
 * 3) Publish the form to the Contacts folder.
 * 4) Set the form as the default form for the Contacts folder by changing the folder properties.

Each Outlook item has a standard Message Class field to keep track of which form should be used to display the item. The default message class for a contact is IPM.Contact, and when the form is published, the message class is changed to reflect the name of the published form. So in the previous steps, if the form was called MyForm when it was published, it would have a message class of IPM.Contact.MyForm. When you create a new item based on the published form, the Message Class field of the item is set to IPM.Contact.MyForm.

For more information about working with Message Classes, please see the following article in the Microsoft Knowledge Base:

170301 OL97: How to Update Existing Items to Use a New Custom Form

One-Off Forms
In the typical scenario above, information about the form (the "form definition") is not saved with each item. The form is basically "linked" using the Message Class field. The size of a typical item may be 300 or 500 bytes.

NOTE: For purposes of simplicity, this article will use the term "linked form" to indicate a situation in which the form definition is not saved within an item and the Message Class field is set to use a custom form. However, it is possible to have the form definition saved with an item. Items that have a custom form definition stored within them are referred to as being "one-offed" or "a one-off."

When a form is one-offed, it will use the form definition that is stored with the item instead of the published form. If a form definition is saved with an item, the item's Message Class is changed back to the default message class for that form type, such as IPM.Contact.

Standard Ways Forms Become One-Offs
Forms become one-offs:
 * By default. Mail message forms are one-offs by default due to the nature of the item. If you open a default mail item, enter design mode, and click the Properties page of the form, you will see the "Save form definition with item" check box is automatically selected. This is not the case with other types of forms, but is by design for mail forms since these forms are routed to other individuals. If the form definition was not saved with the item, the item would not display properly when it is received, because the form would most likely be unavailable (unless it was published in the Organizational Forms Library on the Microsoft Exchange Server, making it available to everyone in the enterprise).
 * By design. When designing a custom form that is not a mail message form, you can select the "Save form definition with item" check box yourself. This would typically be undesirable, but may be desirable under certain circumstances.

Items One-Offed Unexpectedly
Assume you have a linked forms scenario and you have 10 items already created that are using your published custom form. If you open one of the items, and the form definition is somehow changed for that one particular item, Outlook will automatically one-off the item (create a one-off form) and save the form definition with the item. The Message Class field will change back to the default message class for that type of item, and the size of the item will noticeably increase.

Following are known scenarios where items can be unexpectedly one-offed.  You are in a typical linked forms scenario, open an existing item in a folder, make changes to the form in design mode, and save or send the item.

If you want to change the form for all of the items in the folder, instead of opening an existing item, follow these steps:

 Open a new item based on your custom form. Makes form design changes to that item. Using that item, republish the form with the same name. Close and do not save changes to the item.

All of the items in the folder will now use the updated custom form the next time the items are opened, because the Message Class still refers to the published form. The first time an item is opened after the form is changed, Outlook will briefly display a message indicating that the new form is being installed (copied to the forms cache). You used Microsoft Visual Basic Scripting Edition (VBScript) code in the custom form and used some methods or commands that are causing the item's form definition to change. The following methods most commonly cause this behavior:

<ul> ShowFormPage and HideFormPage</li> Methods that exist for the FormDescription object</li> The Delete method for the Action object</li></ul>

For more information about the ShowFormPage and HideFormPage methods causing the Message Class field to reset, please see the following article in the Microsoft Knowledge Base:

174276 OL97: ShowFormPage/HideFormPage Changes Form's Message Class

</li> You used a user-defined field on the form, but the field did not actually exist in the item when the form was published, but rather only existed in the folder. In this case, when you create a new item based on the custom form and enter a value into the field on the form, Outlook automatically adds the user-defined field to the item (changing the form definition) and therefore Outlook one-offs the form.</li> Assuming you published a message form so that it is available for everyone, if you open a new instance of the form, change any of the Message Options, and then send the form, the form will become a one-off form because Outlook updates the actions on the form.</li></ul>

Additional Notes
<ul> If the "Save form definition with item" check box is not selected, that does not necessarily mean that the form definition is not saved with the item. If the Message Class field is the default message class for that type of form, and the form used to display the item is a custom form, the form is one-offed.</li> One-off forms are a common cause of the "Enable/disable" security warning Outlook displays if a form contains VBScript code. Because the code is not in a "registered" form, Outlook will always display the warning. For more information about the security warning, please see the following article in the Microsoft Knowledge Base:

166780 OL97: Why Outlook Displays a Security Warning Opening an Item

</li> If you programmatically change the message class of the item to try to "re-link" the item (changing the message class from IPM.Contact to IPM.Contact.MyForm), the form definition will still remain with the item, but will be inaccessible. There is no apparent way to remove the form definition from an item other than creating a new item without a form definition and copying the data from the old item to the new one.</li></ul>

<div class="references_section">