Location-Based Metadata Defaults in SharePoint Server 2010 (ECM)
Applies to: SharePoint Server 2010
In this article
Introducing Location-Based Metadata Defaults
Conditions and Precedence
Registering Event Receivers to Apply Default Metadata
Configuring Metadata Defaults for Locations
Location-Based Metadata Defaults Programmability
This topic introduces location-based metadata defaults, their configuration options, precedence rules that govern their application and how location-based metadata defaults use event receivers to apply default metadata.
Introducing Location-Based Metadata Defaults
Location-based metadata defaults manages the default values of metadata fields based on location and applies them so that they are available when the user edits a document. When a user interacts with a Microsoft SharePoint Server 2010 site, SharePoint Server applies default values so that they appear the first time that the user sees a document edit form. Microsoft Office 2010 applications such as Microsoft Word 2010 get the default values for a location when the document is saved. When saving the document, the client application gets content type information for the location where the content item is saved, and the server applies the default values and builds the property schema inside the Office 2010 document.
Conditions and Precedence
Location-based metadata defaults follow conditional rules to determine when default values are applied to a document. This section first lists the conditions, and then explains the precedence rules that are used to apply them.
Defaults are applied:
When you upload a single file.
When you add files in bulk by using Explorer View or by using the Upload Multiple Documents ActiveX control.
When you create a new publishing page.
When you create a new default document in a document set.
When a workflow creates a document.
When you save directly from Office 2010 client applications or a SharePoint Workspace.
After the document conversion has completed.
SharePoint Server 2010 applies and enforces location-based metadata defaults by first establishing a set of general precedence rules to determine what metadata defaults are applied and in what order. For example, specific precedence rules are used to apply defaults to the server, register event receivers, determine the sequence of events that fire when a document is uploaded to the server, and so on.
How and when SharePoint Server 2010 applies location-based metadata defaults to items is governed by how the feature sets precedence. First, when uploading a document to a folder in a document library, location-based metadata default values for columns are acquired from different places, including:
The document that is being uploaded, which may contain a column value, a built-in column such as "Title," or a document that was previously stored with a schema applied (that included the same column). These are both cases where the document being uploaded can contain a column value.
The field definition on the list, which may specify a default value.
The location to which the document is being uploaded in the document library, which may specify a default column value.
Precedence rules are used to determine the value that is applied to a column:
If the uploaded document contains a value for the field equal to the list default for the field definition, SharePoint Server 2010 overwrites the field's current value with a location-based default if one exists based on precedence rules.
If the uploaded document contains a value that differs from the list default, then SharePoint Server 2010 retains that value even if a location-based default exists for it.
If a field does not exist, the server uses the default value that is set in the field definition.
Registering Event Receivers to Apply Default Metadata
The first time that you configure a location-based metadata default for any location in a document library, SharePoint Server 2010 registers a new synchronous ItemAdded post-event event receiver on that document library. After the event is registered, the server applies it to the per-location defaults. A sequence of events affects how location-based metadata defaults are promoted out of documents to the appropriate column in a SharePoint Server 2010 list, what defaults are specified for a location, and whether the values of any properties need to be updated or corrected.
User uploads a document to a location. At this time, metadata is promoted out of the document.
The new ItemAdded event receiver runs. It checks what location-based metadata defaults are specified for the location and updates the value of any properties if a default is specified and the current value is equivalent to the default for the specified content type.
The user sees the standard edit form for the item, and the correct defaults for the location are already there.
If you remove the last per-location default in the document library, the server unregisters the event receiver.
After the document is uploaded to the server, the ItemAdded event is triggered and the document’s metadata values for all columns are promoted to the appropriate column in the list. SharePoint Server 2010 displays the Edit form for the document and the server changes the actual metadata values by using general precedence rules.
Configuring Metadata Defaults for Locations
You can configure location-based metadata defaults on columns that support setting defaults, in a hierarchy of folders. If metadata values are configured on a parent folder, then its subfolders inherit the metadata values from the parent unless a different metadata value is explicitly specified on a subfolder. Depending on whether or how folders or metadata are manipulated through the UI or API, the default metadata values of folders and subfolders can be affected.
Assuming no defaults are configured for any folder or subfolder, and that the list includes only one column (a text column named "TheOnlyColumn" with an empty string for a default value), a series of three actions modifies the default metadata values of folders and subfolders based on inheritance. For example, consider a sample structure where:
A folder named DocLib is the parent.
Folders named Alpha and Beta are subfolders of the DocLib folder.
The folders AlphaOne and AlphaTwo are subfolders of Alpha.
BetaOne is a subfolder of Beta.
First Action: Navigating to the Beta Folder and Setting a Default Value
A user navigates to the Beta folder and sets a default value of "Z" for TheOnlyColumn.
Table 1. Effect of setting metadata values on folders: first action
If you add an item in this folder . . . |
The default value of TheOnlyColumn is . . . |
|---|---|
DocLib (root) |
Blank |
Alpha |
Blank |
AlphaOne |
Blank |
AlphaTwo |
Blank |
Beta |
Z |
BetaOne |
Z |
The change affects both the Beta folder and the BetaOne folder: Modifying the metadata value of Beta affects BetaOne because BetaOne is a subfolder of Beta, so it inherits the metadata value of its parent.
Second Action: Navigating to the Alpha Folder and Setting a Default Value
A second user navigates to the Alpha folder and sets a default value of "Y".
Table 2. Effect of setting metadata values on folders: second action
If you add an item in this folder . . . |
The default value of TheOnlyColumn is . . . |
DocLib (root) |
Blank |
Alpha |
Y |
AlphaOne |
Y |
AlphaTwo |
Y |
Beta |
Z |
BetaOne |
Z |
The change affects the Alpha folder and its subfolders. The Beta folders are not affected.
Third Action: Navigating to the AlphaOne Folder and Setting a Default Value
Finally, another user navigates to folder AlphaOne and sets a default value of "X".
Table 3. The effect of setting metadata values on folders: third action
If you add an item in this folder . . . |
The default value of TheOnlyColumn is . . . |
|---|---|
DocLib (root) |
Blank |
Alpha |
Y |
AlphaOne |
X |
AlphaTwo |
Y |
Beta |
Z |
BetaOne |
Z |
The value of the AlphaTwo folder is still "Y". The change to the AlphaOne folder does not affect AlphaTwo, because AlphaTwo is not a child of the AlphaOne folder.
Location-Based Metadata Defaults Programmability
The object model for location-based metadata defaults is found primarily in the MetadataDefaults type. It included methods that you can use to apply location-based metadata defaults; and get, set, and remove default metadata from String and SPFolder objects, and get field default values. The managed reference documentation for MetadataDefaults contains code snippets that demonstrate this functionality.
See Also
Concepts
Developing with Document Management Features in SharePoint Server 2010 (ECM)
Document Management Programming Model in SharePoint Server 2010 (ECM)