For your reference, these are our previous seven articles:

1. Part 1, BDC Purpose and technical architecture
2. Part 2, Application Definition File (ADF) and its Development
3. Part 3, Developing an ADF to Connect to Web Services
4. Part 4, Consuming Business Data through Web Parts and SharePoint Lists
5. Part 5, Implementing Enterprise Search with Business Data
6. Part 6, Integrating User Profiles with Business Data
7. Part 7, Working with the BDC Object Model

With that, let’s dive into BDC actions and start by asking what is an action.

What is an action?

An action is simply an operation upon a selected item. The operation can retrieve information about the selected item, or it can launch a program or Web page with the selected item as a parameter. The operation is a predefined URL link in each BDC item that enables you to act on the item, such as editing, or mapping it using Live Search as we demonstrated in Part 4.
An action is composed of a URL target where the action is to occur, and the matching parameters in the URL QueryString format. When we associate an action with an entity, we can pass parameters to that action based on the contents of one or more fields. For example, in the Live Search example in Part 4, we associate the Live Search page’s URL with a customer and provide the customer’s address to parameterize the search.

From the above, major characteristics of actions are as follows:

1. URL-based, parameter-driven
2. Actions on any entity and appear everywhere an entity goes
3. User can take action in ECB menu
4. Custom actions means custom code

A perfect example of action is the default View Profile action, as shown in Figure 1.

Figure 1  View Profile action in a Business Data Actions Web Part

Through a View Profile action we can navigate to the profile page of an entity. Clicking the View Profile action in a Business Data Actions Web Part as shown in Figure 1 above, as well as in a Business Data column, or in a Business Data List Web Part, lets us view the details of an item on that item’s profile page. Figure 2 shows that a Profile page that displays employee details.

Figure 2  A Profile page that displays employee details

What is a Profile page?

A profile page is automatically generated for each entity that has a SpecificFinder method after BDC imports an ADF file, a profile page can display all the information from a record in the BDC.  As we’ve seen in Figure 2, a profile page can display all the fields in a record for a specific employee. The default profile page contains a BDC Item Web Part for that entity.
If we put the profile page in Edit mode, there are actually two Web parts: a Business Data Item Builder and a Business Data Item that connect together. The Item Builder parses the querystring (http://win7:10001/ssp/admin/Content/Employee.aspx?EmployeeID=1) and passes the EmployeeID value to the Business Data Item, which then executes the SpecificFinder method and returns a record of Employee data.

Figure 3  Profile page components

Default Profile Page and default action

As we have seen from above section, the default action (View Profile) along with the default Profile page is automatically created when the entity has a SpecificFinder method.  To provide an ECB menu user experience, we can also add actions in a Business Data List Web part without using the Business Data Actions Web Part.

Defining an Action

There are three ways to add an action: 1) defining it in the ADF, 2) adding it in the BDC admin page after the ADF has been imported into BDC, and 3) through the BDC Object Model. Here we’re focus the first two.

Defining it in the ADF

To define an Action for the specified BDC entity, we’ll first locate the <Actions> section within the <Entities> and <Entity> hierarchy.

Figure 4  Actions is nested within the Entities/Entity in ADF

And insert the <action> portion like this one:

<Actions>
<Action Name=”Update Employee” Position=”1″ IsOpenedInNewWindow=”false” Url=”pages/editemployee.aspx?EmployeeID={0}” ImageUrl=”">
<ActionParameters>
<ActionParameter Name=”EmployeeID” Index=”0″ />
</ActionParameters>
</Action>

Adding an action in the BDC admin page

In the SSP administration page (View Application –> View Entity), the action is defined below and the URL that takes EmployeeID as a parameter: http://dpm:10001/ssp/admin/Content/Employee.aspx?EmployeeID={0}

Figure 5  Add an action the SSP Admin page

Custom Actions

We also can create custom actions for entities in BDC. Among other things, custom actions allow users to navigate to any custom page to manipulate business data.
Here are some scenarios that custom actions can do:

1. Parameterize custom search
2. Update employee in HR system
3. Customize profile page for an entity
4. Integrate BDC search into enterprise report center

We’ll be creating custom actions in the last part the article.

Figure 6 Enable View Profile action in a Business Data List Web part

This enables the ECB-style action, we will specify a Title property and add the following in the ADF:
<Entity EstimatedInstanceCount=”0″ Name=”Employee”>
<Properties>
<Property Name=”Title” Type=”System.String”>LastName</Property>
</Properties>
</Entity>

It specifies which column in the Business Data List/Related List Web part displays the Actions menu. It also specifies the name of the TypeDescriptor that corresponds to the column you want to display as the default column in Business Data lists.

In the Business Data Column scenario, we can also display the action menu and link the column to the business data profile in a Business Data list.

Figure 7  View Profile action in Business Data Column

This is default behavior OOB for a Business Data column.  When adding the column, just make sure the following two are checked:

• Display the actions menu
• Link this column to the profile page to

Figure 7  Enable the actions menu and profile page in Business Data list

These profile pages are used and being indexed by BDC Search. The following search results display the profile pages that contain the search keyword (s).  Notice in Figure 8 how a search for Great Lakes will display the profile pages for both this customer and their orders.

Figure 8  BDC Search Results in Profile Pages

Enhancing the Profile Page

By default, the profile page is hosted on the Shared Services Provider site collection where the BDC administration site is located. The search result (that is, the URL) links back to the Shared Services Administration site collection address that is not scalable when you extend the Web application. In real world, we may not want to give end users access to the SSP Admin site for security reason. A better practice is to create our own profile pages and host them in any site that is not part of the SSP site collection.
In this example, we’ve created a dashboard page in Report Center to replace the default Profile Page. The Report Center provides enterprise reporting capabilities that are scalable and centralized.  We can direct users to custom profile pages by updating the View Profile action.

Figure 9  Replace the default Profile Page with Custom Report Center

As an alternative, we can also replace the default the URL in Action element in ADF with the path to the Profile.aspx page:

<Actions>
<Action Position=”1″ IsOpenedInNewWindow=”false” Url=”http://reportcenter/Pages/Profile.aspx?EmployeeID={0}” ImageUrl=”/_layouts/1033/images/viewprof.gif” Name=”View Profile”>
<ActionParameters>
<ActionParameter Index=”0″ Name=”EmployeeID” />
</ActionParameters>
</Action>
</Actions>

An action to call the Profile.aspx page for each Employee ID has been defined. This action will be the default action provides in the search result.

Now let’s create Profile page to display information about the Employee entity in Report Center. (The Report Center is a site that provides a central location for business-intelligence-related information.)

1. In the http://reportcenter site, create a new Blank Web Part Page called “Profile.aspx”.
2. Add the following two web parts: Query String (URL) Filter Web Part and Report Viewer Web Part.
3. Configure the Query String (URL) Filter Web Part to pickup parameter “EmployeeID” from the URL query string.
4. Configure the Report Viewer Web Part to display the employee profile report called “Employee Profile”.
5. Connect the Query String (URL) Filter Web Part parameter to the SQL Server Reporting Services Report Viewer Web Part parameter “EmployeeID”.

Figure 10  SQL Server Reporting Services Report Viewer

Note: Please make sure you use this Web Part and not the OOB Report Viewer Web Part.

Test that the page is picking up the URL string parameter “EmployeeID” correctly by typing the following URL: http://reportcenter/Pages/Profile.aspx?EmployeeID=108

Figure 11  Custom Profile Page in Report Center

Creating Custom Actions

Creating custom actions requires custom code. The approach we take is to treat the BDC source simply as a data reader, and to build our CRUD (create/read/update/delete) logic in custom code. The BDC object model provides the means to retrieve collections, list items and enumerators, and we can use GenericInvoker to perform CRUD, which has been extensively covered in Part 7. We get the Web Parts to display data, and then we can use custom actions to create and update records by using Web parts and InfoPath Forms.

Creating Web Parts

We have created and deployed two Web Parts using the Object Model as shown below, with one inserting a record and one updating an existing record. (Special thanks to Lightning Tools! I’ve used BDC Meta Man to help with creating the Web parts.)

Figure 12  The two Custom Web Parts can be used to add and update employee records

Add these two actions in the SSP Admin page:

Figure 13  Adding actions in the SSP Admin page

Now you can access the two actions from the content menu in the Employee List:

Figure 14  Custom Actions Add Employee and Update Employee in the context menu

Figure 15  Add Employee Web Part

Figure 16  Update Employee Web Part

Creating InfoPath Form

MSDN has a great article titled Using Business Data Catalog Actions to Pass Parameters to InfoPath 2007 Browser Forms that walks you through this in detail.  So I’ve created our InfoPath Form and added the action using the Form Template path:
http://dpm/_layouts/FormServer.aspx?XsnLocation=http://dpm/FormServerTemplates/EmployeeUpdate.xsn&DefaultItemOpen=1&EmployeeID={0}&FirstName={1}&LastName={2}

Figure 17  Adding Custom Action that uses InfoPath Form

Figure 18  Update Employee in InfoPath Form

Conclusion

