Building Records Management Solutions with SharePoint Server 2007

Article
10/16/2013

Summary: Learn records management features and concepts, such as Records Center configuration, and records series planning and routing, and explore the Official File Web service and a sample client application to create and deploy a custom router with a routing type. (13 printed pages)

Spence Harbar, harbar.net (Microsoft Certified Master, SharePoint MVP)

August 2009

Applies to: Microsoft Office SharePoint Server 2007

Contents

Introduction to Records Management with SharePoint Server 2007
Planning Considerations
Using the Records Center Site Template
Building a Sample Client Application
Using the SharePoint Object Model
Building a Custom Router
Conclusion
Additional Resources

Download the code samples that accompany this article:MSDN Sample - Building Records Management Solutions Demo Code

Introduction to Records Management with SharePoint Server 2007

Microsoft Office SharePoint Server 2007 provides powerful and flexible support for records management through a combination of features that include content types, information management policies, the Records Center site template, auditing, Web services, and a rich object model. By combining these features, Office SharePoint Server 2007 enables you to implement a records management solution that is tailored to specific needs, instead of forcing a particular and perhaps overly burdensome approach to records management upon an organization. By building upon common SharePoint features, it also enables developers to rapidly implement records management solutions by using common tools and skills, and enables information workers to easily participate in an organization's records management process.

Planning Considerations

As with many enterprise content management disciplines, records management is first and foremost a process, to which a technology solution offers an implementation approach and enforcement. Therefore, it is imperative that you carefully consider the overall records management process before implementing a solution with SharePoint Server 2007.

Planning considerations are paramount to a successful records management implementation. This article focuses on an introduction to customizing and extending the built-in (out-of-the-box) capabilities of SharePoint Server. For more information about planning, see Downloadable book: Records Management Guide for Microsoft Office SharePoint Server 2007 on Microsoft TechNet.

Using the Records Center Site Template

The Office SharePoint Server 2007 Records Center site template is designed to implement records management and retention. By combining standard SharePoint Server 2007 features with specific records management features, the Records Center provides:

Record routing When a document is sent to the Records Center site, the record is routed to the correct document library based on its type. When a record is sent to the Records Center site, other information is sent with the record. This other information includes the record's audit history and all of its metadata.
Policy enforcement SharePoint Server 2007 includes Information Policy features that are useful for records management, as follows:
- Auditing Logs events and operations performed on documents.
- Expiration Specifies how long to retain the record and provides an action to take when the retention period ends.
- Barcodes Provides each record with a barcode graphic and numeric value.
Programmable interface The Records Center site's programmable interface provides a method to send a file, its associated metadata, and its audit history to the Records Center site as part of a business process. You can also design additional information policy management features that meet your enterprise's unique requirements.
Hold The Records Center site provides a way to suspend a record's expiration policy. It includes a hold feature that lets records managers create named holds that protect specified records from expiring and being destroyed.

Creating the Records Center

In many deployment scenarios, the Records Center is not intended for use by end users, but instead by records managers and external parties such as lawyers. As such, in many implementations the Records Center is hosted in a highly secure manner, and is not directly accessible to end users. Although the Records Center template can be used to create a site collection like any other site template in SharePoint Server 2007, the Records Center is intended to be created within its own dedicated Web application. This enables a clean separation between the collaborative or publishing spaces used by end users and the Records Center, distinct security settings for the Records Center, and, if necessary, the implementation of additional Web application policies.

It is also extremely common to associate the Records Center Web application with a Shared Services Provider different from the one used by end user applications, to ensure that there is no possibility that search results include items from the Records Center through search misconfiguration. In larger deployments, the Records Center is hosted by a dedicated SharePoint farm, providing further isolation and ability for independent security and management controls.

For the examples in this article, the Records Center is created on a dedicated Web application within the same farm and is associated with the same Shared Services Provider as our collaboration sites. The Web application and site collection are created at http://records/.

To create a new Records Center

Using SharePoint 3.0 Central Administration, click Application Management.
In the SharePoint Web Application Management section, choose Create or extend Web application.
On the Create or extended Web application page, click Create a new web application.
Enter the configuration options that you want for IIS Web Site, Security Configuration, Load Balanced URL, Application Pool, and Database Name and Authentication.
Click OK, and then wait while the new Web application is created.
On the Application Created page, click Create Site Collection.
On the Create Site Collection page, type a Name and Description and select the root path (/).

Figure 1. Records Center site template
Within the Template Selection section, choose a Language, and then select the Records Center template from the Enterprise tab.
Enter a Site Collection Administrator, and then click OK to create the site collection.

Figure 2. Records Center site

Records Center site

After the site collection is created, you can browse to it by using Internet Explorer, to see the standard Records Center implementation.

By clicking the View All Site Content link, you can also see additional lists and libraries that are created as part of the site collection. Table 1 describes the lists and libraries created in a Records Center site collection.

Table 1. Lists and libraries in a Records Center site collection

