Chapter 27
Using the Business Data Catalog Web Services

IN THIS CHAPTER

• Overview of the Business Data Catalog
• Using the Business Data Catalog Web Service
• Using the BDC Field Resolver Web Service

The Business Data Catalog (BDC) is an incredibly powerful feature of Microsoft Office SharePoint Server (MOSS) 2007 that connects native SharePoint data such as lists and Web Parts to data stored in external Line of Business (LOB) systems. This chapter provides you with an overview of the BDC and illustrates the different ways in which your code can interact with BDC-related web services.

Overview of the Business Data Catalog

As you saw in Chapter 10, “Integrating Enterprise Business Data,” and Chapter 11, “Creating Business Data Applications,” the Business Data Catalog is made up of metadata that describes an external Line of Business application that either exposes functionality via a web service or stores data in a relational database.

The BDC allows SharePoint administrators to access and view LOB data, and it allows developers to write code against the BDC model so that their code will work against any external entities.

Chapters 11 and 12 referred to several concepts inherent to the BDC:

• LOB systems and system instances—The LOB system is the top level in the BDC hierarchy. It is a container of entities and related metadata.
• Entities—An entity can be represented by a row in a table or a single result from a web service. Examples of entities shown in Chapters 11 and 12 include customers, bugs, bug issues, products, and order items.
• Methods—Methods are actions that can be performed against an entity that are either Structured Query Language (SQL) queries or invocations of web service methods.
• Finders—A Finder is a specific type of method that can be used to locate individual entities or groups of identities either by specific identifiers or by wildcard matches.

One thing that developers might find disappointing about the BDC Web Service is that you cannot use it to make changes to the catalog. There are no methods on either of the BDC Web Services that will let you upload new metadata files or modify existing metadata. That said, the ability to query the contents of the BDC and use the Field Resolver Web Service is extremely useful to developers. The next two sections illustrate how to use the BDC Web Service and the Field Resolver Web Service.

Using the Business Data Catalog Web Service

The Business Data Catalog Web Service is a service provided by MOSS, not by Windows SharePoint Services (WSS) v3.0. As a result, the service is located at the root level of a portal site, for example, http://server/_vti_bin/businessdatacatalog.asmx. Note that in many configurations of SharePoint, the web services themselves reside in a different Internet Information Services (IIS) web application and on a different port number than the rest of the SharePoint installation, for example, http://server:1122/_vti_bin/businessdatacatalog.asmx or, using host headers, http://services.server.company.com/_vti_bin/businessdatacatalog.asmx.

At the top level of the hierarchy of metadata contained within the BDC is the LOB system instance. Thankfully, the developers of the new BDC Web Service decided to return structured data instead of free-form Extensible Markup Language (XML). As a result, obtaining the list of LOB system instances returns an array of LobSystemInstanceStruct structs. The properties of this struct are shown in Table 27.1.

Table 27.1. LobSystemInstanceStruct Properties

The code in Listing 27.1 shows a set of sample code that connects to the BDC Web Service, provides default credentials, and returns a list of LOB system instances as well as the properties associated with each LOB system instance.

Listing 27.1. Enumerating LOB Systems

Figure 27.1 shows the output of the console window when the preceding code is executed.

Figure 27.1. Enumerating LOB instances and properties.

Below each LOB system instance in the metadata hierarchy are the entities. Entities are returned from the web service in the form of an array of EntityStruct structs. The EntityStruct struct has the same member names and types as the LobSystemInstanceStruct struct. Listing 27.2 contains sample code that enumerates through the list of entities that belong to a given LOB system instance and the properties associated with that entity.

Note that to invoke the GetEntitiesForLobSystemInstance method, you need to supply the numeric identifier for the LOB system instance. You can figure out the ID for the LOB system instance by examining the id property of the LobSystemInstanceStruct struct returned by the web service. In the sample shown in Listing 27.2, the ID supplied is that of the AdventureWorks sample instance.

Listing 27.2. Enumerating Entities and Associated Properties

When the preceding code is compiled and executed against the Adventure Works sample BDC application, it produces output like that shown in Figure 27.2.

Figure 27.2. Enumerating entities and associated properties.

One of the types of metadata that resides below the entity level in the BDC is the method. A method is an action that can be performed on an action (though methods cannot be directly invoked via the BDC Web Service). You can use the GetMethodsForEntity and the GetMethodInstancesForEntity methods to return method and method instance structures. Table 27.2 contains a list of the properties on the MethodStruct structure.

Table 27.2. MethodStruct Properties

Table 27.3 contains a list of properties on the MethodInstanceStruct structure.

Table 27.3. MethodInstanceStruct Properties

Listing 27.3 shows a sample of enumerating methods and method instances for each entity within a BDC application.

Listing 27.3. Enumerating Methods and Method Instances

When the preceding code is compiled and executed, the output resembles that of the output shown in Figure 27.3.

Figure 27.3. Enumerating methods and method instances.

Below the method level in the hierarchy, there are method filter descriptors, which can be retrieved and enumerated much like the rest of the metadata illustrated so far in this chapter. Listing 27.4 shows how to do this.

Listing 27.4. Enumerating Filter Descriptors for a Method

When the preceding code is compiled and executed, the output resembles the following snippet:

ID
        Comparator (System.String) : Equals
Name

Using the BDC Field Resolver Web Service

Although you might not be able to directly execute methods against the entities within the BDC using web services, you can make use of the BDC Field Resolver Web Service to retrieve a list of fields and their associated values for a given entity.

Just like with the BDC Web Service, the BDC Field Resolver Web Service is provided by MOSS. You can access it via the uniform resource locator (URL) http://server:port/_vti_bin/bdcfieldsresolver.asmx.

The code in Listing 27.5 illustrates how to enumerate the fields and values associated with a given entity.

Listing 27.5. Using the BDC Field Resolver Web Service

The Resolve method takes the following arguments:

• systemInstance—The name (not numeric ID) of the LOB system instance in which the value should be resolved
• entity—The name of the entity being resolved (for example, Customer, Product)
• valueToResolve—The identifier value of the entity to be resolved
• fieldNames—A colon-delimited string of field names to resolve into values

You might have noticed that the field names passed to the Resolve method for the second example don’t have spaces contained in them. That is because the actual names of the fields must be passed into the method, not the descriptions. You can get at the names of the fields easily if you were the one who developed the BDC application, or you can simply query the BDC application Registry using the object model or using the web service discussed earlier in this chapter.

When the preceding code is compiled and executed against the AdventureWorks sample BDC application, the output looks similar to the following:

UniqueMatch
FirstName:Jon
LastName:Yang

UniqueMatch
Name:Mountain-500 Black, 52
ListPrice:539.9900
ProductNumber:BK-M18B-52

Summary

The Business Data Catalog is an integral part of the new Microsoft Office SharePoint Server 2007. It allows developers and end users to access data contained within remote Line of Business systems, creating an environment of integration and aggregation that was previously painstaking and costly to develop manually. This chapter provided illustrations of how to interact with the BDC using two BDC web services: the BDC Web Service and the BDC Field Resolver Web Service.