SharePoint Document Libraries and Property Promotion

I have just been doing some investigations around Office Property Promotion and WSS Document Libraries and I thought it might be useful to share my learnings.

What is "Property Promotion"?
This is the name of the SharePoint feature which copies Office document Properties from a document (or file) into the columns of a SharePoint Document Library, thereby "promoting" them. Further, it also "demotes" them by copying them from the SharePoint Document Library back into the property within the document (or file) whenever it is changed via SharePoint. See below for some screen shots to assist.

Document Properties
Fig 1. The Document Property that is "Promoted". This shows a custom property called "Test" which has been set to "Aardvark". To access this dialog, from Word File -> Properties:

This all sounds like a great feature right? And it is, but there are a couple of little tricks to making it work smoothly, here are some common questions and answers:

1. When are properties promoted?
Properties are promoted under the following circumstances:

  • Whenever you select the "New Document" button in a document library to create a new document, or edit an existing document using the "Edit in ...." drop down menu option, upon saving it you will be prompted with the following standard SharePoint File Properties dialog, but with the values already populated:

File Properties
Fig 2. The standard SharePoint WSS File Properties dialog box with "promoted" property.

  • When you save a document you have created outside of SharePoint directly via a web folder (or URL) pointing to a WSS library, you will get exactly the same behaviour as above.
  • When you select "Upload Document" and then perform an "Upload Multiple Files..." using the following tool:

Multiple Upload
Fig 3. The "Upload Multiple Files" dialog box, only available with Office 2003.

  •   Important, it will NOT promote properties when doing a single file upload. This is because the screen to upload displays all the properties associated with the SharePoint document library, and at this point in time SharePoint doesn't actually know which document you plan to upload and therefore cannot complete the properties for you.

2. When are properties demoted?
Whenever you change a property in WSS, usually via the "Edit Properties" option on the drop down menu, your properties will be "demoted" into the document (or file).

3. What document types are supported?
Word/Excel/PowerPoint/XML Files

4. What property types are supported?
Only properties of type "Text" are supported

5. Which properties are promoted?
Only the Custom properties are support (see Fig 1.), unfortunately at this time that means none of the standard properties, besides "Title", are supported.

6. How are XML properties handled during "Property Promotion"?
XML Property Promotion is supported in Forms Libraries only, see the following section in the SharePoint SDK (https://www.microsoft.com/downloads/details.aspx?FamilyId=AA3E7FE5-DAEE-4D10-980F-789B827967B0&displaylang=en)for more information:

Property Promotion
The XML property promotion process defines how to present information from XML files in the columns of a Windows SharePoint Services form library. The columns that are to be promoted, and the data that the XML parser of a form library requires to extract information and store it in list columns, are defined in the properties.xfp file, which is stored in the Forms folder of the form library. Each field defined in the properties.xfp file creates a column in the UserData table of the database, and each XML file in the form library adds a corresponding row to the table. XML Property Promotion works in conjunction with columns already in the SharePoint form library but adds additional columns.

Using Collaborative Application Markup Language (CAML), you can create a properties.xfp file and place it in the Forms folder of a form library to customize XML Property Promotion.

Hopefully that covers most of the bases, if I have missed anything out, as always, feel free to comment away!