Chapter 11
Creating Business Data Applications

IN THIS CHAPTER

• Using the Business Data Catalog Administration API
• Using the Business Data Catalog Runtime API
• Creating BDC-friendly Applications

Developing applications that expose themselves to the Business Data Catalog (BDC) as well as applications that can directly affect the BDC can be a large portion of a developer’s tasks on the new version of SharePoint. This chapter provides an overview of creating, editing, and querying BDC application data using the BDC administration object model and querying BDC applications and viewing BDC application data using the BDC runtime object model. Finally, this chapter provides information on some of the things you can do within your own code to make your applications more BDC-friendly.

Using the Business Data Catalog Administration API

Chapter 10, “Integrating Business Data,” mentioned that the Extensible Markup Language (XML) format for defining a BDC application was difficult and unwieldy. It also mentioned that there was a lack of tool support for defining BDC applications or for editing the XML file.

The XML file is actually just a shortcut. When you upload the XML file to SharePoint, SharePoint actually makes use of the BDC administration application programming interface (API) to configure the Business Data object model.

Using the BDC administration object model, you can create new Line of Business (LOB) system instances, entities, associations, and methods. You can also query existing metadata contained within the BDC, but those operations are slower using the administration object model than using the runtime object model, which is specialized for fast read-only access.

Developers perform three main tasks using the BDC administration object model:

• Creating a LOB system, entity, and method
• Creating access control lists (ACLs) for metadata objects
• Importing metadata into the BDC

You saw how to import metadata into the BDC using XML files and the SharePoint web-based graphical user interface (GUI) on the Shared Services website in Chapter 10. The sample contained in Listing 11.1 illustrates how to create a complete LOB system and entity. It uses the Create method of the LobSystems collection to create the LOB system and then creates a LOB system instance from that system.

Listing 11.1. Creating a LOB System and Entity Using the Administration Object Model

In addition to creating an entity, each entity can have methods for index retrieval that return a list of identifiers and methods for wildcard searching and browsing by title, and so on. The combination of entities, methods, and associations allows for data contained in an external source to be indexed, cataloged, and rendered within SharePoint. Figure 11.1 shows the contents of the BDC after programmatically creating a new LOB system, LOB system instance, and entity.

Figure 11.1. Entity information after creation.

Using the Business Data Catalog Runtime API

The BDC runtime API is another section of the object model that allows you to examine the contents of BDC application metadata as well as execute methods, locate entities, and much more. The metadata access is quicker than using the administration model because the metadata in the runtime version of the object model is read-only.

Using the BDC runtime API, you can accomplish anything that the BDC Web Parts can do. The following is a list of the most common coding scenarios for the BDC runtime API:

• Querying for a LOB system and entities
• Using a wildcard Finder
• Using a specific Finder
• Entity enumeration using Finders
• Direct method execution against entities

Querying Metadata

The first example, shown in Listing 11.2, illustrates using the key namespace in the BDC, Microsoft.Office.Server.ApplicationRegistry, to query the metadata for a LOB system application and its entities.

Listing 11.2. Querying BDC Metadata Using the Runtime Object Model

The most important piece of working with any part of the BDC API is remembering to point your code at the right Shared Services provider. The BDC is a service provided to farms by an SSP (Shared Services Provider), and as such, any time you access the BDC, you need to indicate the SSP name, as follows:

     SqlSessionProvider.Instance().SetSharedResourceProviderToUse(
         "SharedServices1");

Before you can enumerate entities or examine the metadata, you need to get a reference to the LobSystemInstance representing the registered BDC application. In the preceding code, the list of entities belonging to a given system instance is retrieved with the GetEntities method.

The output of the application contained in Listing 11.2 will look something similar to the following text (assuming you have the AdventureWorks sample installed):

Installed LOB System Instances:
          BugSystemInstance
          AdventureWorksSampleInstance
          BugSystemFromCode

Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.Db.DbConnectionManager
AdventureWorksSample
339
Entity Product, ID 341
Entity SalesOrder, ID 372
Entity Customer, ID 392

