Using a BDC Item/Entity Picker Control in Custom SharePoint Application Pages

I recently had the need to create a custom SharePoint application page (living in_layouts directory) that needed to display the BDC entity picker control, so that a user filling out this form could select a BDC entity instance, exactly like a user would in a business data column defined on a list. It took a while to figure it out, here are the steps to get it working:

Step 1 – Dissecting the ItemPicker control

The control that MOSS uses to render the BDC entity picker is called ItemPicker. You can add it to your aspx page by adding the following reference and code:

Like the People Picker control (PeopleEditor), you have properties that you can set, such as AllowEmpty, MultiSelect, NoMatchesText, etc. However, there is one more property that you have to set, ExtendedData, that cannot be easily set in the aspx markup, so I create a handler in the markup for the Init event, and then set all the properties in code behind:

Step 2 – Setting ExtendedData

In order for the control to work properly, you have to set the ExtendedData property, using the ItemPickerExtendedData Class. This needs to be done via code, so be sure to create a reference to your control first, and handle the Init event of the control:

I’ve broken it out into a little helper method that takes in three parameters, the LOB Instance Name (name of your BDC LOB application instance), Entity name (the name of your Entity, e.g. "Customer"), and the entity display name column (the Name attribute in the TypeDescriptor of the column that acts as the display name column for your entity).

The important things happening here are:

  1. Setting the SystemInstanceId (this marries the control to a particular BDC application).
  2. Setting the EntityId (this marries the control to a particular entity).
  3. Setting the PrimaryColumnId (points the control to the TypeDescriptor that acts as the Identity column)
  4. Setting the SecondaryColumnIds (points the control to the TypeDescriptors for all the other columns you need to bring in).

Step 3 – Consuming the Data

To consume the data, perform some validation, and then try to get a PickerEntity object out of the Entities property of the control:

Once you have a PickerEntity, you can get the ID of the entity instance via the Key property, the display name via the DisplayText property, and also get all the other column data via the EntityData property.

Note that the .Key property is the encoded ID of the entity instance (you can use EntityInstanceIdEncoder to encode/decode this ID). Note also that the EntityData comes back as a HashTable of TypeDescriptor ID/value pairs, so you can’t index into this with a friendly column name. You’ll have to traverse the Entity and its fields, get the TypeDescriptor ID of the column you are interested in, and then use that to index into the hash table. That can be a pain, so it’s almost easier to simply grab the .Key, decode it, and then call FindSpecific() on your Entity.

If you want to pre-populate the entity picker, check out this article:

For SharePoint 2010, and the BCS ItemPicker, see the following article:

6 comments on “Using a BDC Item/Entity Picker Control in Custom SharePoint Application Pages
  1. Thanks, great post!
    Did you ever try this out with multiselect enabled on the picker? If I do this, the selected keys in the picker dialog are encoded. Kind of “__bg40005300; __bg40008300; __bg800013002300″. How to show the keys in plain text on the dialog?
    Thx 4 help :)

  2. Hey Andrew,

    You’re right, I got the same result for multiselect, and I wasn’t able to figure out how to get around that.

    I even poked around with Reflector on the Business Data Filter web part from MS. It uses the BDC picker on a web form to select an entity, but it doesn’t allow for multi-select.

    Luckily I didn’t need that.

  3. Hi,

    i am trying this code. For some reason The browse button is disabled on the control rendered in my custom webpart for item picker, and even if I enter the data it says no exact match found.
    But I have validated the entity by creating an external data column, where it works.

    Any pointers on troubleshooting this?


Comments are closed.