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

Overview

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
      Implements RecordsRepository.IRouter

      Public Function OnSubmitFile(ByVal recordSeries As String, &_
      ByVal sourceUrl As String, ByVal userName As String, &_
      ByRef fileToSubmit() As Byte, &_
      ByRef properties() As &_
      Microsoft.Office.RecordsManagement.RecordsRepository.RecordsRepositoryProperty, &_
      ByRef destination As Microsoft.SharePoint.SPList, &_
      ByRef resultDetails As String) As RecordsRepository.RouterResult &_
      Implements RecordsRepository.IRouter.OnSubmitFile

         Dim result As RecordsRepository.RouterResult &_
         = RecordsRepository.RouterResult.SuccessContinueProcessing

         Try

            ' Add the properties to a hash table for easier access.
            Dim hashProperties As Hashtable = New Hashtable()
            For Each prop In properties
               If (Not hashProperties.ContainsKey(prop.Name)) Then
                  hashProperties.Add(prop.Name, prop.Value)
               End If
            Next

            ' If this has a "Project" field, put the record in proper location.
            If (hashProperties.ContainsKey("Project")) Then
               Using web As SPWeb = destination.ParentWeb

                  ' Get the destination for this content.
                  Dim projectLibrary As String = "Project Records"
                  Dim projectFolderPath As String &_
                  = projectLibrary & "/" & hashProperties("Project").ToString()

                  ' Get the file name and destination url
                  Dim fileName As String = Path.GetFileName(sourceUrl)
                  Dim destinationPath As String &_
                  = projectFolderPath.TrimEnd("/") & "/" & fileName

                  ' Get the folder.
                  Dim folder As SPFolder = web.GetFolder(projectFolderPath)

                  ' Add the file to the folder.
                  Dim file As SPFile &_
                  = folder.Files.Add(destinationPath, fileToSubmit, hashProperties, False)

                  ' Added the file so no need for further processing.
                  result = RecordsRepository.RouterResult.SuccessCancelFurtherProcessing

               End Using

            End If
                    
         Catch ex As Exception

            ' If an exception occurs, reject the file and send an error message back.
            result = RecordsRepository.RouterResult.RejectFile
            resultDetails = "TODO: Add my error message here..."
         End Try

         Return result
      End Function
   End Class

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

ADD
Show: