Authoring Step 5: Define the Customer entity
At its basic level, an entity consists of a title (defined in the Properties element), a unique identifier (which equates to a primary key), and methods that are used to both define the fields of an entity as well as tell the Business Data Catalog how to pull the entity data out of the LOB system.
In the case of databases, a Business Data Catalog method contains a Properties element that defines the database query, a Parameters element that defines the data returned from the query, and a MethodInstances element that defines the different ways the method can be called. However, in the case of Web services, a method describes the Web method that should be invoked to get the desired data. The method name should match the Web method name, and the Parameters element defines the data returned from the Web method; a MethodInstances element defines the different ways the method can be called. All names and types should match the names and types in the Web services proxy.
In this step, you will define an entity named Customer. In addition to the usual Finder and SpecificFinder methods, the Customer entity also defines an IDEnumerator method to enable you to search on and crawl customers.
The Web method GetCustomerByID, which is used as the SpecificFinder method, is also reused as the association method to get addresses by CustomerID. The GetCustomerByID Web method contains an address collection in the return structure that is used to get addresses for a customer by using associations. This shows that you do not always need to have a separate method as the association method. You can reuse whole return structure or part of the return structure of another method instance (SpecificFinder in this case) as an association method.
The Customer entity also demonstrates the self-referential entity association concept. Customers can have child customers. In the Business Data Catalog, this is implemented by using associations. The GetChildCustomersForCustomer Web method is used to return the child customers given a CustomerID.
Prerequisites
Authoring Step 4: Define the Address entity
To define the Customer entity
Add the XML for the Customer entity after the Address entity element.
<!-- The Customer entity has IDEnumerator, Finder, and SpecificFinder.--> <!-- The Customer return structure from the Web method GetCustomerByID also contains an address collection which is used to get addresses for a customer.--> <!-- The Customer entity also demonstrates the self-referential entity association concept - cusomers have child customers. The GetChildCustomersForCustomer method is the association method.--> <Entity EstimatedInstanceCount="10000" Name="Customer"> <Properties> <Property Name="Title" Type="System.String">Name</Property> </Properties> <Identifiers> <Identifier TypeName="System.String" Name="CustomerID" /> </Identifiers> <Methods> <!--Demonstrates the self-referential entity association concept.--> <!--Each customer in the back-end data source has a ParentCustomerID.--> <Method Name="GetChildCustomersForCustomer"> <Parameters> <!--Parameter names are tokens used by the Business Data Catalog. You can name them anything.--> <!--TypeDescriptor names must match the back-end input and output structures'/fields' names.--> <Parameter Direction="In" Name="custid"> <TypeDescriptor TypeName="System.String" IdentifierName="CustomerID" Name="custid" /> </Parameter> <Parameter Direction="Return" Name="Customers"> <!-- The TypeName attribute takes the type and the LOB system name for complex types.--> <!-- The IsCollection is true here because the customer array is a collection of customers.--> <!-- The TypeDescriptor with IsCollection= true can have only one child.--> <TypeDescriptor TypeName="SampleWebServiceProxy.Customer[], SampleWebService" IsCollection="true" Name="ArrayOfCustomer"> <TypeDescriptors> <TypeDescriptor TypeName="SampleWebServiceProxy.Customer, SampleWebService" Name="Customer"> <TypeDescriptors> <TypeDescriptor TypeName="System.String" IdentifierName="CustomerID" Name="CustomerID" /> <TypeDescriptor TypeName="System.String" Name="Name" /> <TypeDescriptor TypeName="System.Int64" Name="WorkPhoneNumber" /> <TypeDescriptor TypeName="System.Int64" Name="MobilePhoneNumber" /> <TypeDescriptor TypeName="System.String" Name="Industry" /> <TypeDescriptor TypeName="System.String" Name="WebSite" /> </TypeDescriptors> </TypeDescriptor> </TypeDescriptors> </TypeDescriptor> </Parameter> </Parameters> </Method> <Method Name="GetCustomerIDs"> <Parameters> <Parameter Direction="Return" Name="CustomerIDs"> <TypeDescriptor TypeName="System.String[]" IsCollection="true" Name="ArrayOfString"> <TypeDescriptors> <TypeDescriptor TypeName="System.String" IdentifierName="CustomerID" Name="CustomerID" /> </TypeDescriptors> </TypeDescriptor> </Parameter> </Parameters> <MethodInstances> <MethodInstance Type="IdEnumerator" ReturnParameterName="CustomerIDs" ReturnTypeDescriptorName="ArrayOfString" ReturnTypeDescriptorLevel="0" Name="GetCustomerIDsInstance" /> </MethodInstances> </Method> <Method Name="GetCustomers"> <FilterDescriptors> <FilterDescriptor Type="Wildcard" Name="Name" /> <!-- Limit filter tells the Business Data Catalog to bring back only the specified number of rows back from the LOB application.--> <!-- Note that the back-end method should support this functionality to return only the specified number of rows. See SampleWebService for a sample.--> <FilterDescriptor Type="Limit" Name="Limit" /> </FilterDescriptors> <Parameters> <Parameter Direction="In" Name="name"> <TypeDescriptor TypeName="System.String" AssociatedFilter="Name" Name="name" /> </Parameter> <Parameter Direction="In" Name="limit"> <TypeDescriptor TypeName="System.Int32" AssociatedFilter="Limit" Name="limit" /> </Parameter> <Parameter Direction="Return" Name="Customers"> <TypeDescriptor TypeName="SampleWebServiceProxy.Customer[], SampleWebService" IsCollection="true" Name="ArrayOfCustomer"> <TypeDescriptors> <TypeDescriptor TypeName="SampleWebServiceProxy.Customer, SampleWebService" Name="Customer"> <TypeDescriptors> <TypeDescriptor TypeName="System.String" IdentifierName="CustomerID" Name="CustomerID" /> <TypeDescriptor TypeName="System.String" Name="Name" /> <TypeDescriptor TypeName="System.Int64" Name="WorkPhoneNumber" /> <TypeDescriptor TypeName="System.Int64" Name="MobilePhoneNumber" /> <TypeDescriptor TypeName="System.String" Name="Industry" /> <TypeDescriptor TypeName="System.String" Name="WebSite" /> </TypeDescriptors> </TypeDescriptor> </TypeDescriptors> </TypeDescriptor> </Parameter> </Parameters> <MethodInstances> <MethodInstance Type="Finder" ReturnParameterName="Customers" ReturnTypeDescriptorName="ArrayOfCustomer" ReturnTypeDescriptorLevel="0" Name="FindCustomerInstances" /> </MethodInstances> </Method> <Method Name="GetCustomerByID"> <!--SpecificFinder for customer.--> <!--The GetCustomerByID is also reused as an association method for getting addresses of a customer.--> <Parameters> <Parameter Direction="In" Name="id"> <TypeDescriptor TypeName="System.String" IdentifierName="CustomerID" Name="id" /> </Parameter> <Parameter Direction="Return" Name="Customer"> <TypeDescriptor TypeName="SampleWebServiceProxy.Customer, SampleWebService" Name="Customer"> <TypeDescriptors> <TypeDescriptor TypeName="System.String" IdentifierName="CustomerID" Name="CustomerID" /> <TypeDescriptor TypeName="System.String" Name="Name" /> <TypeDescriptor TypeName="System.Int64" Name="WorkPhoneNumber" /> <TypeDescriptor TypeName="System.Int64" Name="MobilePhoneNumber" /> <TypeDescriptor TypeName="System.String" Name="Industry" /> <TypeDescriptor TypeName="System.String" Name="WebSite" /> <!--The Customer structure also contains a collection of addresses for the customer. --> <!--Return parameters can have multiple TypeDescriptors with IsCollection=true. This is an example of that.--> <!--When Business Data Caltalog executes the SpecificFinder, it ignores the addresses collection since it's a collection.--> <!--When this same method is used to get addresses for a customer in an association, the return TypeDescriptor name is specified as CustomerAddresses.--> <TypeDescriptor TypeName="SampleWebServiceProxy.CustomerAddress[], SampleWebService" IsCollection="true" Name="CustomerAddresses" > <TypeDescriptors> <TypeDescriptor TypeName="SampleWebServiceProxy.CustomerAddress, SampleWebService" Name="CustomerAddress" > <Properties> <!--Business Data clients can only display primitives and flat structures by default.--> <!--To display the Street structure which is part of the Address, we use ComplexFormatting.--> <!--To use ComplexFormatting, you need to enable it at the TypeDescriptor that contains the struct like shown below.--> <Property Name="ComplexFormatting" Type="System.String" /> </Properties> <TypeDescriptors> <TypeDescriptor TypeName="SampleWebServiceProxy.CustomerStreet, SampleWebService" Name="Street"> <Properties> <!--After ComplexFormatting is enabled in the container of this struct, define the format here.--> <!--{0}, {1} stand for BlockNumber and Street of the Street struct. --> <Property Name="FormatString" Type="System.String">{0}, {1}</Property> </Properties> <TypeDescriptors> <TypeDescriptor TypeName="System.String" Name="BlockNumber" /> <TypeDescriptor TypeName="System.String" Name="Street" /> </TypeDescriptors> </TypeDescriptor> <TypeDescriptor TypeName="System.String" Name="City" /> <TypeDescriptor TypeName="System.String" Name="StateProvince" /> <TypeDescriptor TypeName="System.String" Name="CountryRegion" /> <TypeDescriptor TypeName="System.String" Name="PostalCode" /> </TypeDescriptors> </TypeDescriptor> </TypeDescriptors> </TypeDescriptor> </TypeDescriptors> </TypeDescriptor> </Parameter> </Parameters> <MethodInstances> <MethodInstance Type="SpecificFinder" ReturnParameterName="Customer" ReturnTypeDescriptorName="Customer" ReturnTypeDescriptorLevel="0" Name="FindCustomerInstance" /> <!--Association is defined at the bottom.--> </MethodInstances> </Method> </Methods> </Entity>