Add BCS Secondary Fields to a custom list definition

When working with BCS data and creating an external data column in a list or library it is often desirable to show some or all of the secondary fields. In the SharePoint UI this is a simple task, completed by checking off the fields to capture for viewing, searching, filtering, and sorting later.

 bcssecondaryfields1

However, when you’re building your list or library using a custom list definition schema.xml file this is not as simple. After struggling a bit trying to code the XML myself, it dawned on me that I could mock up the field using the UI and then extract the properly formated field tags by getting the schemaxml proerty of the list.

 bcssecondaryfields2

 

There are various ways to do this but I’ve found the simplest way it to use a tool like SharePoint Manager

  1. Browse to the list/library definition using SharePoint Manager
  2. Copy and paste the SchemaXML property into a text file
  3. Save the text file with an XML extention
  4. Open the XML file in Visual Studio (or some other XML editor). If using Visual Studio, select “Format Document” from the Edit/Advanced menu (Ctrl+E, D)
  5. Scroll down to find the external data field you created through the UI. You’re looking for a <Field> tag with a the Type attribute equal to “BusinessData” The next <Field> tag with Type=”Note” will be the hidden field that stores the key value for the selected value. All the additional <Field> tags that follow will be the secondary fields you selected in the UI.
 bcssecondaryfields3

If you copy and paste those Field tags into your list definition schema file and remove the “SourceID” attribute, the list definition will generate a list with the appropriately defined external data column including the secondary fields.

To dig a little deeper note that you could potentially do this by hand. Creating the field tags for the hidden primary key field and the additional secondary fields isn’t all that difficult.

Where this all get’s tricky is trying to figure out how to format the SecondaryFieldBdcNames, SecondaryFieldWssNames, SecondaryFieldsWssStaticNames attributes of the primary “BusinessData” field tag. Below is our example field tag for the primary business data field.

<Field Type=BusinessData DisplayName=Order Required=FALSE ID={5a261e1a-e157-436c-83a2-fda125d72266} StaticName=Order0 BaseRenderingType=Text Name=Order0 ColName=nvarchar3 RowOrdinal=0 Version=6 Group=“” SystemInstance=MSSExternal EntityNamespace= http://sharepoint/bidemo EntityName=Order BdcField=OrderNumber Profile=/_layouts/ActionRedirect.aspx?EntityNamespace=http%3A%2F%2Fjturner%2Dsrv08r2%2Fbidemo&amp;EntityName=Order&amp;LOBSystemInstanceName=MSSExternal&amp;ItemID= HasActions=True SecondaryFieldBdcNames=15%2014%2015%208%20CustomerRegion%20CustomerState%20CustomerTarget%20Product%2011 RelatedField=Order_ID SecondaryFieldWssNames=33%2033%2033%2027%20Order%5Fx003a%5F%5Fx0020%5FCustomerRegio%20Order%5Fx003a%5F%5Fx0020%5FCustomerState%20Order%5Fx003a%5F%5Fx0020%5FCustomerTarge%20Order%5Fx003a%5F%5Fx0020%5FProduct%2012 RelatedFieldBDCField=“” RelatedFieldWssStaticName=Order_ID SecondaryFieldsWssStaticNames=33%2033%2033%2027%20Order%5Fx003a%5F%5Fx0020%5FCustomerRegio%20Order%5Fx003a%5F%5Fx0020%5FCustomerState%20Order%5Fx003a%5F%5Fx0020%5FCustomerTarge%20Order%5Fx003a%5F%5Fx0020%5FProduct%2012 AddFieldOption=AddToDefaultContentType, AddFieldToDefaultView/>

If you take the value of SecondaryFieldBdcNames attribute for instance and decode it you get:
15 14 15 8 CustomerRegion CustomerState CustomerTarget Product 11
The text CustomerRegion, CustomerState, etc all make sense, they are the root BDC field names. However the numbers that proceed and follow the field names allude me completely.

Regardless, I hope this workaround helps anyone out there who too was struggling to define secondary fields in a custom list definition.

Published by

Julie Turner, MVP

Julie has been building software on primarily the Microsoft platform for over 20 years. With a degree in Electrical Engineering specializing in microprocessor system design from Worcester Polytechnic Institute she came at software initially from a very low level but quickly realized a love and aptitude for developing rich user experiences and solutions. She worked her way up through internal IT ranks reaching a Director of IT position before realizing more impact could be made in consulting and really focused in on the SharePoint platform in 2007. Since then her focus has been on the SharePoint platform, Office 365, Azure, and client side development. She's the co-author of the Widget Wrangler JavaScript library and continues to try and help innovate SharePoint and Office 365 solutions for her clients. She is a 2017 recipient of the Microsoft MVP award for Office Servers and Services.

3 thoughts on “Add BCS Secondary Fields to a custom list definition”

Leave a Reply