Authoring Step 4: Define the Address External ContentType

Applies to: SharePoint Server 2010

At its basic level, an external content type consists of a title (defined in the Properties element), a unique identifier (which equates to a primary key), and methods that are used to define the fields of an entity and tell the Business Data Connectivity (BDC) service how to pull data out of the external system.

In the case of databases, a BDC 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 that the method can be called. All names and types should match the names and types in the Web services proxy.

In this step, you define an external content type named Address. The Address entity in the SampleWebService proxy demonstrates a scenario in which it is acceptable not to define an identifier for the entity. This is because we just want to display a list of addresses for a customer and do not want to search or display unique addresses. Without an identifier, the BDC treats the addresses that are returned by the external system as just a blob of data; you cannot run actions on this external content type, use the entity instance picker, relate addresses with another external content type, or search on or crawl for the external data.

Another important concept this external content type demonstrates is BDC support for complex formatting. You can use the complex formatting feature to display the address structure in a formatted manner, such as "Street, BlockNumber, City, State - PostalCode, Country".

Prerequisites

Authoring Step 3: Define the LobSystem Instance

To define the Address external content type

1. Add the XML for the Address external content type after the LobSystemInstances element. This XML defines the external content type’s title and a method to return addresses.

   Note

   The GetAddresses method defined here is a "dummy"; it does not exist in the Web service. The only reason for defining this method in the XML is because of a current limitation of the BDC that requires all entities to have a finder method.

   <Entities>
     <Entity Namespace="SampleWebService" Version="1.1.0.0" 
             EstimatedInstanceCount="10000" Name="WSAddress" 
             DefaultDisplayName="WSAddress">
       <Methods>
         <Method IsStatic="false" Name="GetAddresses">
           <Parameters>
             <Parameter Direction="In" Name="id">
               <TypeDescriptor TypeName="System.String" 
                               IdentifierName="CustomerID" 
                               Name="id" 
                               DefaultDisplayName="CustomerID" />
             </Parameter>
             <Parameter Direction="Return" Name="Addresses">
               <TypeDescriptor 
                 TypeName="BCSServiceProxy.CustomerAddress[], http://air-mail/WSOrders2010/service.asmx?wsdl" 
                 IsCollection="true" Name="CustomerAddresses">
                 <TypeDescriptors>
                   <TypeDescriptor 
                     TypeName="BCSServiceProxy.CustomerAddress, http://air-mail/WSOrders2010/service.asmx?wsdl" 
                     Name="CustomerAddressesElement">
                     <Properties>
                       <Property Name="ComplexFormatting" Type="System.String" />
                       <Property Name="FormatString" Type="System.String">
                         {0}, {1}, {2}, {3} - PostalCode, {4}
                       </Property>
                     </Properties>
                     <TypeDescriptors>
                       <TypeDescriptor 
                         TypeName="BCSServiceProxy.CustomerStreet, http://air-mail/WSOrders2010/service.asmx?wsdl" 
                         Name="Street">
                         <TypeDescriptors>
                           <TypeDescriptor TypeName="System.String" 
                                           Name="BlockNumber" />
                           <TypeDescriptor TypeName="System.String" 
                                           Name="Street" />
                         </TypeDescriptors>
                       </TypeDescriptor>
                       <TypeDescriptor TypeName="System.String" 
                                       Name="City" />
                       <TypeDescriptor 
                         TypeName="BCSServiceProxy.States, http://air-mail/WSOrders2010/service.asmx?wsdl" 
                         Name="StateProvince" />
                       <TypeDescriptor TypeName="System.String" 
                                       Name="CountryRegion" />
                       <TypeDescriptor TypeName="System.String" 
                                       Name="PostalCode" />
                     </TypeDescriptors>
                   </TypeDescriptor>
                 </TypeDescriptors>
               </TypeDescriptor>
             </Parameter>
           </Parameters>
           <MethodInstances>
             <Association Name="GetAddressesForCustomer" 
                          Type="AssociationNavigator" 
                          ReturnParameterName="Addresses" 
                          DefaultDisplayName="Customer Addresses Navigate Association">
               <SourceEntity Namespace="SampleWebService" Name="WSCustomer" />
               <DestinationEntity Namespace="SampleWebService" Name="WSAddress" />
             </Association>
           </MethodInstances>
         </Method>
       </Methods>
     </Entity>
   </Entities>
   

2. Save the XML file.

Next Steps

Authoring Step 5: Define the Customer External ContentType