Editing Business Data Using Business Data Catalog Actions and InfoPath Forms Services
Summary: Learn how to build applications that use the Business Data Catalog in Microsoft Office SharePoint Server 2007 with Web services and the Single Sign-On Service. Then, examine using Microsoft Office InfoPath 2007 and Microsoft Office Forms Services to edit the data that is returned through the Business Data Catalog. (32 printed pages)
Jason Masterman, Collaboration Experts
June 2008
Applies to: Microsoft Office SharePoint Server 2007, Microsoft Office InfoPath 2007, Microsoft Office Forms Services 2007
Contents
Overview
Enterprise Application Integration Scenario
Business Data Catalog Overview
Defining Application Metadata and the Business Data Catalog
Security and the Business Data Catalog
Security and the Business Data Catalog
Deploying an InfoPath Form Using InfoPath Forms Services
Configuring InfoPath Forms Services for Single Sign-On
Expanding the Business Data Catalog Application
Conclusion
Additional Resources
Download the sample that accompanies this article: Editing Business Data Using BDC Actions and InfoPath Forms Services: Sample Code
Overview
In an enterprise, users want and need better access to the information that is available throughout the enterprise organization. Typically, enterprise information is stored and made available through several different databases and Web services. Common systems in a large enterprise can include SAP, PeopleSoft, Seibel, Oracle, Microsoft SQL Server and many Web services. However, these back-end Web services and databases all require various data access technologies and authentication models for connection and authentication needs.
Developers in the enterprise need a way to build applications that can easily aggregate the information in these various back-end systems and Web services to quickly and easily surface the data to end users. In the process of making available large amounts of disparate information, developers must also build systems that are more secure and easier to maintain for the life of the application.
Microsoft Office SharePoint Server 2007 simplifies access and broadens the reach of enterprise application data through a new feature, the Business Data Catalog. The Business Data Catalog provides enterprise integration with back-end databases and Web services. You can access data exposed via the Business Data Catalog throughout all aspects of Office SharePoint Server 2007, such as through the new Business Data Catalog Web Parts, lists, search, user profiles, and custom applications that use the Business Data Catalog APIs.
Enterprise systems often require different mechanisms for authentication, many of which are not standard Windows Authentication mechanisms. But users want an easy way to access information across multiple back-end systems without being required to authenticate independently with each system. Microsoft Office SharePoint Portal Server 2003 introduced a single sign-on (SSO) service credential store that could house multiple credentials for a single user or application. Office SharePoint Server 2007 enhances this service and it can be used by Business Data Catalog applications. With the SSO service enhancements and the ability to use SSO applications from the Business Data Catalog, Office SharePoint Server 2007 can help provide secure and more easily managed access to enterprise systems.
This article does the following:
Examines how developers can build applications to take advantage of the Business Data Catalog
Focuses on using the Business Data Catalog with Web services while also using the SSO service
Addresses how to use Microsoft Office InfoPath 2007 and Microsoft Office Forms Services to edit data that is surfaced through the Business Data Catalog
Before Getting Started
This article refers to several different technologies. To get the most out of the example code it provides, you must configure all the required services to build the examples. Following is a list of useful resources for the specific technologies used, and references to setup information.
Shared Services
Business Data Catalog
Single Sign-On
Web Services Installed on Microsoft Internet Information Services (IIS)
InfoPath and Microsoft Office Forms Services
Download the Code
To understand and best use the examples that are discussed in this article, be sure to download Editing Business Data Using BDC Actions and InfoPath Forms Services: Sample Code.
Enterprise Application Integration Scenario
This section describes the enterprise application integration scenario and the general steps to build it. Following is a general diagram of the scenario.
Figure 1. Diagram of enterprise application integration scenario
.gif "Enterprise application integration scenario")
General Steps to Building the Scenario
The following list of steps is not meant to serve as a complete set of setup instructions, but instead provides an overview of what you need to accomplish for the scenario to work.
Download and attach the Adventure Works Cycles Database 2000 database to an instance of SQL Server.
Build the Adventure Works Cycles Database 2000 Web service. The Web service must do the following:
Return a list of customers.
Return the details of a single customer, given an ID.
Update customer details.
Allow configuration of a Web service on IIS with security, so that credentials must be provided to access the Web service.
Create an SSO application.
The SSO application provides credentials for the Business Data Catalog application to access the Adventure Works Web service.
Build a Business Data Catalog application for using the Adventure Works Web service.
The Business Data Catalog application will do the following:
Use Business Data Catalog–generated proxy classes for type information.
Use SSO for credentials to access the Web service.
Provide Actions for modifying customer records via a Microsoft Office InfoPath form deployed by using Microsoft Office Forms Services 2007.
The InfoPath form deployed by using Form Services does the following:
Loads customer data passed to it when users click Business Data Catalog Actions.
Enables access (through its configuration) via Form Services and any browser.
Upon initiation accepts parameters passed to it from the Business Data Catalog Actions link and load data.
Writes changes back via the Adventure Works Web service
Business Data Catalog Overview
The Business Data Catalog defines a metadata model for connecting, accessing, retrieving, and acting upon data in databases and Web services. This metadata model allows a developer to define a Business Data Catalog application in the form of XML or through the Business Data Catalog APIs. After a Business Data Catalog application is created, users can access the applications without writing code. Users can place Business Data Catalog Web Parts on SharePoint site pages and connect them to the entities defined in the Business Data Catalog application or via code that uses the Business Data Catalog APIs. The Business Data Catalog Web Parts then render the back-end systems data within the Web Parts.
The Business Data Catalog is made available through the shared services of Microsoft Office SharePoint Server 2007. You must configure shared services before creating any Business Data Catalog applications. For more information about how to configure shared services, see the Office SharePoint Server setup.
The Microsoft Office SharePoint Server 2007 SDK offers key examples that demonstrate the use of the Business Data Catalog with both databases and Web services. This article focuses on Web services to provide more detailed knowledge of how to take advantage of the Business Data Catalog via Web services. Detailed information about the Business Data Catalog itself is available in the Microsoft Office SharePoint Server 2007 SDK.
Business Data Catalog Web Parts
Table 1 describes the Business Data Catalog Web Parts and their uses.
Table 1. Business Data Catalog Web Parts
| Web Part Name | Description |
|---|---|
Business Data Actions |
Displays a list of actions from the Business Data Catalog. |
Business Data Item |
Displays one item from a data source in the Business Data Catalog. |
Business Data Item Builder |
Creates a business data item from parameters in the query string and provides it to other Web Parts. The Web Part is used only on Business Data profile pages. |
Business Data List |
Displays a list of items from a data source in the Business Data Catalog. |
Business Data Related List |
Displays a list of related items to one or more parent items from a data source in the Business Data Catalog. |
Web Services Used in this Article
To help readers better understand how to use the Business Data Catalog with Web services, this article makes use of the scenarios defined in the Microsoft Office SharePoint Server 2007 SDK for the AdventureWorks2000 database, and wraps them with Web services. For example, the Microsoft Office SharePoint Server 2007 SDK defines a Business Data Catalog application for connecting to and accessing customers from the AdventureWorks2000 database. This article describes how to connect to a Web service that uses the AdventureWorks2000 database and how to return customer records from the Web service. This scenario provides the reader with the detailed information about how to configure a Business Data Catalog application that uses a Web service and all its corresponding methods, inputs, and outputs—similar to the Business Data Catalog samples in the SDK that use the Adventureworks2000 database without Web services. Because the Adventureworks2000 database defines "Customer" records (and to many developers a "customer" is a "customer"), when working in a Web service scenario the types differ from those of a Business Data Catalog application using ADO.NET to connect to a back-end database.
After looking at how to build a Business Data Catalog application that uses a basic Web service from scratch, we make use of one of the Web services samples provided in the Microsoft Office SharePoint Server 2007 SDK—SampleWebService—to discuss additional features such as Associations. Associations provide the glue that connects different entities, such as Customers to Orders, which are provided in a back-end set of Web service methods.
AdventureWorks Web Service
The first Web service we look at, the AdventureWorks Web service defined for this application, provides three key methods. The first method returns a list of customers. This method is passed a string that is queried against the database for any customers whose last name contains the provided string. The second method returns the details of a specific customer; the customer ID is passed as input. The third method is provided for updating customer information. The following code shows the method signatures for the three methods.
Code listing 1
[WebMethod]
public Customer[] GetCustomers(string LastName)
{…}
[WebMethod]
public Customer GetCustomer(int CustomerID)
{…}
[WebMethod]
public void UpdateCustomer(Customer customer)
{…}
The customer record that is returned is a simple Microsoft .NET Framework type that can easily be serialized by the XmlSerializer class used for serializing types in Web service methods. Following is the class definition of the customer type.
Code listing 2
public class Customer
{
public int IndividualID;
public string FirstName;
public string LastName;
}
Remember that any class defined in the .NET Framework and returned as a method of a Web service must be serialized easily into XML that can be consumed by other systems. In our example, the Customer class returns basic primitive types: two strings for first and last name and an integer type for the customer's ID.
Defining Application Metadata and the Business Data Catalog
The first step in creating a Business Data Catalog application is to define the application metadata. You can build the metadata needed for a Business Data Catalog application in two ways:
Define the metadata by building an XML file that can be imported later into the Business Data Catalog through the SharePoint Central Administration pages.
Use the Business Data Catalog APIs to create the metadata directly in the database. The application can then be exported to XML via the SharePoint Central Administration pages.
For this example, the Business Data Catalog application was defined directly in an XML file without using the Business Data Catalog APIs.
Defining the Business Data Catalog Application Metadata
Building the Business Data Catalog application XML requires an understanding of the Business Data Catalog schema and required elements, and detailed knowledge of the back-end system that is being accessed. Business Data Catalog applications are typically generated by developers or database administrators who have significant knowledge of the entities being exposed in the back-end systems. To generate the Business Data Catalog application XML via a graphical tool, you can use the Business Data Catalog Definition Editor tool (which is available in the Microsoft Office SharePoint Server 2007 SDK download). The minimal Business Data Catalog application contains the following XML top-level node and subelements, which are described in more detail in the following sections.
Code listing 3
<?xml version="1.0" encoding="utf-8" ?>
<LobSystem
Type="WebService"
Version="2.0.0.0"
Name="AdventureWorksWebService"
xmlns="https://schemas.microsoft.com/office/2006/03/BusinessDataCatalog">
<Properties>
<!--Used for defining:
- The Web service URL,
- Wsdl proxy namespace
- and other general information. -->
</Properties>
<!--LobSystemInstances purpose is to provide authentication
and connection information. -->
<LobSystemInstances>
<LobSystemInstance Name="AdventureWorksWebService">
<!--Connection properties -->
<Properties>...</Properties>
</LobSystemInstance>
</LobSystemInstances>
<!--Entity information: a business object that exists in the line of
business application - in this example the "Customer". -->
<Entities>
<!--Customer Entity-->
<Entity Name="Customer">
<!--Customer -->
<Properties>...</Properties>
<Identifiers>
<!--Identifiers enable the Business Data Catalog to uniquely
identify an entity instance such as a particular customer.
Identifiers are required to do anything useful with the
entity instance. -->
</Identifiers>
<!--Methods provide the operations related to the entity. -->
<Methods>
<Method Name="GetCustomers">...</Method>
<Method Name="GetCustomer">...</Method>
</Methods>
<!--Actions provide a mechanism for acting on the
data from a particular entity. In our example, actions are
used to connect to an InfoPath form for editing customers. -->
<Actions>...</Actions>
</Entity>
</Entities>
</LobSystem>
Understanding the Business Data Catalog Schema and Metadata
Microsoft provides a Business Data Catalog schema to help you define the XML required for Business Data Catalog applications. When using Microsoft Visual Studio 2005 to build XML definitions for Business Data Catalog applications, ensure the XML document schema property is set to "bdcmetadata.xsd", located in the path drive:\Program Files\Microsoft Office Servers\12.0\Bin. In Visual Studio, select the XML document properties as shown in Figure 2.
Figure 2. XML document properties to select
.gif "XML document properties to select")
Making a reference to the bdcmetadata.xsd file provides IntelliSense within the XML editor of Visual Studio.
LobSystem Element
If you take a closer look at the XML Business Data Catalog application definition defined earlier, you see the top-level node <LobSystem>. This is the root element of the Business Data Catalog application metadata definition. The Type attribute specifies whether this is a database or Web service application type. We are using a Type of WebService because our Business Data Catalog application will retrieve data from a Web service. The Version specifies the version of the Business Data Catalog application definition and is verified when importing a definition to ensure that new definitions do not overwrite existing application definitions. Finally, the Name attribute defines the name of the application.
LobSystem Properties
Within the Lobsystem element we have defined the properties shown in Code listing 4.
Code listing 4
<Properties>
<Property Name="WildCardCharacter"
Type="System.String">%
</Property>
<Property Name="WsdlFetchUrl"
Type="System.String">http://basicauth/AdventureWorksWS/Service.asmx
</Property>
<Property Name="WebServiceProxyNamespace"
Type="System.String">AdventureWorksNamespace
</Property>
</Properties>
Following are the definitions for the previous properties:
WildCardCharacter Allows the Business Data Catalog application developer to specify what wildcard character the back-end system expects when submitting queries.
WsdlFetchUrl Provides the address that the Business Data Catalog application uses during the import process to fetch the Web Services Description Language (WSDL) for the Web service application and builds the generated proxies.
WebServiceProxyNamespace Provides a way for developers to specify a namespace to contain the generated proxy classes. The WebServiceProxyNamespace property is a very important property that is used later when defining the types passed into and returned from the methods defined on an entity.
LobSystemInstances Element
After specifying the LobSystem element and properties, a LobSystemInstances element is defined. This important section contains several pieces of information that our sample application needs to use the enterprise single SSO for connecting to our Web service.
Code listing 5
<LobSystemInstances>
<LobSystemInstance Name="AdventureWorksWebService">
<Properties>
<Property Name="WebServiceAuthenticationMode"
Type="System.String">Credentials</Property>
<Property Name="WsdlFetchAuthenticationMode"
Type="System.String">Windows</Property>
<Property Name="WebServiceSsoApplicationId"
Type="System.String">EnterpriseServices</Property>
<Property Name ="SsoProviderImplementation"
Type="System.String">
Microsoft.SharePoint.Portal.SingleSignon.SpsSsoProvider,
Microsoft.SharePoint.Portal.SingleSignon, Version=12.0.0.0,
Culture=neutral, PublicKeyToken=71e9bce111e9429c
</Property>
</Properties>
</LobSystemInstance>
</LobSystemInstances>
Following are definitions for the previous properties:
WebServiceAuthenticationMode Specifies the type of credentials the Business Data Catalog passes when invoking methods defined on entities in the application. For our example, the web service will be invoked by passing a custom set of user credentials retrieved from the SSO application. The credentials retrieved from the SSO application are not the credentials of the currently authenticated user viewing the Web page containing the Business Data Catalog Web Part. These credentials used for calling the Web service are read from the SSO application specified in the WebServiceSsoApplicationId property shown above.
WsdlFetchAuthenticationMode Provides a way of specifying the type of credentials used when first importing the Business Data Catalog application and retrieving the WSDL to generate the Web service proxy classes. This is a useful feature as it allows users to use credentials from the SSO store when working with Business Data Catalog Web Parts that talk to the Business Data Catalog application, but allows administrators to use a different set of credentials when they are simply trying to configure the application.
WebServiceSsoApplicationId Contains the name of the SSO application that the Business Data Catalog connects to for retrieving credentials when invoking this LOB application. In our example, the SSO application name is EnterpriseServices.
Note
Take care when setting this property as there is a similar property named SsoApplicationId that is used for database application types.
SsoProviderImplementation Contains the namespace qualified class name and strong-named assembly name of the SSO provider to use. Because Office SharePoint Server 2007 provides the ability to have custom SSO providers, this value can be different in situations where a custom provider is configured. In our example, we use the default provider included with Office SharePoint Server 2007.
Entities Element and Entity Element
At the heart of a Business Data Catalog application definition are the Entities it describes. The Entities element can contain multiple Entity elements. The Entity elements contained within the Entities element are the business objects belonging to a database or Web service back-end LOB system. In our first example the Customer is the entity defined for the Web service LOB system being used. The Entities and Entity elements themselves are straightforward to define. However, the child elements contained within them require more explanation.
Following is the beginning element definition for the Customer entity. Notice that beside the Name attribute is the EstimatedinstanceCount attribute. This attribute provides an estimate of the number of entity instances and can be used by client applications to determine how to display the returned entities.
Code listing 6
<Entity Name="Customer" EstimatedInstanceCount="20000">
Entity Properties
At the top of our Customer entity definition is the Properties element, which contains the specific properties defined for this entity. In our example the only Property element defined is the Name property. This property specifies the name of a type that is defined later in the TypeDescriptor elements. This property is important because it is used to set the default column displayed for the entity in Business Data Lists and the column to display on the Actions menu.
Code listing 7
<Properties>
<Property Name="IndividualID"
Type="System.String">IndividualID
</Property>
</Properties>
Entity Identifiers
Entity identifiers are absolutely essential to any entity definition in which end users want the full support of all the Business Data Catalog Web Parts. Entity identifiers allow the Business Data Catalog to uniquely identify an entity instance. The identifier element provides a way of specifying the unique key (in database terminology) that uniquely identifies a record or entity instance. Surprisingly, the entity identifier element is not a required element. However, without defining the identifier many Business Data Catalog features simply cannot be performed. Specific entity instances cannot be identified without specifying an entity identifier. Without uniquely being able to identify entity instances, the action, search, and indexing features of the Business Data Catalog cannot be used. In our example, you uniquely identify the Customer entity through an integer field, IndividualID. The following code example defines the XML for this identifier.
Code listing 8
<Identifiers>
<Identifier TypeName="System.Int32" Name="IndividualID" />
</Identifiers>
Another important feature of Identifiers is the ability of the Business Data Catalog to support composite identifiers in the back-end LOB system. For an example of how to define composite identifiers, see "Walkthrough: Sample Web Service, Authoring Step 8: Define the LineItem entity" in the Microsoft Office SharePoint Server 2007 SDK. Excerpted from the SDK, the following code example shows how to define a composite identifier.
<Entity EstimatedInstanceCount="10000" Name="LineItem">
<Properties>
<Property Name="Title" Type="System.String">ProductName</Property>
</Properties>
<Identifiers>
<Identifier TypeName="System.String" Name="OrderID" />
<Identifier TypeName ="System.String" Name="ProductID" />
</Identifiers>
....
....
</Entity>
Entity Methods
Looking deeper into the entity metadata definition we find the methods that this particular entity supports. The Methods element is where the serious work in defining the metadata happens. The Methods element contains one or more Method elements. Each Method element describes the name of the method for accessing data in the LOB system and any input parameters or return types for the method. To better understand the Method element, think of it as defining a normal Microsoft Visual C# or Microsoft Visual Basic 2005 or later function, but doing so with XML. To get started defining method signatures in terms of XML, developers must understand the data types that are involved and how to define those types for the Business Data Catalog.
A discussion of type information in general is very useful before going into the details of how to define entity methods and their corresponding inputs and outputs. This section can be a bit tricky when working with Web services as the type information in the SDK examples can be confusing.
Understanding Types
Defining a Business Data Catalog application that consumes information provided through a Web service should be straightforward. However, because our Web service uses a complex type, the Customer type, you must first understand how the Business Data Catalog handles types when defining the metadata for an application.
Considering our options, in typical application development any application that consumes a Web service can have access to the Visual Studio IDE build proxies for working with those Web services by adding a reference to the Web service. Visual Studio adds the Web reference and behind the scenes invokes the wsdl.exe tool to generate proxy classes for working with the referenced Web service. These proxy classes are made a part of the application adding the reference and can be found by looking at the referencemap.cs file that is generated. You can generate these same proxy classes by running the wsdl.exe command line tool directly and passing the address of the Web service, as shown in the following code example.
Code listing 9
wsdl.exe http://someserver/somewebservice.asmx
This code will generate a Visual C# proxy class that you can include in any application that must invoke the Web service. The class provided in the proxy can be instantiated like any other class in Visual C# by using the new keyword, and methods exposed in the Web service can be invoked as methods on the generated proxy class. For example, for our Web service method definitions shown in Code listing 1, the generated proxy class would have a method named GetbCustomers that returns an array Customers, a GetCustomer method that returns a Customer, and an UpdateCustomer method that takes a Customer as a parameter.
At this starting point for working with a Web service, we need to answer several questions:
Will the Business Data Catalog build generated proxy classes automatically?
If the Business Data Catalog generates the proxy classes, where are they stored?
How can the information in the Web service proxy classes be described in the metadata that makes up a Business Data Catalog application?
What if the developer wants to generate an assembly that contains the type information instead of having the Business Data Catalog generate the proxies?
Where and how does the Business Data Catalog find and load the types specified in Business Data Catalog applications?
The Business Data Catalog can and by default will generate proxy classes for working with a Web service application automatically. The proxy classes used for working with the Web service are generated during the import of the XML Business Data Catalog application definition. To import a complete Business Data Catalog application definition, navigate to the SharePoint Central Administration pages Shared Services Provider, and in the Business Data Catalog section click the Import Application Definition link. Figure 3 shows the Import Application Definition page.
Figure 3. Import Application Definition page
.gif "Import Application Definition page")
During the import of the application definition, the WsdlFetchUrl specified in Code listing 4 is queried, and in the default scenario the Web service proxies are generated with an assembly that is stored in the database. This is then used to access the Web service methods.
The question for any developer trying to build Business Data Catalog applications is how to define metadata that represents the types defined in the Business Data Catalog generated proxies. References to types in XML files, such as an ASP.NET web.config file, will use the Namespace.ClassName, AssemblyName syntax for specifying types in sections such as httpModules or httpHandlers.
This similar syntax is used to specify types in Business Data Catalog application metadata, as shown in the following code example. In simple terms, the following example specifies that the method return type is an array of customers. The actual return type must be defined in detail in the metadata, breaking out all the underlying fields of an actual Customer record that is returned. Looking at the following example, notice that the actual XML is self-describing.
Code listing 9
<Parameter Direction="Return" Name="Customers">
<TypeDescriptor Name="ArrayOfCustomer" TypeName="AdventureWorksNamespace.Customer[],
AdventureWorksWebService" IsCollection="true">
<TypeDescriptors>
<TypeDescriptor Name="Customer" TypeName="AdventureWorksNamespace.Customer,
AdventureWorksWebService">
<TypeDescriptors>
<TypeDescriptor Name="IndividualID" IdentifierName="IndividualID" TypeName="System.Int32"/>
<TypeDescriptor Name="FirstName" TypeName="System.String" />
<TypeDescriptor Name="LastName" TypeName="System.String" />
</TypeDescriptors>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</Parameter>
However, given that the default behavior of the Business Data Catalog application import process is to generate the proxies automatically and store the assembly in the database, what is the actual Namespace, Class, and AssemblyName that is used? The Namespace value is easy to determine by looking at the metadata examples and the SDK documentation, and more specifically at the WebServiceProxyNamespace attribute specified in the LobSystem element (see Code listing 4). However, what is the name of the assembly that was stored in the database, and where do we specify the name of the assembly in our Business Data Catalog application XML? In the XML sample, the assembly name is the "AdventureWorksWebService" value specified after the "," in the TypeName attribute, shown in bold in the following code.
Code listing 10
TypeName="AdventureWorksNamespace.Customer[],AdventureWorksWebService
The value specified for the assembly name portion of a TypeName attribute is determined by the value of the Name attribute of the LobSystem element, shown in bold in the following code.
Code listing 11
<LobSystem
Type="WebService"
Version="2.0.0.0"
Name="AdventureWorksWebService"
In building out the example, we found that determining this value is difficult and that the sample Web service metadata is misleading. First we looked to determine how to set the assembly name value and tried several options; in one we tried to set the LobSystemName value. However, this attribute, though shown in the metadata example with the SDK, cannot be specified when importing an XML definition and an error is returned during the import process. It appears this value is set by the actual import process and can be seen when exporting a Business Data Catalog application.
Method Parameters and TypeDescriptors
Now that we have a better understanding of how to specify type information, let’s take a closer look at all the parameters defined for the GetCustomers method.
Code listing 12
<Parameters>
<Parameter Direction="In" Name="CustomerName">
<TypeDescriptor TypeName="System.String" Name="CustomerName" />
</Parameter>
<Parameter Direction="Return" Name="Customers">
<TypeDescriptor Name="ArrayOfCustomer" TypeName="AdventureWorksNamespace.Customer[],AdventureWorksWebService" IsCollection="true">
<TypeDescriptors>
<TypeDescriptor Name="Customer" TypeName="AdventureWorksNamespace.Customer,AdventureWorksWebService">
<TypeDescriptors>
<TypeDescriptor Name="IndividualID" IdentifierName="IndividualID" TypeName="System.Int32"/>
<TypeDescriptor Name="FirstName" TypeName="System.String" />
<TypeDescriptor Name="LastName" TypeName="System.String" />
</TypeDescriptors>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</Parameter>
</Parameters>
In the previous example, the first parameter defined is the input parameter Customer. This parameter is passed in when the GetCustomers method is called and is used by the Web service to find customers with last names similar to the value passed in. The definition of this parameter is a string data type as specified in the TypeDescriptor subelement. The next parameter is the Return parameter named Customers. This parameter specifies that an array of Customer types is returned. Notice that the actual TypeName attribute uses the array syntax "[]" for the Customer type and has an additional attribute IsCollection, which is set to true. Contained within the TypeDescriptors element of ArrayOfCustomer is the actual definition of the CustomerTypeDescriptor. Notice how the types are defined from the outside in, meaning the ArrayOfCustomer is specified first, then the Customer type, then the actual elements that make up the fields of a Customer. Each of these types is defined in XML in terms of a TypeDescriptor element.
Business Data Catalog Type Options
You have two options for defining type information when building Business Data Catalog applications that consume Web services.
The Business Data Catalog generates standard Web service proxy classes via wsdl.exe by invoking the Web service specified in the metadata. These proxy classes are generated when importing the Business Data Catalog application, and the assembly that contains the generated proxy classes is stored in the SQL Server database. The XML definitions refer to these types, as described earlier in this article.
The developer generates Web service proxy classes and the assembly directly. The generated assembly is placed in the global assembly cache. The XML metadata used in the TypeDescriptors references the strong-name types defined in the assembly, as shown in many of the SDK samples. For more information, see the Microsoft Office SharePoint Server 2007 SDK.
MethodInstance Elements
Next, for each entity method a MethodInstance element is defined to describe how to use the method and pass any default values. In this example, the GetCustomerMethod has a FindCustomerInstancesMethodInstance defined. This particular method is defined as a Finder method. There are several method types defined in the Microsoft Office SharePoint Server 2007 SDK documentation. However, to make an entity useful and get a basic sample working, developers must define a Finder method, and a SpecificFinder method is almost always needed. Finder methods provide a generic list of entity instances, while SpecificFinder methods find a particular instance. In our Web service example, the GetCustomers method provides the Finder, while the GetCustomer method provides the SpecificFinder. More information can be found in the Microsoft Office SharePoint Server 2007 SDK, but having at least these two method types makes entities easy to work with from most of the Business Data Catalog Web Parts that are provided by default.
Code listing 13
<MethodInstances>
<MethodInstance Name="FindCustomerInstances"
Type="Finder"
ReturnParameterName="Customers"
ReturnTypeDescriptorName="ArrayOfCustomer" />
</MethodInstances>
Actions
Actions provide a way of performing some task or action against the entity information listed in Business Data Catalog Web Parts. In the example provided, customers can be edited through Actions defined in the Business Data Catalog metadata. The Action allows the user to bring up the Customer data in an InfoPath form made available through Microsoft Office Forms Services. In the metadata example shown in Code listing 14, we define an Action that when clicked by the user loads the Customer.xsn InfoPath form. The InfoPath form is passed the Customer IndividualID, FirstName, and LastName field values. These values are dynamic, based on which customer is selected in the list of Customer instances from within the Business Data Catalog Data List Web Part.
Figure 4 shows the user experience for users, and what an Action can be used for. Users can select an individual Customer from the Customer List and then select the Edit Customer action item. The user sees a browser-based version of the InfoPath form for editing Customer data. The InfoPath form is passed the Customer values from the actual customer selected in the list, shown all through the use of Action information defined in the metadata.
Figure 4. User experience for users and example of an Action
.gif "User experience for users and example of an Action")
Following is the actual Actions metadata defined for this example.
Code listing 14
<Actions>
<Action
Name="Edit Customer"
Position="1"
IsOpenedInNewWindow="true"
Url="https://servername/SiteDirectory/teamsite/_layouts/FormServer.aspx?XsnLocation=https://servername/FormServerTemplates/Customer.xsn&DefaultItemOpen=1&IndividualID={0}&FirstName={1}&LastName={2}"
ImageUrl="">
<ActionParameters>
<ActionParameter Name="IndividualID" Index="0" />
<ActionParameter Name="FirstName" Index="1" />
<ActionParameter Name="LastName" Index="2" />
</ActionParameters>
</Action>
</Actions>
The most important part of the XML shown earlier is the URL value. There are several distinct pieces to the URL:
A Forms Services browser-based page for rendering the InfoPath template. In the previous example, the following value contains this information:
http://servername/SiteDirectory/teamsite/_layouts/FormServer.aspx?XsnLocation that defines the InfoPath template to load:
XsnLocation=http://servername/FormServerTemplates/Customer.xsnDefaultItemOpen=1that specifies to open the form via the browser.Any parameters the template expects and will load in the LoadingEvent of the InfoPath form. This is a name/value pair separated with "&". In our example, it is the three fields for the Customer, as shown in the following code:
&IndividualID={0}&FirstName={1}&LastName={2}"ActionParameters element that specifies the values substituted for the URL placeholders denoted with {0}, {1}, and {2}. In our example, the IndividualID value of an entity instance is passed as a parameter in the URL string "IndividualID{0}".
Building the first Business Data Catalog application and corresponding XML can be time-consuming and tedious. However, after a developer has the basics and understands the fundamental pieces defined earlier, the entire process becomes much easier and faster. Though several companies are providing tools to generate metadata so that developers do not need to manually generate the files, understanding the details can only help when the tools fail to work as expected or the development scenario is slightly different.
Security and the Business Data Catalog
The sample application we discussed uses the SSO service to provide credentials to the back-end Web service being called by the Business Data Catalog application. The following steps were used to configure the SSO application.
To configure the SSO application
Run the EnterpriseServicesSSO application provided in the code download (Editing Business Data Using BDC Actions and InfoPath Forms Services:Sample Code. This will create an SSO application named EnterpriseServices. You will want to modify these values and recompile the application. The default values are set to the following credentials for the currently logged-on user:
Username: WebServiceUser
Password: Pass@word1
Domain:JMCINC
Another option is to manually create the SSO application by using the following steps:
Create an SSO application named EnterpriseServices through the Central Administration pages.
Open the SharePoint Central Administration pages, click the Operations tab, and then click Manage settings for single sign-on.
Click Manage settings for enterprise application definitions.
Click New Item, and then specify the following values in the Create enterprise application definition page:
Display Name: Enterprise Services
Application Name: EnterpriseServices
Contact email address: An e-mail address you choose
Account Type: Individual
Field 1: Username
Field 2: Password
Field 3: Domain
Navigate to the Manage account information for enterprise application definitions page, and then select the EnterpriseServices application you created.
In the user account name section, type a domain qualified name and then set the username, password and domain fields to a valid account in Windows.
The credentials provided here are used by the Business Data Catalog application for connecting to our Web service application.
This completes building the SSO application and specifying credentials. The Business Data Catalog application metadata defined earlier can use this SSO application through the WebServiceSsoApplicationId property specified in the LobSystemInstance element.
Note
There are several ways of authenticating when building Business Data Catalog applications. The Microsoft Office SharePoint Server 2007 SDK addresses standard modes for working with databases. This example makes use of a different Windows user account for calling the Web service. This is done to ease the amount of additional configuration involved. Though the account used is a valid Windows user account, it is a different set of credentials from the user who is navigating to the Web page displaying the business data Web Part. The credentials stored in the SSO database could be completely unrelated to a valid Windows user account.
Deploying an InfoPath Form Using InfoPath Forms Services
You must develop and deploy an InfoPath form by using Forms Services to make use of the actions defined earlier for editing our Customers. Figure 5, which you can use for reference, shows the form.
Figure 5. InfoPath form
.gif "InfoPath form")
Following are the steps used to build the InfoPath form, deploy it, and connect it by using the Business Data Catalog Actions Web Part.
To build, deploy, and connect the InfoPath form
Start InfoPath and design a new blank form.
In the task pane on the right, from layouts select Table with title.
Click the Layouts drop-down list to change to the Controls view, and then add controls to produce the form that is shown in Figure 5.
On the Tools menu, point to Programming, and then click Loading Event.
Visual Studio starts and opens the code window for editing the form-loading event.
Add the following code to read and load the Customer parameters into the form.
public void FormEvents_Loading(object sender, LoadingEventArgs e) { XPathNavigator myNav = this.MainDataSource.CreateNavigator(); string id = e.InputParameters["IndividualID"].ToString(); string firstName = e.InputParameters["FirstName"].ToString(); string lastName = e.InputParameters["LastName"].ToString(); myNav.SelectSingleNode("/my:myFields/my:ID", this.NamespaceManager).SetValue(id); myNav.SelectSingleNode("/my:myFields/my:FirstName", this.NamespaceManager).SetValue(firstName); myNav.SelectSingleNode("/my:myFields/my:LastName", this.NamespaceManager).SetValue(lastName); }Ensure that the values used in the code match the name of the control IDs placed on the InfoPath form.
In the task pane on the right, click Design Checker.
Figure 6. Design Checker
.gif "Design Checker")
In the Design Checker, click the Change Compatibility Settings link. In the Form Options dialog box, under Categories, select Compatibility, and then select the Design a form template that can be opened in a browser or InfoPath check box, as shown in Figure 7.
Figure 7. Compatibility setting
.gif "Compatibility setting")
Save your InfoPath form on disk.
On the File menu, click Publish to publish the InfoPath form to a SharePoint site.In the dialog box that opens, select To a SharePoint server with or without InfoPath Forms Services.
On the next page, specify a team site URL to publish the form to.
On the next page, ensure that Enable this form to be filled out by using a browser is selected, as shown in Figure 8.
Figure 8. Enable this form to be filled out by using a browser
.gif "Enable this form to be filled out using a browser")
This will require that the InfoPath form being deployed is approved.
On the next page, specify the location for the form template that the administrator will use for approving and uploading to the forms server.
On the next page, add all the fields of the form to make them available for lists and Microsoft Office Outlook folders
Choose Publish to publish the form. Now that the form is published, it must be approved in InfoPath Forms Services.
Open the SharePoint Central Administration pages and navigate to the Application Management tab.
In the InfoPath Forms Services section, click Manage form templates.
On the next page, click the Upload form template link in the action bar on the page.
In the Upload Form Template page, click the browse button to navigate to the InfoPath form saved for approval in step 9.
Figure 9. Upload Form Template page
.gif "Upload Form Template page")
Click Verify to ensure there are no errors in the form. Then, after verification, click Upload to upload the form.After it is uploaded, the form must be approved for the site collection that you want to be able to use the form from. Navigate to the team site that will contain your Business Data Catalog Web Parts, and then on the Site Actions menu, click Site, and then click Go to top level site settings.
Click Site Collection Features.
In the Features section, locate the InfoPath form that you approved and then click Activate to make the template active for this site collection.
The form can now be used with the actions of a Business Data Catalog application.
This concludes preparing the InfoPath form for displaying Customer information to edit from our Business Data Catalog Web service application. However, to use the InfoPath Form Web site, Office SharePoint Server must be configured with some of the basic Business Data Catalog Web Parts. Following are the steps to configure the Web Parts for this example.
To configure the Web Parts for the example
Navigate to a team site, and then for Site Settings, click Edit Page.
In a Web Part zone on the page, click Add Web Part.
Click the Business Data List Web Part, and then click Add.
In the Edit drop-down list on the Web Part, click Modify Shared Web Part.
In the Editor pane that appears on the right side of the browser, in the Type section, click Browse, and then select the Customer type of the AdventureWorksWebService application.
Click OK to add and configure the Web Part.
Add another Web Part to the page. This time, select the Business Data Actions Web Part.
On the Edit menu, click Modify Shared Web Part, and then select the Customer for the type.
Do not set the Item property for the Web Part as it will be populated by connection information.
Click OK to close the property editor.
On the Custom Action Web Part, click Edit, click Connections, click Get Item From, and then click Customer List to connect this Web Part to the Customer List Web Part.
Exit Edit Mode for the page.
You should now be able to select a customer from the list of customers and then select Edit Customer from the Customer Actions Web Part. This will display the InfoPath form created earlier.
The page should now contain the two Web parts, one for listing the Customer entities from the Web service and another Web Part that will link to the InfoPath form when a Customer is selected and the action is clicked in the Actions list. This is shown in Figure 10.
Figure 10. Customer list and actions
.gif "Customer list and actions")
When a the user selects a particular Customer and clicks the Edit Customer action, the user is presented with the InfoPath form rendered in the browser.
Configuring InfoPath Forms Services for Single Sign-On
InfoPath Forms Services can also be configured to take advantage of SSO applications. To configure Forms Services to use SSO, you must define a Universal Data Connection (UDC) file and some basic configuration by using Central Administration pages. In the InfoPath Forms Services section of the SharePoint Central Administration pages, administrators must first enable the Web service Proxy. This allows Forms Services to use the UDC file to connect to the Web service; the UDC file defines the SSO application to use for connecting to the Web service. Figure 11 shows how to enable the Web service Proxy for Forms Services.
Figure 11. Enabling Web service Proxy for Forms Services
.gif "Enabling Web service Proxy for Forms Services")
The Microsoft Office Forms Server 2007 help file (OFS12sdk.chm provided in the Microsoft Office SharePoint Server 2007 SDK download contains detailed information about configuring the Web service Proxy and UDC files for use with SSO.
Expanding the Business Data Catalog Application
The previous sections addressed several key pieces of technology for building Business Data Catalog applications. The sample we discussed demonstrated how to use Web services, security, SSO, InfoPath forms, Forms Services, and the Business Data Catalog Web Parts. However, to better demonstrate the power of the Business Data Catalog, you need to define multiple entities and the relationships among those entities. For example, a typical scenario involves Customers, Orders, and Line items. We have already seen that a Web service application can define methods returning instances of types such as a Customer. Next, we look at how to define the relationships between entities such as Customers and Addresses. In Business Data Catalog terms, the object that defines the relationship between two entities is called an Association.
The Microsoft Office SharePoint Server 2007 SDK includes several working sample applications that demonstrate much of the functionality of the Business Data Catalog. We will use the SampleWebService application located in <InstallDrive:>\2007 Office System Developer Resources\SharePoint Server 2007 SDK\CodeSamples\SampleWebService to discuss Web services that expose multiple entities and how to define associations among those entities. The SampleWebService application is a complete Web service application that defines several methods for returning Customer, Order, Line Item, Region, and Address information. There is also a complete Business Data Catalog application definition contained in the SampleWebService.xml file located with the project.
Office SharePoint Server 2007 SDK SampleWebService
For additional information and a more extensive sample Web service that uses multiple entities, look at the SharePoint Server SampleWebService, with complete code and a large volume of supporting documentation. You should also familiarize yourself with the SampleWebService project provided in the SDK. There are several classes defined in the Web service, as shown in the following solution.
Figure 12. SampleWebService project
.gif "SampleWebService project")
The Visual Studio Project defines the Web service and methods for interacting with the data in the SampleWebService.cs file and corresponding class files (for example, Customer.cs, CustomerAddress.cs, and LineItem.cs), while the complete Business Data Catalog application definition is contained in the SampleWebService.xml file provided with the sample.
To set up and work with the sample
Run the SampleWebService project from Visual Studio or deploy the application to IIS.
Modify the WsdlFetchUrl property of the SampleWebService.xml file to point to the Web service URL.
Import the SampleWebService.xml file into the Business Data Catalog to create the application.
SampleWebService Entities
Customer, Address, Region, Order, and Line Item. Each entity demonstrates a unique feature about the Business Data Catalog. For example, the Address entity is used only in an association with the Customer entity, and as a result does not have an Identifier element. An Identifier element uniquely identifies an entity, much as a key in the database world. The SampleWebService.xml file contains several comments that define each unique feature demonstrated for each entity. Instead of paraphrasing all of the comments and information provided in the SampleWebService.xml file, this article discusses one of the additional important aspects of defining a Business Data Catalog application, which is an Association. Before you continue, ensure that you have reviewed the SampleWebService project.
Associations
Associations define the connection between entities in a Business Data Catalog application. The following XML is taken from the SampleWebService.xml application and defines an association between Customer and Addresses.
Code listing 15
<Association
Name="CustomerToAddresses"
AssociationMethodEntityName="Customer"
AssociationMethodName="GetCustomerByID"
AssociationMethodReturnParameterName="Customer"
AssociationMethodReturnTypeDescriptorName="CustomerAddresses"
AssociationMethodReturnTypeDescriptorLevel="1">
<SourceEntity Name="Customer" />
<DestinationEntity Name="Address" />
</Association>
This is a unique example to look at because the Customer Web service defines a field that is an array of Address entities for that particular Customer.
The attributes of the association define the following:
Name A descriptive name of the association.
AssociationMethodEntityName The name of the entity that contains the method used to find or traverse the associated item. In the SampleWebService project, the Customer entity defines the method used for retrieval of the association data.
AssociationMethodName The actual method name on the entity that is used to retrieve the association data. In the SampleWebService project, the Customer entity defines a GetCustomerByID method that returns a unique Customer, which contains a field that is an array of all the Addresses for that Customer.
AssociationReturnParameterName The name of the return parameter (data type) that contains the destination entity instance. In the SampleWebService project, the Customer entity is returned but each customer contains an array of Address entities. So, though a customer type is returned, the Address type is retrieved as a nested type of the Customer.
AssociationMethodReturnTypeDescriptorName An optional attribute. The name (type) of the return parameter that contains the destination entity instances. In the SampleWebService project, there is a TypeDescriptor definition within the Customer entity that defines the CustomerAddress[] with Name=CustomerAddresses. This name is used for the association definition and allows the association to use only part of the Customer return structure (the address).
AssociationMethodReturnTypeDescriptorLevel Indicates the level of the TypeDescriptor in the return structure. In the SampleWebService project, the Address is TypeDescriptor one level within the Customer.
SourceEntity The source entity for the association. You can have more than one SourceEntity defined for an association. In some cases, more than one entity must be used to obtain the DestinationEntity.
DestinationEntity The destination entity. In the SampleWebService project, the destination entity is the Customers Address.
Conclusion
The Business Data Catalog is an exciting new technology that provides much more than a way of surfacing data from databases to SharePoint sites. The Business Data Catalog can connect to Web service applications allowing virtually any type of system that exposes a Web service to be surfaced within SharePoint sites. After you develop a Business Data Catalog application, end users can easily gain access to the data defined in the Business Data Catalog application without writing any code. Just add Business Data Catalog Web Parts.
Additional Resources
For more information, see the following resources: