|
An information management policy in SharePoint 2007 is a set of rules and actions that help an organization to manage the content in their SharePoint sites. Policies are assigned to lists and content types. Therefore they make it easy to enforce a policy without your users having to think about it. This MSDN page contains a nice overview of the architecture of the policy architecture in SharePoint.
Out of the box there are 4 policies:
- Expiration
- Auditing
- Document Labels
- Document Bar Codes
These 4 policies are available as “Policy Features”. These can be used to specify the policy for a SharePoint list or a content type. These polices can be specified at the site collection level to be used throughout the whole site, or directly at the list/content type.
The nice thing is that the policy framework is an extensibly framework, so you can write your own information management policies. This will be the first of a number of posts on this topic. The first part shows you how to create and register a policy so that it can be used. The scenario I used for this example is not very useful, but I wanted to have a simple policy to start with.
Because I was listening to the latest Depeche Mode DVD (Live in Milan) when reading the SDK, I decided to create a “Policy of Truth”. Administrators the specify a policy can enter a number of keywords. When new content is added to SharePoint lists (or document libraries) that have our policy assigned, our policy will check the metadata for the presence of one of the keywords. When one of the keywords is found, and the metadata also contains the word “truth” or “proof”, a link to the item is submitted to a central list in a special site collection. This way, we can easily manage our version of “the truth”. Not very useful, but pretty straightforward and it covers most aspects of building a custom policy.
Step 1 – Create the policy feature
In the first step we will create the policy feature. To do this you need to implement the IPolicyFeature interface. At this stage we will only implement an empty Policy feature to be sure that we get it registered correctly. The actual work done by the policy will be covered in the next post. Here is the code for the poliy feature:
public class PolicyOfTruth : IPolicyFeature
{
public PolicyOfTruth()
{
}
public void OnCustomDataChange(PolicyItem policyItem, Microsoft.SharePoint.SPContentType ct)
{
}
public void OnGlobalCustomDataChange(PolicyFeature feature)
{
}
public bool ProcessListItem(Microsoft.SharePoint.SPSite site, PolicyItem policyItem, Microsoft.SharePoint.SPListItem listItem)
{
return true;
}
public bool ProcessListItemOnRemove(Microsoft.SharePoint.SPSite site, Microsoft.SharePoint.SPListItem listItem)
{
return false;
}
public void Register(Microsoft.SharePoint.SPContentType ct)
{
}
public void UnRegister(Microsoft.SharePoint.SPContentType ct)
{
}
Add this to a class library, strong name the assembly and add it to the GAC. IPolicyFeature can be found in the Microsoft.Office.RecordsManagement.InformationPolicy namespace. To use this you need a reference to Microsoft.Office.Policy.dll.
Step 2 – Create the manifest
In a later step we will register the new policy. To do this we need a manifest. I saved this to a manifest.xml file that is loaded by the process that registers the policy.
<?xml version="1.0" encoding="utf-8" ?>
<p:PolicyFeature id="TST.POC.PolicyFeatures.PolicyOfTruth"
xmlns:p="urn:schemas-microsoft-com:office:server:policy" group="Policy">
<p:LocalizationResources>dlccore</p:LocalizationResources>
<p:Name>Policy of Truth</p:Name>
<p:Description>
This policy helps us to achieve the goals set in our
'one version of the truth' project
</p:Description>
<p:Publisher>Ton Stegeman</p:Publisher>
<p:ConfigPage>policyoftruthsettings.ascx</p:ConfigPage>
<p:ConfigPageInstructions>
You can add keywords here.
If any of these keywords is found in the item's metadata and the metadata also has
the word 'truth' or 'proof', then the item is considered to be the 'truth'. And our
truth is something we need to manage. Separate your keywords with a ';'
</p:ConfigPageInstructions>
<p:AssemblyName>
TST.POC.PolicyOfTruth, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=503edd7b21a430b3
</p:AssemblyName>
<p:ClassName>TST.POC.PolicyFeatures.PolicyOfTruth</p:ClassName>
</p:PolicyFeature>
The name and description are used to describe your policy. The ConfigPage and ConfigPageInstructions are used on the page that is loaded when a user creates a new policy. The instructions are displayed in the left column of the page and the ASCX in the ConfigPage element is loaded when a user checks the box for our “Policy of Truth” policy. The AssemblyName and ClassName elements are the reference to the policy feature we created in step 1.
Step 3 – Create the configuration page.
The configuration page is the page that is loaded when a user creates a policy using our feature. The screenshot below shows the control for this specific policy.
To create this control, you create a new ASCX file and copy that to the SharePoint LAYOUTS folder. The contents of my PolicyOfTruthSettings.ASCX file:
<!-- _lcid="1033" _version="12.0.4518" _dal="1" -->
<!-- _LocalBinding -->
<%@ Assembly Name="TST.POC.PolicyOfTruth, Version=1.0.0.0, Culture=neutral, PublicKeyToken=503edd7b21a430b3"%>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities"
Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Control Language="C#" Inherits="TST.POC.PolicyOfTruth.PolicyOfTruthSettings" %>
<p>
<table cellpadding="0" class="ms-authoringcontrols">
<tr>
<td> </td>
<td><asp:Label runat="server" Text="Enter your keywords, separated by ';'"></asp:Label></td>
</tr>
<tr>
<td> </td>
<td>
<asp:TextBox id="TextBoxKeywords" runat="server" MaxLength="1024"
class="ms-input" ToolTip="Enter your keywords here." />
<asp:RequiredFieldValidator
id="RequiredValidatorKeywords"
ControlToValidate="TextBoxKeywords"
ErrorMessage="At least one keyword is required."
Text="Please enter on or more keywords separated by a semicolon."
EnableClientScript="false"
runat="server"/>
</td>
</tr>
</table>
</p>
You can see here the this control inherits a custom class that I have created called “PolicyOfTruthSettings”. This class inherites from CustomSettingsControl and is compiled into the same assembly as created in step 1. The CustomSettingsControl can be found in namespace “Microsoft.Office.RecordsManagement.InformationPolicy”. It is an abstract control with some abstract methods that our CustomSettingsControl needs to implement. Here is the code for this class in my example:
public class PolicyOfTruthSettings : CustomSettingsControl
{
private SPContentType _contentType;
private string _customData;
private SPList _list;
protected TextBox TextBoxKeywords;
public override Microsoft.SharePoint.SPContentType ContentType
{
get {return _contentType;}
set {_contentType = value;}
}
public override string CustomData
{
get
{
XmlDocument doc = new XmlDocument();
XmlElement rootNode = doc.CreateElement("data");
doc.AppendChild(rootNode);
XmlElement keywordsNode = doc.CreateElement("keywords");
rootNode.AppendChild(keywordsNode);
keywordsNode.InnerText = TextBoxKeywords.Text;
_customData = doc.InnerXml;
return _customData;
}
set {_customData = value;}
}
public override Microsoft.SharePoint.SPList List
{
get {return _list;}
set {_list = value;}
}
public override bool LoadPostData(string postDataKey,
System.Collections.Specialized.NameValueCollection values)
{
string oldData = this.CustomData;
string newData = values[postDataKey];
if (oldData!=newData)
{
this.CustomData = newData;
return true;
}
return false;
}
public override void RaisePostDataChangedEvent()
{
}
protected override void OnLoad(EventArgs e)
{
base.OnLoad(e);
if ((base.IsPostBack) || (string.IsNullOrEmpty(_customData)))
{
return;
}
using (XmlReader reader = XmlReader.Create(new System.IO.StringReader(_customData)))
{
reader.ReadStartElement("data");
reader.ReadStartElement("keywords");
TextBoxKeywords.Text = reader.ReadString();
reader.ReadEndElement();
reader.ReadEndElement();
}
}
}
The most important parts of this control are the CustomData property and the OnLoad. All custom data that you collect using the controls in the CustomSettingsControl is saved with the policy as xml. You can see that when you export a policy. See the last step for an example of the policy we are developing. A warning here: you should be careful with this xml, because if you create some xml that cannot be parsed or has another error, SharePoint will crash the page leaving you with a corrupt policy that cannot be removed. In my case I created a site collection policy that made all other policies inaccessible, so I had to re-create the site collection. So be warned!. In the CustomData property the xml is generated with the values of the controls. The OnLoad reads the xml string and sets the values for the usercontrol(s) in your editor.
Step 4 – Register the policy feature
The last step after you have deployed the assembly and the ascx file is to register the policy feature in the PolicyCatalog. Although I am not 100% sure, I think there is 1 policy catalog for each MOSS server. This MSDN page in the SharePoint Server 2007 SDK contains more information. The way to register your custom policy is doing it programmatically. I do it in a custom tool that makes it easy to register / unregister the custom policy. The best way to do it (and the way SharePoint does it) is by creating a new SPFeatureReceiver object that registers the policy. Here is the code to register our policy:
PolicyFeatureCollection policyFeatures = PolicyCatalog.FeatureList;
foreach (PolicyFeature policyFeature in policyFeatures)
{
if (policyFeature.Id=="TST.POC.PolicyFeatures.PolicyOfTruth")
{
MessageBox.Show("Policy was already installed");
return;
}
}
string manifest = System.IO.File.ReadAllText("manifest.xml");
PolicyFeature.ValidateManifest(manifest);
PolicyFeatureCollection.Add(manifest);
This piece of code first checks if the policy is not registered. If it is not, it reads the manifest for the policy from the manifest.xml file. Then this manifest is validated and added to the PolicyFeatureCollection. The objects referenced here are in the same namespace that we used in step 1 and 2.
And if you need to unregister it:
PolicyFeatureCollection policyFeatures = PolicyCatalog.FeatureList;
foreach (PolicyFeature policyFeature in policyFeatures)
{
if (policyFeature.Id == "TST.POC.PolicyFeatures.PolicyOfTruth")
{
PolicyFeatureCollection.Delete(policyFeature.Id);
return;
}
}
Step 5 – Test
After you successfully registered your policy feature, you are now ready to test if your policy is available. To create a policy at the site collection level, go to “Site collection policies” in the Site Collection Administration. When you click Create, the “Policy of Truth” should be available:
When you check the box, you will see the screenshot from step 3. After creating and saving the policy, you can export it to an xml file. If you open this file, you can see that the data we entered in our custom control, is stored in the policy xml. This was done by the CustomSettingsControl from step 3. An example of the xml:
<p:Policy xmlns:p="office.server.policy" local="false" id="62bb137b-e4c5-4dab-9b90-c9b3e54384c5">
<p:Name>The truth about SharePoint</p:Name>
<p:Description>This policy manages 'truth' items on SharePoint in our portal</p:Description>
<p:Statement>
SharePoint list items and documents that are considered to be the truth about SharePoint
Technologies, will be managed by our 'truth manager'.
</p:Statement>
<p:PolicyItems>
<p:PolicyItem featureId="TST.POC.PolicyFeatures.PolicyOfTruth">
<p:Name>Policy of Truth</p:Name>
<p:Description>This policy helps us to achieve the goals set in our 'one version of the
truth' project</p:Description>
<p:CustomData>
<data>
<keywords>SharePoint; MOSS; WSS</keywords>
</data>
</p:CustomData>
</p:PolicyItem>
</p:PolicyItems>
</p:Policy>
You can also directly assign a new policy on a list or a content type, or you can assign the policy we just created for the site collection.
In the next item we’ll make the policy do some work.
Update 15–02–2007 – Added overview of all parts:
- Part 1 – introduction and creating the policy feature
- Part 2 – implementing the handler and submitting to a records center
- Part 3 – implementing and testing the policy
|
tonstegeman