Product Catalog

This walkthrough demonstrates how the Partner Portal application uses the Business Data Catalog (BDC) to expose product information from a back-end catalog management system to partners. The BDC allows you to expose line-of-business (LOB) data from back-end systems simply by creating an XML file. You do not need to write additional code. This topic assumes that you have a basic understanding of the BDC. If you are new to the BDC, see Integrating Line-of-Business Systems.

The Product Catalog Web service exposes read-only data for product categories and products. It is part of a simulated external product catalog application. Information in the product catalog is not partner specific. The same information is accessible to any authenticated partner. The Partner Portal application uses a trusted subsystem model to secure the Web service. This means that the Web service trusts the application pool identity that is used by the SharePoint Web application.

The following diagram illustrates how the data that is exposed by the BDC is integrated into the Partner Portal application.

Catalog integration

Using the Product Catalog

To see how the product catalog uses the standard BDC Web parts, open the URL http://<<Server_Name>>:9001/sites/productcatalog/default.aspx.

The following figure shows the Product Catalog page.

Product Catalog page

You can see the root category with a list of subcategories, and select categories to see their subcategories. The following figure shows the Root Category page.

Root Category page

Click the Dental Equipment category. Click X-ray. The following figure shows the Category Profile page for Dental Equipment.

Category Profile page

By clicking X-Ray, you will see the product catalog page for that product. The Partner Portal application has overridden the default hyperlinks so that the Product Profile page links to the application’s publishing page for that product. The following picture shows the Product Details page for the X-ray machine.

Product Details page

Code Walkthrough

The product catalog is implemented with the following components:

• The Product Catalog Web service.
• The BDC application definition file.
• Web parts that are provided by the BDC.
• A custom Web part for the product detail view.

The Product Catalog Web Service

Many enterprises use Web services to access back-end data and operations. The Product Catalog Web service exposes the operations of a simulated product catalog system. This is a minimal implementation that uses a fixed, read-only data set. The Contoso.LOB.Services.ProductCatalog Web service is implemented by the Contoso.LOB.Services project. The data is provided by the ProductCatalogDataSet class. The data set is initialized at load time by reading XML data stored in the Contoso.LOB.Services\App_Data\ProductCatalogDataSet.xml file.

The Web service is implemented with Windows Communication Foundation (WCF) and uses the basicHttpBinding. For more information on WCF see Windows Communication Foundation on MSDN**.** The BDC can access basic Web services such as those that are exposed by ASMX, but it does not support many of the configuration options that are available in WCF. By using the basicHttpBinding, the exposed services are compatible with the BDC’s basic Web service client. For more information on using the basicHttpBinding, see Interoperability with ASP.NET Web Services and How to: Configure WCF Service to Interoperate with ASP.NET Web Service Clients.

WCF uses interfaces to define service operations. The catalog service uses the IProductCatalog interface that is located in the Contoso.LOB.Services\Contracts\IProductCatalog.cs file to define its service interface. The ProductCatalog class implements this interface and supports the following Web service operations:

• GetProductSkus. This operation returns a list of string-valued stock keeping unit IDs (SKUs) for all products in the dataset.
• GetProductBySku. This operation returns a product for the SKU specified, or null if no match found.
• GetProductsByCategory. This operation returns the list of products contained in the category specified.
• GetProducts. This operation returns a list of all products in the product catalog data set.
• GetCategoryById. This operation returns the category for the ID specified, or null if no match found.
• GetCategories. This operation returns a list of all categories in the Product Catalog data set.
• GetChildCategoriesByCategory. This operation returns a list of subcategories of the given category for the ID specified.
• GetPartsByProductSku. This operation returns a list of parts for the product for the SKU specified.

Note

In order to simulate the latency that is typically inherent in database lookups, the Product Details Web service inserts timed delays into each invocation of its Web service methods. The duration of this delay is configured in the Contoso.LOB.Services\Web.config file with the sleepAmount application setting. The default delay is 501 milliseconds. The duration of this delay is designed to make the application caching behavior noticeable.

The Product Catalog Metadata Model

Applications define BDC metadata about the services that are provided by the LOB systems. The metadata model represents, for example, LOB systems, LOB system instances, entities, operations, and associations. More concretely, it describes the information and relationships that are exposed by the Product Catalog service to SharePoint through the BDC. For more information about the BDC metadata model, see Integrating Line-of-Business Systems. The following diagram represents the metadata model that is defined for the catalog application.

BDC metadata model

All entities and associations are exposed by the Product Catalog Web service. Associations describe how the BDC should navigate from one entity to another. A Category entity represents the product category. Because categories are hierarchical, categories can be children of other categories. For example, hospital equipment is a child of the root category, and emergency room is a child category of hospital equipment. The CategoryToChildCategories association describes this relationship. A Product entity represents a product that is offered by Contoso for sale to its partners. Each Product entity is assigned to a category. A category can have zero or more products. The CategoryToProducts association describes this relationship. A Part is an entity that represents a replacement part for a product. A product can have zero or more replacement parts. The ProductToParts association describes this relationship.

