Creating a Web Service Connection by using the Business Data Catalog Definition Editor

Summary: Learn how to create a Web service connection for the Business Data Catalog in Microsoft Office SharePoint Server 2007 by using the Microsoft Business Data Catalog Definition Editor tool for Microsoft Office SharePoint Server 2007. (32 printed pages)

Jo-Anne West, Microsoft Corporation

August 2007

Applies to: Microsoft Office SharePoint Server 2007

Contents:

• Overview of Business Data Catalog Definition Editor

• Adding an LOB System

• Configuring the SampleWebService LOB System Settings

• Configuring the Customer Entity Name and Identifier

• Configuring the Customer Entity Methods

• Creating Method Instances

• Creating Associations

• Testing the Method Instances

• Exporting the LOB System Instance Metadata

• Importing the Application Definition File into the Shared Services Provider

• Modifying an Existing Application Definition by using the Business Data Catalog Definition Editor

• Next Steps

• Conclusion

• Additional Resources

Overview of Business Data Catalog Definition Editor

The Business Data Catalog in Microsoft Office SharePoint Server 2007 exposes and incorporates line-of-business (LOB) data into other baseline portal functionality, such as lists and Enterprise Search. To incorporate this data into your portal site, you must build an application definition file, which is an XML file that identifies where the data is stored (either in a database, or as a Web service) and what format the data is stored in (for example, what the data types and primary keys are).

For more information about the Business Data Catalog, see Business Data Catalog. For more information about Enterprise Search and the Business Data Catalog, see Enabling Business Data Search, and Searching Business Data. For details about how you can use the Business Data Catalog Definition editor to create a connection to database, see Creating a Database Connection by using the Business Data Catalog Definition Editor.

The Microsoft Business Data Catalog Definition Editor helps you to create application definition files for the Business Data Catalog. This tool automatically generates the XML for the definition file, so you do not need to manually create the file in an XML editor.

This how-to topic shows you how to create an application definition file for the Business Data Catalog and how to create a connection to a Web service by using the new Business Data Catalog Definition Editor. This example uses the Walkthrough: Sample Web Service, included with the Microsoft Office SharePoint Server 2007 Software Development Kit (SDK).

System Requirements

Before you begin, you must install the following:

• Microsoft Office SharePoint Server 2007, Enterprise Edition.

• Microsoft Business Data Catalog Definition Editor. This tool is part of the Microsoft Office SharePoint Server 2007 SDK download (beginning with the 1.2 release, August 2007).

To build a Business Data Catalog application definition file, use the following procedures.

Adding an LOB System

Begin by adding a LOB system.

To add an LOB system

1. On the Start menu, click Microsoft Business Data Application Definition Editor.

2. In the tool, click Add LOB System.

   Figure 1. Add LOB System

   

3. In the Add LOB System window, click Connect to Webservice.

4. Enter the Web service URL.

   Figure 2. Entering the Web service URL

   

5. Click Connect.

6. Click Add Web Method.

   Figure 3. Add Web method

   

7. Drag the following methods to the Design Surface:

   • GetChildCustomersForCustomer

   • GetCustomerIDs

   • GetCustomers

   • GetCustomerByID

8. Click OK.

   Figure 4. Web methods added

   

9. In the LOB System Name dialog box, type SampleWebService in the LOB System Name field, and then click OK to create the connection to the Web service.

   Figure 5. Create the connection to the Web service

   

Configuring the SampleWebService LOB System Settings

Next, configure the SampleWebService LOB system settings, such as the authentication mode and wildcard character settings.

To configure the SampleWebService LOB system settings

1. In the Metadata Objects pane, select the SampleWebService node.

2. In the Properties pane, type "$" in the WildCardCharacter field.

   Note

   The wildcard character is usually either the "$", "*", or the "%" character, depending on the LOB system.

   Figure 6. Wildcard property

   

3. In the WsdFetchAuthenticationMode field, click PassThrough.

   Figure 7. WsdFetchAuthenticationMode property

   

