Step 5 (Optional): Create the Outlook Form Region (*.ofs) and Form Region Manifest (FormRegionManifest.xml)

The Microsoft Outlook form region file contains the layout for the unmapped properties (fields) from the external data source. This form region file is paired with the form region manifest file, which contains information that Outlook requires to load the form region.

Applies to: SharePoint Server 2010

For simple solutions, Microsoft Business Connectivity Services (BCS) by default creates a form region to show the additional unmapped fields from the external data source. These are displayed as Business Connectivity Services extended properties in the adjoining form region of the Outlook inspector if the number of such fields is less than or equal to five, and in a separate form region if the number of such fields is greater than five. In an intermediate declarative Outlook solution, you can specify where you want the unmapped fields to be displayed in the form region manifest file. Table 1 describes the different locations where the Outlook form region, which contains the unmapped fields, can appear in Outlook.

Table 1. Locations of the Outlook form region

Form Region Location	Description
Separate	Adds the form region as a new page in an Outlook form.
Adjoining	Appends the form region to the bottom of an Outlook form's default page.
Replacement	Replaces the form's default page with the specified Outlook form storage (.ofs) file.
ReplaceAll	Replaces the form with the specified Outlook form storage (.ofs) file.

If you need a custom form region in your intermediate declarative Outlook solution, create an Outlook form storage file (*.ofs) that contains the layout for the unmapped properties (fields) from the external data source. You also have to create a form region manifest file. This file contains information that Outlook requires to load the form region. For more information about the XML schemas for form regions, download the Office 2010 Reference: Office Fluent User Interface XML Schema, and see the sections "Form Region Manifest" and "Form Region Localization Manifest."

To create a form region in Outlook

1. In Outlook on the File menu, click Options, click Customize Ribbon, and then under Main Tabs, select the Developer check box. This adds a Developer tab to the ribbon.

2. On the Developer tab, in the Custom Forms group, click Design a Form. Then, select a Design Form, depending on the Outlook item type (Contact in this case). In the Design group, click New Form Region.

3. In the Tools group, click Control Toolbox.

4. From the Toolbox window, drag the controls you want to the form region (for this example, start with a TextBox).

5. Right-click the control, and then click Properties.

6. In the Properties dialog box, on the Value tab, next to Choose Field, click New.

7. In the New Column dialog box, in the Name field, type the name of the PropertyName attribute in the OfficeItemProperty field of the solution manifest (OIR.config) and choose the matching type, such as Integer or Date/Time. Click OK to close the dialog box.

8. Click OK to close the Properties dialog box.

9. Add all other properties you want in the same way.

10. Add or modify any labels or the design of the form as you want.

11. In the Design group, click Form Region, and then click Save Form Region As. Name the form region formRegionCustomer.ofs and save it to your Solution Artifacts folder.

12. Next, create the form region manifest file. You can use the BCS Artifact Generator Tool to create the form region manifest file based on the BDC model.

    Alternately, you can author the form region manifest manually, as follows.

    1. Copy the template file that is provided in the SharePoint 2010 SDK (see Template: FormRegionManifest.xml), and then save it to the Solution Artifacts folder as formRegionCustomer.manifest.xml.

    2. Open formRegionCustomer.manifest.xml for editing in an XML editor. If you are opening the XML file in Visual Studio, attach the FormManifest schema. This will give you IntelliSense functionality and help you create valid entries.

    3. Replace the values marked with EnterX in the XML with valid values. The following XML example shows how the file might look after editing.

       <?xml version="1.0" encoding="utf-8"?>
       <FormRegion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                   xmlns="https://schemas.microsoft.com/office/outlook/12/formregion.xsd">
         <icons>
           <page>addin</page>
         </icons>
         <name>CustomerForm</name>
         <formRegionType>adjoining</formRegionType>
         <exactMessageClass>false</exactMessageClass>
         <layoutFile>formRegionCustomer.ofs</layoutFile>
         <title>Customer Details</title>
       </FormRegion>
       

    4. Save and close the file.

13. Now you are ready to update the OIR.config file with the details about the custom form region. Remember that the BCS Client Runtime will use this file to determine what components are in a declarative solution. To do this, locate the <FormRegions> element and replace it with the following.

    <FormRegions xsl:type="Declarative:DeclarativeFormRegions">
      <FormRegion Name="Customer" InternalName="CustomerForm" 
                  FormFileName="formRegionCustomer.ofs" 
                  ManifestFileName="formRegionCustomer.manifest.xml" />
    </FormRegions>
    

14. Save and close the file.

You have successfully created a custom form region and a form region manifest file to extend your intermediate declarative Outlook solution, and have updated the OIR.config file with this information. You should now repackage the solution, deploy it to Outlook, and then test it to ensure it works as you expect.

Next Steps

Step 6 (Optional): Create Custom Outlook View Definitions (*.ovd)