OL97: Working with Form Definitions and One-Off Forms

• Microsoft Outlook 97

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 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 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/default.asp

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

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

   Article-ID: Q170301
   Title     : 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:

  1. Open a new item based on your custom form.

  2. Makes 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 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:

      - ShowFormPage and HideFormPage
  

      - Methods that exist for the FormDescription object
  

      - The Delete method for the Action object
  

  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:

        Article-ID: Q174276
        Title     : OL97: ShowFormPage/HideFormPage Changes Form's Message
                    Class
  
  

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

Additional Notes

• 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.
• 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:

        Article-ID: Q166780
        Title     : OL97: Why Outlook Displays a Security Warning Opening
                    an Item
  
  

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

REFERENCES

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

   Article-ID: Q166368
   Title     : OL97: How to Get Help Programming with Outlook

   Article-ID: Q170783
   Title     : OL97: Q&A: Questions about Customizing or
               Programming Outlook