Configuring the Customer Entity Name and Identifier

Now you can configure the Customer entity for the SampleWebService LOB system.

To configure the Customer entity

1. Expand the SampleWebService node, and then expand the Entities node.

2. Select the Entity0 node.

   Figure 8. Entity0 node

   

3. In the Properties pane, type Customer in Name field.

   Note

   The DefaultDisplayName field updates automatically as soon as you navigate from the Name field.

   Figure 9. Entity Name property

   

4. In the Metadata Objects pane, expand the Customer node.

5. Right-click the Identifiers node, and then select Add Identifier.

   Figure 10. Add identifier

   

6. In the Properties pane, type CustomerID in the Name field.

   Figure 11. Customer entity identifier Name property

   

7. Select System.String for the Type field.

   Figure 12. CustomerID Type property

   

Configuring the Customer Entity Methods

Next, configure the following Customer entity methods:

• GetChildCustomersForCustomer

• GetCustomerIDs

• GetCustomers

• GetCustomerByID

First, you map the method parameters for each method. Then add filters to the GetCustomerIDs method. Finally, you associate the method parameters with the filters.

To map the parameters for GetChildCustomersForCustomer method

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetChildCustomersForCustomer node.

2. Expand the Parameters node, and then expand the custid node.

3. Select custid.

   Figure 13. custid parameter

   

4. In the Properties pane, select CustomerID[Customer] from the Identifier list.

   Figure 14. custid Identifier property

   

5. In the Metadata Objects pane, within GetChildCustomersForCustomerParameters node, expand the Return node, and then expand the second Return node.

6. Expand the Item node, and select CustomerID.

   Figure 15. CustomerID parameter

   

7. In the Properties pane, select CustomerID[Customer] from the Identifier list.

   Figure 16. CustomerID Identifier property

   

To map the parameters for GetCustomerIDs method

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetCustomerIDs node.

2. Expand the Parameters node, then expand the Return node, and then expand the second Return node.

3. Expand the Item node.

4. In the Properties pane, select CustomerID[Customer] from the Identifier list.

To map the parameters for GetCustomers method

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetCustomers node.

2. Expand the Parameters node, expand the Return node, and then expand the second Return node.

3. Expand the Item node, and then select CustomerID.

4. In the Properties pane, select CustomerID[Customer] from the Identifier list.

To map the parameters for GetCustomerByID method

1. In the Metadata Objects window pane, expand the Methods node, and then expand the GetCustomerByID node.

2. Expand the Parameters node, expand the id node, and then select id.

3. In the Properties pane, select CustomerID[Customer] from the Identifier list.

4. In the Metadata Objects pane, within GetCustomersByIDParameters node, expand the Return node, and then expand the second Return node.

5. Expand the Item node, and select CustomerID.

6. In the Properties pane, select CustomerID[Customer] from the Identifier list.

To configure the filters for GetCustomers method

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetCustomers node.

2. Right-click Filters, and then click Add Filter.

   Figure 17. Add Name filter for GetCustomers method

   

3. In the Properties pane, type Name for the Name field.

   Figure 18. Name property for GetCustomers Name filter

   

4. In the FilterType field, select WildcardFilter.

   Figure 19. FilterType property for GetCustomers Name filter

   

5. Repeat Steps 1-3; however, this time type Limit in the Name field.

6. In the FilterType field, select Equals.

   Figure 20. FilterType property for GetCustomers Limit filter

   

To associate parameters with filters

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetCustomers node.

2. Expand the Parameters node, and then expand the name node.

3. Select name.

   Figure 21. GetCustomers name parameter

   

4. In the Properties pane, select Name from the FilterDescriptor list.

   Figure 22. GetCustomers name parameter FilterDescriptor property

   

5. Repeat Steps 1-3 for the limit parameter.

6. In the Properties pane, select Limit from the FilterDescriptor list.

Creating Method Instances

Now you create the following method instances:

• IDEnumerator method instance type for the GetCustomerIDs method

• Finder method instance type for the GetCustomers method

• Specific Finder method instance type for the GetCustomerByID method.

To create the GetCustomerIDs IDEnumerator method instance

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetCustomerIDs node.

2. Right-click Instances, and then select Add Method Instance to open the Create Method Instance window.

   Figure 23. Add method instance for GetCustomerIDs

   

3. In the Create Method Instance window, select Id Enumerator for Method Instance Type, and then click OK.

   Figure 24. Select method instance type

   

4. In the Properties pane, type GetCustomerIDsInstance for the Name field.

   Figure 25. GetCustomerIDs method instance Name property

   

To create the GetCustomers Finder method instance

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetCustomers node.

2. Right-click Instances, and then select Add Method Instance to open the Create Method Instance window.

3. Select Finder for Method Instance Type, and click OK.

4. In the Properties window pane, type GetCustomersInstance for the Name field.

To create the GetCustomerByID Specific Finder method instance

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetCustomerByID node.

2. Right-click Instances, and then select Add Method Instance to open the Create Method Instance window.

3. Select Specific Finder for Method Instance Type, and then click OK.

4. In the Properties pane, type GetCustomerByIDInstance for the Name field.

Creating Associations

Next, create the association for the GetChildCustomersForCustomer method.

To create the association

1. In the Metadata Objects pane, expand the Methods node, and then expand the GetChildCustomersForCustomer node.

2. Right-click Instances, and then select Add Method Instance to open the Create Method Instance window.

3. Select Association for Method Instance Type.

4. Select Customer for the Source Entity field.

5. Select the Return node for the Return TypeDescriptor field.

   Figure 26. Create GetChildCustomersForCustomer method instance

   

6. Click OK.

7. In the Properties pane, type CustomerToChildCustomers for the Name field.

   Figure 27. GetChildCustomersForCustomer Name property

   

Testing the Method Instances

Now you can test the method instances.

To test the CustomerToChildCustomers method instance

1. In the Metadata Objects pane, expand the GetChildCustomersForCustomer node within the Methods node, and then expand the Instances node.

2. Right-click CustomerToChildCustomers, and then select Execute to open the Execute window for the method instance.

   Figure 28. Execute CustomerToChildCustomers method instance

   

3. Click the Search button or click anywhere in the Value field to open the Select Entity Instance window.

   Figure 29. Execute CustomerToChildCustomers window

   

4. Select GetCustomerIDsInstance, and then click Next to display the first page of results.

   Figure 30. GetCustomerIDsInstance method results

   

5. Select one of the CustomerID values returned in the results, and then click OK to return to the Execute window.

   Figure 31. Select CustomerID

   

6. Click Execute to display the customer data associated with the CustomerID you selected.

   Figure 32. CustomerToChildCustomers method results

   

7. Verify that the customer data that appears is for the CustomerID that you specified.

To test the GetCustomerIDsInstance method instance

1. In the Metadata Objects pane, expand the GetCustomerIDs node within the Methods node, and then expand the Instances node.

2. Right-click GetCustomerIDsInstance, and then select Execute to open the Execute window for the method instance.

   Figure 33. Execute GetCustomerIDsInstance method

   

3. Click Next to display the first page of results and verify that CustomerIDs are displayed.

   Figure 34. GetCustomerIDsInstance method results

   

4. Click Next to page through the results.

To test the GetCustomersInstance method instance

1. In the Metadata Objects window pane, expand the GetCustomers node within the Methods node, and then expand the Instances node.

2. Right-click GetCustomersInstance, and select Execute to open the Execute window for the method instance.

   Figure 35. Execute GetCustomersInstance method

   

3. Enter the sample value A for the Name field.

4. Enter the sample value 2 for the Limit field.

5. Click Execute to display the results for the sample query.

   The query should return no more than two results, and the first letter of the Name field value should be A.

   Figure 36. GetCustomersInstance method results

   

To test the GetCustomerByIDInstance method instance