In this final article, we have focused on actions that users can take on the business entities. We can define actions in ADF or add it “after the fact”. We have also created custom actions using the BDC object model by using custom Web parts and InfoPath forms to enable CRUD (create/read/update/delete) operation support. Once added, actions can be performed from within the list, which becomes relatively transparent to the user where the data comes from. [The statement that the BDC data is read-only is not true anymore as we have just demonstrated.] As you have learned from our 8-part series, BDC enables user interaction in business intelligence, enterprise content management, collaboration and social features, and enterprise search.

Looking Forward to SharePoint Server 2010

BDC has evolved to what is now called BCS (business connectivity services) in SharePoint 2010. Even though we can use BDC to enable connectivity to external systems, it was difficult to create solutions because of the lack of a designer and it was not so simple to create a solution that enabled users to make changes and write that data back to the external store. BCS now enables you to integrate LOB data into SharePoint and Office with full CRUD support, tighter integration with Office client applications, and better tools for modeling business entities. BCS is all about connecting to external data. We look forward to sharing with you the exciting new features in BCS and what they can do for you in the near future. Until then, aloha!

For your reference, these are our previous six articles:

1. Part 1, BDC Purpose and technical architecture
2. Part 2, Application Definition File (ADF) and its Development
3. Part 3, Developing an ADF to Connect to Web Services
4. Part 4, Consuming Business Data through Web Parts and SharePoint Lists
5. Part 5, Implementing Enterprise Search with Business Data
6. Part 6, Integrating User Profiles with Business Data

Until now, we have been working strictly with the out-of-the-box features and capabilities of BDC. MOSS Enterprise has also provided us another powerful approach for working with BDC, which is to employ the BDC Object Model and programmatically interact with a LOB system. This gives us as developers the power and control over BDC to further meet growing business needs.

You might be wondering why we use the BDC Object Model when you can just use ADO.NET. The reason is two-fold: 1) you already have BDC in place that has already abstracted the complexity of the business data and you want to maximize your investments, and 2) BDC takes care of authentication, authorization, and other security requirements, which is extremely helpful if you are writing a custom application that calls into a back-end system. So this makes the BDC Object Model a compelling API for us.

Using the BDC Object Model, we can accomplish many things such as the following examples:

1. Auto-populate a SharePoint list that has a Business Data Column
2. Directly edit a customer in SAP
3. Synchronize content between SharePoint and an LOB system
4. Update and manipulate the ADF schema

We now know what the Object Model can do so let’s first exam where the BDC Object Model fits in BDC architecturally.

The BDC Object Model Overview

To see where the BDC Object Model fits in the BDC world, let’s revisit the BDC architecture from Part 1 with Custom Applications highlighted in Figure 1.

Figure 1 The BDC Object Model Creates Custom Applications.

As you can see from the figure above, BDC allows developers to connect to disparate LOB systems and these systems are exposed as data sources to various MOSS features such as Web Parts, list columns, enterprise search, user profiles, and custom applications that can be developed to interface with SharePoint.

Custom applications can be also developed to customize and extend the existing capabilities of BDC. That’s where the BDC Object Model fits in the picture and becomes the focus of this article. The BDC Object Model provides us with new namespaces and classes (methods and properties) we can use in Visual Studio the same way we use a standard set of .NET classes and interfaces. The OOB Web Parts such as Business Data List Web Part goes through this same API that we are going to learn about. You can also create your custom Applications using the same API.

As we have learned already, BDC abstracts the business logic in an XML-based ADF file and stores it in a shared service provider (SSP) database. This file contains all the necessary configuration data that determines how the BDC will connect to the remote systems and which requested data to make available through the BDC Object Model. The following figure shows the interaction between the ADF and the Object Model.

Figure 2 The BDC Object Model and How It Works

As you can see, BDC Object Model consists of Runtime and Administration object models. Each of these performs different tasks:

1. Runtime object model

• Browse metadata, execute methods, retrieve instances, traverse relationships
• Used to build custom applications

2. Administration object model

• Create, read, update, and delete metadata and manage permissions
• Used to edit the metadata internally or to build metadata management tools

Using the BDC Object Model

In order to connect to the BDC from our code, we will use the root namespace within the BDC Object model Microsoft.Office.Server.ApplicationRegistry. If you’re curious as to the term Application Registry, just know that it was the original name for BDC. It’s defined in the assembly Microsoft.sharepoint.portal.dll. Through the root namespace we have access to the child namespaces and its classes that we are going to use later in the article. Here they are listed in this table:

Table 1: Namespaces and Classes

Tip: MetadataModel and Administration use some of the same class names such as LobSystem and Entity so one way to avoid conflict when using them together is to use an alias as follows:

using BDCAdmin = Microsoft.Office.Server.ApplicationRegistry.Administration;

MSDN already has a code sample linked here on how to use the Administration object model to create and import an ADF. Since it’s more practical to us, we will use the Runtime object model primarily throughout this article.

