Routing a Record to a SharePoint 2010 Document Library Subfolder

Summary:  Learn about routing a record to a Microsoft SharePoint Server 2010 document library folder by using the content organizer feature and document routing rules.

Applies to: Business Connectivity Services | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio

Provided by:   Spencer Harbar (Microsoft Certified Master, SharePoint MVP), Harbar.net

Contents

• Introduction to Routing a Record to a SharePoint 2010 Document Library Subfolder

• Example Scenario for Routing a Record to a SharePoint 2010 Document Library Subfolder

• Configuring the Content Organizer

  • Configuring Content Organizer Rules

  • Programmatically Creating Content Organizer Rules

  • Submitting Records

• Conclusion

• Additional Resources

Introduction to Routing a Record to a SharePoint 2010 Document Library Subfolder

To redirect incoming records to a folder within a document library, use the content organizer feature of SharePoint Server 2010 to configure routing rules to manage the redirects. Although the content organizer was originally designed for use with a records archive, you can use it whenever you need to route or redirect incoming content to any document library. After you set up content organizer rules, use them to route items regardless of how they are submitted to the library: through the user interface (UI) or through custom code.

Example Scenario for Routing a Record to a SharePoint 2010 Document Library Subfolder

In the example scenario, Contoso is a SharePoint Server 2010 site based on the team site template, and the Contoso Records Center uses the records center template. The example scenario uses two site collections: http://contoso/ and http://contoso/recordscenter/. Documents come from the team site template (http://contoso) and are routed to the records center template (http://contoso/recordscenter/). SharePoint Server 2010 configures the content organizer's rules at http://contoso/recordscenter/.

Content Type

The example scenario uses a single content type, named Sales Proposal, that is based on a parent Document content type.

Table 1. Sales proposal content type

Deploy this content type to both the http://contoso/ site collection and the http://contoso/recordscenter/ site collection by using the content type publishing capability of the Managed Metadata Service (MMS). MMS is not required, but the content type must exist at both site collections for this scenario to work.

Send To Connection

The example scenario uses a Send To connection, which enables you to copy a record from the http://contoso/ site collection to the http://contoso/recordscenter/ site collection. A Send To connection is not the only way to import items into the Records Archive, and no matter what mechanism is used, the content organizer rules route the record to the appropriate folder.

Destination Records Library

The records archive contains a records library named Sales Proposals. The Sales Proposals library contains two folders, Contoso and AdventureWorks. The library also contains the Sales Proposal content type. After the library is configured, the content organizer rules route records to the appropriate folder based on the value of the Customer column.

Configuring the Content Organizer

When working with a destination site that is based on the Records Center template, the content organizer site feature is activated by default, and its settings are configured automatically.

Content organizer settings

For other site types, the content organizer feature may need to be activated.

To activate the content organizer site feature

1. On the Site Actions menu, click Site Settings, and then click Manage Site Features.

2. Click Activate for the content organizer feature.

Two new Site Administration options appear: Content Organizer Settings and Content Organizer Rules. To enforce the use of content organizer rules, enable the Redirect Users to the Drop Off Library setting.

To configure content organizer settings

1. In the Site Administration section of Site Settings, click Content organizer Settings.

2. Select the Require users to use the organizer when submitting new content to libraries with one or more organizer rules pointing to them check box. (See Figure 1.)

3. Click OK to save changes.

Figure 1. Content organizer settings

Configuring Content Organizer Rules

SharePoint Server 2010 requires content organizer rules to route incoming records to a specified location. After the content organizer site feature is enabled, a type of user called a Rule Manager can be specified. Rule Managers (in addition to members of the Site Owners group and other users with full control permissions) can create content organizer rules.

To configure content organizer rules

1. In the Site Administration section of Site Settings, click Content Organizer Rules.

2. Click Add new item.

3. In the Content Organizer Rules: New Rule dialog box, in the Rule Name section, type a name for the rule in the Name field (for example, Contoso Sales Proposals).

   Figure 2. Content Organizer dialog box: Rule Name section

   

4. In the Submission's Content Type section, enter Custom Content Types in the Group combo box and enter Sales Proposal in the Type combo box.

   Figure 3. Content organizer rule: Content type of the submission

   

5. In the Conditions section, enter Customer in the Property combo box, and select Contoso in the Value combo box.

   Figure 4. Content organizer rule: Conditions

   

6. In the Target Location section, click Browse. In the pop-up window, select the Contoso folder in the Sales Proposals records library, and then click OK.

   Figure 5. Content organizer rule: Target Location

   

7. Click OK to save the new content organizer rule.

8. Repeat steps 2 through 7 for Adventure Works Sales Proposals, using the Adventure Works customer value and the Adventure Works folder.

Programmatically Creating Content Organizer Rules

You can create content organizer rules programatically by using the EcmDocumentRouterRule class. Creating rules programmatically is useful in scenarios where automation is required, or when it is undesirable to allow site users to manage rules.

The following code example creates another content organizer rule, this time for Woodgrove.

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Taxonomy;
using Microsoft.Office.RecordsManagement.RecordsRepository;

