Creating Intermediate Declarative Outlook Solutions Using Business Connectivity Services

Applies to: SharePoint Server 2010

In this article
Capabilities of Simple vs. Declarative Outlook Solutions
What Kind of Customizations Can You Perform?
How Do You Create an Intermediate Declarative Outlook Solution?
How Do Intermediate Declarative Outlook Solutions Work?
Components of an Intermediate Declarative Outlook Solution
Recommended Approach for Creating a Declarative Outlook Solution
Tools for Creating Intermediate Declarative Outlook Solutions

Microsoft Business Connectivity Services (BCS) enables information workers to surface external content types (such as Customer, Employee, or Order) within Microsoft Outlook 2010 as a native Outlook Item Type (such as a Contact Item, Task, Post, or Appointment) by taking an external list offline. Such a solution is known as a simple solution, and simple solutions rely on the native capabilities of Microsoft Office 2010 and Microsoft SharePoint 2010.

Simple solutions, however, offer little or no support for customization. In addition, Business Connectivity Services does not provide an extensible programming model for simple solutions. However, if you need to create customized solutions in Outlook, you can create an intermediate declarative Outlook solution. This type of solution is specific to Outlook 2010 in this release of Business Connectivity Services.

Capabilities of Simple vs. Declarative Outlook Solutions

The following table lists the capabilities of simple versus intermediate declarative Outlook solutions.

Table1. Simple vs. declarative Outlook solutions

Capability	Simple Outlook Solution	Intermediate Declarative Outlook Solution
Number of external content types in a solution	One	Can include more than one.
Actions and ribbons	Default ribbon and actions provided by Business Connectivity Services.	Can include custom ribbons and actions.
Showing related external content types	No way to show related information about an external content type in a task pane. However, note that if you define an association, Business Connectivity Services does provide an external item picker control to enable users to pick a source external item in the destination external content type.	Can show related information by defining custom ribbons and task panes.
Customizing the view in Outlook	Users can customize the view in Outlook and export the view definition.	The developer can include a custom view definition in the solution so that the external data is displayed by default in that customized view for all users that install that solution.
Customizing form regions	The default form regions provided by Business Connectivity Services can only contain Outlook controls. You cannot customize them to contain External Data Parts to show external data in Outlook.	Can create and customize form regions that contain External Data Parts to show external data in Outlook.

What Kind of Customizations Can You Perform?

By using an intermediate declarative Outlook solution, you can do the following:

• Show native or custom external data parts in the Outlook task pane  You can define custom task panes and present external data to users by hosting external data parts (either those provided by Business Connectivity Services or custom external data parts created by a developer) in a task pane.

• Include custom ribbons and actions   You can define ribbon files and custom actions that are exposed in the ribbon or in an external data part that either trigger code or launch a browser that points to a specified URL that can take Business Data Connectivity (BDC) service fields as parameters. Actions can be URL-based or can point to code actions created by a developer.

• Create a custom view definition in Outlook  Starting with basic Outlook elements, you can customize the view that is shown for a folder of external data. Business Connectivity Services provides a command to save the customized view as an Outlook View Definition (.ovd) file, so that it is available to users who install the declarative solution.  

• Customize Outlook form regions to present external data in Outlook  You can create customized Outlook form regions that show external data by designing new form regions in Outlook.

How Do You Create an Intermediate Declarative Outlook Solution?

You create an intermediate declarative Outlook solution by creating the following artifacts: a BDC model, a solution manifest (OIR.config), a subscription for each external content type, and optionally, a custom ribbon, one or more task pane layouts, custom form regions, and custom Outlook view definitions. Then, you can package these solution artifacts into an Office development tools in Visual Studio 2010 ClickOnce package by using the BCS Solution Packaging Tool. After you package the solution artifacts, users can install the package in Outlook.

Alternately, you can create the BDC model first, and then use the BCS Artifact Generator Tool to generate the artifact files based on the BDC model. After generating the artifacts, package the solution into an Office development tools in Visual Studio 2010 ClickOnce package by using the BCS Solution Packaging Tool.

How Do Intermediate Declarative Outlook Solutions Work?

An intermediate declarative Outlook solution takes advantage of the Business Connectivity Services Client Runtime to interpret the solution artifacts and tells the runtime what external data to show, from where to show it, how to show it, and what users can do with it. The Business Connectivity Services client cache on the client maintains the metadata and the cached external content types that are of interest to the user. A declarative solution uses the native Business Connectivity ServicesOutlook add-in that presents the elements defined in the solution artifacts at run-time within Outlook. This architecture enables experienced users and developers to focus on solving business needs, instead of managing the complexity of interacting with the Outlook and Business Connectivity Services APIs to perform common and repetitive tasks.

Components of an Intermediate Declarative Outlook Solution

Table 2 describes the typical components of an intermediate declarative Outlook solution, how many of each component is allowed in a solution, and what each component does.

Table 2. Components of an Intermediate Declarative Outlook Solution

