Creating Custom Routers in SharePoint Server 2007

Summary:  Learn how to extend the router functionality in Microsoft Office SharePoint Server 2007 to apply customized logic and business rules consistently to every new record in the records center.

Office Visual How To

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

Microsoft Corporation

April 2008

Overview

In Microsoft Office SharePoint Server 2007, you can send content to the records center and route the content to the correct 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 in Office SharePoint Server 2007.

By extending the router, you can apply highly customized logic and business rules consistently to every new record. Examples of custom routers include converting incoming files to a standard file format, ensuring that a duplicate record does not already exist, and routing records based on metadata instead of content type.

Code It

To implement a custom router, you must first create a project that references the Microsoft.SharePoint and Microsoft.Office.Policy assemblies. The next step is to create a class that uses the Microsoft.SharePoint namespace and the Microsoft.Office.RecordsManagement.RecordsRepository namespace. In the following example, the Microsoft.Office.RecordsManagement.RecordsRepository namespace is referenced as RecordsRepository.

The class derives from the IRouter interface and contains a public method named OnSubmitFile, which takes the parameters shown in Table 1.

Table 1. OnSubmitFile parameters

Parameter Description
recordSeriesString that represents the record routing type specified for the submitted document.
sourceUrlString that represents the URL of the document being submitted.
userNameString that represents the user logon name of the document submitter.
fileToSubmitDocument being submitted.
PropertiesStructure that represents the document properties specified by the document submitter.
DestinationString that represents the list in the record repository to which the document is to be submitted, based on the value specified for the recordSeries parameter.
resultDetailsString that represents any additional information from the router about its processing of the document.

The method returns a RouterResult enumeration value that specifies the result of the router processing.

Table 2. RouterResult enumeration values

Value Description
SuccessContinueProcessingThe router successfully completed its processing, and the record repository continues with its processing of the document.
SuccessCancelFurtherProcessingThe router successfully completed its processing, but the record repository discontinues its processing of the document. The record repository returns a success value to the calling application, and also the contents of the resultData parameter.
RejectFileThe router did not complete its processing successfully. The record repository returns an error to the calling application, and also the contents of the resultData parameter.

For this example, the logic inside the method is kept to a minimum, and a RouterResult enumeration value of SuccessContinueProcessing is returned. In other examples, the logic in this method is extended to meet specific routing scenarios.

To use the custom router within the records center, you must first compile the assembly with a strong name and place it in a location that Office SharePoint Server can access, such as the global assembly cache or directly in_app_bin. In this example, the assembly is added to the global assembly cache.

The next step is to add the router to the records center. In this example, you use a PowerShell script to perform this task. The script loads the Microsoft.SharePoint and Microsoft.Office.Policy assemblies. You define specific information about the router, such as the router name, assembly information, and fully qualified class name. You obtain a RecordSeriesCollection object from the records center. This object is a logical representation of the Record Router list. Finally, you add the custom router to the RecordSeriesCollection by calling the AddRouter method and passing in the router information.

[System.Reflection.Assembly]::Load("Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, `
PublicKeyToken=71e9bce111e9429c")
[System.Reflection.Assembly]::Load("Microsoft.Office.Policy, `
Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c")
$url = "http://mossrtmvpc/records"
$routerName = "MetadataRouter"
$routerAssembly = "CustomRouter, Version=1.0.0.0, `
Culture=neutral, PublicKeyToken=3df96847a5b47cfe"
$routerClass = "CustomRouter.MetadataRouter"
$site = [Microsoft.SharePoint.SPSite]($url)
$web = $site.OpenWeb()
$seriesCollection = ` 
[Microsoft.Office.RecordsManagement.RecordsRepository.RecordSeriesCollection]($web)
$seriesCollection.AddRouter($routerName, $routerAssembly, $routerClass)

The result of this script is that the custom router is registered in the records center and is now available in the Router field for selection on the items in the Record Routing list, as shown in Figure 1.

Figure 1. Custom router displayed in the Router list

Custom router displayed under Router list

The final step in configuring the router is to ensure that the server farm from which records originate is configured to send records to the records center. You do this in Windows SharePoint Services 3.0 Central Administration, as follows.

To configure the server farm

  1. In Central Administration, click Administrative Tasks.

  2. On the Administrative Tasks page, under External Service Connections, click Records Center.

  3. On the Configure Connection to Records Center page, select Connect to a Records Center.

  4. In the URL box, type the URL to the OfficialFile.asmx Web service that is contained in the _vti_bin directory of the records center.

    For example, if a records center is location at https://localhost/RecordsCenter, the path to the Web service is https://localhost/RecordsCenter/_vti_bin/OfficialFile.asmx.

  5. Enter the display name, such as Records Center, and then click OK.

  6. This enables the Send To / Records Center option in the Edit Control Block (ECB) menu and ensures that records are sent to the records center.

When you have everything configured correctly, it is time to test the custom router, as follows.

To test the custom router

  1. Edit the Unclassified Records item, and select MetadataRouter.

    The Unclassified Records item is used because it is the only item in the Record Routing list for this example.

  2. Next, set a breakpoint in the OnSubmitFile method, and attach to the W3wp.exe process.

  3. Finally, from a document in a document library outside the records center, on the Edit Control Block (ECB) menu, select Send To, and then select Records Center.

If everything is working correctly, your breakpoint will be hit.

Read It

This example uses a PowerShell script for registration of the router. It makes the custom router available by adding the router information to the record series collection in the records center. You can also remove the custom router from the records center by using a similar PowerShell script. To remove the router, you call the RemoveRouter method from the RecordSeriesCollection class, passing in the router name that is defined when the router is installed.

[System.Reflection.Assembly]::Load("Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, `
PublicKeyToken=71e9bce111e9429c")
[System.Reflection.Assembly]::Load("Microsoft.Office.Policy, Version=12.0.0.0, Culture=neutral, `
PublicKeyToken=71e9bce111e9429c")
$url = "http://mossrtmvpc/records"
$routerName = "MetadataRouter"
$site = [Microsoft.SharePoint.SPSite]($url)
$web = $site.OpenWeb()
$seriesCollection = ` 
[Microsoft.Office.RecordsManagement.RecordsRepository.RecordSeriesCollection]($web)
$seriesCollection.RemoveRouter($routerName)

You can convert the scripts in this example to Microsoft Visual C# or Microsoft Visual Basic and use them as callout code to deploy a custom router as a SharePoint Feature or a solution.

See It Creating Custom Routers in SharePoint Server 2007

Watch the Video

Video Length: 00:07:00

File Size: 5.77 MB WMV

Explore It