The BDC Application Definition File

The BDC uses an application definition file for specifying the metadata model. The application definition file ProductCatalogDefinition.xml contains XML descriptions for the Product Catalog Web service described in the Product Catalog Web Service section. This file was originally created with the Business Data Catalog Editor and then manually edited. See Integrating Line-of-Business Systems for more information.

Note

In all of the XML code shown below for the ProductDetailsDefinition.xml file, the Type and TypeName attributes have been elided (...) whenever they reference the built-in string type. This is to make reading the code easier. Refer to the XML file for the full text.

The LobSystem Declaration

The LobSystem object contains all of the sections that are related to the definition of the service. The following XML code shows the LobSystem object declaration.

<LobSystem 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="https://schemas.microsoft.com/office/2006/03/BusinessDataCatalog BDCMetadata.xsd" 
  Type="WebService" 
  Version="1.0.0.0" 
  Name="ContosoProductCatalogService"   
  xmlns="https://schemas.microsoft.com/office/2006/03/BusinessDataCatalog">
  
  ...

The LobSystem object references standard BDC schemas. It also defines the type of the LobSystem object as a Web service. For more information, see LobSystem in the BDC documentation.

The Properties Section

The properties section is contained within the LobSystem object declaration and provides properties for the system. The following XML code defines the Properties object.

...
<Properties>
    <Property Name="WsdlFetchUrl" Type="System.String">
        https://localhost:8585/Contoso.LOB.Services/ProductCatalog.svc
    </Property>

    <Property Name="WebServiceProxyNamespace">
        ContosoProductCatalogProxy
    </Property>
</Properties>
...

The WsdlFetchUrl property gives the URI of the Product Catalog Web service that the BDC runtime uses to get the Web service definition. The BDC also uses the URI at run time as the endpoint to access the LOB service.

The WebServiceProxyNamespace provides the logical name for the Product Catalog Web service. This name is used in the remainder of the definitions within the LobSystem object declaration. For example, the logical name is used when defining operations that the Product Catalog Web service provides.

Note

The application definition file can specify either a database system or a Web service system as its data source. The Partner Portal application uses a Web service.

The LobSystemInstances Section

The following code shows the LobSystemInstances section of the BDC application definition file.

  <LobSystemInstances>
    <LobSystemInstance Name="ContosoProductCatalogService">
      <Properties>
        <Property Name="LobSystemName" Type="System.String">
           ContosoProductCatalogService
        </Property>
        <Property Name="WebServiceAuthenticationMode"     
Type="Microsoft.Office.Server.ApplicationRegistry.SystemSpecific.WebService.HttpAuthenticationMode">
           RevertToSelf
        </Property>
      </Properties>
    </LobSystemInstance>
  </LobSystemInstances>

This section sets the Name attribute to ContosoProductCatalogService. The name, which must be unique, is used when:

• Administering the BDC using SharePoint's shared services provider user interface.
• Using XML to configure the Microsoft Office SharePoint Services–provided Web Parts that will display this data.
• Invoking the GetLobSystemInstanceByName method of the Microsoft.Office.Server.ApplicationRegistry.MetadataModel.ApplicationRegistry static class, which is the programmatic entry point into the BDC data.

This section also sets the WebServiceAuthenticationMode property to RevertToSelf. This security mode implements the Trusted Subsystem pattern. When a user requests product information, the SharePoint application pool identity is used to authenticate to this instance of the Product Catalog Web service. For more information on the Trusted Subsystem approach see Business Data Catalog Authentication, Trusted Subsystem in the WCF documentation, and the whitepaper Trusted Subsystem Design.

The Entities Section

The Entities section provides the definitions of the business entities and related methods of the catalog service that are exposed through BDC. There are subsections for the category and product business entities.

The Category Business Entity

The Entity element declares the Category entity. It contains subsections for properties, identifiers and methods.

...
<Entity EstimatedInstanceCount="10000" Name="Category">
   <Properties>
      <Property Name="Title" Type="System.String">Name</Property>
   </Properties>

   <Identifiers>
      <Identifier ... Name="CategoryId" />
   </Identifiers>

  <Methods>
     <Method Name="GetCategoryById"> ... </Method>
     <Method Name="GetChildCategoriesByCategory"> ... </Method>
     <Method Name="GetCategories"> ... </Method>
  </Methods>   
</Entity>
...

The subsections are:

• The Properties subsection gives the display title that is used for category lists.
• The Identifier element defines the unique key that is used to index into the table of categories.
• The Methods section declares each method that is available for this business entity.

Each method declaration includes a detailed declaration of the data types that are used by that method. For example, the following XML shows the type descriptors that are used within the declaration of the GetCategoryById method.

...
<Method Name="GetCategoryById"> ... </Method>
  <Parameters>

    <Parameter Direction="In" Name="categoryId">
      <TypeDescriptor ... IdentifierName="CategoryId" Name="categoryId" />
    </Parameter>

    <Parameter Direction="Return" Name="Return">
      <TypeDescriptor 
         TypeName="ContosoProductCatalogProxy.Category,ContosoProductCatalogService"    
         Name="Category">
        <TypeDescriptors>
          <TypeDescriptor ... IdentifierName="CategoryId" Name="CategoryId" />
          <TypeDescriptor ... Name="Name" />
          <TypeDescriptor ... Name="ParentId" />
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>

  </Parameters>
...
</Method>
...

This XML code shows how the data provided to and returned from the GetCategoryById method is structured. The Direction=In attribute is used for input parameters. The Direction=Return attribute is used for the return value.

Note

If you do not define Finder methods, your entity cannot be used in certain BDC Web Parts.

The following code shows the special XML markup that is required for the Finder method.

...
   <Method Name="GetCategories">    
     ...
     <MethodInstance Type="Finder" ReturnParameterName="Return" 
           ReturnTypeDescriptorName="Categories" ReturnTypeDescriptorLevel="0" 
           Name="FindCategoriesInstance" />
   ...
   </Method>
   ...
   <Method Name="GetCategoryById"> 
    ...

    <MethodInstance Type="SpecificFinder" ReturnParameterName="Return" 
         ReturnTypeDescriptorName="Category" ReturnTypeDescriptorLevel="0" 
         Name="FindSpecificCategoryInstance" />
   </Method>

...

The methods FindCategoriesInstance and FindSpecificCategoryInstance allow the caller to look up data that corresponds to product category records.

The Product Business Entity

The ProductCatalogDefinition.xml file also contains definitions for the Product entity. The following XML code shows these definitions.

...
<Entity EstimatedInstanceCount="10000" Name="Product">
   <Properties>
      <Property Name="Title" Type="System.String" >Product</Property>
   </Properties>

   <Identifiers>
      <Identifier ... Name="Sku" />
   </Identifiers>
  
   <Methods>
      <Method Name="GetProductsByCategory"> ... </Method>
      <Method Name="GetProductBySku"> ... </Method>
      <Method Name="GetProducts"> ... </Method>
      <Method Name="GetProductSkus"> ... </Method>
   </Methods>
</Entity>
...

Like the Category business entity, the Product entity has special methods that are marked as Finder and SpecificFinder. The GetProducts method is the Finder method, and the GetProductBySku is the SpecificFinder method. Unlike the Category entity, the Product entity defines the GetProductSkus method which is used as the IdEnumerator. IdEnumerator methods are used specifically by SharePoint Search for crawling BDC entities.

The following XML shows a sample type descriptor for the GetProduct method.

...
<Method Name="GetProducts">
   <Parameters>
      <Parameter Direction="Return" Name="Return">
         <TypeDescriptor TypeName="ContosoProductCatalogProxy.Product[],ContosoProductCatalogService" IsCollection="true" Name="Products">
            <TypeDescriptors>
               <TypeDescriptor TypeName="ContosoProductCatalogProxy.Product,ContosoProductCatalogService" Name="Product">
                  <TypeDescriptors>
                      <TypeDescriptor ... Name="CategoryId" />
                      <TypeDescriptor ... Name="ImagePath" />
                      <TypeDescriptor ... Name="LongDescription" />
                      <TypeDescriptor ... Name="Name" />
                      <TypeDescriptor ... Name="ShortDescription" />
                      <TypeDescriptor ... IdentifierName="Sku" Name="Sku" />
                      <TypeDescriptor ... Name="ThumbnailImagePath" />
                  </TypeDescriptors>
                </TypeDescriptor>
             </TypeDescriptors>
          </TypeDescriptor>
       </Parameter>
     </Parameters>
     ...
</Method>
...

The Product business entity includes fields such as CategoryID and ImagePath. These are the data attributes of the product.

The Associations Section

Relationships between entities are declared with the Associations element.

...
<Associations>
    <Association Name="CategoryToChildCategories" 
                 AssociationMethodEntityName="Category" 
                 AssociationMethodName="GetChildCategoriesByCategory" 
                 AssociationMethodReturnParameterName="Return" 
                 AssociationMethodReturnTypeDescriptorName="Categories" 
                 AssociationMethodReturnTypeDescriptorLevel="0">
       <SourceEntity Name="Category" />
       <DestinationEntity Name="Category" />
    </Association>
    <Association Name="CategoryToProducts" AssociationMethodEntityName="Product" 
                 AssociationMethodName="GetProductsByCategory"  
                 AssociationMethodReturnParameterName="Return" 
                 AssociationMethodReturnTypeDescriptorName="Products" 
                 AssociationMethodReturnTypeDescriptorLevel="0">
       <SourceEntity Name="Category" />
       <DestinationEntity Name="Product"/>
    </Association>     
  </Associations>
...

The CategoryToChildCategories association is implemented by invoking the GetChildCategoriesByCategory method. The CategoryToProducts association is implemented with the GetProductsByCategory method.

For more information about association, see Association on MSDN.

Home page on MSDN | Community site