SharePoint 2007: BDC - Extending the "Hello World" example even further - adding specific finders

Posted on 4/24/2007 @ 5:19 AM in #SharePoint by | Feedback | 45257 views

SharePoint 2007: BDC - The Business Data Catalog

This post is in continuation to a series of blogposts I put up on BDC - the Business Data Catalog.

Table of Contents:

  • Introduction
  • In-built Webparts
  • Lists with Business data type columns
  • Search
  • User Profiles
  • Other custom applications targeting a common runtime object model.
  • Making it easier to author XML Applications: BDCMetaMan

  • In my series on BDC, I just got done creating a simple BDC example where I can connect to NorthWind.Customers, and fetch all Customers (entites) that are in a specific city.

    Both times, I was warned by my SSP that "Profile Page Creation" was skipped. Well, fear no more because in this blogpost, I am going to extend that very example, so we indeed do end up using Profile Pages.

    To acheive this, use the following steps -

  • Start with the XML Goo you already used here.
  • Modify the Method "GetCustomers", change the RdbCommandText to this -
    SELECT CustomerID, ContactName, Address, City FROM Customers WHERE (City like @City) AND (CustomerID Like @CustomerID)
  • Change FilterDescriptors to this -
  • <FilterDescriptors>

      <!-- Define the filters supported by the back-end method (or sql query) here. -->

      <FilterDescriptor Type="Wildcard" Name="City" >


          <Property Name="UsedForDisambiguation" Type="System.Boolean">true</Property>



      <FilterDescriptor Type="Wildcard" Name="CustomerID"/>


  • Add a new MethodInstance at the bottom of the XML as shown below -
  • <MethodInstance Name="CustomerSpecificFinderInstance" Type="SpecificFinder" ReturnParameterName="Customers" />

  • Change the Parameters to as shown below ...
  • <Parameter Direction="In" Name="@City">

      <TypeDescriptor TypeName="System.String" AssociatedFilter="City" Name="City">


          <DefaultValue MethodInstanceName="CustomerFinderInstance" Type="System.String">%</DefaultValue>

          <DefaultValue MethodInstanceName="CustomerSpecificFinderInstance" Type="System.String">%</DefaultValue>




    <Parameter Direction="In" Name="@CustomerID">

      <TypeDescriptor TypeName="System.String" AssociatedFilter="CustomerID" Name="CustomerID" IdentifierName="CustomerID">


          <DefaultValue MethodInstanceName="CustomerFinderInstance" Type="System.String">%</DefaultValue>

          <DefaultValue MethodInstanceName="CustomerSpecificFinderInstance" Type="System.String">%</DefaultValue>




    <Parameter Direction="Return" Name="Customers">



  • Save the XML. :-)

    Redeploy the application using the following steps -
  • Go to the SSP
  • Click n Business Data catalog//view applications --> Delete the previous application (or you could also version, but I'm gonna be lazy and consistently lazy)
  • Click on Business data catalog//import application definition
  • Browse to the Xml Goo as your "Application Definition File", choose to import as a "Model", and hit "Import"
  • Note - you won't see the "Profile Page Creation skipped" message anymore.

    Your BDC application is ready to eat. You can use it in the following manner.


    • Go to your favorite sharepoint site.
    • Edit a page that accepts webparts.
    • Add a webpart called "Business Data List". If you created this site using the Blank Template, you will need to first go and enable this webpart in the webpart gallery (Site Actions --> Site Settings --> WebPart gallery).
    • When you add the WebPart, it'd look like this -
    • Do exactly that, Click on "Open the Tool Pane" (or you can also "Modify Shared Web Part" under the Edit menu).
    • In the tool pane, put in "Customer (NorthWindTraders)" under the "Type" text field. It's better if you use the finder button, so there are no typos. Mine looks like this -
    • Hit "OK" at the bottom of the page, and your webpart should look like this now -
    • Click "Exit Edit Mode", and type in a City of "London" (or whatever else you please), hit "Retreive Data" and assuming you actually followed all I wrote in this post above properly, you should see results in your BDC webpart as shown below -
    • Now, go ahead and EDIT the page one more time. Add yet another WebPart, this time the Business Data Item webpart.
    • Click on "Open the tool pane" or modify the shared webpart.
    • Specify "Customer (NorthWindTraders)" as the Type of entity you are interested in, but just for fun, don't specify the specific Item. My screen looks like this -
    • Hit "OK"
    • Now, while still in Edit Mode, "CONNECT" the Customer List webpart, so that it supplies the necessary entity to the Customer WebPart. This is shown as below -
    • Now go ahead and Exit Edit Mode.
    • Search for customers in a city, and select one of them using the provided radio button. You should see the individual customer now appear on the right side as shown below -
    • AWESOME :-)

    Now, since you have created a profile page, and implemented a specific finder method, you can now go ahead and start using the BDC data in a custom list.

    Also, there is a curious "View Profile" action on the top of the profile. How could you customize that, so you could provide more actions to the end user? This is done by adding custom actions to the entity.

    Sound off but keep it civil:

    Older comments..

    On 3/6/2008 1:00:27 AM Supriyo Ghosh said ..
    Hi Sahil,

    First off all thanx for such a good tutorial on BDC.

    I have completed successfuly the part 1 & 2 of the hello world example, but in this section i have followed all the steps as directed by you. At the end of the steps

    after connecting the webparts am getting an prompt sgowing the message "An unhandled exception has occurred: There was an error in callback."

    Please help me out of this error.

    Thanx in advance.



    On 3/11/2008 10:34:22 AM Bart Kemps said ..
    The primary keys in all my business data are integers, so using only one sql-statement like

    "SELECT CustomerID, ContactName, Address, City FROM Customers WHERE (City like @City) AND (CustomerID Like @CustomerID)"

    will not work.

    So is it impossible for sharepoint to display my data in a master/clientview?

    On 3/14/2008 6:57:28 AM Pushpendra Gautam said ..
    can u tell how to deploy BDC application incliding ADF file .

    Give me steps .

    is it possible to deploy BDC application using feature.

    On 4/16/2008 5:21:13 AM Francois said ..
    no worries... I have sorted my issue, you need to add Property "UsedForDisambiguation" on your filterdescriptor to enable partial search results

    On 4/25/2008 3:14:04 PM David Buttrick said ..
    I owe you a beer for this great working example.

    Using this, I've been able to convert theory into practice for my company.

    If you're in St. Louis anytime, the drinks are on me!


    On 4/26/2008 5:10:28 PM Sahil Malik said ..
    David - don't be surprised if I fly over to St. Louis specially for that beer.

    On 5/7/2008 10:34:03 AM Tom said ..
    Hi, I am absolutely loving these tutorials!

    I was wondering that if you could display, eg, 4 columns of data on initial search, then when you clicked the customer, the data that appeared on the right had more columns?

    So, eg, on search

    ID, Name, Address

    on right

    ID, Name, Address, City, PostalCode, Country, Phone

    On 5/8/2008 9:54:36 AM Iain Nickalls said ..
    Hi Sahil,

    Like those above I'd just like to thank you for the brilliant tutorials. So easy to follow, but more importantly, understand.

    However, I do have the same problem as Supriyo above. I get an "Unhandled Exception" when clicking on a customer. Do you have any pointers as to where I may be going wrong?

    Thanks again.

    On 5/23/2008 8:12:10 AM Neeraj said ..
    HI ,This article is very good but i need to made the new webpart such that it will extend the Business data Item (BDI) but i did not find the base class for BDI , to which i will extend to my webpart

    something like

    class a :BDIClass



    from where i will g

    et BDIClass



    On 6/11/2008 12:22:38 AM Jonas said ..
    Now you can get BDC functionality in WSS and MOSS standared edition.

    Check this out:


    On 6/19/2008 4:26:03 PM cj said ..
    When I click the radio button in my Bus. Data List then I receive the error "An unhandled exception has occurred: There was an error in the callback." The Javascript error appears as "'__pendingCallbacks[...].async' is null or not an object ." It appears as if this an ASP.NET 2.0 error ( so I do not know how I will be able to work around this. I get the same error if I call a Business Data Action part.

    Ultimately, I need to be able to click on a line in the Data List and have it open a URL.

    Anyone else have this and/or a workaround?

    On 7/24/2008 11:16:53 AM RyanB said ..
    Great tutorials. It's a blessing that someone took the time to explain how the BDC really works and put it into action.

    I'm wondering if there is a way to make more than one filter field appear when the page initially loads, rather than forcing the user to click Add to bring in another filter field.

    Thanks for any info!

    On 9/12/2008 9:14:13 AM Ravindra said ..
    Hi, Your post was very helpful.

    I want to use the Customer Name as a column in my list in SharePoint. How to do it?

    If I do it using a Specific Finder, it requires a CustomerId to get the specific Customer, I want to show it as a dropdown with list of all the Customers listed there. Any pointers would be helpful.

    On 9/29/2008 3:13:12 PM Ven said ..
    Hi Sahil,

    I have the following questions. Please answer them.

    1. Difference between the various the Authentication techniques in BDC

    2. Difference between Parameter Types - In,Out,InOut,Return

    3. Difference between Parameters and FilterDescriptors

    4. When a Stored Procedure with an input parameter has to be executed and return a single table of data,what will be the structure of the XML?

    5. When a Stored Procedure with an input parameter has to be executed and returns more than 1 table of data,what will be the structure of the XML?

    6. What will be structure of XML for executing a Stored Procedure including Joins,Views etc?

    7. When to use Associations?Does the above scenario necessitate the use of Associations?

    8. When to use Actions tag?

    9. When to use Method Instance tags?

    10. Should I use the TypeDescriptor of type IDataReader even if I am going to get only one record(entity) as output or is it sufficient to use the

    TypeDescriptor of type IDataRecord? In a scenario where I am going to get only one record(entity) as output, should I use the MethodInstance of type

    SpecificFinder mandatorily or is it optional?

    11. Is FilterDescriptor mandatory to be included?

    12. Suppose my ADF file has already got Finder,SpecificFinder methods.Now my Stored Procedure changes to include a new Business Logic. Should I create a

    new ADF file for that or I can reuse the same file? If I can, please let me know how.

    Please explain these scenarios with sample XML files for each. Please explain very clearly with examples

    On 9/30/2008 11:45:19 AM Troy said ..
    I too am getting the "__pendingCallbacks[...].async" issue. What's the trick to avoid this?

    On 9/30/2008 9:07:42 PM Troy said ..
    I figured I better post my answer .. user error! Be sure you copy the Parameters correctly .. amazing this could cause a javascript error. I had both an IdentifierName for both @City and @CustomerID, when it should only be defined for @CustomerID. A left over from a prior example.


    <TypeDescriptor TypeName="System.String" IdentifierName="CustomerID" AssociatedFilter="City" Name="City">


    <TypeDescriptor TypeName="System.String" AssociatedFilter="City" Name="City">

    On 10/7/2008 5:40:45 AM sunil said ..
    hey..thats very well drafted...really helpful...but i need something on bdc which can be used to fetch data programatically on sharepoint list using BDC API like administration and runtime..i have one example here

    but i face the problem of mapping ssp name from other code is not running on local farm ...can anyone help me out.....your comments are highly appreciated...

    thanks in advance..

    On 1/16/2009 7:27:29 AM Dutchman Rick said ..

    great post, thnx a lot!

    I had the same callstack errors as described above. I did change the following:


    <Identifier Name="City" TypeName="System.String" />


    <TypeDescriptor TypeName="System.String" AssociatedFilter="City" Name="City">

    replace for:

    <TypeDescriptor TypeName="System.String" AssociatedFilter="City" Name="City" IdentifierName="City">


    <TypeDescriptor TypeName="System.String" Name="City">

    replace for:

    <TypeDescriptor TypeName="System.String" IdentifierName="City" Name="City">

    it worked for me;)

    On 1/27/2009 7:33:23 AM bassi said ..
    I have two BDC Related List web parts A and B, connected to one BDC Related List web part C,which is connected to BDC list webpart D. When I select value in D, it in turn display some values in C,when I select in C it shows related values in A & B.

    Issue is, when I select Value in D, it shows the list in C webPart with no one selected in C. But A & B shows the previous related value of selected in C web Part.

    I dont want that, if there is no value selected in C, A & B should not show any value .

    How to achive that.

    On 2/25/2009 12:39:37 PM ashwini said ..
    Thanks for the information but i have a question when using specific finder method.

    when the BDC list is loaded ,Can the radio button in the list be defaulted to the first radio button in the list.This way the first master and detail data is always shown in the BDC list and item webparts respectively.This will not require selecting a radio button as the first one is always selected by default.It we want something other than the first item in the list we can select the radio button on the item and view the detail in the BDC item webpart. Can the radio button be defaulted to the first one in the BDC list webpart ?

    On 3/4/2009 12:40:58 AM Arshad said ..
    Hi, sahil. its great article that how we can connect the two web parts and can show their details, but as mention above like An unhandled exception has occurred:There was an error in the callback. even i am getting the same Error. i tried lot but its not happening.

    please help me on that.

    On 3/24/2009 8:33:08 AM Hariom said ..
    Malik saab,

    I need to know the exact dll name of the Business Data Item web part used in this example. I don't see any web part like this in my site's web part gallery. Any help in this regard will be a great favour.

    On 4/21/2009 8:22:14 AM Pria said ..
    Hi.. Even i am getting this exception: an unhandled exception has occurred there was an error in the callback

    Please check my type descriptors below:

    <Parameter Direction="In" Name="@EmployeeKey">

    <TypeDescriptor Name="@EmployeeKey" TypeName ="System.String" AssociatedFilter ="EmployeeKey">



    <Parameter Direction="Return" Name="Employees">

    <TypeDescriptor TypeName="System.Data.IDataReader, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" IsCollection="true" Name="EmployeeDataReader">


    <TypeDescriptor TypeName="System.Data.IDataRecord, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" Name="EmployeeDataRecord">


    <TypeDescriptor TypeName="System.String" Name="FirstName" DefaultDisplayName="FName"/>

    <TypeDescriptor TypeName="System.String" Name="MiddleName"/>

    <TypeDescriptor TypeName="System.String" Name="LastName"/>

    <TypeDescriptor TypeName="System.String" Name="Phone"/>

    <TypeDescriptor TypeName="System.String" Name="EmployeeKey" IdentifierName="EmployeeKey"/>






    Everything looks fine.. But i still face the error..

    Any help would be much appreciated.

    On 5/5/2009 3:32:46 PM John Bailo said ..
    I am trying to remove the menu bar from the built-in Business Data List. I set Chrome=None, but it still shows. Is it possible?

    On 11/11/2009 11:39:14 AM surabhi said ..
    Hi sahil,

    I'm trying to use BDC filter webpart to pass parameter to Reporting service webpart.

    When I configure BDC filter webpart, it's not returning me individual client id. Instead it's returning me some random big id. and giving me error "No exact match was found."\\

    Any idea?