How does the Custom SharePoint retention Policy work

Some time ago we created a custom retention policy for a customer and last week I had to give some support. I had to dive in it again because I forgot all about it.

Why did we build this?

We build this custom retention policy to move a document to the record center when a specified field has a specified value. This field could be any type of field other than a data time field. The specification of the field and his value was in a list on the root site of the Site collection that the customer can maintain.

What is the default behavior of the retention policy?

Let’s start at the beginning, what can we do with a default retention policy? A retention policy gives you the ability to do some action on a document or list item based on a time-based criteria. You can create a policy on the Site Collection thru the link “Content Type Policy Templates (/_layouts/15/Policylist.aspx)”. Here you can create a policy or edit existing policies. Whenyou create a new policy you have four options:

  • Retention
  • Auditing
  • Barcodes
  • Labels

This blog focuses on the first option. When you select retention you can create stages that determine what needs to happen at what time. One policy can have multiple stages and every stage has an event and action. The event is by default based on a date time field with a calculation and the action is what needs to be done when this event has happened, for example transfer the document to another site collection. You can have multiple stages that run in a parallel sequence.

Figure 1: Shows the default options within a stage.

After you’ve created a policy created you can set it on a content type.

When you want a retention policy on a document library you need to configure the stages inside the document library.

What can we customize?

The default retention allows you to select date fields, If you have some requirement that states that a document should be moved or start a workflow if some field has a specific value, than you need a custom retention policy. A custom retention policy only works with an on-premises SharePoint environment because you need to create code that runs on the server. When you have a hybrid environment the custom retention policy is only available in the site collection that are on the on-premises SharePoint environment To create a custom retention policy we need to build a SharePoint solution (WSP-package) that contains one class. This class needs to inherit from “Microsoft.Office.RecordsManagement.PolicyFeatures.IExpirationFormula”. This will give you 1 method called “ComputeExpireDate” witch has 2 parameters:

  • SPListItem
  • XmlNode

The method “ComputeExpireDate” needs to return a Nullable As you can see the return is in DateTime format and that’s why the default only works with data time fields.

In this method you have the control to specify when the item should expire based on the input.

Deploying the solution.

After you created the class you can deploy this as any normal solution, but you need to register the class in SharePoint to be noticed as a Policy that can be used on your Content type. There is no option in the UI to add this and should be done by code or PowerShell.

I created a piece of PowerShell to deploy this to the farm. On the farm level this is called “PolicyResource” and you can add your customization to the “PolicyResourceCollection”. This collection contains all Policy Resources in the form of XML.

This is an example of the XML that needs to be imported with PowerShell. You can use this snippet :

?The delete part is to make sure that there is no policy with the same ID, because you cannot update the XML. The variable $policyResource contains the XML Now that you have added the policy resource to the collection you can view it in the Central Admin with the url: /_admin/featuresettings.aspx?id=Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration

Using it

Now that the custom code is installed and configured you can create a retention policy in the site collection as we did in the first section of this blog, but now we can select the other option (Set by a custom retention formula installed on this server) in the dialog.

Figure 2: Stage window where you can select the cutom retention formula

In the dropdown next to it you can select your custom PolicyResource and configure the action you want.

How do you test this?

One major thing you need to be aware of is that these policies are not applied the moment that the status is changed or the date is reached. The solution depends on two timer jobs that run once a week by default. You can change these schedules if necessary. The timerjobs are:

  • Information management policy
  • Expiration policy

The information management policy needs to run first and set the expiration date, the expiration policy executes the action.

Also posted on MicrosoftHelden