Troubleshooting BDC Associations and Related Data List Web part

Tue, Jun 22, 2010 4-minute read

I’ve been working with the BDC and a proprietary CRM system to bring data about sales history into SharePoint. I’ve been using the basic BDC tool - Business Data Catalog Definition Editor - that is bundled with the SharePoint SDK. It’s very basic, and there are one or two commercial products out there, but it just about does enough, and is free, after all. It enables you to define the entities, relationships and methods, and test them, within the tool. The error reporting is moderate - you’re informed about the major issues, but, some errors only appear when you’ve imported the ADF and are actually working within the SharePoint environment.

I encountered one such error working with Business Data Lists, and, more specifically, Related Business Data Lists. The error manifests in two forms. This error message is displayed in the web part:

The Business Data Catalog is configured incorrectly. Administrators, see the server log for more information.

And if you check the event log on the server:

A Metadata Exception was constructed in App Domain ‘/LM/W3SVC/xxx/Root-x-xxx’. The full exception text is: Could not find appropriate places on the root TypeDescriptor to read sub-identifier values for the Instance of Entity ‘xxx'

You will have likely encountered this error before whilst developing the ADF. It’s essentially saying: “I’ve selected all this data from the database, but I can’t find the correct places on the return type, so I’m not sure what to do.” What’s infuriating about this is that if you try your method in the BDC DE, it will work fine. So it’s a bit of trial and error to work out exactly what it’s complaining about. So here are some notes and things to check/try:

  1. The method with the error is the one that with a MethodInstanceType of GenericInvoker.
  2. If you defined the Association (i.e., the tables to join together) in the BDC DE using the design surface, and your database is configured correctly with the foreign keys, etc. (which it will need in order to determine the relationship), then the method name will probably start FK_ followed by 2nd_entity_on_1st_entity, e.g., FK_orders_customer
  3. I read elsewhere that “identifier which is used in order to call the method in one entity, same identifier should also be present in other entity” - what this means is in your Associated data (what I’m calling “target” data) you must have one parameter which uses the identifier from the “source” data in its Type Descriptor (see attached image, red boxes)
  4. I took (3) a few steps further and ensured that the name of the parameter and TypeDescriptor in each entity were identical (attached, green boxes)
  5. I also assume that this is true of any method in source that is calling the target, that is, you’ll most likely be calling the target from your Finder method, which is the method you use in a Business Data Item / Business Data List webpart. The BDC DE does not create the Finder method for you - you have to create it manually. If you wanted to be able to add the Associated data to any of your other methods, you’d need to ensure (3) & (4) above, although I’m not familiar with any circumstances where you’d need to do this.
  6. Ensure there is an item on your TypeDescriptors for the return parameter for each of the entity identifiers. By default, BDC DE creates a structure of Parameter > OutParamName > Reader > Record. If your entity as two identifiers called “ref” and “number”, make sure that under Record, there is at least a TypeDescriptor for “ref” and “number” which link to the appropriate identifier
  7. Deploying and testing your ADFs is a bit of a rigmarole. The BDC will let you upgrade existing applications, but since it uses a cache, timer jobs and various other things in the deployment, you can never be quite sure if your new version is “live” - it is possible to delete the existing application, refresh the webpart page until you see an error, then install the new version, although this is time consuming and a very brute force approach!
  8. The name of the TypeDescriptors in your Record relate to the name of the column returned by the database - but if you want things to be more descriptive you can use aliases in the query, and reference those in the ADF

Hopefully that’s of some use. If you’re using the BDC on a very regular basis, it’s undoubtedly worth investing in a decent BDC tool.