Friday 5 September 2008

Creating and attaching Information Management Policies

I haven't posted anything for a while and here is something I meant to post
Sorry for the formatting issues with the code Hope this Overview helps.

Background information about information Policies
Polices are defined in xml markup
A skeleton Policy described in xml.

<p:Policy xmlns:p="office.server.policy" id="" local="true">
<p:Name></p:Name>
<p:Description></p:Description>
<p:Statement></p:Statement>
<p:PolicyItems>
<p:PolicyItem featureId="">
<p:Name></p:Name>
<p:Description></p:Description>
<p:CustomData>
<data>
</data>
</p:CustomData>
</p:PolicyItem>
</p:PolicyItems>
</p:Policy>

Note the Policy id attribute takes a string that uniquely identifies this policy
Example “Microsoft.Office.RecordsManagement.Policy”

Each policy contains a number of Policy Items
A Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration Policy Item defined in xml.

<p:PolicyItem featureId="Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration">
<p:Name>Expiration</p:Name>
<p:Description>
Automatic scheduling of content for processing, and expiry of content
that has reached its due date.
</p:Description>
<p:CustomData>
<data>
<formula id="Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration.Formula.BuiltIn">
<number>0</number>
<property>Created</property>
<period>days</period>
</formula>
<action type="workflow" id="" />
</data>
</p:CustomData>
</p:PolicyItem>

These Policy items are used to configure the Policy Features for this Policy.
See Stegeman Blog for more information on how to create your own custom Policy Features.

Managing Information Management Policies via Code
Creating a Information Management Policy
The Policy needs to be defined in xml markup. This definition can then be passed to the
Policy.ValidateManifest () method that will validate the XML against the Policy Xml schema.
Once the policy has been validated it can be added to the policy collection using the PolicyCollection.Add () method

Example

string xmlManifest = generatePolicyXML(policyId,
Name,
string.Empty,
string.Empty,
FieldName,
WorkflowAssociationId);

Policy.ValidateManifest(xmlManifest);

PolicyCollection.Add(site, xmlManifest);

In this example I am generating the XML Manifest using a method and passing it various parameters once we have the xmlManifest string populated I pass it for validation to the Policy.ValidateManifest (string) method (Note this will through an exception that explains why it is unable to validate the XML) and then I add it to the Site via the PolicyCollection.Add (SPSite, string)

Retrieving a Information management Policy for a Site
To retrieve an Information Management Policy for a site we need to first get the Policy Catalog for that site and then retrieve the Policy from the catalog. We retrieve the Policy Catalog by creating a new PolicyCatalog object passing the SPSite object to the Constructor. We can then access the PolicyList collection of the new PolicyCatalog object to retrieve the Policy.

Example

using (SPSite site = new SPSite(siteId))
{
PolicyCatalog policyCatalog = new PolicyCatalog(site);
Policy returnPolicy = policyCatalog.PolicyList[policyId];

if (returnPolicy != null)
{
//Code to run aganst the new Policy Object …
}
}

In this example I am creating the SPSite object from a Guid that is the Id for the site. Once I have the site object I pass it to the PolicyCatalog Constructor to create a new PolicyCatalog object that relates to the site. Once I have the PolicyCatalog for the site I can use its PolicyList Collection to retrieve a Policy using the Policy’s Id. Note that if a Policy does not exist with the supplied Policy ID then the Collection returns null so I check the returned Policy is not null before running code against it.

Attaching a Information Management Policy to a Content Type
To attach a Site Information Management Policy to a Content Type, we first need to fetch the site policy and then attach it to the Content Type using the Policy.CreatePolicy () passing it the Policy and Content Type.

Example

using (SPWeb web = site.OpenWeb())
{
SPContentType contentType = web.ContentTypes[contentTypeId];
if (contentType != null)
{
Policy.CreatePolicy(contentType, policy);
}
}

In this example I fetch the SPWeb Object and use it to fetch the Content Type with the supplied Content Type ID. Once I have the Content Type I check that that the returned value is not null and then I pass it to the Policy.CreatePolicy (SPContentType, Policy). Note a content type can only have one policy attached at any time and it may be best to check that the content type does not have a policy attached by testing that the Policy.GetPolicy (SPContentType) method returns null and not a Policy object else the Policy.CreatePolicy () method will through an exception.

Configuring the Expiration PolicyFeature

Creating an Expiration PolicyFeature Formula
The Expiration PolicyFeature has a custom data node that defines the when the item will expire. This is stored in the formula node.

Example

<formula id="Microsoft.Office.RecordsManagement.PolicyFeatures.
Expiration.Formula.BuiltIn">
<number>0</number>
<property>ERMExpiryDate</property>
<period>days</period>
</formula>


The Formula id Points the out of the box, built in formula
Number refers to the number of units to append to the date
Property refers to the Field in the item to retrieve the date from
Period refers to the unit that the number represents.
There are 3 period options: days, months, years.

Creating an Expiration PolicyFeature Action that calls a Workflow
The Expiration PolicyFeature has a custom data node that defines what action should be taken once the Item has expired. We want to start off a workflow so our XML looks like this

Example

<action type="workflow" id="feebb1e3-68f0-40ce-8dc0-e297814680ab" />


I define the type of action to be workflow and set the id to point the ParentAssociationId of the Content Types Workflow Association.
Setting this ID is one of the resigns that have not been able to get around in CAML.
This Guid is neither the Workflow Associations Id nor the Workflow Template ID but the Parent Association Id of the Workflow association.

Resources
MSDN
Introduction to Information Management Policy
Policy Schema Overview
Private Blogs
MOSS Custom policies part 1 - Creating a custom information management policy

3 comments:

fromonesource said...

I have had some trouble crafting the xml file like you describe. When I package into a feature, I get an error like this:

Object reference not set to an instance of an object. at Microsoft.Office.RecordsManagement.InformationPolicy.Policy.get_IsLocal()
at Microsoft.Office.RecordsManagement.InformationPolicy.ApplicationPages.PolicyUI.OnLoad(EventArgs e)
at System.Web.UI.Control.LoadRecursive()
at System.Web.UI.Page.ProcessRequestMain(Boolean includeStagesBeforeAsyncPoint, Boolean includeStagesAfterAsyncPoint)

I am trying to build a content type with an expiration policy. I get the error above only when I include the XmlDocument NamespaceURI="office.server.policy" node which contains the policy itself. Judging by the error it seems that it is not associating the policy with the content type properly. You mention that the Policy id attribute should uniquely identify the policy. Could you explain this further? I have tried the GUID of the content type, the site and even "Microsoft.Office.RecordsManagement.Policy"

Thanks

fromonesource said...

To clarify, I get the error when I try to view the Information Management Policy Settings on the content type settings page.

John Vivian said...

@FromOneSource
Sorry for the late reply

The Policy Id is just a string that is used the Identify the policy. It can be used to find the Policy in code.

Things to look out for are:
1) Does the Workflow exist in the List Before you attach the policy.
2) Are you using the correct Workflow Assocation ID (It needs to be the Parent Association Id and not the Association ID)

I had this problem when I was trying to define the Policy with in the Content Types CAML Definition.
This was mostly due to using the wrong Workflow Association ID.

Hope this reply is not too late.