Now we have the basic understanding of the BDC Object Model. Let’s make use of it by applying it to the following three scenarios:

1. Auto-populate a SharePoint list that has a Business Data Column
2. Create a BDC Utility Class that can be used in custom Applications and Web services
3. Create a custom application to update the LOB systems

Since all three of these will use the Runtime object model, we can initialize our code examples by first referencing the assembly Microsoft.sharepoint.portal.dll and then import the namespaces accordingly depending on the tasks:

Now that namespaces have been imported, the next line of code designates the Shared Service Provider (SSP) that provides the ADF. This is accomplished using the following call to the SqlSessionProvider singleton Instance property:

using Microsoft.SharePoint;
using Microsoft.Office.Server.ApplicationRegistry.Runtime;
using Microsoft.Office.Server.ApplicationRegistry.Infrastructure;
using Microsoft.Office.Server.ApplicationRegistry.MetadataModel;

SqlSessionProvider.Instance().SetSharedResourceProviderToUse(sspName);

The next set of code is the actual connection to the appropriate BDC and system instance. The connection is established by indicating the LobSystemInstance and Entity objects with the following statements:

LobSystemInstance lobInstance = ApplicationRegistry.GetLobSystemInstanceByName(“SynergyData”);

//Connect to the customers entity

Entity customers = lobInstance.GetEntities()["Customers"];

Following are the top steps we perform to call into the BDC and retrieve the data:

1. Connect to the named SSP
2. Connect to LOB Instance
3. Connect to entity
4. Connect to method for the entity
5. Execute the method
6. Parse the results

Now that you understand how to initialize your projects that use the Runtime API, let’s now examine each scenario:

1. Auto-populate a SharePoint list with Business Data Column

This application automatically populates a SharePoint list that has a Business Data Column storing customer records. First we create a SharePoint teamsite named teamsite and a SharePoint list called Customers. Then we reference both the SharePoint assembly Microsoft.SharePoint.dll and BDC assembly Microsoft.SharePoint.Portal.dll. Then code the using clauses to import the namespaces and code against the BDC Object Model by connecting to BDC and execute the method instance which will return all customers.

As my colleague Randy Williams has already demoed in his blog, here’s the complete code:

//Get SPList handle

