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 ( 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!

Comments (14)
  1. Hi there, great article. Have been a reader of your blog for a while now, and just wanted to say thanks.

  2. Daniel MCPherson says:

    Thanks for the feedback, nice to know there are people out there! <grin>

  3. Yuval Kronenfeld says:


    i think you have a mistake – the properties are not promoted when doing multiple upload and not single upload (well at least for me 🙂 )

    Am i right ?



  4. Daniel MCPherson says:

    Hey Yuval, properties are certainly promoted when do the multiple upload, but not with a single upload. Make sure you check all the points in the section: "When are properties promoted" specifically, that the field names are the same and of type string.

  5. Yuval Kronenfeld says:

    Sorry – my mistake,I understood it wrong.

    It works perfect.

    by the way – do you know how can I just reflect the standard properties?

    Thank you for the article.


  6. Mads Nissen says:

    Related to how this works is my little sharepoint change request posted here:

    The annoying thing is that you often want to use these props as fields in your document, however you’ll need a macro to actually update the fields OnOpen in order for the new values to display. Also, values should be entered on create, not save..

    just my two cents..

  7. Poqwe says:


    This is exactly as I thought it should work. However, when I save into doc library, the web file properties pop/up windows doesn’t open. Am I missing something in client side or is a configuration in SPS?

  8. Point2Share says:

    Well, it’s been 2 years of Point2Share!

    I’m a little late with the Anniversary, but it seems I started…

  9. The following points may be valuable as you consider migrating content from Windows file shares to SharePoint…

Comments are closed.

Skip to main content