Component	File Name	How Many Allowed	Description
BDC model	Must be named metadata.bdcm or metadata.xml.	One per solution. Required.	Defines all the external content types and their associations.
Cache subscription file	Must be named *Subscription.xml. For example, CustomerSubscription.xml and OrderSubscription.xml.	One for each external content type in the solution. Required.	Defines how to populate the Business Connectivity Services client cache.
Outlook view definition file	*.ovd	Zero or more.	Defines a custom view in Outlook.
Outlook form storage file	*.ofs	Zero or more.	An Outlook form region file.
Form region manifest	*.manifest.xml	Zero or more. But required if a form region (*.ofs) is present.	A manifest file that tells Outlook which form region file to load.
Solution manifest	Must be OIR.config.	One per solution. Required.	The solution manifest that describes the solution.
Ribbon file	*.xml	One per solution.	The Outlook ribbon file.
Layout file	*.xml	Zero or more. One per task pane.	Defines the controls that will be surfaced in the task pane, which external content types they should be populated with, and any other custom properties that the control exposes.
Custom assembly	*.dll	Zero or more.	If your solution references any reusable Business Connectivity Services code components, such as custom code actions, custom external data parts, or custom ribbon manager.
Icon	*.ico or a graphic file format, such as *.png or *.jpg.	Zero or more	Displayed in the Outlook user interface.
InfoPath form	*.xsn	Zero or more	Used to present external data in Microsoft InfoPath forms.

Recommended Approach for Creating a Declarative Outlook Solution

Creating an intermediate declarative Outlook solution consists of generating the required solution artifact files and packaging the artifacts into a ClickOnce package. You can create the solution artifact files in the following ways:

• Tooling Approach - You can use the BCS Artifact Generator Tool to generate the XML artifact files. This tool requires a BDC model file, which you must have created first using SharePoint Designer or an XML editor.

• Manual Approach - You can author the XML artifact files manually using an XML editor.

Use the following approach to create an intermediate declarative Outlook solution by using Business Connectivity Services:

1. Create a BDC model that defines the external content types used in the solution and their associations, and save it as metadata.bdcm (see Step 1: Create the BDC Model (Metadata.bdcm)). This topic also describes a shortcut to create a BDC model for your solution without writing all the XML from the beginning.

2. Create cache subscriptions for each of the external content types used in the solution by using the template provided in this SDK, and save them as XML files as in the following format: "<ExternalContentTypeName>Subscription.xml"; for example, OrderSubscription.xml or CustomerSubscription.xml. See Step 2: Create Cache Subscriptions (*Subscription.xml).

3. Create a solution manifest (OIR.config) to provide the general solution settings, Outlook folder information, and property mappings by using either the BCS Artifact Generator Tool or the template provided in this SDK. Have Business Connectivity Services autogenerate a form region for you to display the properties that cannot be mapped to an Outlook property. See Step 3: Create the Solution Manifest File (OIR.config).

4. Package the artifacts into a ClickOnce package by using the BCS Solution Packaging Tool. Then, install the package and test the solution in Outlook. See Step 4: Package and Deploy the Declarative Outlook Solution.

5. If the basic functionality works as you expect, then extend the solution with one or more of the following customizations as needed:

   1. Create custom Outlook form regions (*.ofs). See Step 5 (Optional): Create the Outlook Form Region (*.ofs) and Form Region Manifest (FormRegionManifest.xml).

   2. Create custom Outlook view definitions (*.ovd). See Step 6 (Optional): Create Custom Outlook View Definitions (*.ovd).

   3. Create task pane layouts (*.xml). See Step 7 (Optional): Show External Data Parts in Outlook Task Pane (Layout.xml).

   4. Define custom ribbon and actions (ribbon.xml, OIR.config). See Step 8 (Optional): Define the Ribbon and Actions (Ribbon.xml).

6. Package the artifacts, deploy the package in Outlook, and retest the solution.

Tools for Creating Intermediate Declarative Outlook Solutions

You can use a variety of tools to build intermediate declarative Outlook solutions including SharePoint Designer (for the BDC model) and Outlook (for customized form regions and view definitions). To create the XML files that your Outlook declarative solution needs, you can use any XML editor. Visual Studio can provide IntelliSense, which can be helpful when creating the XML files. Samples and templates are provided as part of this walkthrough to get you started. Alternately, you can use the BCS Artifact Generator Tool to generate the XML artifact files, except for the BDC model, which you must have created first using SharePoint Designer or an XML editor.

You can use the BCS Solution Packaging Tool to create a ClickOnce package for an Outlook declarative solution.

See Also

Concepts

Useful Resources for Creating an Intermediate Declarative Outlook Solution

Walkthrough: Creating an Intermediate Declarative Outlook Solution

Walkthrough: Using BCS Reusable Code Components in a Declarative Solution

Walkthrough: Localizing an Intermediate Declarative Outlook Solution to Another Language

Frequently Asked Questions: Declarative Outlook Solution

Other Resources

Templates for an Intermediate Declarative Outlook Solution

Intermediate Declarative Outlook Sample Solution Artifacts