Chapter 29
Working with Records Repositories

IN THIS CHAPTER

• Overview of Records Repositories
• Using Records Repositories
• Creating Your Own Records Repository

One of the main driving factors for corporations to adopt centralized document management solutions beyond version control is compliance and auditing. Virtually every industry these days has requirements on document management that often dictate that certain documents be placed in a read-only repository that can be audited at a later date. This chapter provides an overview of how Microsoft Office SharePoint Server (MOSS) facilitates such compliance and how you can both consume and create your own records repository.

Overview of Records Repositories

Records repositories are covered in this section of the book because they are facilitated almost entirely through the use of the Official File Web Service. SharePoint provides a default implementation of the Official File Web Service in the file officialfile.asmx. This file doesn’t do any good unless you access it through the relative uniform resource locator (URL) of a SharePoint website created from the Records Center site definition.

When a SharePoint web application has been configured to link to an external records repository, the name of the records repository appears on the Send To submenu for individual documents within any site in that web application’s site collection.

As mentioned earlier, you can configure a web application to send files to a SharePoint Records Center site, or to a web service that you developed on your own, provided your web service’s definition matches what SharePoint is looking for.

Using Records Repositories

This section of the chapter provides an overview of how to use records repositories within SharePoint, as well as how to write code that consumes the Official File Web Service.

Using the Records Center Site Definition

When you create a new site, there is a site definition called Records Center on the Enterprise tab. When this site is provisioned, it creates a default document library called Unclassified  Records. This document library serves as the default location for submitted records. In a real-world scenario, your Records Center site might have multiple rules for record routing and multiple document libraries that serve as possible destinations for records.

To add record routing rules, you just need to add items to the Record Routing list. You can also temporarily place record storage on hold by adding items to the Holds list.

By default, SharePoint does not enable the drop-down menu item that allows an item to be sent to a Records Center site because the default installation does not include an instance of this site definition.

The first step toward using a records repository is to open the SharePoint 3.0 Central Administration site and go to Application Management. About halfway down the page on the right is a link called Records Center. When you click this link, you will be given a chance to configure the link to a records center for all sites and site collections within that web application. It is extremely important to note that you can only have one records center defined for each web application in a SharePoint installation.

Figure 29.1 shows a screenshot of the Configure Connection to Records Center screen.

Figure 29.1. Configure a connection to a records center.

This screen allows you to turn on or off access to an external records center and to supply the URL for the records center. The URL for the records center must be the full URL of the records center website followed by _vti_bin/officialfile.asmx.

To get the Official File Web Service within the Records Center site to work, you either need to enable anonymous access or you need to make sure that the identity of the application pool of the submitting application has contribute access to the destination document library.

When the Records Center site is provisioned, a site group called “Web Service Submitters for Records” preceded by the name of the records center is created. For example, if you have a Records Center site called “SEC Compliance,” then there will be a site group named “SEC Compliance Web Service Submitters for Records.” Any identity that needs to be able to submit to the web service needs to be a member of this group.

After the link to the Official File Web Service has been established, there will be a new item on the Send To submenu on every document contained in every site within the application’s site collections, as shown in Figure 29.2.

Figure 29.2. Send To menu after configuring a records center destination.

When the file has been submitted to the repository, its filename is modified so that it is guaranteed to be unique and the file and its metadata information are stored in a folder under the document library indicated by the routing rule. Figure 29.3 shows a sample of the metadata information that was submitted to the records repository along with the simple text file from Figure 29.2.

Figure 29.3. Metadata information stored in a records repository.

Using a Custom Records Center

Using a custom records center should provide the exact same end-user experience as using a Records Center site provided by SharePoint. When you (or some other developer) have provided an officialfile.asmx Web Service with all of the required methods (discussed later in this chapter), you should be able to submit files to the custom repository using the Send To menu just as you would with a Records Center site.

If you already have compliance procedures in place, you might not want to use the Records Center site. Many companies use document storage facilities that are far more secure than the Records Center site or they might use facilities provided by UNIX operating systems. In this case, you might want to provide your own web service that deals with the persistence of documents and their metadata. Keep in mind that the Records Center site provides more functionality than just the web service—it provides read-only access to the vault of stored documents and metadata as well as a web-based administration console for routing rules.

Submitting Files via Workflows

One way in which records repositories are made even more powerful is through the use of workflows. One of the activity types that is predefined within the SharePoint 2007 workflow system is the SendToRecordRepository activity. When you include this activity in a document workflow, it will send the document to the document repository defined for the web application in which the workflow is running.

This enables some extremely powerful and robust compliance and document storage scenarios. One example might be an enhanced approval workflow. After all of the involved parties have approved the document, you could design the workflow so that the document is automatically submitted to the records center just before the workflow completes.

Programmatically Submitting Files Using the SPFile Class

The SPFile class has a method that provides a convenient means of submitting a file to a records repository. The method name is SendToOfficialFile, and it can take one or two string arguments:

• recordSeries—Indicates the record series for the file
• additionalInformation  (out)—Provides for additional information text, including the URL of the page used to supply values for missing properties

Listing 29.1 illustrates how to use the SharePoint object model to locate an individual instance of the SPFile class and then submit that file to the defined records repository.

Listing 29.1. Submitting Files Programmatically via the SPFile Class

One extremely common use for the SendToOfficialFile method is in responding to events. Responding to events such as file check-ins, file uploads, and modifications, you can automatically submit files to the defined records repository without requiring manual intervention by the user.

Querying an Official File Web Service

The Official File Web Service contains a few methods that can be used to interrogate it. You can obtain the list of routing rules and information on the official file server, as shown in Listing 29.2.

Listing 29.2. Querying the Official File Web Service

The output of the preceding code will look similar to the following text when run against a default Records Center site:

As you can see from the preceding Extensible Markup Language (XML) fragment, the default implementation of the Records Center site contains a document library called Unclassified  Records that is the default location for all submitted files. You can define custom routing paths for individual content types and you can define alternate mappings and destinations by adding items to the Record Routing list in the Records Center site.

Creating Your Own Records Repository

Creating your own records repository either from scratch or as a front for an existing records repository already in use within your organization involves creating an implementation of the Official File Web Service.

The Official File Web Service exposes the methods discussed in the following sections.

SubmitFile

This method accepts an array of bytes containing the raw file, as well as additional metadata information. It returns an XML fragment containing information pertinent to the file submission. The following is a list of parameters to the SubmitFile method:

• fileToSubmit—An array of bytes containing the raw contents of the file being submitted.
• properties—An array of OfficialFileProperty objects. In any implementation of this web service, the OfficialFileProperty class must have the following public string fields: Name, Other, Type, Value.
• recordSeries—The name of the record routing type of the file being submitted. If this doesn’t match any routing type on file, the default routing type will be used.
• sourceUrl—A string containing the fully qualified URL of the file being submitted.
• userLoginName—The name of the user submitting the file.

GetServerInfo

This method queries information about the records repository server. It returns an XML string that has the following structure (the values returned in this sample are from the MOSS 2007 server):

Summary

Microsoft Office SharePoint Server 2007 provides a comprehensive solution for document management, document version control, and document warehousing and vaulting through the Records Center site definition and the Official File Web Service. This chapter provided you with an overview of how to use the Records Center site definition, how to consume the Official File Web Service, and what you need to do to create your own Official File Web Service.