Knowledge Base

Description of form definitions and one-off forms in Outlook 2002

Article ID: 290657

Article Last Modified on 11/23/2006

APPLIES TO

Microsoft Outlook 2002 Standard Edition

This article was previously published under Q290657

For a Microsoft Outlook 97 version of this article, see 176567.

For a Microsoft Outlook 98 version of this article, see 181266.

For a Microsoft Outlook 2000 version of this article, see 207896.

SUMMARY

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

MORE INFORMATION

NOTE: Throughout this article there is an important 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 the "user interface" 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 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:

Start with a new, default Contact form to use as the basis for your custom form.
Customize the form to suit your needs.
Publish the form to the Contacts folder.
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 additional information about working with message classes, 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

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

You can specify that a form is a one-off by clicking to select the "Send form definition with item" check box on the form's Properties page when in design mode. You would typically do this when the form is not registered in a form library where the recipient has access to it. Selecting this option ensures that the person will see the custom form when the item is opened.

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.

The 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:
1. Open a new item based on your custom form.
2. Make form design changes to that item.
3. Using that item, republish the form with the same name.
4. 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 same 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:
- Methods that exist for the FormDescription object.
- Methods related to the properties of controls, usually for enabling/disabling controls or making them hidden/shown. This will happen when setting the following control properties: PossibleValues, ItemProperty, and LayoutFlags. This will not happen with the ReadOnly property.
- Methods related to the Action object.
You created a field for use in the folder but the field did not actually exist in the item when the form was published. In this case, if you create a new item based on the custom form and use the Outlook in-cell editing feature to enter a value into an item in a table view, Outlook automatically adds the user-defined field to the item on-the-fly. This changes the form definition and therefore the item is one-offed.For additional information about using user-defined fields in solutions, click the article number below to view the article in the Microsoft Knowledge Base:

290656 OL2002: Working With User-defined Fields in Solutions

Typical Symptoms

Although solutions and situations vary greatly, there are some signs to be aware of that can indicate that forms are becoming one-offed.

The VBScript code in a form no longer runs. This is because by default Outlook does not run VBScript code in one-off forms. This is part of the new e-mail security features in Outlook 2002. For more information about this security-related restriction, click the following article number to view the article in the Microsoft Knowledge Base:

290500 Description of the developer-related e-mail security features in Outlook 2002
A macro virus warning is unexpectedly displayed when an item is opened. 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 published or trusted form but actually in the item itself, Outlook will always display the warning. Ideally you should try to avoid the scenario that is causing the form to be one-offed in the first place. For additional information about the security warning, click the following article number to view the article in the Microsoft Knowledge Base:

290663 Outlook does not run VBScript code when you open an item
The size of an item increases unexpectedly.
The icon for an item changes unexpectedly, typically indicating a change in the message class field.

Identifying a One-Off Item

If an item is unexpectedly one-offed and then you notice that the "Send form definition with item" check box is not selected, that does not necessarily mean the form definition is not saved with the item.

An item is a one-off if its Message Class field is the default message class for that type of item but when the item is opened the form used to display the item is a custom form.

When developing a folder-based solution, you may want to display the Message Class and Size fields in a table view so you can be sure that the items in the folder are behaving as you expect. Also, a change in the icon for an item oftentimes indicates a status change but you should restart Outlook to be sure the proper icon is being displayed.

Steps to Reproduce the Problem

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

The following steps illustrate how adding a user-defined field to an item can create a one-off form.

Open a new mail message.
On the Tools menu, click Forms and then click Design This Form.
Using the Control Toolbox, add a CommandButton to the P.2 page.

On the Form menu, click View Code. Add the following VBScript code into the VBScript Editor and then close the editor:

Sub CommandButton1_click()
   ' This changes the form definition by adding a text field.
   Set MyProp = Item.UserProperties.Add("MyField",1)
   ' Send the item
   Item.Send
End Sub

On the Tools menu, click Publish Form As and then publish the form in the Inbox as "Form1"
When prompted to enable the "Send form definition with item" option, click No. Close and do not save changes to the form.
On the Actions menu, click New Form1 to open an item based on the form.
Address it to yourself.
Use the CommandButton on P.2 to send the message.
When you receive the message, open it to read it.

Note that the macro warning message appears. Also, the size of the item is relatively large (~6K).

Workaround

If you need to have a scenario where an item will become a one-off, you can work around the side-effects of a one-off item by resetting the message class field and then saving the item in code. As an example, use the following code instead of the code given above in the "Steps to Reproduce the Problem" section and the item will not enable the macro warning message.

Sub CommandButton1_click()
   ' Save the MessageClass property
   sSaveMessageClass = Item.MessageClass

   ' This changes the form definition
   Set MyProp = Item.Userproperties.Add("MyField", 1)

   ' Restore the MessageClass property
   Item.MessageClass = sSaveMessageClass

   ' Save the changes to the form
   Item.Save

   ' Send the item
   Item.Send

End Sub

NOTE: If you programmatically change the message class of an item, the size of the item is not reduced. There is no way to truly remove the unwanted form definition from an item other than creating a new item without the form definition and copying the data from the old item to the new one.

REFERENCES

For additional information about available resources and answers to 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

Additional query words: OutSol OutSol2002 workaround

Keywords: kbforms kbvba kbinfo KB290657

Microsoft KB Archive/290657

Contents