Document Property Promotion and Demotion
Applies to: SharePoint Foundation 2010
Property promotion refers to the process of extracting values from properties of a document and writing those values to corresponding columns on the list or document library where the document is stored. Property demotion is the same process in reverse. Values are read from list columns and written to document properties.
Microsoft SharePoint Foundation can work together with a document parser to make the process of promoting and demoting properties automatic. When the values of document properties change, the changes can be automatically written back to the list. When the values of columns or fields in a list item change, the changes can be automatically written back to the document that is associated with the list item. Thus both the document and its associated list item remain in sync.
SharePoint Foundation initiates property promotion or demotion when the following events occur:
A file is uploaded to a document library.
The fields of a list item that is associated with a file are modified.
The Properties property of an SPFile object is updated programmatically.
A file is downloaded for the first time after the list schema has changed.
In each case, SharePoint Foundation determines whether a parser is associated with the file type. If one is, SharePoint Foundation invokes the parser, passing it the document and a property bag object. The parser then either fills the property bag with values that need to be promoted to the list or extracts from the property bag the values that need to be demoted to the document.
SharePoint Foundation only promotes or demotes document properties that match list columns that apply to the document. The columns that apply to a document are specified by the following:
The document's content type, if one is assigned.
The columns in the document library, if the document does not have a content type.
For more information about content types, see Content Types.
SharePoint Foundation also stores the entire document property collection in a hash table, which you can access programmatically through the Properties property of an SPFile object. You cannot access the document properties hash table through a user interface.
For information about how the built-in XML parser promotes and demotes document properties for XML files, see XML Document Property Promotion and Demotion.
Promotion
SharePoint Foundation creates an instance of the IParserPropertyBag Interface and populates the object with any document properties that are specified on the list. It then invokes the document parser for the file type and calls the parser’s Parse method, passing both the document and the property bag as arguments. After the method returns, SharePoint Foundation accesses the property bag and determines which document properties match which list columns and writes those values to the list.
The following figure illustrates the document promotion process. In this process, the parser extracts document properties from the document and writes them to the property bag. Of the four document properties, three are included in the document's content type. SharePoint Foundation in turn matches properties in the property bag to columns (fields) of the document library and then promotes these properties to the document library; that is, it writes their property values to the appropriate columns. Because the document's content type does not include the Status column, SharePoint Foundation does not promote the fourth document property, Status, even though the document library includes a matching column. SharePoint Foundation also writes all four document properties to the Properties property of the SPFile object that represents the document in the document library.
.gif "Property promotion using a custom parser")
Demotion
SharePoint Foundation creates an instance of the IParserPropertyBag Interface and populates the object with document properties that are specified on the list. It then invokes the document parser for the file type and calls the parser’s Demote method, passing both the document and the property bag as arguments. The Demote method accesses the property bag, matches list columns to document properties, and writes appropriate values back to the document.
The following figure shows the document property demotion process. To update two document properties, SharePoint Foundation invokes the parser, passing it the document to be updated, and a property bag object that contains the two document properties. The parser reads the property values from the property bag and updates the properties in the document. When the parser finishes updating the document, it sets a flag passed in an output parameter that indicates that it has changed the document. SharePoint Foundation then saves the updated document to the document library.
.gif "Property demotion using a custom parser")