List or Library	Usage	Description
Record Routing list	Records Center User	Stores the record routing types, and implements a file plan. Incoming records are matched against the record routing list to determine their final destination library within the Records Center. By default, the list includes one routing type named Unclassified Records. Incoming records that do not match a routing type are routed to the Unclassified Records library.
Holds list	Records Center User	Defines external actions that might require a suspension of information management policies, such as disposition.
Submitted Email Records list	System	Stores records that are sent by e-mail to the Records Center until they are processed. This list is enabled for e-mail by default but relies upon the farm incoming e-mail settings, which must be configured separately.
Unclassified Records library	Records Center User	Stores incoming records that do not match a routing type, which can then be routed manually by a records manager.
Records Pending Submission library	System	Stores incoming records with incomplete metadata until that metadata is completed.
Missing Properties library	System	Stores the metadata for incoming records with incomplete metadata and enables an Edit Item page where metadata can be completed.
Hold Reports library	Records Center User	Stores reports that list all items assigned to a hold.

Note

System lists are used by the Records Center and are not intended to be viewed and edited by Records Center users.

Connecting Web Applications to the Records Center

After you create a Records Center, it is accessible to external applications via SMTP (the incoming e-mail feature) or via the Official File Web service. This Web service can be used to enable end users to send files manually to the Records Center. By default, you can configure one Records Center per farm.

To configure the Records Center connection

In SharePoint 3.0 Central Administration, click Application Management.
In the External Service Connections section, select Records Center.
On the Configure Connection to Records Center page, click Connect to Records Center.

Figure 3. Connecting Web applications to the Records Center
Enter the URL to the Records Center Web service and a Description, and then click OK.
You can also configure the Records Center connection programmatically by setting the officialFileUrl property of the AdministrationWebApplication object, as shown in the following code.
```
SPWssWebApplication app = SPGlobalAdmin.AdministrationWebApplication;
app.officialFileUrl = "url";
app.officialFileName = "description";
app.update();
```
Now all document libraries contain a link to the Records Center within the Send To menu item, as shown in Figure 4.

Figure 4. Records Center Send To menu
Before the connection will work, you must give the application pool identity of the external applications permission to use the Official File Web service. You do this by using a special SharePoint group created in the Records Center, named Records Center Web Service Submitters, as shown in Figure 5.

Figure 5. Records Center Web Service Submitters group

Now that the connection is configured, users can submit records to the Records Center manually. However, the records will be routed to the Unclassified Records library because there are no other record routing rules specified.

Although you can have only one Records Center connection per farm, you can overcome the scale limitations of a single site collection by implementing multiple Records Centers and creating a custom router to determine which Records Center to route the record to.

Implementing Sample Record Routing

To ensure that records are routed to the correct library to participate in information management policy constraints, you must create a destination document library and an entry in the Record Routing list. In addition, in a real-world scenario information management policies would be applied to the destination library.

The Record Routing list matches incoming records based upon the content type name. Therefore, the content types must be defined and used within the collaboration spaces that will submit records. For the purposes of this sample, a simple content type named Car Design is created with the columns Color (text), Transmission (choice), and Engine (choice). After you create the Site content type, you assign it to document libraries to enable the creation of sample content that is based upon it.

Figure 6. Sample Records Center content type

Sample Records Center content type

Now that you have a content type that defines your record, you create a destination library named Car Designs within the Records Center. At this stage, a Record Routing item is required.

To create a Record Routing item

On the Records Center home page, within the Record Routing Web Part, click New, and then click New Item.
In the Title field, type Car Design (the name should match the name of the content type created earlier).
In the Location field, type Car Designs (the name of the document library created earlier).
Click OK to create the item.

Figure 7. New routing record

After you create the Record Routing item, all submitted records of content type Car Design are routed to the Car Designs document library within the Records Center. By default, the metadata is copied to an XML file within the destination library.

Figure 8. Destination record library

Destination record library

This metadata can be promoted to document libraries if columns matching the metadata are present on the destination library. Additionally, if you require columns to be completed, when a record is submitted to the Records Center, an item is created in the Missing Properties library and the user is prompted to complete those columns.

By using the Aliases column of the Record Routing list, you can also ensure that records of different content types are routed to the Car Designs library by including the names of these content types in a delimited list.

Building a Sample Client Application

The default behavior of the Records Center connection is appropriate for small implementations and demonstrations. However, in a real-world scenario, records come from many different systems. Just as the Records Center connection uses the Official File Web service, you can build your own clients to interact with the Records Center.

This sample presents an extremely simple Windows Form application with a single button that enables the user to select a file and submit it to the Records Center.

To build a sample client application

Add a service reference to the project. Click the Advanced button, click the Add Web Reference button, and then enter the URL of the Official File Web service.

Figure 9. Adding reference to Official File Web service
After the Web reference is added to the project, more using statements are needed within the class. Add the following using statements.
```
using System.Net;
using System.IO;
using RecManSample.OfficialFile;
```

