EcmDocumentRouterRule class

Represents a rule that defines document-routing behavior for the content organizer.

Inheritance hierarchy


Namespace:  Microsoft.Office.RecordsManagement.RecordsRepository
Assembly:  Microsoft.Office.Policy (in Microsoft.Office.Policy.dll)


Public Class EcmDocumentRouterRule
Dim instance As EcmDocumentRouterRule
public class EcmDocumentRouterRule


The following sample code creates a rule to organize documents of the “Contract” content type into a document library on the site. It exemplifies how to use the Content Organizer API to organize documents on the site.

using System;
using System.Text;
using Microsoft.SharePoint;
using TaxonomyField = Microsoft.SharePoint.Taxonomy.TaxonomyField;
using EcmDocumentRoutingWeb = Microsoft.Office.RecordsManagement.RecordsRepository.EcmDocumentRoutingWeb;
using EcmDocumentRouterRule = Microsoft.Office.RecordsManagement.RecordsRepository.EcmDocumentRouterRule;
using EcmDocumentRouter = Microsoft.Office.RecordsManagement.RecordsRepository.EcmDocumentRouter;
using DocumentRouterAutoFolderSettings = Microsoft.Office.RecordsManagement.RecordsRepository.DocumentRouterAutoFolderSettings;

namespace Microsoft.SDK.SharePointServer.Samples
    class ContentOrganizerCodeSample
        /// <summary>
        /// Sample code to create a content organizer rule that organizes documents of the Contract content type to a document library within the site.
        /// Also exemplifies usage of content organizer API to organize documents in the site.
        /// </summary>
        /// <remarks>This code sample assumes that the site contains a content type called "Contract" derived from the Document content type.
        /// The Contract content type contains a required TaxonomyField called "Business Division" </remarks>
        /// <param name="args"></param>
        /// <see cref="SPContentType"/>
        /// <see cref="SPField.Required"/>
        /// <see cref="TaxonomyField"/>
        /// <exception cref="System.ArgumentException">List did not exist in the site</exception>
        static void Main(string[] args)
            // Change http://SiteUrl to the absolute url of the content organizer enabled site where the custom router needs to be registered.
            const string absoluteSiteUrl = "http://SiteUrl";
            // Change Organize Documents to the desired name for the rule.
            const string ruleName = "Organize Documents";
            // Change "Sample rule to organize documents" to a description for the rule.
            const string ruleDescription = "Sample rule to organize documents";
            // Change My Documents to the desired library to which documents matching this rule should be organized.
            const string ruleLibraryName = "My Documents";
            // Change Contract to the name of the content type on which this rule should be based.
            const string ruleContentTypeName = "Contract";

            // Values for Condition on fields - See SPField class for more details
            // Set conditionFieldId with the serialized Guid, Id property of the SPField used in the condition
            const string conditionFieldId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
            // Set conditionFieldInternalName with the InternalName property of the SPField
            const string conditionFieldInternalName = "FieldInternalName";
            // Set conditionFieldTitle with the Title property of the SPField.
            const string conditionFieldTitle = "FieldTitle";
            // Set conditionOperator with the operator used to evaluate whether a document matches this rule. 
            // If conditionOperator is set to be a unary operator (IsEmpty or IsNotEmpty), it will be applied on the value of the condition field on the document.            
            const string conditionOperator = "Contains";
            // Set conditionFieldValue with the value used as an operand for "Op" if "Op" is a binary operator (Contains, Equal etc.,).
            const string conditionFieldValue = "Restaurant";

            // Values for automatic folder creation settings
            // Change Business Division to the name of the managed metadata field on which automatic folder creation is based.
            const string autoFolderPropertyName = "Business Division";
            // Replace with a format of your choice. Place holder %1 will be replaced by the name of the field and %2 will be replaced by the value of the field for the document.
            const string autoFolderNameFormat = "Contract %1 - %2";

            // An empty title indicates absence of conditions.
            string conditionXml = string.IsNullOrEmpty(conditionFieldTitle) ?
                string.Empty :
                String.Format(@"<Condition Column=""{0}|{1}|{2}"" Operator=""{3}"" Value=""{4}"" />",
                conditionFieldId, conditionFieldInternalName, conditionFieldTitle,

            // The condition Xml can repeat 0-5 times depending on the number of conditions required for a document to match this rule.
            string conditionsXml = String.Format("<Conditions>{0}</Conditions>", conditionXml);

            using (SPSite contentOrganizerSiteCollection = new SPSite(absoluteSiteUrl))
                SPWeb contentOrganizerSite = contentOrganizerSiteCollection.OpenWeb();
                EcmDocumentRoutingWeb contentOrganizerSiteWrapper = new EcmDocumentRoutingWeb(contentOrganizerSite);

                // Ensure that the content type exists for this rule                
                SPContentType ruleContentType = contentOrganizerSite.ContentTypes[ruleContentTypeName];

                // Ensure that the final location exists for this rule.
                SPList ruleLibrary = contentOrganizerSite.Lists[ruleLibraryName];
                // Ensure that the final location contains the content type of the rule.
                if (ruleLibrary.ContentTypes.BestMatch(ruleContentType.Id) == null)
                    throw new ArgumentException(String.Format(
                        "Ensure that the library {0} contains content type {1} before creating the rule",
                // Create a blank rule
                EcmDocumentRouterRule organizeDocument = new EcmDocumentRouterRule(contentOrganizerSite);
                // Configure the rule to specify conditions that match the rule and final location for documents matching this rule.
                organizeDocument.Name = ruleName;
                organizeDocument.Description = ruleDescription;
                // Configure the rule so that it will be evaluated on documents of "Contract" content type
                organizeDocument.ContentTypeString = ruleContentType.Name;
                organizeDocument.RouteToExternalLocation = false;
                // Set a priority for this rule which indicates the order in which rules are executed. This is a number between 0 and 9.
                organizeDocument.Priority = "2";
                // Specify where the documents that match this rule get saved to.
                // To route documents externally, the TargetPath value can be set to one of the SendTo connections configured for this web application or site subscription.
                // Example: organizeDocument.TargetPath = contentOrganizerSiteCollection.WebApplication.OfficialFileHosts[0];
                organizeDocument.TargetPath = ruleLibrary.RootFolder.ServerRelativeUrl;

                // Set the conditions string for this rule
                organizeDocument.ConditionsString = conditionsXml;
                // AutoFolder configuration: Optionally enable automatic folder creation for this rule based on a non-empty (required or boolean) field. 
                // Folders will be created for each unique value of this field in the TargethPath and documents will be saved here.

                // Ensure the SPField for the autofolder property
                TaxonomyField autoFolderField = ruleContentType.Fields[autoFolderPropertyName] as TaxonomyField;
                if (autoFolderField == null)
                    throw new ArgumentException(String.Format("The field {0} is not a valid Taxonomy Field", autoFolderPropertyName));

                // Get a handle to the rule auto folder settings.
                DocumentRouterAutoFolderSettings autoFolderSettings = organizeDocument.AutoFolderSettings;
                // Configure AutoFolderSettings for this rule based on the "Business Division" Taxonomy field.                 
                autoFolderSettings.AutoFolderPropertyName = autoFolderField.Title;
                autoFolderSettings.AutoFolderPropertyInternalName = autoFolderField.InternalName;
                autoFolderSettings.AutoFolderPropertyId = autoFolderField.Id;
                // Term store Id required to get the value of the field from the document. Required for TaxonomyField types.
                autoFolderSettings.TaxTermStoreId = autoFolderField.SspId;
                // Set a format for the name of the folder. 
                autoFolderSettings.AutoFolderFolderNameFormat = autoFolderNameFormat;
                // Enabled automatic folder creation for values of the "Business Division" field.
                autoFolderSettings.Enabled = true;

                // Update the rule and commit changes.

Thread safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See also


EcmDocumentRouterRule members

Microsoft.Office.RecordsManagement.RecordsRepository namespace