After you have access to the metadata that constitutes the BDC application, the next thing you might want to do is gain access to the data itself. Although you can certainly use the BDC Web Parts for visual access to the data, there will probably be many times where you want to work with the BDC data directly. Using the BDC API to access remote data provides you with a datasource-agnostic means of accessing remote LOB systems and their data.

Using a Specific Finder

One of the ways in which the BDC allows you to access data is through the use of what is called a specific Finder. A specific Finder is an abstraction around the act of locating a single entity through the use of its unique identifier.

The code in Listing 11.3 shows how to make use of a specific Finder to locate an individual entity within an LOB system instance, but to gain access to its properties, data, and even associated entities.

Listing 11.3. Locating an Entity and Associated Entities

An identifier is defined within the BDC metadata for the AdventureWorks database that allows customer entities to be located by their ID. In the case of the preceding code, the entity with the ID of 746 is located within the AdventureWorks instance. The fields belonging to that entity are then retrieved and sent to the console. Finally, all of the orders associated with customer 746 are retrieved using the GetAssociatedInstances method.

The following text is the output produced by the code in Listing 11.3. Remember that you need to have the AdventureWorks SQL server database and the sample BDC application installed for this to work properly.

Customer Fields:
IndividualID:740
FirstName:Aaron
LastName:King
            SalesOrderID:37692
            OrderDate:7/17/2003 12:00:00 AM
            IndividualID:740
            SubTotal:2359.9800
            SalesOrderID:40879
            OrderDate:10/11/2003 12:00:00 AM
            IndividualID:740
            SubTotal:2398.0500

Using a Filter Finder

Filter Finders are methods used to retrieve only the data that is necessary to apply a filter. Assuming you have an entity that can be filtered either by ID or by Name, you might create a filter Finder that returns just the ID and name of each entity in the system so that a filter could be applied.

The code in Listing 11.4 invokes a filter Finder and displays all of the fields returned for each entity in the system.

Listing 11.4. Retrieving Entities Using a Filter Finder

Using a Wildcard Finder

Using filter Finders is extremely useful for obtaining the smallest amount of filterable data available for each entity, but if you want to return a subset of entities that have been filtered based on a wildcard search query, you can use a wildcard Finder, such as the code shown in Listing 11.5.

Listing 11.5. Using a Wildcard Finder

Executing Methods Directly

Each BDC application metadata contains a list of method instances. These methods can be invoked directly through the BDC API, as shown in Listing 11.6.

Listing 11.6. Direct Method Execution—Finding a Single Entity

Creating BDC-friendly Applications

Now that you’ve seen how SharePoint and SharePoint developers consume LOB data using the BDC and its associated APIs, you should be able to start creating applications that will integrate seamlessly with SharePoint and the BDC.

Building BDC-compatible Web Services

Working from the list of actions that you can take with the BDC API, you should now have a fairly clear idea of the kinds of operations that a BDC-friendly web service should support. The following is a list of some of the methods that, when implemented in a web service, will make for a considerably more BDC-friendly service:

• A method to retrieve each entity by a single piece of uniquely identifying information. For example, for Adventure Works, you need a method that retrieves a customer by ID, a method that retrieves an order by ID, and so on.
• A method for each type of filter you might want to support. If you plan to allow filters by name, by ID, or by any other field, you should provide a web service method for each type of filter.
• A method for retrieving entities related to another entity. For example, if you have a relationship between customers and orders, you need to provide a method that retrieves all orders for a given customer. If the relationship is two-way, you need to provide two methods: one for each direction.

Exposing Relational Data to SharePoint

Thankfully, exposing normalized relational data is virtually done for you. Any database that is in third normal form or relatively close will be able to be exposed via an abstraction that involves entities, entity associations, entity properties, identifier columns, filter methods, and Finders. During the process of defining the metadata for a business data application, you might find that all of the queries you need to satisfy the BDC requirements have already been written as stored procedures or defined in code elsewhere.

Summary

The BDC is an extremely powerful new addition to the arsenal of tools available to the SharePoint developer. Knowing how much functionality is available through the use of the runtime and administration APIs can be invaluable in making technology decisions, architecture decisions, and in developing your own custom code. This chapter provided code samples and guidance for interacting with the BDC at the object model level.