1. In the Metadata Objects pane, expand the GetCustomers node within the Methods node, and then expand the Instances node.

2. Right-click GetCustomerByIDInstance, and then select Execute to open the Execute window for the method instance.

   Figure 37. Execute GetCustomerByIDInstance method

   

3. Enter a value, such as 1000 for the CustomerID field.

4. Click Execute to display the customer data for the CustomerID value that you entered.

   Figure 38. GetCustomerByIDInstance method results

   

Exporting the LOB System Instance Metadata

After you confirm that the connection for the LOB system, along with the entities, associations, and methods, are configured correctly within the Business Data Catalog Definition Editor, you are ready to export the LOB system instance metadata to an application definition file.

To export the metadata

1. Select the SampleWebService node in the Metadata Objects window, and then click Export.

   Figure 39. Export SampleWebService application definition

   

2. Save the file as SampleWebService.xml.

   Figure 40. Save SampleWebService application definition file

   

Importing the Application Definition File into the Shared Services Provider

Next you import the application definition file into the Shared Services Provider (SSP).

To import the application definition file into the SSP

1. To start the SharePoint 3.0 Central Administration Web page, click Start, and then point to All Programs. Point to Microsoft Office Server, and click SharePoint 3.0 Central Administration.

2. In the left navigation pane, click the name of your SSP.

3. In the Business Data Catalog section, click Import application definition.

4. In the Import Application Definition page that opens, browse to SampleWebService.xml, select the file, and then click Open.

5. Click Import.

6. Click Browse, locate the file, and then double-click it.

7. Leave all other application definition settings with their default values, and then click Import.

Modifying an Existing Application Definition by using the Business Data Catalog Definition Editor

You can also modify the metadata in an existing application definition file by importing it into the Business Data Catalog Definition Editor. If you are modifying the application definition for an existing application in the Business Data Catalog, you must export the metadata file for the application definition from the SSP first.

To export the application definition file from the SSP

1. To start the SharePoint 3.0 Central Administration Web page, click Start, point to All Programs, and then point to Microsoft Office Server and click SharePoint 3.0 Central Administration.

2. In the left navigation pane, click the name of your SSP.

3. In the Business Data Catalog section, click View applications.

4. In the Applications list, click the application name.

5. Click Export Application Definition to open the Export Application Definition page.

6. Click Export, and then click Save.

To import an application definition file into the Business Data Catalog Definition Editor and modify the metadata

1. On the Start menu, click Microsoft Business Data Catalog Definition Editor.

2. Click Import.

3. Browse to the location of the application definition file, select it, and then click Open.

   After the LOB system data is loaded into the Business Data Catalog Definition Editor, you can make several changes to the LOB system instance, such as:

   • Changing the connection string

   • Changing the authentication mode

   • Adding or removing entities

Next Steps

After completing these tasks, you can configure Enterprise Search to crawl this content so that your users can search business data. For information about how to configure Enterprise Search, see Walkthrough: Configuring Search for the AdventureWorks Business Data Application Sample. For details about how you can customize the Search user interface this scenario, see Walkthrough: Add a Tab and Custom Search Page with Enterprise Search Web Parts to the Search Center.

Conclusion

The Business Data Catalog in Microsoft Office SharePoint Server 2007 enables you to integrate LOB data that is hosted outside of the portal into elements such as lists and Enterprise Search within Office SharePoint Server 2007. The Business Data Catalog requires a definition file with metadata that defines the connection to the external data source and identifies the data type that is being retrieved from the data source.

The Business Data Catalog Definition Editor automatically generates the XML metadata for the LOB system, making it easy to create an application definition file for the Business Data Catalog.

Additional Resources

For more information about the Business Data Catalog and Office SharePoint Server 2007, see the following resources:

• Microsoft Office SharePoint Server 2007 SDK download

• Microsoft Office SharePoint Server 2007 SDK online

• Business Data Catalog Information Center

• SQL Server 2005 Samples and Sample Databases