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 built 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 its 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 a Site Collection thru the link "Content Type Policy Templates (/_layouts/15/Policylist.aspx)". Here you can create a policy or edit existing policies.
When you create a new policy, you have four options:
This article 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 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 field. 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 collections 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 one method called “ComputeExpireDate” that has two parameters:
The method “ComputerExpireDate” needs to return a Nullable<DateTime>.
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 creat 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.
<Description>A custom policy that calculates the expiration date based at the status field</Description>
This is an example of the XML that needs to be imported with PowerShell. You can use this snippet:
$MicrosoftOfficePolicy=[System.Reflection.Assembly]::Load("Microsoft.Office.Policy, Version=22.214.171.124, Culture=neutral, PublicKeyToken=71e9bce111e9429c")
#try to delete
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: <Central admin>/_admin/featuresettings.aspx?id=Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration
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 article, 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 custom 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 timer jobs 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.
This article is published with permission. You can Arjan’s original blog here: http://www.arjancornelissen.nl/Blog/Bericht/38/How-does-the-Custom-SharePoint-retention-Policy-work