SharePoint Development from a Documentation Perspective
This is the second in a five-part series on how to use the built-in XML parser in WSS V3 to promote and demote document properties in your XML files, including InfoPath 2007 forms.
Read part one here.
When WSS V3 invokes the built-in XML parser to parse XML files, the parser uses the document's content type to determine which document properties map to which content type columns, and where those document properties are stored in the document itself. Therefore, to have WSS V3 use the built-in XML parser with your XML files, you must:
· Create a content type that includes the necessary parsing information. For each document property you want promoted and demoted, include a field definition that includes the name of the document property that maps to the column the field definition represents, and where the document property is stored in the document.
· Make sure that the content type ID is a document property that is demoted into the document itself. This ensures that the built-in XML parser can identify and access the correct content type for the document. (We’ll talk about this more in a later post.)
Document properties are promoted to and demoted from columns on the document library in which the document is stored. If the document is assigned a content type, these columns are specified in the content type definition. In the content type definition XML, each column included in the content type is represented by a FieldRef element.
Note Field elements represent columns that are defined for a site or list. FieldRef elements represent references to columns that are included in the content type. The FieldRef element contains column attributes that you can override for the column as it appears in this specific content type, such as the display name of the column, and whether it is hidden, or required on the content type. This information also includes the location of the document property to map to this column as it appears in the content type. This enables you to specify different locations for the document property that maps to the column in different content types.
Because of this, to specify the information the built-in XML parser needs to promote and demote a document property, you must edit the FieldRef element that represents the document property's corresponding column in the content type definition.
The figure below illustrations the actions the parser takes when an XML file is checked in to a document library. WSS V3 invokes the parser, which looks at the content type ID column to determine where in the document the document's content type ID is stored. The parser then looks inside the document for its content type at this location. The parser then examines the content type, to determine which FieldRef elements contain document property information. For each FieldRef element mapped to a document property, the parser looks for the document property at the location in the document specified in the matching FieldRef element. If the parser finds the document property at the specified location, it promotes that value to the matching column.
When an XML document is first uploaded to a document library, the built-in XML parser must first determine the content type of the document, and whether that content type is associated with the document library.
There are several attributes you can edit in a Field or FieldRef element to map that element to a document property and specify the location of the property in the document.
First, the Field or FieldRef element must contain an ID attribute that specifies the ID of the column in the document library. For example:
Next, add additional attributes to the Field or FieldRef element that specifies the location of the document property in the document. Document properties can be stored in either:
· The XML content of the document, or
· The processing instructions of the document.
The attributes you add to the Field or FieldRef element to specify the property location depends on whether the property is stored as XML content or processing instructions. These attributes are mutually exclusive; if you add an attribute that specifies a location in the XML content, you cannot also add attributes that specify a location in the processing instructions.
To edit a column’s field definition schema programmatically, use the SPField.SchemaXML object.
If you store the document property in the document as XML content, you specify an XPath expression that represents the location of the property within the document. Add a Node attribute to the Field or FieldRef element, and set it equal to the XPath expression. For example:
If you specify an XPath expression that returns a collection of values, you can also include an aggregation attribute in the Field or FieldRef element. The aggregation attribute specifies the action to take on the value set returned. This action can be either an aggregation function, or an indication of the particular element within the collection.
Possible values include the following:
· plaintext Converts node text content into plain text.
· first Specifies that property promotion and demotion be applied to the first element in the collection.
· last Specifies that property promotion and demotion be applied to the last element in the collection.
Because processing instructions need not be just XML, XPath expressions are insufficient to identify document properties stored in processing instructions. Instead, you must add a pair of attributes to the Field or FieldRef element that specify the processing instruction and processing instruction attribute you want to use as a document property:
· Add a PITarget attribute to specify the processing instruction in which the document property is stored in the document.
· Add a PIAttribute attribute to specify the attribute to use as the document property.
These attributes would instruct the parser to examine the following processing instruction and attribute for the document property value:
You can also add another pair of attributes, PrimaryPITarget and PrimaryPIAttribute. This attribute pair is optional. Like PITarget and PIAttribute, they work in unison to identify the location of the document property. However, if they are present, the built-in XML parser looks for the document property in the location they specify first. If there is a value at that location, the parser uses that value and ignores the PITarget and PIAttribute attributes. Only if the location specified by the PrimaryPITarget and PrimaryPIAttribute attributes returns a null value does the parser then look for the document property at the location specified by the PITarget and PIAttribute attribute pair.
If you specify the PrimaryPITarget and PrimaryPIAttribute attributes, you must also specify PITarget and PIAttribute attributes. The parser only uses the PrimaryPITarget and PrimaryPIAttribute attributes if the processing instruction attribute specified by the PITarget and PIAttribute pair does not exist in the document, not if that attribute exists but is null or empty.
In my next post, we’ll discuss how the XML parser determines a document’s content type in the first place.
I've just finished putting together a lot of information around how document parsers work within Windows SharePoint Services V3, including how to use the built-in XML parser, and how to create your own custom parsers for custom file types. This material won't be included in the WSS SDK until the next major update, so I figured I'd give you a preview of it here. For the next five posts, I'm going to be covering how to use the built-in XML parser in WSS V3 to promote and demote document properties in your XML files, including InfoPath 2007 forms.
So without further ado:
WSS V3 includes a built-in XML document parser you can use to promote and demote the properties included in your XML documents. Your XML files can adhere to any schema you choose. As long as your XML file meets the requirements listed below, WSS V3 automatically invokes the built-in XML parser whenever document property promotion or demotion is required.
(Property promotion refers to extracting document properties from a document, and writing those property values to the appropriate columns on the document library where the document is stored. Property demotion refers to taking column values from the document library where a document is stored, and writing those column values into the document itself.)
Using the built-in XML parser for your custom XML files helps ensure that your document metadata is always up-to-date and synchronized between the document library and the document itself. Users can edit document properties in the document itself, and have the property values on the document library automatically updated to reflect their changes. Likewise, users can update property values at the document library level, and have those changes automatically written back into the document itself.
For WSS V3 to invoke the built-in XML parser for an XML file, that XML file must meet the following requirements:
· The file must have an extension of .xml.
· The file must not be a WordML file. WSS V3 contains a separate built-in parser for WordML files; WSS V3 automatically invokes this parser for XML files created using WordML.
Additionally, for the XML parser to actually promote and demote document properties, the XML file should be assigned a content type that specifies where each document property is located in the document, and which content type column that property maps to. (We'll talk about that in a later entry in this series.)
The following is a brief overview of how the built-in parser operates:
When a user uploads an XML document, WSS V3 examines the document to determine if the built-in XML parser should be invoked. If the document meets the requirements, WSS V3 invokes the parser to promote the appropriate document properties to the document library.
Once invoked, the XML parser examines the document to determine the document content type. The parser then accesses the document's content type definition. The content type definition includes information about each column in that content type; this information can include:
· The document property that maps to a given column, if there is one
· The location where the document property is stored in the document itself
Using this information, the XML parser can extract each document property from the correct location in the document, and pass these properties to WSS V3. WSS V3 then promotes the appropriate document property to the matching column included in the content type.
Likewise, WSS V3 can also invoke the built-in XML parser to demote properties from the content type columns, on the document library, into the document itself. When WSS V3 invokes the demotion function of the parser, it passes the parser the document and the column values to be demoted into the document. Once again, the parser accesses the document's content type definition. The parser uses the content type definition to determine:
· Which document properties map to the column values passed to it for demotion
· The location of those document properties in the document
Using this information, the parser writes the column values into the applicable document property locations in the document.
For a document property to be demoted, the column to which it is mapped must be defined with its ReadOnly attribute set to "false".
In my next post, we'll discuss how to use content type to specify XML document properties. Stay tuned.
I've got another conceptual poster for download. This one deals with document parsers, and how Windows SharePoint Services uses them to promote and demote document properties.
The poster gives a quick (but stylish) overview of:
· How WSS uses your custom parser to promote and demote document properties for documents of your custom file type.
· How the built-in XML parser promotes and demotes document properties for XML files.
· What built-in parsers are included in WSS for specific file types.
Document parsers are something I'm hoping to have a lot more to say about soon. I'm putting the finishing touches on some topics for the WSS SDK dealing with them. Once I get those topics finished, I'll post some excerpts here. Stay tuned.
And this time around, I'm saving the poster as an attachment to this post. Not that the fine people at OfficeZealot aren't wonderful for hosting my other posters, but I hate to have to bug them all the time. And I'm curious to see if the attachment functionality actually works. The poster should be listed as an attachment at the end of this post. Click to download it. If you have any problems, please leave me a message in the comments section so I know things aren't working out.
So, a reader emailed me the other day, asking for more information on content type IDs: what they are, how to create your own, etc. Because he asked nicely, and because I like to keep both my readers happy, I decided to write up a quick overview of content type IDs.
The truth is, this is something I had hoped to get into the Beta 2 SDK, but the clock ran out. So his question gave me the perfect excuse to write the material up for the next refresh of the SDK. Consider this a preview then.
Because I’m planning on incorporating this material into the SDK, you’ll forgive me if I slip into my formal, developer documentation writing style.
<Authoritative SDK Voice>
Content type IDs uniquely identify the content type. Content type IDs are designed to be recursive. The content type ID encapsulates that content type’s “lineage”, or the line of parent content types from which the content type inherits. Each content type ID contains the ID of the parent content type, which in turn contains the ID of that content type’s parent, and so on, ultimately back to and including the System content type ID. By parsing the content type ID, you can determine which content types the content type inherits, and how two content types are related.
Windows SharePoint Services V3 uses this information to determine the relationship between content types, and for push down operations.
You can construct a valid content type ID using one of two conventions:
· Parent content type ID + two hexadecimal values
· Parent content type ID + “00” + hexadecimal GUID
There is one special case, that of the System content type, which has the content type ID of “0x”. The System content type is the sealed content type from which all other content types ultimately inherit.
For all other content types, you must use one of the above methods for constructing a valid content type ID.
Note that if you use the first method, the two hexadecimal values cannot be “00”.
A content type ID must be unique within a site collection.
Let’s examine each of these conventions in turn.
Windows SharePoint Services V3 uses the first method for generating content type IDs for the default content types that come included with the platform. For example, the content type ID of the Item content type, one of the most basic content types, is 0x01. This denotes that the Item content type is a direct child of System. The content type ID of the Document content type is 0x0101, and the Folder content type has a content type ID of 0x0120. By parsing these content type IDs, we can determine that both Document and Folder are direct children of Item, which in turn inherits directly from System:
In this way you can determine not only what content types a content type inherits from, but at which point two content types have common ancestors.
The figure below maps out the relationship of the four content types discussed above. In each, the unique portion of the content type ID is represented by blue text.
Windows SharePoint Services V3 employs the second content type ID generation convention when creating content type IDs for:
· Site content types you create based on other content types.
· List content types, which are copied to a list when you add a site content type to that list.
For example, if you have a content type with a content type ID of “0x010100D5C2F139-516B-419D-801A-C6C18942554D”, you would know that the content type was either:
· A site content type that is a direct child of the Document content type, or
· A list content type created when the Document site content type was added to a list.
In general, the first content type ID generation technique emphasizes brevity, in that it only takes two hexadecimal digits to denote a new content type. The second approach emphasizes uniqueness, as it includes a GUID to denote the new content type. Each approach is best in certain situations.
We recommend you use the GUID approach to identify any content types that are direct children of content types you did not create. In other words, use the GUID approach if the parent content type is:
· A default content type included in Windows SharePoint Services V3, such as Document.
· A content type developed by a third party.
That way, you are guaranteed that the content type ID is unique and will not be duplicated later by the developer of the parent content type.
Once you’ve uniquely identified a content type in this manner, however, you can use the first method to identify any children of that content type. In essence, the GUID used in your content type can act as a de facto namespace for your content type. Any children based on that content type can be identified by just two hexadecimal digits. Because the maximum length of a content type ID is finite, this approach maximizes the number of content type “generations” allowable.
Content type IDs have a maximum length of 512 bytes. Because two hexadecimal characters can fit in each byte, this gives each content type ID an effective maximum length of 1024 characters.
For example, suppose you wanted to create a new content type, myDocument, based on the default Windows SharePoint Services V3 content type Document. For the myDocument content type ID, you start with the Document content type ID, 0x0101, and append 00 and a GUID. This uniquely identifies the myDocument content type, guaranteeing Windows SharePoint Services won’t later add another default content type with the same content type ID (which would be possible, if you had only appended two hexadecimal digits). To generate content type IDs for any content types you derive from myDocument, however, you can simply append two hexadecimal digits to the myDocument content type ID. This keeps the length of the content type ID to a minimum, thereby maximizing the number of content type “generations’ allowable.
The figure below illustrates this scenario. Again, the unique portion of each content type ID is represented by blue text.
</Authoritative SDK Voice>
Now, the above information is probably most useful to developers working with the XML definition of content types. This way, if you’re looking at a content type ID in an XML file, or need to generate one for a content type definition file you’re writing, you’ll understand how to construct and parse them manually.
The SharePoint object model, on the other hand, includes methods to parser and compare content type IDs. Specifically, you can use the SPContentTypeID.Parent method to find the parent of a content type without having to parser the content type ID yourself. The SPContentTypeID object also contains several methods that enable you to compare content types by ID, and identify a common ancestor.
One last thing that might be of interest. If you want to take a look at actual content type IDs in WSS, here’s what you can do: navigate to the Content Type Gallery for a site. When you click on a content type, the URL to that content type contains a parameter, ctype, which is in fact the content type ID for that content type.
Written while listening to: The Replacements : Let It Be
Gotta love Beta documentation.
Turn out that some of the material I wrote in the WSS Beta 2 SDK concerning content types is not strictly technically accurate, in the sense that it’s dead wrong. Ahem. The problem came from the fact that I was documenting content types as they were initially designed, not necessarily as they were implemented.
Specifically, here are the three things I documented incorrectly in the WSS Beta 2 SDK:
· You create content types at the site level, and then apply them to the lists on the site (or on child sites). You do not create content types directly on the lists themselves.
· Content types can contain references to columns. You do not create columns directly within the content type itself.
· Child sites do not contain content type references back to site content types created on a parent site.
So as you read through the conceptual topics about content types, please keep this in mind. My apologies for the mistakes; they'll be corrected in the final version of the SDK.
Unfortunately, I also included this incorrect information in one of the content type technical posters I offered for download. So, if you've already downloaded the poster titled "Using Columns and Content Types to Organize and Mange Your Content in Windows SharePoint Services (version 3)", please download the corrected version.
I’ve attached the corrected content type poster below (at least, I have if the attachment functionality works. This is the first time I’ve used it). The guys at OfficeZealot, who are hosting the poster downloads, were also kind enough to upload the corrected poster, so the link in my original post should get you the corrected poster now as well.
And for a more complete discussion how content types and columns interact, see my earlier post right there.
Written while listening to Nellie McKay : Pretty Little Head (23 track version)
Today I want to address a piece of SharePoint terminology that confused me no end when I first started working on the products. So, as a service to beginning SharePoint programmers the world over, here’s a quick (and hopefully precise, if not definitive) overview of three terms that tend to be used to mean the same thing: column, field, and document property.
Columns on Sites and Lists
Basically, what all three terms refer to a specific piece of metadata on a SharePoint item.
In other words, this:
In the UI, these are called ‘columns’ because, well, that’s what they are displayed as: columns. Each piece of metadata you’re collecting for a list is represented as a column on that list (Whether the column is actually displayed on the list or not. Columns can be hidden.)
However, if you take a look under the hood, either in the SharePoint schemas or object model, you’ll find they’re called Fields. This is what they were called in V2, and for compatibility sake, that’s what they remain in V3. (Database columns tend to be called ‘fields’, so that might be where the term originally crept in.)
So far, that’s all pretty straightforward. But V3 adds some complexity (and correspondingly, much flexibility and power) with the addition of content types, and site columns. I’ve talked some about content types here. Site columns can be thought of as templates; you create the site column at the site level, then you can apply it to the various lists and sub-sites as you wish. Site columns are represented as <Field> elements in the site schema, and Field objects in the object model.
When you add a site column to a list, the column definition is copied locally to the list, as a list column. So, in the list schema, the list column is represented by a <Field> element in the list schema now. In the object model, it’s represented by a Field object.
Another important point to mention: when you add a site column to a list, the resulting list column has the same field ID as the site column. SharePoint uses this to track which list columns are “children” of a given site column. This enables you to make changes to a site column and propagate those changes out to all the list columns that are children of the site column.
You can also create columns at the list level. These columns only apply to the list on which they are created. You can think of them as one-offs. You can add list columns to content types on that list, but that's it. List columns are also represented as <Field> elements in the list schema, and SPField objects in the object model. Because they were created from scratch, though, they do not have a parent/child relationship with any other column.
Columns in Content Types
Here’s where it gets interesting:
If there’s certain item metadata you want to track in a content type, you include a column that represents that metadata. However, you cannot create a column in a content type; rather, you have to create the column, and then reference that column in the content type definition. Because of this, when you add a column to a content type, the content type schema doesn’t contain a <Field> element, it contains a <FieldRef> element. This is true of both site and list columns you add to content types.
The <FieldRef> element is a reference to a column defined elsewhere, either at the site or list level. In the field reference, you can override a subset of the column properties, such as:
· Display name
· XML promotion and demotion attributes
· Whether the field is read-only, required, or hidden
Changing these properties in the field reference only changes them as they apply to the specific content type that contains the field reference, of course.
Field references retain the same field ID as the column they reference.
If you create a content type based on a parent content type, be default all the columns in the parent are included in the child content type, as <FieldRef> elements.
Now, when you add a content type to a list, the columns referenced in that content type get copied locally onto the list as list columns. In other words, the columns referenced by the various <FieldRef> elements in the content type schema are copied onto the list schema as <Field> elements—again, with the child/parent relationship to the site column.
As mentioned earlier, when you add a list column to a list content type, it's added as a <FeildRef> in the list content type schema.
Therefore, columns are always represented by <Field> elements in site and list schemas, but always represented by <FieldRef> elements in content type schemas.
Field references in content types are represented by the SPFieldLink object in the SharePoint object model.
The term 'document property' is most often used in the context of talking about a particular piece of metadata you're interested in tracking for a document. That is, the particular column value for that document. The last modified date, for example. When you upload a bunch of documents and display the last modified date for each, you get a column of last modified date values, as in the screen shot above.
The document property might be something you're tracking solely at the document library level, or it might also be included in the document itself.
(In which case, WSS V3 includes functionality that enables you to promote and demote the document property, so the value in the document is always in synch with the value in the column.
Property promotion refers to extracting document properties from a document, and writing those property values to the appropriate columns on the document library where the document is stored. Property demotion refers to taking column values from the document library where a document is stored, and writing those column values into the document itself.
WSS includes several built-in document parsers that automatically promote and demote document properties for well-known file types. In addition, you can use the built-in XML parser to promote and demote properties from your custom XML files. Finally, WSS also includes a document parser interface, which enables you to build custom parsers that can promote and demote document properties from your custom file types.)
Hopefully, the figure below illustrates this relationship. You add the site column Author to a content type; in the content type schema, the column is represented by a <FieldRef> element. When you add the content type to a list, WSS adds the Author column as a <Field> element. Both elements have the same field ID as the Author site column. When you add the list column ItemNo to the list content type, WSS adds it as a <FieldRef> element, with the same field ID. For Document C, the actual values for those two columns are stored in the document itself, and also displayed in the columns on the list.
The Bottom Line
So, to review:
What are called columns in the user interface are referred to as fields in the schema and object model.
You can create columns at two levels: the site, and list levels. These columns are represented as <Field> elements in the site and list schema, and Field objects in the object model. List columns created when you add a site column to a list retain a child/parent relationship with the site column, and retain the same field ID as the site column.
You cannot create a column in a content type. When you add a column to a content type, it's added as a <FieldRef> in the content type schema. When you add a content type to a list, the columns referenced by the <FieldRef> elements in that content type schema are added to the list as <Field> elements.
Therefore, columns are always represented by <Field> elements in site and list schemas, and always represented by <FieldRef> elements in content type schemas.
Document properties usually just refer to a field as it applies to a specific document. The document property might be something you're tracking solely at the document library level, or it might also be included in the document itself.
Postscript: A Short Digression Concerning the SPContentType Object
In the SharePoint object model, the SPContentType object contains both a SPFieldLinkCollection and an SPFieldCollection object. But if columns in content types are represented by field references, how can you have a collection of fields in the content type? Because it's one of the ways we're making your life easier, that's why.
The SPFieldCollection in the SPContentType object enables developers an easy way to get a 'merged view' of a column's attributes, as they are in that content type. By merged view, I mean all the attributes of a field, merged with those attributes that have been overridden in the field reference. When you access a field through SPContentType.SPFieldCollection["myField"], WSS merges the field definition with the field reference and returns the resulting SPField object to you. That way, you don't have to look up a field definition, then look up all the attributes in the field definition overridden by the field reference for that content type. We do it for you.
Because of this, there's a 1-to-1 correlation between the items in the SPFieldLinkCollection and SPFieldCollection objects. For each SPFieldLink you add to a content type, we add an SPField object that represents the merged view of that column as it's defined in the content type. You cannot directly add or delete items from an SPFieldCollection object in an SPContentType object; trying to do so throws an error.
Written while listening to Nick Cave : Henry's Dream
I’m sure it comes as no surprise that Office InfoPath 2007 is the forms designer of choice for Office SharePoint Server 2007. But the average SharePoint developer, used to reaching for ASP.NET when he needs to create a form for SharePoint, might be surprised at all the places you can employ InfoPath to quickly create forms for enterprise management functions.
The main reason for this is the fact that in InfoPath 2007 you can create what the InfoPath guys are calling symmetrical forms. Symmetrical forms are InfoPath forms that can be hosted either in the Office client applications like Word, PowerPoint, and Excel, as well as in the SharePoint Server browser interface. So you can create a single form, and know it’ll look and work the same whether the user sees it in an Office application or in the browser interface.
(How is this possible? Short version: SharePoint Server 2007 uses Office Forms Services, a server-based run-time environment for InfoPath 2007 forms, to host the forms in the browser. Office Forms Services consumes the forms you create in the InfoPath client and renders them in an ASP.NET framework, which acts as a run-time environment for the form. This environment presents a form editing experience that matches the InfoPath 2007 client application. The Office client applications, on the other hand, include the ability to host the native InfoPath forms. )
So naturally, symmetrical forms are very handy for enterprise content management areas, where the user might be working with documents in their native client application, or online through the SharePoint Server browser interface.
Here’re a couple of the places where you can employ InfoPath forms for enterprise content management in SharePoint Server 2007:
· Document Information Panels
A document information panel is a form that is displayed within the client application, and which contains fields for the document metadata. Document information panels enable users to enter important metadata about a file anytime they want, without having to leave the Microsoft Office system client application. For files stored in document libraries, the document information is actually the columns of the content type assigned to that file. The document information panel displays a field for each content type property, or column, the user can edit.
You can create document information panels either from within SharePoint Server, or directly from InfoPath 2007.
How to: Create or Edit a Custom Document Information Panel from within Office SharePoint Server 2007
How to: Create a Custom Document Information Panel from InfoPath
· Workflow Forms
You can create InfoPath forms for use with workflows in SharePoint Server 2007. That way, the user can interact with the workflow form from within the Office client application, and not just through the browser.
SharePoint Server 2007 uses Office Forms Services to display workflow forms, be they association, initiation, modification, or edit task forms. The only difference is that there’s a different .aspx page hosting the Office Forms Services control for each type of workflow form. Initiation forms are hosted by a different .aspx page than modification forms, for example. Each different hosting page knows how to submit the information from its type of form to SharePoint Server (and hence, to the workflow engine).
The .aspx pages that contain the Office Forms Services web part are included as part of SharePoint Server, of course.
How to: Design an InfoPath Form for a Workflow in Office SharePoint Server 2007
So if your putting together an enterprise content management solution in Office SharePoint Server, and you’d like your user to be able to interact with your custom forms in the client application and the browser, it might be worth your while to take a look at InfoPath 2007 and Office Forms Services.
Written while listening to Johnny Cash : Personal File
Today I'm making another SharePoint technical poster available for download. This one details the records repository functionality offered in Windows SharePoint Services V3 and Office SharePoint Server 2007.
(As always, it's the fine folk at Office Zealot.com who are doing the real heavy lifting by hosting the poster I have for download. Many thanks, guys. To check out the other SharePoint technical poster and namespace diagrams available for download, refer to this topic, and this one too.)
Just click the link below to download a full-color PDF of the poster:
Using Record Repository Features in Windows SharePoint Services (version 3) and SharePoint Server 2007
And what are records repositories, you ask? Read on for a quick overview:
Now, everyone knows that SharePoint offers a great environment for collaborating on documents. But sooner or later, most documents are 'finished'; that is, they reach a state where you're not going to be making further changes to them. And you may want to store some of these documents, in their finalized state, for a long time. To facilitate long-term storage for such documents, SharePoint offers several features of interest to developers:
The Official File Web Service
The Official File Web Service, part of Windows SharePoint Services V3, is a Web Service that enables you to automate the process of moving documents into a records repository. Now, what exactly that records repository is is up to you: it could be a SharePoint site (which we'll talk about in a minute), or it could be an entirely different storage system. It's your choice. There's nothing inherently SharePoint-specific about the Web Service. Basically, the Web service enables you to pass a document, along with any metadata you want to package with it, to some document storage facility. You can also specify a record routing type, which is simply the name of a location within the repository where you want to store the document. How the document storage facility processes the document and its metadata internally is, of course, up to it.
When you send a file to the record repository, either manually or through the object model, you are sending a copy of that file. The original file is not altered in any way and contains no link to its copy in the record repository. However, the copy is submitted to the repository with a pointer to the location of the original file.
To read more about the Official File Web Service in the Windows SharePoint Services V3 SDK, start here.
The Records Repository Site Template
Office SharePoint Server 2007 builds on the Official File Web Service by including a site template that has been optimized for use as a records repository. The Records Repository site template has been customized for use as a records repository. Site features that are not useful for a records repository, such as Discussions, have been hidden by default. Conversely, useful site components, such as Reporting, are prominently featured.
In addition to implementing the Official File Web Service, the site template includes several features that enable record managers to customize that implementation:
· A record routing type table, which lets record managers specify where different types of content are stored within the records repository.
· A record routing type entry in that table, called Unclassified Records, which is the default record routing type.
· A default document library, Unclassified Records, for storage of files assigned the Unclassified Records record routing type.
To read more about the records repository site template in the Office SharePoint Server 2007 SDK, start here.
IRouter Interface for Custom Records Repository Routers
Lastly, Office SharePoint Server also includes the IRouter interface, which enables you to implement custom records repository routers. You can use a custom router to perform your own custom processing on submitted documents; either before SharePoint does its own standard processing, or to replace that processing altogether.
You can specify one custom router for a specific record routing type. When a user submits a file of that record series type to the record repository, the record repository calls the custom router to perform its custom processing before the records repository performs any of its standard processing. When complete, the router returns whether it succeeded, and if successful, whether the record repository should perform its standard processing and storage of the submitted file.
The custom router has the ability to edit the submitted document and its associated metadata, as well as update the location to which the submitted document is to be stored.
After you specify a custom router for a given record routing type, the records repository invokes the router whenever a file of that record routing type is submitted through any mechanism, including the user interface, object model, and STMP.
To read more about implementing custom routers, start with this topic.
Written while listening to Richard Thompson : More Guitar
If you're interested in extending the enterprise content management features in Office SharePoint Server 2007, take note: we've just released the Enterprise Content Management Starter Kit on MSDN.
This download is a great grab-bag full of information and examples of the extensible ECM features included in Office Server 2007. Among the sample code projects are examples of custom:
· Document Inspector modules
· Record repository routers
· Record repository Web Service application
· Search and process tools
· Multiple flavors of custom workflows, including: sequential and state workflows, custom workflow activities, multi-stage and replicating workflows, and workflow modifications.
So if you want sample projects for the ECM features, chock full of tips, tricks and best practices straight from the product team, this one's for you.
Just as important, if you plan on rolling your own workflows for the SharePoint environment, are the two Visual Studio workflow project templates included in the download. These project templates are designed to get you up and coding SharePoint workflows with a minimum of fuss: they include references to the necessary SharePoint namespaces, as well as having the SharePoint-specific workflow activities included on the designer Toolbox. One is for creating workflows for Windows SharePoint Services V3; the other, for workflows you plan to use in SharePoint Server 2007.
Written while listening to Artic Monkeys : Whatever People Say I Am, That's What I'm Not