SPSite site = new SPSite(http://MOSS);
SPWeb web = site.OpenWeb(“teamsite”);
SPList customerList = web.Lists["Customers"];

//Connected named SSP using the following call to the SqlSessionProvider singleton instance property
SqlSessionProvider.Instance().SetSharedResourceProviderToUse(“SSP”);

//Connect to the LOBSystemInstance
LobSystemInstance lobInstance = ApplicationRegistry.GetLobSystemInstanceByName(“SynergyData”);

//Connect to the customers entity
Entity customers = lobInstance.GetEntities()["Customers"];

//Connect to our finder method for customers
MethodInstance getCustomers = customers.GetFinderMethodInstance();

//Execute finder method
IEntityInstanceEnumerator results = (IEntityInstanceEnumerator ) customers.Execute(getCustomers, lobInstance);

//iterate through each row returned and add a new item
while (results.MoveNext())
{
SPListItem item = customerList.Items.Add();
item["Customers_ID"] = EntityInstanceIdEncoder.EncodeEntityInstanceId(new object[] { results.Current["CustomerID"].ToString() });
item.Update();
}

2. Create a BDC Utility Class

We’re going to create a custom library that uses the BDC Object Model to connect to an ADF.  We treat the BDC source simply as a data reader and to build our create/update/delete logic in an assembly. The BDC object model provides the means to retrieve collections, list items and enumerators, and we do the rest. In this class, we are going to create the following three static methods:

1. ExecuteFinder()
2. ExecuteSpecificFinder()
3. ExecuteGenericInvoker()

Let’s go through the code one by one. Here’s the first static method named ExecuteFinder that returns all of the entity records.

namespace SharePointMag
{
public class BDCUtil
{
public static DataSet ExecuteFinder(string SSPName, string LobSystemInstance, string Entity)
{
DataSet ds = new DataSet(Entity);

//Connect to named SSP
if (SSPName != null)
SqlSessionProvider.Instance().SetSharedResourceProviderToUse(SSPName);

//Connect to LOB Instance
LobSystemInstance lobInstance = ApplicationRegistry.GetLobSystemInstanceByName(LobSystemInstance);

//Connect to customers entity
Entity entity = lobInstance.GetEntities()[Entity];

//Connect to Finder method for customers
MethodInstance finder = entity.GetFinderMethodInstance();

//Execute Finder method
DbEntityInstanceEnumerator records = (DbEntityInstanceEnumerator)entity.Execute(finder, lobInstance);

//Load matching entities into a DataTable
DataTable entitiesTable = new DataTable();
while (records.MoveNext())
{
//Load each entity and include the Action URL
DbEntityInstance record = (DbEntityInstance)records.Current;
DataTable entityTable = record.EntityAsDataTable;
entityTable.AcceptChanges();
entitiesTable.Merge(entityTable);
}

//DataTable ordersTable = customerOrders.Tables.Add(“Orders”);
ds.Tables.Add(entitiesTable);
return ds;
}
}
}

The following code calls ExecuteFinder of BDCUtil class to return the customers records:

public static DataSet GetEntity()
{
return BDCUtil. ExecuteFinder(“SSP”, “SynergyDataInstance”, “Customers”);
}

The following is a Web service example to call the BDCUtil class to return all the customer records:

[WebMethod]
public DataSet GetCustomers()
{
string SSPName=“SSPPS”;
string strLOBInstance=“SynergyDataInstance”;
string Entity=“Customers”;
DataSet ds = new DataSet(Entity);
ds = BDCUtil. ExecuteFinder(SSPName, strLOBInstance, Entity);
return ds;
}

Note: For simplicity, we explicitly pass in the name of LOB Instance and Entity in our examples. They could also be “discovered” if you desire. Please check out this MSDN article titled How to: Get Started with Using the Runtime Object Model.

The second method named ExecuteSpecificFinder returns a single row of record identified by its ID.

public static DataSet ExecuteSpecificFinder(string SSPName, string LobSystemInstance, string Entity, object[] parameters)
{
DataSet ds = new DataSet(Entity);

//Connect to named SSP
if (SSPName != null)
SqlSessionProvider.Instance().SetSharedResourceProviderToUse(SSPName);

try
{
//Connect to LOB Instance
NamedLobSystemInstanceDictionary lobInstances = ApplicationRegistry.GetLobSystemInstances();
LobSystemInstance lobInstance = lobInstances[LobSystemInstance];
Entity entity = lobInstance.GetEntities()[Entity];

//Get the specific mathcing record
DbEntityInstance record = (DbEntityInstance)entity.FindSpecific(parameters, lobInstance);

//Loading matching entity into DataTable
DataTable entityTable = record.EntityAsDataTable;

//Return the results as a dataset

//DataSet ds = new DataSet(Entity);
ds.Tables.Add(entityTable);
return ds;
}
}

The following code calls the ExecuteSpecificFinder of BDCUtil class to return one row of employee record.

public static DataSet ExecuteSpecificFinder()
{
object[] parameters = new object[1];
parameters[0] = 1; //Employee ID;
return BDCUtil.ExecuteSpecificFinder(“SSP”, “SynergyDataInstance”, “Employees”, parameters);
}

This is the returned employee record that’s displayed in XML format:

<Employees>
<Employees>
<EmployeeID>1</EmployeeID>
<LastName>Davolio</LastName>
<FirstName>Nancy</FirstName>
<Title>Sales Representative</Title>
<TitleOfCourtesy>Ms.</TitleOfCourtesy>
<BirthDate>12/8/1948 12:00:00 AM</BirthDate>
<HireDate>5/1/1992 12:00:00 AM</HireDate>
<Address>507 – 20th Ave. E.Apt. 2A</Address>
<City>Seattle</City>
<Region>WA</Region>
<PostalCode>98122</PostalCode>
<Country>USA</Country>
<HomePhone>(206) 555-9857</HomePhone>
<Extension>5467</Extension>
<Photo>FRwvAAIAAAA…truncated…</Photo>
<Notes>Education includes a BA in psychology from Colorado State University in 1970. She also completed “The Art of the Cold Call.” Nancy is a member of Toastmasters International.</Notes>
<ReportsTo>2</ReportsTo>
<PhotoPath>http://portal.synergy.com/hr/employeephotos/ndavolio.jpg</PhotoPath>
<LoginAccount>synergy\ndavolio</LoginAccount>
</Employees>

Note: The <Photo> element has been truncated to save space here.

Now let’s move on to GenericInvoker by adding ExecuteGenericInvoker method in our BDCUtili class. The ExecuteGenericInvoker method calls the GenericInvoker method instance to write back to LOB systems.

public static void ExecuteGenericInvoker(string SSPName, string lobSystemInstance, string entityName, string methodInstance, object[] parameters)

{ //Connect to named SSP
if (SSPName != null)
SqlSessionProvider.Instance().SetSharedResourceProviderToUse(SSPName);

NamedLobSystemInstanceDictionary instances = ApplicationRegistry.GetLobSystemInstances();
LobSystemInstance instance = instances[lobSystemInstance];
Entity entity = instance.GetEntities()[entityName];
MethodInstance methInst = entity.GetMethodInstances()[methodInstance];
entity.Execute(methInst, instance, ref parameters);
}

In our third example, we look at GenericInvoker and then call the ExecuteGenericInvoker method we’ve just added.

3. Create a Custom Application to Update the LOB systems

BDC is very well known as read-only tool. It’s read-only because the OOB functionality does not make use of GenericInvoker methods. However, the object model and ADF support this type of method instance that we invoke just as we would invoke any other method. If you think of this as a stored procedure call and if I can call a stored procedure that runs a select statement, I should be able to call a stored procedure that inserts or updates as long as the underlining data repository supports them. In other words, the GenericInvoker method allows us to call other SQL commands. For our situation, we’ll use it to write back to our back-end system.

So let’s first add the GenericInvoker method in our ADF file and then call the ExecuteGenericInvoker method in our BDCUtil class . (Note: I’ve used BDC Meta Man to help generate the ADF and create ExecuteGenericInvoker. Thanks Lightning Tools! If you use BDC Definition Editor, you cannot select byte array byte[] as the return type of the field. You can instead select byte and edit the ADF by hand by changing byte to byte[].)  The following is the ADF and for the purpose of this example, only a single entity called Employees has been defined.

<Entity EstimatedInstanceCount=“0“ Name=“Employees“>
<Identifiers>
<Identifier TypeName=“System.Int32“ Name=“EmployeeID“ />
</Identifiers>
<Methods>
</Methods>
</Entity>
<Method Name=“insertEmployees“>
<Properties>
<Property Name=“RdbCommandText“ Type=“System.String“>
Insert into Employees(LastName,FirstName,Title) Values(@LastName,@FirstName,@Title);select NewEmployeeID = SCOPE_IDENTITY()</Property>
<Property Name=“RdbCommandType“ Type=“System.String“>Text</Property>
</Properties>
<Parameters>
<Parameter Direction=“In“ Name=“@LastName“>
<TypeDescriptor TypeName=“System.String“ Name=“LastName“ />
</Parameter>
<Parameter Direction=“In“ Name=“@FirstName“>
<TypeDescriptor TypeName=“System.String“ Name=“FirstName“ />
</Parameter>
<Parameter Direction=“In“ Name=“@Title“>
<TypeDescriptor TypeName=“System.String“ Name=“Title“ />
</Parameter>
<Parameter Direction=“Return“ Name=“Employees“>
<TypeDescriptor TypeName=“System.Int32“ Name=“NewEmployeeID“ />
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Name=“EmployeesInserter“ Type=“GenericInvoker“ ReturnParameterName=“Employees“ />
</MethodInstances>
</Method>
<Method Name=“updateEmployees“>
<Properties>
<Property Name=“RdbCommandText“ Type=“System.String“>Update Employees SET LastName=@LastName,FirstName=@FirstName,Title=@Title WHERE(EmployeeID=@EmployeeID)</Property>
<Property Name=“RdbCommandType“ Type=“System.String“>Text</Property>
</Properties>
<Parameters>
<Parameter Direction=“In“ Name=“@EmployeeID“>
<TypeDescriptor TypeName=“System.Int32“ Name=“EmployeeID“ />
</Parameter>
<Parameter Direction=“In“ Name=“@LastName“>
<TypeDescriptor TypeName=“System.String“ Name=“LastName“ />
</Parameter>
<Parameter Direction=“In“ Name=“@FirstName“>
<TypeDescriptor TypeName=“System.String“ Name=“FirstName“ />
</Parameter>
<Parameter Direction=“In“ Name=“@Title“>
<TypeDescriptor TypeName=“System.String“ Name=“Title“ />
</Parameter>
<Parameter Direction=“Return“ Name=“Employees“>
<TypeDescriptor TypeName=“System.Int32“ Name=“EmployeeID“ />
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Name=“EmployeesUpdater“ Type=“GenericInvoker“ ReturnParameterName=“Employees“ />
</MethodInstances>

</Method>

<Method Name=“deleteEmployees“>
<Properties>
<Property Name=“RdbCommandText“ Type=“System.String“>Delete Employees WHERE(EmployeeID=@EmployeeID)</Property>
<Property Name=“RdbCommandType“ Type=“System.String“>Text</Property>
</Properties>
<Parameters>
<Parameter Direction=“In“ Name=“@EmployeeID“>
<TypeDescriptor TypeName=“System.Int32“ Name=“EmployeeID“ />
</Parameter>
<Parameter Direction=“Return“ Name=“Employees“>
<TypeDescriptor TypeName=“System.Int32“ Name=“EmployeeID“ />
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Name=“EmployeesDeleter“ Type=“GenericInvoker“ ReturnParameterName=“Employees“ />
</MethodInstances>
</Method>

I’ve created three GenericInvoker MethodInstances and they are EmployeesInserter,EmployeesUpdater, and EmployeesDeleter. When a method instance is executed, it will eventually call the appropriate SQL command as shown here:

• Insert into Employees(LastName,FirstName,Title) Values(@LastName,@FirstName,@Title);select NewEmployeeID = SCOPE_IDENTITY()
• Update Employees SET LastName=@LastName,FirstName=@FirstName,Title=@Title WHERE(EmployeeID=@EmployeeID)
• Delete Employees WHERE(EmployeeID=@EmployeeID)

The following method ExecuteGenericInvoker is to call the GenericInvoker method:

public static void InsertEmployee()

{
object[] parameters = new object[3];
parameters[0] = “He”; //Last Name;
parameters[1] = “Wen”; //First Name;
parameters[2] = “SharePoint Architect”; //Title;

try
{
BDCUtil.ExecuteGenericInvoker(“SSP”, “SynergyDataInstance”, “Employees”, “EmployeesInserter”, parameters);
}

catch (Exception exception)
{
Console.WriteLine(exception.ToString());
}
}

The result is as you can see here highlighted:

In the same token, the following code will update the employee record:

In the same token, the following code will update the employee record:

public static void UpdateEmployee()
{
object[] parameters = new object[4];
//The parameters must match the parameters defined in ADF
parameters[0] = “10″; //Employee ID;
parameters[1] = “He”; //Last Name;
parameters[2] = “Wen”; //First Name;
parameters[3] = “MOSS Architect”; //Title;

try
{
BDCUtil.ExecuteGenericInvoker(“SSP”, “SynergyDataInstance”, “Employees”, “EmployeesUpdater”, parameters);
}

catch (Exception exception)
{
Console.WriteLine(exception.ToString());
}
}

Result is as follows:

Note: the order of the parameters must match that of the parameters defined in the updateEmployees method in the ADF. The ReturnParameterName (ReturnParameterName=”Employees”) is required in the EmployeeUpdater and EmployeeDeleter MethodInstance, even though they have no parameters to return.

As we have just learned, the GenericInvoker method is extremely useful because it takes care of authentication and authorization while enabling our custom applications to call in and execute business logic stored in the back-end to insert/update/delete LOB systems.

Write-back Best Practice

Even though BDC can update the LOB systems, it’s not suited for all scenarios. I strongly recommend you to take it into consideration governance and change management that your organization might require. Here are some additional best practices:

1. Understand the vendor support implications for changes that you make. For example, directly querying SharePoint databases is not Microsoft supported because the risk involved in damaging it.
2. Understand data integrity rules before using GenericInvoker method to make direct changes.
3. Have error handling in place.
4. When full inserts and updates are needed, consider using the LOB vendor’s own API that provides transactional write-back capabilities from the client to the underlying LOB application. Another way this can be done is using custom actions which will be covered in detail in Part 8.

Conclusion

BDC Object Model provides a new and exciting solution by allowing direct integration with LOB systems. In this article we have explored the BDC Object Model and exploited the capabilities of the BDC from code. BDC encapsulates the business logic of the back-end systems and developers can just work with the BDC objects to interact with those systems. We’ve demonstrated how to retrieve customer records to populate a SharePoint list that has a BDC data column, and then created a BDC utility class to act as a data layer, finally called the utility class to update the back-end system. With this you can now develop custom applications to interface with SharePoint using the BDC Object Model.  And for organizations that have invested in BDC, you are on your way to leveraging the real power of BDC!

If you’ve been following our BDC series, we’ve previously gone through the following topics:

1. Part 1, BDC Technical Architecture
2. Part 2, Application Definition File (ADF) and its Development
3. Part 3, Developing an ADF to Connect to Web Services
4. Part 4, Using BDC Web Parts to Consume BDC Data and Embedding BDC Data in Lists

• How can I find the customer information for Great Lake Good Market in CRM?
• How can I find the projects and resources details in Project Server 2007?
• How can I find an employee’s legal name in HR system?

With the help of the BDC Search, these all become possible. The Enterprise Search in MOSS can gather, index, and offer full-text search on all business data (entity instances) from applications registered in the BDC. Not only does it enable us to find answers in MOSS, but also it allows us to do so without having to leave SharePoint to go to these systems individually. It makes integrating search into existing line of business (LOB) applications like a CRM solution easier.

For example, if we register the Northwind sample database in the BDC, Enterprise Search can crawl it and return customer data in search results. In addition, the Enterprise Search feature’s extensibility enables us to create customized search experiences. We can create a custom search tab in the Search Center where our users can search for customers in the database, and we can also create a custom UI for the search results based on which we can also take action. So let’s dive right into it.

BDC Search Overview

As we’ve covered in prior articles, surfacing the BDC data to SharePoint using BDC Web Parts and lists is just first part of the BDC saga, it can also enable you to index and search on the BDC data. The following figure is an example of searching for information about a customer and then displaying both structured data from the database and unstructured documents and content stored within SharePoint.

Figure 1: Enterprise Search with BDC

Here’s another example of leveraging BDC to index Project Server data and enable us to search the different objects (projects, tasks, resources, custom fields, lookup tables, and so on). This is of great value because out of the box the Project Server data is not indexed. Only the objects in project workspace are indexed such as Issues, Risks, Documents, etc. For instance, if we are looking for project detail information for the Enterprise resource planning (ERP) project, we can search our Project Server and find the answers as shown in Figure 2:

Figure 2: Search Project Server with BDC

The BDC is truly a catalog of business applications that helps bridge the gap between MOSS and business applications by bringing in key data from various applications to SharePoint sites, lists, searches, and user profiles. Let’s revisit the BDC architecture from Part 1 with both XML Metadata and Search components highlighted in Figure 3.

Figure 3: BDC architecture with emphasis on the Search

Firstly, we’ve highlighted the XML Metadata because it is the key element in the Application Definition that makes the BDC Search possible. BDC operates off of an XML-based Application Definition File (ADF). The metadata in ADF enables MOSS to crawl the BDC data source and add them to the search index.

Secondly, we highlight the Search component because the search engine uses a protocol handler to crawl and a security trimmer to filter results. BDC uses these just like third party implementations when supporting BDC searching.

BDC Search enables us to quickly find content in business data through search queries. It also integrates with search scopes and search center to become an integral part of MOSS Enterprise Search. Here I’ve created a custom search tab and a search scope for the BDC data to create a unique search experience in which the BDC search results are segregated from the rest of SharePoint search results. See Figure 4.

Figure 4: Customized BDC Search Experience in Search Center

By enabling the search of BDC data, BDC Search extends the SharePoint search capabilities. This extends the reach of the back-end LOB systems. Today most LOB systems don’t have Full-Text search capability and BDC Search can serve for that purpose.

However, out of the box the BDC Search does not support indexing unstructured data like documents in a document management system. This is because the protocol handler for BDC is meant to connect to external structured data only. With custom protocol handlers, it’s possible to make MOSS index unstructured data . For example, using Web services to directly support BDC we can enable SharePoint to search, list, and retrieve documents from an external document management system via Web services.

Now let’s look into how to enable BDC Search.

Enabling BDC Search

One might think once we import an ADF, we can start to search. BDC Search doesn’t come automatically, and we must enable it. To enable BDC Search, we must first make sure these two methods exist in the ADF for the entity you want to crawl:

1. SpecificFinder
2. IdEnumerator

These are the only required metadata for Enterprise Search to use BDC to index the business application’s data.

In Part 2, we’ve covered the ADF and its vocabulary: System (data source), Entity (table), Method (operation on entity), and Association (relationship). There are three primary types of methods: Finder, SpecificFinder and IdEnumerator. An IdEnumerator method returns a searchable list of unique IDs for an entity. This list enables indexing of the entities and SpecificFinder is then used to find details for the entity instance based on the specific ID. Therefore, IdEnumerator and SpecificFinder work together to enable Enterprise Search to use BDC to crawl the business data.

Now since we have a good understanding of what it takes, let’s put it in action. We’re going to use Business Data Catalog Definition Editor, a free tool from the MOSS SDK, to create our ADF (shown in Figure 5 below). Though one of the limitations of this tool is that it doesn’t create a Finder method, BDC Search doesn’t need use this anyway, so it works very well for creating an ADF that’s just used for searching. You can learn how to use this tool here.

Incidentally, both MOSS BDC Design Studio and BDCMetaMan will create these methods necessary to implement BDC searching.

We begin by adding a LOB system for our sample database, a modified version of Northwind database. We’re going to use the Customers entity that resembles one in a CRM system (or the like).

Figure 5: Create Application Definition

To index and search for Customers entity in the database, we’re performing the following tasks:

1. Define an IdEnumerator method in the BDC definition (Figure 6)
2. Define a SpecificFinder method in the BDC definition (Figure 7)

Figure 6: Define a special type of MethodInstance method IdEnumerator.

The IdEnumerator method returns a list of CustomerID records, which will be indexed by MOSS Search. So now we know that the sole purpose of IdEnumerator here is to enable Search. Here’s the SQL query:

Figure 7: Define a SpecificFinder