Using Metadata Tags to Route Documents to Libraries in SharePoint Server 2007

SharePoint 2007

Summary:  Learn how to implement a custom router in Microsoft Office SharePoint Server 2007 that routes documents to a specific folder in the records center by using metadata on the document instead of the content type.

Office Visual How To

Applies to:  2007 Microsoft Office System, Microsoft Office SharePoint Server 2007

Microsoft Corporation

March 2008


Microsoft Office SharePoint Server 2007 lets you send content to the records center and route the content to the proper location in the repository based on its content type. You can extend this router functionality by implementing a custom router. In this Microsoft Office Visual How To, you learn how to implement a custom router that routes documents to their proper location in the records center by using metadata, such as a retention code or project designation, on the document rather than the content type. This example also demonstrates how to route an incoming record to a specific folder.

Code It

For this scenario, documents that are sent to the records center are routed using a custom router. The router determines if an incoming document contains a metadata field name Project, which results in the document being routed to the Project Records library. In addition, the value in this project field determines the specific folder location to which the document is routed. Also, the metadata from the original document is applied to the newly created record.

Several items were configured in the records center for this example. First, a custom router was created and implemented on the Unclassified Records item in the Record Routing list. A library named Project Records is in the records center, and two folders named Project A and Project B were added. In the Shared Documents library of a team site outside the records center, a choice field named Project was added. The Project field has two choices, Project A and Project B, displayed as a drop-down menu. Finally, two documents were uploaded to this library: one with the Project field set to Project A, and the other with the field set to Project B.

You add the logic for the router to the OnSubmitFile method of the class that implements the IRouter interface. The first step in determining if the incoming document should be routed to the Project Records library is to see if it contains a Project metadata field. The metadata properties are passed into the method as a RecordsRepositoryProperty structure, which is converted to a Hashtable.

   public class MetadataRouter : RecordsRepository.IRouter
      public RecordsRepository.RouterResult OnSubmitFile(string recordSeries, 
         string sourceUrl, string userName, ref byte[] fileToSubmit,
         ref Microsoft.Office.RecordsManagement.RecordsRepository.RecordsRepositoryProperty[]
         properties, ref SPList destination, ref string resultDetails)
         RecordsRepository.RouterResult result 
         = RecordsRepository.RouterResult.SuccessContinueProcessing;


            // Add the properties to a hash table for easier access.
            Hashtable hashProperties = new Hashtable();
            foreach (RecordsRepository.RecordsRepositoryProperty property in properties)
                if (!(hashProperties.ContainsKey(property.Name)))
                    hashProperties.Add(property.Name, property.Value);

            // If this has a "Project" field, put the record in proper location.
            if (hashProperties.ContainsKey("Project"))
               using (SPWeb web = destination.ParentWeb)
                  // Get the destination for this content.
                  string projectLibrary = "Project Records";
                  string projectFolderPath = projectLibrary + "/" + 

                  // Get the file name and destination URL.
                  string fileName = Path.GetFileName(sourceUrl);
                  string destinationPath = projectFolderPath.TrimEnd('/') + "/" + fileName;

                  // Get the folder.
                  SPFolder folder = web.GetFolder(projectFolderPath);

                  // Add the file to the folder.
                  SPFile file 
                  = folder.Files.Add(destinationPath, fileToSubmit, hashProperties, false);

                  // Added the file so no need for further processing.
                  = RecordsRepository.RouterResult.SuccessCancelFurtherProcessing;
         catch (Exception ex)
            // If an exception occurs, reject the file and send an error message back.
            result = RecordsRepository.RouterResult.RejectFile;
            resultDetails = "TODO: Add my error message here..."; 
         return result;

If the Hashtable contains a Project property, you identify this as a document that should be routed to the Project Records location and define the specific location in the library the records should be added to. You determine the destination folder by using the value of the Project property as the name of the folder in the Project Records library. You add the file to the folder by obtaining an SPFolder object and calling the File.Add method on the folder, passing in the URL to the file destination, the byte array of the file, the Hashtable that contains all the properties, and a Boolean to overwrite an existing file if it exists. After the file is added to the folder, the method returns RouterResult.SuccessCancelFurtherProcessing.

To test the scenario, select Send To, and then select Records Center on a document in the previously configured Shared Documents library. This sends the document to the records center and invokes the custom router, which processes the metadata and adds the file to the correct folder in the Project Records library as identified by the value of the Project property of the incoming file.

Read It

If an error occurs during the execution of the code within the router, you can pass an error message back to the user. You do this by setting the value of the resultDetails variable and returning a RouterResult of RejectFile. This variable is passed in to the OnSubmitFile method as a reference, and its value is returned to the user as an error message. Processing of the file does not continue.

You can implement custom routers to enhance the existing routing functionality, such as editing the metadata or file contents before placing the file in the records center. Additionally, you can implement enhanced routing capabilities, such as routing files based on their metadata, as with this example, or routing files to other records centers contained within the organization.

This example does not automatically partition every 2000 items into a new folder, as dictated by Office SharePoint Server best practices. To ensure that these best practices are followed, you can add logic to automatically partition new folders, or you can evaluate the folder structure to ensure it is balanced in this regard.

Also, this specific scenario applies only when a small set of metadata is used for routing, which is particularly useful for routing by retention code, for example. You can expand it further to allow the router owner the flexibility to choose the properties with which to route the incoming records.

See It

Using Metadata Tags to Route Documents

Watch the Video

Video Length: 00:07:05

File Size: 5.35 MB WMV

Explore It

Community Additions