Chances are you’ve already read Brad Stevenson’s post Types of Solutions and you’re interested in building a BCS solution.

If you’ve read my post on the BCS Solution Packaging Tool, perhaps you’ve already tried to build and package a solution yourself.

To help out developers and power users we’ve created another new tool called the BCS Artifact Generator which will greatly help you get started building working solutions, which you can then customize however you’d like.

To use the tool simply select your BDC Model (see Lionel Robinson’s post Creating an External Content Type in SharePoint Designer 2010 for help creating a BDC Model), give your solution a name, then follow the wizard which guides you through picking and choosing how your solution will look in Outlook. When you click “Generate” the tool will produce a folder containing all of the files necessary to run a BCS solution.

You can then point the Solution Packaging Tool at this folder to package and deploy your solution to Outlook, all in a matter of minutes.

You can download the free Artifact Generator tool from MSDN Code Gallery.

Also, be sure to download the free Solution Packaging Tool, also from MSDN Code Gallery.

Creating a Declarative Solution for Outlook

To create a declarative BCS solution in Outlook, you’ll do the following:

1. Create the necessary solution artifacts (see below for details)
2. Put the artifacts in a folder
3. Create a BCS Package (a special type of VSTO ClickOnce package) using that folder - Optional: put the BCS Package somewhere public (i.e. SharePoint) where your users can then go to deploy the solution
4. Deploy the solution package to Outlook
5. You’re done!

Creating a BCS Package is done using the Solution Packaging Tool, which we’ve seen already. This post will examine the first step – creating the solution artifacts. We’ll show you how quickly and easily you can do this using the Artifact Generator tool.

What are the required artifacts?

To have a solution you’ll need the following three files at the very least:

1. BDC Model
2. Solution Manifest (OIR.config file)
3. Subscription(s)

Having these three artifacts will allow you to create and deploy a solution in Outlook. In addition, your solution can contain the following three customizations:

A) A custom item Taskpane (item C in the screenshot below)

B) A custom item Form Region (item D in the screenshot below)

C) A custom ribbon containing item action buttons (item B in the screenshot below)

The following screenshot shows a declarative solution and each of the three aforementioned customizations:

To add a custom Taskpane to your solution you’ll need each of the following:

a) InfoPath Form [.xsn]

b) Layout file [.xml]

c) A few lines of XML added to the Solution Manifest

To add a custom Form Region to your solution you’ll need each of the following:

a) Office Form Storage File [.ofs]

b) Form Region Manifest [.xml]

c) A few lines of XML added to the Solution Manifest

To add a custom ribbon tab with action buttons to your solution you’ll need each of the following:

a) Ribbon definition file [.xml]

b) A few lines of XML added to the Solution Manifest

Using the Artifact Generator

You can now use the Artifact Generator to create most of these files automatically:

• Solution Manifest (including the additional lines needed for each customization)
• Subscription(s)
• Layout file
• Form Region Manifest
• Ribbon definition file

Before using the tool, be sure to create the following files if you’d like to include them for use:

• BDC Model
• [Optional] InfoPath form (to show item details in the taskpane)
• [Optional] Office Form Storage file (to customize the added form region)

Steps to use the Artifact Generator

1. Give your solution a name
2. Import the BDC Model
3. Click “Next”
4. You can customize each of the External Content Types (ECT) that are mapped to Outlook item types by clicking “Customize” (see below for customization options):

1. First, you can change the name that is displayed for that item.
2. You can also change the icon that is displayed for that item.
3. Click “Next”.
4. For the ECT fields (i.e. “Product Serial Number”) that aren’t mapped to regular Outlook fields (like “First Name”, “Phone Number”, etc.), a form region will be automatically generated for your solution. You can also create and customize this region yourself by creating an Office Form Storage file and selecting to use that file for this item.
5. Click “Next”.
6. If the External Content Type has an association (in the BDC Model) you can show those associated items in a list on a taskpane (i.e. when you open a customer contact, it will show the orders that the customer has placed).
7. You can also add an InfoPath form which will show the field details for each item you select in that list. First create and customize the InfoPath form and select it for use in the wizard for this item.
8. Click “Next”.
9. To add a ribbon for the item which can have action buttons that perform custom actions for the item, click “Add a custom action” and then choose a name for the ribbon tab and for the ribbon group label where the button appears.
10. By default the Artifact Generator will help you create one action button to start with. You can easily edit the Ribbon definition file later to add more buttons. This default button is a “URL Action” type of button, which opens up a URL in the browser based on a parameter value for that item. Enter a URL (be sure to add “{0}” in the URL where the value should go) and select a field to use as that parameter.
11. Click “Finish”.

• Click “Generate artifacts”.
• A folder containing these newly generated artifacts will be created at the same location of the tool itself. The folder will also open up, displaying the artifacts.

Then, use the BCS Solution Packaging Tool to select this folder and create a new solution package to be used for installation and deployment of the solution. Be sure to select “Outlook Intermediate Declarative Solution” as the solution type.

You should now have created an Intermediate Declarative Solution in Outlook!

Data Solution

If you’ve read my post Overview of BCS Advanced Code-Based Solutions or the MSDN article Creating Advanced Code-Based Solutions Using Business Connectivity Services you’re aware that you can create Office Add-Ins using Visual Studio which can integrate with BCS and external data.

These solutions need metadata and subscriptions on the machine running the solution, which dictate synchronization of the external data between the client and the external system. This metadata can be set up on that machine by having a user deploy a Simple Solution to Outlook or SharePoint Workspace, but this requires additional steps that each user of your solution would have to perform initially.

The ideal and recommended approach is to use a complementary Data Solution to go with your Office Add-In, which will set up the metadata and subscriptions on the user’s machine automatically.

A Data Solution requires the following files:

• BDC Model
• Subscription(s)

Again, you can either create the subscriptions by hand or use the Artifact Generator to create them for you. Simply import your BDC Model to the Artifact Generator and click “Generate artifacts”. Then, use the Solution Packaging Tool to point to that folder and create a BCS Package of type “Data Solution for Office Add-In”.

If the user deploys this solution and then deploys your Office Add-In, your add-in will be able to display and manipulate external BCS data.

To try this out for yourself, check out the following: Business Connectivity Services Excel 2010 Add-In.

Thanks for reading, and enjoy the tool!

Russell Palmer

Program Manager