namespace ContentOrganizerRules
{
    class CreateRule
    {
        static void Main(string[] args)
        {
            string absoluteSiteUrl = "http://contoso/recordscenter/";
            string ruleName = "Woodgrove Sales Proposals";
            string ruleDescription = "Sample rule to organize documents";
            string ruleLibraryName = "Sales Proposals";
            string ruleFolderUrl = "Sales Proposals/Woodgrove";
            string ruleContentTypeName = "Sales Proposal";

            string conditionFieldId = "90d69139-483c-4872-8ce0-5884bd370513"; // SPField.Id
            string conditionFieldInternalName = "Customer"; //SPField.InternalName
            string conditionFieldTitle = "Customer"; //SPField.Title

            string conditionOperator = "Equal";
            string conditionFieldValue = "Woodgrove";

            // Build the conditionSettings XML from the constants above.
            string conditionXml = 
                String.Format(@"<Condition Column=""{0}|{1}|{2}"" Operator=""{3}"" Value=""{4}"" />",
                conditionFieldId, conditionFieldInternalName, conditionFieldTitle,
                conditionOperator,
                conditionFieldValue);
            string conditionsXml = String.Format("<Conditions>{0}</Conditions>", conditionXml);

            // Grab the SPWeb object and the rules library.
            using (SPSite contentOrganizerSiteCollection = new SPSite(absoluteSiteUrl))
            {
                SPWeb contentOrganizerSite = contentOrganizerSiteCollection.OpenWeb();
                EcmDocumentRoutingWeb contentOrganizerSiteWrapper = 
                  new EcmDocumentRoutingWeb(contentOrganizerSite); 
                SPContentType ruleContentType = contentOrganizerSite.ContentTypes[ruleContentTypeName];
                SPList ruleLibrary = contentOrganizerSite.Lists[ruleLibraryName];

                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",
                        ruleLibraryName,
                        ruleContentTypeName));
                }

                // Create a blank rule.
                EcmDocumentRouterRule organizeDocument = new EcmDocumentRouterRule(contentOrganizerSite);

                // Configure the rule.
                organizeDocument.Name = ruleName;
                organizeDocument.Description = ruleDescription;
                organizeDocument.ContentTypeString = ruleContentType.Name;
                organizeDocument.RouteToExternalLocation = false;
                organizeDocument.Priority = "5";
                organizeDocument.TargetPath = 
                  contentOrganizerSite.GetFolder(absoluteSiteUrl + ruleFolderUrl).ServerRelativeUrl;
                organizeDocument.ConditionsString = conditionsXml;
                
                // Update the rule and commit changes.
                organizeDocument.Update();
            }
        }
    }
}

Submitting Records

A Send To connection can be used to import items into the records archive, but the content organizer rules route a record to the appropriate folder regardless of the import method.

Use the SendToOfficialFile method to submit records by using code, if the records are already stored on a SharePoint Server 2010 site. Use the OfficialFileService class to submit files that are stored outside SharePoint Server 2010.

When using the OfficialFileService class in this scenario, include the content type (along with any other required columns) when submitting the record. This enables the record to be routed to the correct location by the content organizer.

The following code example uses the OfficialFileService class to submit records.

using System;
using System.Collections.Generic;
using System.IO;
using RecordsAdmission.OfficialFileService;

namespace RecordsAdmission
{
    class Program
    {
        static void Main(string[] args)
        {
            string filePath = @"c:\contoso.docx";

            RecordsRepository repository = new RecordsRepository();
            repository.Url = "http://contoso/recordscenter/_vti_bin/officialfile.asmx";
            repository.UseDefaultCredentials = true;
            byte[] fileContent = File.ReadAllBytes(filePath);
            
            List<OfficialFileService.RecordsRepositoryProperty> properties = 
              new List<OfficialFileService.RecordsRepositoryProperty>();
            properties.Add(new OfficialFileService.RecordsRepositoryProperty() 
              { Name = "Title", Type = "Text", Value = "ctypetest" });
            properties.Add(new OfficialFileService.RecordsRepositoryProperty() 
              { Name = "Name", Type = "Text", Value = "contosofs.docx" });
            properties.Add(new OfficialFileService.RecordsRepositoryProperty() 
              { Name = "Customer", Type = "Text", Value = "Contoso" });
            properties.Add(new OfficialFileService.RecordsRepositoryProperty() 
              { Name = "ContentType", Type = "Text", Value = "Sales Proposal" });

            string sourceUrl = filePath;
            string userName = @"sharepoint\administrator";

            string result = repository.SubmitFile(fileContent, properties.ToArray(), 
              null, sourceUrl, userName);
            Console.WriteLine(result);
            Console.ReadLine();
        }
    }
}

After the content organizer rules are defined, any incoming records that match the Sales Proposal content type, regardless of how they are submitted, are redirected to the appropriate folder in the Sales Proposals library, as shown in Figure 6 and Figure 7.

Figure 6. Sales Proposals library contents

Figure 7. AdventureWorks folder contents

If the Customer value of a record does not match any rules, the record is sent to the Drop Off Library, which is the default location for items that do not match any rule.

Conclusion

This article explains how to redirect incoming records to a folder within a document library by using the SharePoint Server 2010 content organizer feature. First, the article introduces the example record routing scenario. Next, it explains how to create and configure content organizer rules through the UI and programmatically with the object model. Finally, it covers submitting records with a Send To connection and the OfficialFileService class.

Additional Resources

For more information, see the following resources:

• SharePoint 2010 ECM Code Sample: Create a Routing Rule

• Content Organizer Feature Overview for SharePoint Server 2010 Developers (ECM)

• Managing Enterprise Metadata in SharePoint Server 2010 (ECM)

• Migrating Managed Metadata in SharePoint Server 2010

• Enterprise Content Management Resource Center | SharePoint 2010

• SharePoint Developer Center