Within the Click event handler for the form, use the following code to implement the file selection by using a common dialog box.

using (OpenFileDialog dialog = new OpenFileDialog())
{
  if (dialog.ShowDialog() == DialogResult.OK)
  {
    Stream stream = dialog.OpenFile();
    byte[] buffer = new byte[stream.Length];
    stream.Read(buffer, 0, (int)stream.Length);
    stream.Close();
    string[] temp = dialog.FileName.Split('\\');
    string fileName = temp[temp.GetUpperBound(0)];

Instantiate the Official File Web service.
```
    OfficialFile.RecordsRepository offFile = new RecordsRepository();
    offFile.Credentials = CredentialCache.DefaultCredentials;
```
Note

The user of the application must be a member of the Records Center Web Service Submitters Group.

Create a RecordsRepositoryProperties collection.

    RecordsRepositoryProperty[] props = new RecordsRepositoryProperty[1];

Finally, submit the record and display the resulting XML.
```
    string retValue = offFile.SubmitFile(buffer, props, "Car 
      Design", dialog.FileName, @"w2k8moss\administrator");
    MessageBox.Show(retValue);
  }}
```
The user name in the preceding code is the user who is displayed as the submitter within the Records Center, and the third argument is the name of the Record Routing type to use. The result code that is returned as XML is displayed.

Figure 10. Resulting XML

If you want to send additional metadata, you can create RecordsRepositoryProperty properties, and add them to the submitted collection.

RecordsRepositoryProperty prop1 = new RecordsRepositoryProperty();
prop1.Name = "Engine";
prop1.Type = "Text";
prop1.Value = "Petrol";
RecordsRepositoryProperty[] props = new RecordsRepositoryProperty[1];
props[0] = prop1;

If the Records Center Document Library requires the user to complete columns, the result code XML can include a link to the Edit Item form, which you can redirect the user to.

This simple sample application shows the basics of building a custom connector for the Records Center. In a real implementation, it would not include such hard-coded literals and would be expanded based upon the client system into which it is integrated to retrieve metadata and select the routing type that is required.

Using the SharePoint Object Model

In addition to the Official File Web service, the SharePoint object model (Microsoft.Office.RecordsManagement.RecordsRepository) includes a SubmitFile method within the OfficialFileCore class. This can be useful if the application resides on a server within the SharePoint farm; however, this method still calls the Official File Web service. As such, the SharePoint APIs are generally used for administrative purposes, such as enumerating the Record Routing types.

Building a Custom Router

Although the default routing behavior of the Records Center is appropriate for many scenarios, the ability to build custom routers provides tremendous power and flexibility to implement records management in a way that is appropriate for a given organization. You can achieve such custom processing by implementing the IRouter interface. After they are installed, the available routers are displayed within the Record Routing type. The only limitation is that only one router per routing type can be selected. Common examples of custom routers include those that modify the content upon submission or determine the appropriate end destination in an environment that is composed of multiple Records Centers.

The following sample demonstrates a simple custom router that adds an entry to the application event log for each record that is submitted.

Starting with a Class Library project, references to Microsoft.SharePoint.dll and Microsoft.Office.Policy.dll should be added and the following using statements are required.

using System.Diagnostics;
using System.IO;
using Microsoft.Office.RecordsManagement.RecordsRepository;
using Microsoft.SharePoint;

The class must implement the IRouter interface, which includes a single method, OnSubmitFile.

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

    string source = "CustomRouter";
    if (!EventLog.SourceExists(source))
    {
      EventLog.CreateEventSource(source, "RecManSample");
    }

    string fileName = Path.GetFileName(sourceUrl);
    string listName = (null == destination) ? "unknown" : destination.Title;
    string message = "File '" + fileName + "' was submitted to list '" + listName 
       + "' by user '" + userName + "'";


    EventLog.WriteEntry(source, message, EventLogEntryType.Information);

    return result;
  }

A custom router must be deployed to the global assembly cache before it can be added to the Records Center. After the assembly is in the global assembly cache, you can add the router by using the following code.

using (SPSite site = new SPSite("http://records"))
{
  using (SPWeb web = site.OpenWeb())
  {
  RecordSeriesCollection rsc = new RecordSeriesCollection(web);
  rsc.AddRouter("Event Log Router", "RoutingSample, Version=1.0.0.0, 
    Culture=neutral, PublicKeyToken=296ea54be0128acb",
    "RoutingSample.EventLogRouter");
  }
}

Now the router is available for use in the Record Routing Rules, as shown in Figure 11.

Figure 11. Custom record router

Custom record router

Conclusion

This article presents a sample solution that describes the configuration of a Records Center, key concepts and planning considerations for a record series or routing, and information about holds and information management policy. An in-depth look at the Official File Web service is also provided, with a sample client application. Additional examples show how to create a custom router and deploy it to the Records Center site and associate it with a routing type.

Additional Resources

For more information, see the following resources: