Step 2: Define Entities, Methods and Filters

Article
10/16/2013

A line-of-business (LOB) application registered in the Business Data Catalog defines the entities, the methods that can be executed on the entities, and the filters to enable end-user filtering. An entity is a business object, such as Customer or Product, in an LOB application. Methods are the operations related to an entity, and filters help limit the entity instances returned from the method.

In the Business Data Catalog, an entity belongs to a single LOB system and must have a unique name. Entities contain identifiers, methods, filters, and actions.

In this step, you will define an entity called Item in the Amazon ECommerce Web Service sample, and define Finders to get an item by ID as well as get a list of items. You will also add comparison filters to enable end-user filtering on the ID, SearchContext, and Keyword fields.

Prerequisites

Step 1: Connect to the AdventureWorks2000 Database

To define an entity, method, and filters

Open your AWSECommerceService.XML metadata XML file from Step 1.

Insert the following XML to replace the  section in that file:

[xml]

    <Entity Name="Item">
      <Identifiers>
        <Identifier Name="ItemId" TypeName="System.String" />
      </Identifiers>
      <Methods>
        <Method Name="ItemLookup">
          <FilterDescriptors>
            <FilterDescriptor Type="Comparison" Name="ID" >
              <Properties>
                <Property Name="Comparator" Type="System.String">Equals</Property>
              </Properties>
            </FilterDescriptor>
          </FilterDescriptors>
          <Parameters>
            <Parameter Direction="In"  Name="itemLookup">
              <TypeDescriptor TypeName="AWSECommerceService.ItemLookup, AWSECommerceService" Name="itemLookup">
                <TypeDescriptors>
                  <TypeDescriptor TypeName="AWSECommerceService.ItemLookupRequest[], AWSECommerceService" Name="Request">
                    <TypeDescriptors>
                      <TypeDescriptor TypeName="AWSECommerceService.ItemLookupRequest, AWSECommerceService" Name ="RequestObject">
                        <TypeDescriptors>
                          <TypeDescriptor TypeName="System.String[]" Name="ItemId">
                            <TypeDescriptors>
                              <TypeDescriptor TypeName="System.String" AssociatedFilter="ID" IdentifierName="ItemId" Name="ID">
                                <DefaultValues>
                                  <DefaultValue Type="System.String" MethodInstanceName="ItemSpecificFinderInstance">0521004810</DefaultValue>
                                </DefaultValues>
                              </TypeDescriptor>
                            </TypeDescriptors>
                          </TypeDescriptor>
                          <TypeDescriptor TypeName="System.String[]"  Name="ResponseGroup">
                            <TypeDescriptors>
                              <TypeDescriptor TypeName="System.String" Name="ResponseGroupString">
                                <DefaultValues>
                                  <DefaultValue Type="System.String" MethodInstanceName="ItemSpecificFinderInstance">Small</DefaultValue>
                                </DefaultValues>
                              </TypeDescriptor>
                            </TypeDescriptors>
                          </TypeDescriptor>
                        </TypeDescriptors>
                      </TypeDescriptor>
                    </TypeDescriptors>
                  </TypeDescriptor>
                  <TypeDescriptor TypeName="System.String" Name="SubscriptionId">
                    <DefaultValues>
                      <DefaultValue Type="System.String" MethodInstanceName="ItemSpecificFinderInstance">EnterYourSubscriptionIdHere</DefaultValue>
                    </DefaultValues>
                  </TypeDescriptor>
                </TypeDescriptors>
              </TypeDescriptor>
            </Parameter>
            <Parameter Direction="Return"  Name="Response">
              <TypeDescriptor TypeName="AWSECommerceService.ItemLookupResponse, AWSECommerceService" Name="response">
                <!-- The TypeName property of TypeDescriptors for .NET Types found in Web service proxy assemblies should be in the form Fully.Qualified.TypeName, LobSystemName.-->
                <TypeDescriptors>
                  <TypeDescriptor TypeName="AWSECommerceService.Items[], AWSECommerceService" IsCollection="true" Name="Items">
                    <TypeDescriptors>
                      <TypeDescriptor TypeName="AWSECommerceService.Items, AWSECommerceService" IsCollection="false" Name="ItemsArray">
                        <TypeDescriptors>
                          <TypeDescriptor TypeName="AWSECommerceService.Item[], AWSECommerceService" IsCollection="true" Name="Item">
                            <TypeDescriptors>
                              <TypeDescriptor TypeName="AWSECommerceService.Item, AWSECommerceService" IsCollection="false"  Name="ItemArray">
                                <TypeDescriptors>
                                  <TypeDescriptor TypeName="System.String" IdentifierName="ItemId" AssociatedFilter="ID"   Name="ASIN">
                                    <LocalizedDisplayNames>
                                      <LocalizedDisplayName LCID="1033">ASIN</LocalizedDisplayName>
                                    </LocalizedDisplayNames>
                                    <Properties>
                                      <Property Name="DisplayByDefault" Type="System.Boolean">true</Property>
                                    </Properties>
                                  </TypeDescriptor>
                                  <TypeDescriptor TypeName="System.String" Name="DetailPageURL">
                                    <LocalizedDisplayNames>
                                      <LocalizedDisplayName LCID="1033">DetailPageURL</LocalizedDisplayName>
                                    </LocalizedDisplayNames>
                                    <Properties>
                                      <Property Name="DisplayByDefault" Type="System.Boolean">true</Property>
                                    </Properties>
                                  </TypeDescriptor>
                                </TypeDescriptors>
                              </TypeDescriptor>
                            </TypeDescriptors>
                          </TypeDescriptor>
                        </TypeDescriptors>
                      </TypeDescriptor>
                    </TypeDescriptors>
                  </TypeDescriptor>
                </TypeDescriptors>
              </TypeDescriptor>
            </Parameter>
          </Parameters>
          <MethodInstances>
            <MethodInstance Name="ItemSpecificFinderInstance" Type="SpecificFinder" ReturnParameterName="Response" ReturnTypeDescriptorName="Item"/>
          </MethodInstances>
        </Method>
        <Method Name="ItemSearch">
          <FilterDescriptors>
            <FilterDescriptor Type="Comparison" Name="SearchIndex" >
              <Properties>
                <Property Name="Comparator" Type="System.String">Equals</Property>
              </Properties>
            </FilterDescriptor>
            <FilterDescriptor Type="Comparison" Name="Keywords" >
              <Properties>
                <Property Name="Comparator" Type="System.String">Equals</Property>
              </Properties>
            </FilterDescriptor>
          </FilterDescriptors>
          <Parameters>
            <Parameter Direction="In"  Name="itemSearch">
              <TypeDescriptor TypeName="AWSECommerceService.ItemSearch, AWSECommerceService" Name="itemSearch">
                <TypeDescriptors>
                  <TypeDescriptor TypeName="AWSECommerceService.ItemSearchRequest[], AWSECommerceService" Name="Request">
                    <TypeDescriptors>
                      <TypeDescriptor TypeName ="AWSECommerceService.ItemSearchRequest, AWSECommerceService" Name="RequestObject">
                        <TypeDescriptors>
                          <TypeDescriptor TypeName="System.String" AssociatedFilter="SearchIndex" Name="SearchIndex">
                            <DefaultValues>
                              <DefaultValue Type="System.String" MethodInstanceName="ItemFinderInstance">Books</DefaultValue>
                            </DefaultValues>
                          </TypeDescriptor>
                          <TypeDescriptor TypeName="System.String" AssociatedFilter="Keywords"  Name="Keywords">
                            <DefaultValues>
                              <DefaultValue Type="System.String" MethodInstanceName="ItemFinderInstance">Automotive</DefaultValue>
                            </DefaultValues>
                          </TypeDescriptor>
                          <TypeDescriptor TypeName="System.String[]"  Name="ResponseGroup">
                            <TypeDescriptors>
                              <TypeDescriptor TypeName="System.String" Name="ResponseGroupString">
                                <DefaultValues>
                                  <DefaultValue Type="System.String" MethodInstanceName="ItemFinderInstance">Small</DefaultValue>
                                </DefaultValues>
                              </TypeDescriptor>
                            </TypeDescriptors>
                          </TypeDescriptor>
                        </TypeDescriptors>
                      </TypeDescriptor>
                    </TypeDescriptors>
                  </TypeDescriptor>
                  <TypeDescriptor TypeName="System.String" Name="SubscriptionId">
                    <DefaultValues>
                      <DefaultValue Type="System.String" MethodInstanceName="ItemFinderInstance">EnterYourSubscriptionIdHere</DefaultValue>
                    </DefaultValues>
                  </TypeDescriptor>
                </TypeDescriptors>
              </TypeDescriptor>
            </Parameter>
            <Parameter Direction="Return"  Name="Response">
              <TypeDescriptor TypeName="AWSECommerceService.ItemSearchResponse, AWSECommerceService" Name="Response">
                <TypeDescriptors>
                  <TypeDescriptor TypeName="AWSECommerceService.Items[], AWSECommerceService" IsCollection="true" Name="Items">
                    <TypeDescriptors>
                      <TypeDescriptor TypeName="AWSECommerceService.Items, AWSECommerceService" IsCollection="false" Name="ItemsArray">
                        <TypeDescriptors>
                          <TypeDescriptor TypeName="AWSECommerceService.Item[], AWSECommerceService" IsCollection="true" Name="Item">
                            <TypeDescriptors>
                              <TypeDescriptor TypeName="AWSECommerceService.Item, AWSECommerceService" IsCollection="false"  Name="ItemArray">
                                <TypeDescriptors>
                                  <TypeDescriptor TypeName="System.String" IdentifierName="ItemId" Name="ASIN">
                                    <LocalizedDisplayNames>
                                      <LocalizedDisplayName LCID="1033">ASIN</LocalizedDisplayName>
                                    </LocalizedDisplayNames>
                                    <Properties>
                                      <Property Name="DisplayByDefault" Type="System.Boolean">true</Property>
                                    </Properties>
                                  </TypeDescriptor>
                                  <TypeDescriptor TypeName="System.String" Name="DetailPageURL">
                                    <LocalizedDisplayNames>
                                      <LocalizedDisplayName LCID="1033">DetailPageURL</LocalizedDisplayName>
                                    </LocalizedDisplayNames>
                                    <Properties>
                                      <Property Name="DisplayByDefault" Type="System.Boolean">true</Property>
                                    </Properties>
                                  </TypeDescriptor>
                                </TypeDescriptors>
                              </TypeDescriptor>
                            </TypeDescriptors>
                          </TypeDescriptor>
                        </TypeDescriptors>
                      </TypeDescriptor>
                    </TypeDescriptors>
                  </TypeDescriptor>
                </TypeDescriptors>
              </TypeDescriptor>
            </Parameter>
          </Parameters>
          <MethodInstances>
            <MethodInstance Name="ItemFinderInstance" Type="Finder" ReturnParameterName="Response" ReturnTypeDescriptorName="Item"/>
          </MethodInstances>
        </Method>
      </Methods>
    </Entity>

Replace the default value for the SubscriptionID parameter with the SubrscriptionID you obtained from Amazon in both ItemLookup and ItemSearch methods.
Save the XML file.
Add the application definition to the Business Data Catalog. For details, see How to: Add an Application Definition to the Business Data Catalog.
Test the metadata by creating a Business Data List Web Part, a Details Web Part, and a Business Data column of type Item, or any combination of these. For details, see Testing the Metadata.

Next Steps

Step 3 (Optional): Define Actions

Step 2: Define Entities, Methods and Filters

Prerequisites

To define an entity, method, and filters

Next Steps

See Also

Tasks

Concepts

Additional resources