Custom Document Expiration Policy – Part-4: Managing Expiration

In this post, i’ll try to show how expiration warnings can be managed. Basically managing warnings includes some custom menu actions such as:

• Collect Documents – When this action is selected, selected documents are flagged so that they are forced to expire immediately. (Here immediately actually means ‘next time Expiration Timer Job runs’). In other words, selected documents are deleted next day. (Usually expiration timer job runs at 11pm)
• Reset Expiration Dates – When this action is selected, Last Modified Date of documents are set to Now, so that expiration formula runs again and ExpirationDate field of document is updated based on the formula defined. (ExpirationPeriod and ExpirationWarning values can be set in Web.Config. I’ll also show that in this post)

As I mentioned in previous post (https://zieglers.wordpress.com/2010/01/18/custom-document-expiration-policy-part-3-additions/) of ‘Custom Document Expiration Policy‘ posts series, once documents are in expiration warning period, a list entry is created in Expiration Warnings List. From this list, using Actions menu items you can manage document expiration as mentioned above.

Demo: In our demo, i upload a document to a library for which expiration policy has already been applied.

 

I set ExpirationPeriod value to 5 mins and ExpirationWarning value to 3 mins in web.config for that web.

This means after 2 minutes, document i upload will be in Expiration Warning Period and a warning entry will be created in Expiration Warnings list.

Now, I enable ‘Multiple Item Selection’ feature for this library. This feature is necessary if we want to process more than one item in bulk. Item selection can be enabled/diabled using custom actions menu item as shown below.

Once you enable item selection, you’ll see a checkbox next to each list entry, so that you can select multiple items to process. (Cool,eh?!? This is actually achieved by using JQuery. I’ll also try to show details of it in another post. Stay tuned…)

Reset Expiration Dates:

Let’s select above item and, for instance, let’s reset expiration date for that document. In order to do so, after selecting the item, i click ‘Reset Expiration Dates’ custom actions menu item.

Then, i get a nice pop-up message to confirm this operation.

… and i click OK, so that expiration date of this document gets resetted.

Please take a careful look at above screenshot and first screenshot of this post.

You’ll see that in first screenshot, Last Modified time is 3:39pm and Expiration time is 3:44pm. Then, i resetted expiration date for this document at 3:44pm, as a result of this Expiration time in above screenshot is 3:49pm, which is 5 minutes later than last modification time.

This shows us that once i clicked ‘Reset Expiration Dates’, expiration date was calculated again based on our custom defined expiration formula.

Collect Documents:

Collect Documents action is to force documents to expire immediately. This is achieved by setting a boolean field CollectMe to Yes. Also Expiration Date field is set to Now.

Since in my demo environment, i have set up Expiration Timer Job to run every minute, when i check document library after one minute, I see that my test document is deleted/collected.

Here is a demo of how it works:

Similar to Reset Expiration Dates scenario, first I upload my test document.

Then, after 2 minutes, when document is in Expiration Warning Period, warning entry is created in Expiration Warnings List.

Once again enable item selection and select test document.

Then, go to Actions Menu and select “Collect Documents-To-Expire“.

 

At this point CollectMe field is set to YES and Expiration Date field is set to Now. When we go to document library we can see updated fields as shown below.

Also note that Modified and Expiration Date field values are same, which tells us that Expiration Date is set to Now.

Finally, checking the document library after 1 minute, I see that expiration occurred and my test document is deleted/collected. (Moreover, another log entry is created in Expiration History list for this expiration event.)

So, this concludes Managing Expiration post.

Please let me know if you have any suggestions/comments re usability/functionality of Expiration Management feature.

Zieglers

Custom Document Expiration Policy – Part-3: Additions

This post will detail some functional extensions implemented for Custom Expiration Policy.

You can find previous posts related to Custom Expiration Policy here:

• Custom Document Expiration Policy (https://zieglers.wordpress.com/2010/01/18/custom-document-expiration-policy-part-1-overview/) 
• Custom Document Expiration Policy – Implementation Details (https://zieglers.wordpress.com/2010/01/18/custom-document-expiration-policy-part-2-implementation/)

Previously, we implemented our custom expiration policy to take advantage of OOTB delete action. This means when a document expires, it is simply deleted.

In this post we’ll look into details of how to perform a custom action when document expires. Here are the requirements for custom action:

• First, log expiration warning details to a list called Expiration Warnings.
• Then, upon expiration, log expiration details to a list called Expiration History.
• Finally, delete document.

So, that’s how Expiration Warnings and Expiration History lists look like.

Once our custom expiration action is deployed, it shows up in expiration settings under ‘Perform this action‘ dropdown list. I called it ‘Expiration Event Logger‘.

Implementation of custom expiration action is similar to implementation of expiration formula calculation. All we need to do is to implement IExpirationAction interface which can be found in Microsoft.Office.RecordsManagement.PolicyFeatures namespace.

Above OnExpiration method is called once document expires. Here, first we are creating Expiration History List and then deleting the expired document.

In order to create a list and write an entry in it, i used a helper class called ExpirationHistoryList, whose implementation can be seen below.

There is only one constructor. This constructor gets Expiration History List object if created. If it’s not created yet, it creates one.

In addition, WriteEntry method creates log entry in the list along with expiration event details such as document title, list name, web title, … etc.

That concludes this post – logging functionality for expiration policy.

Things to do next: Managing document expiration once expiration warning period is reached using Expiration Warnings list.

Zieglers

Custom Document Expiration Policy – Part-2: Implementation

In my previous post (https://zieglers.wordpress.com/2010/01/18/custom-document-expiration-policy-part-1-overview/), i tried to show how custom expiration policy works. Now in this post, i’ll dive into implementation details.

Here what we do is to create and install our own expiration formula as Policy Resources that are linked to the Expiration Policy Feature.

The Expiration Policy Feature communicates with your custom expiration formula policy resource through a special interface provided for that purpose. The IExpirationFormula interface is declared in the Microsoft.Office.RecordsManagement.PolicyFeatures namespace. This interface declares a single method that is called to compute the expiration date for a given list item.

Policy Namespace Overview

The following figure shows the organization of the major classes of the information policy object model, located in the Microsoft.Office.RecordsManagement.InformationPolicy namespace. The top-level object, PolicyCatalog, represents the catalog containing the site-level Policy and IPolicyFeature collections.

Most of the properties of the various objects are read-only, and cannot be set programmatically. The properties of the various information policies, policy items, policy features, and policy resources are set in the XML specified when the objects are initially added to Office SharePoint Server 2007.

Each Policy object represents an information policy defined for the site and, in turn, includes a collection of PolicyItem objects.

Similarly, each PolicyFeature object represents an installed policy feature, and contains a collection of the PolicyResourceType object that the policy features can use, as well as a collection of the actual policy resources currently installed for the policy feature; each of these policy resources is represented by a PolicyResource object.

The following figure shows the information contained within the Policy Feature Definition, and the items that the information references.

I think above information clears the overall picture. Now let’s see the implementation of IExpirationFormula interface.

Here we need to implement only one method, which is ComputeExpireDate. You can implement your own custom logic to calculate expiration date here and then return it. As for this POC, my custom logic is as follows:

1. Check for existing expiry date, if there is any.

2. If there is, compare it with current time. If time difference is less than 2 minutes, send a warning email to user.

3. If there is no existing expiry date, set it based on following rule:

[Extra Functionality] if user wants this item to be collected immediately (if ‘CollectMe‘ field value is Yes – assuming that there is a Yes/No column called CollectMe in the library), then set expiration date to current time.

if CollectMe is No, then set expiration date to 5 minutes after last modification time.

Pretty straightforward, right? Note that this function will be called each time Expiration Timer Job runs and each time this list item is edited.

Also, here is the snippet of SendWarningEmail helper method. This code is just for demonstration, values are hardcoded, but it shows how to use SPUtility.SendEmail method.

Well, that’s all about it.

Zieglers

Custom Document Expiration Policy – Part-1: Overview

In this post, i’ll try to mention what ‘Custom Expiration Policy‘ is and how you can develop one for your needs.

SharePoint comes with ECM (Enterprise Content Management) capabilities and probably most important building block of ECM is ‘Policies‘. They are also called IMPs (Information Management Policy) withing SharePoint domain. OOTB ones are Labels, Auditing, Expiration and Barcodes. In this post i’ll focus on Expiration Policy, why we need to customize it and how it can be customized.

SharePoint definition of Expiration Policy: “Automatic scheduling of content for processing, and expiry of content that has reached its due date.”

Simply saying ‘Set an expiration date on documents. Once due date is reached, perform an action.’ Here, the main parts are Expiration Date and Action Performed once document expires.

MOTIVATION: Customization need comes into play right at this point. OOTB SharePoint functionality only allows you to set expiration date based on two fields: Created Date and Modified Date. In real life scenarios, setting an expiry date only based on those two fileds may not be sufficient. Also, you might want to do some custom checks or look-ups while setting this date. Another important requirement leading to customization can be the necessity of sending warning emails before document expires.

Hence, I developed a POC to demonstrate how Custom Expiration Policy works.

POC Requirements: POC scenario is really simple.

• Set Expiration Date to Last Modified Date + 5 mins.
• Send warning email within last 2 mins. (This is customization part).
• Delete document when it expires.

POC in ACTION: Now, let’s see how it works.

To test custom expiration policy, i created a test document library called ‘Test’ and defined a policy for this library in ‘Document Library Settings > Information Management Policy Settings’.

Define a policy…

Here enable expiration policy and select custom expiration formula as shown below.

You’ll notice that there is an additional entry for retention period choice, which is “Set by a custom retention formula installed on this server“. Our custom formula name is “SomeCompanyName Custom Expiration“. This entry shows up once you deploy your custom policy resource. We’ll get back into details later about that.

Now, let’s upload a test document to library.

As you can see above, Expiration Date is set to Modified + 5 minutes by our custom expiration formula.

So far so good. Our expectation is now to get a warning email after 3 mins. Normally, SharePoint Expiration Timer Job runs daily between 23:00 and 23:30. But if you don’t want to wait for this you can force it to run in Central Admin.

For demonstration purposes, that’s what i did. Now i check my inbox and here is my warning email. (Message body says “will expire in a month“. Ignore that, since this will be eventually in finalized version of this POC)

Now, I expect to see that document is deleted after 2 mins, which in total makes 5 mins, retention period.

… wait wait wait … one minute passed … wait wait wait … two minutes passed … check test library … 🙂

Document is deleted!!! Mission accomplished 🙂

So this completes our ‘Custom Expiration Policy‘ scenario.

I think so far is enough for this post. I’ll try to show implementation details in another post.

Zieglers

Upload as a Zip file

This post is actually last section of previous post: Download as a Zip file. Since this post focuses on Upload functionality, I thought it’d deserve it’s own space..

 MOTIVATION: Uploading documents individually to a document library can take some time. Eventhough you use ‘Upload Multiple Documents’ functionality, then you have to select your documents one by one again.

 On the other hand, having the flexibility of uploading a zip file to a document library and expanding documents automatically has advantages over uploading multiple documents:

 One single file is uploaded to server vs. multiple files. This means server is kept less busy and less server resources are consumed.

• Zip file is smaller in size, because it is compressed. Again this means that uploaded file size is less than sum of sizes of individually uploaded documents.

• Uploading a zip file is faster due to being small in size.

• Uploading a zip file is more organized since your zip file will contain a logical set of documents, such as project documents.

Ok, that’s enough motivation so far. Let’s get to action.

 Upload a Zip file to a document library:

Upload a zip file functionality can be initiated using Upload section in toolbar.

Once you select ‘Upload as a Zip file and expand‘, you are taken to upload zip file application page.

Here you browse to the zip file you want to upload. Alternatively, you have 2 extract options: Create Folder for Extracted Files and Keep Original Zip file. (I think they are self explanatory.)

Here I select a zip file called BaseTestDocZ.zip.

Once you click OK, zip file is uploaded to server, files are extracted and inserted to document library as shown below.

… and here is the contents of BaseTestDocZ folder:

Finally that concludes this post. Please feel free to share your thought & suggestions.

Note: I’ll post wsp solution for this post soon!!!

Zieglers

Download as a Zip file

This post is about a new list action feature called ‘Download as a Zip file‘.

MOTIVATION: While using SharePoint document libraries, I’m sure almost all of us, time to time, download bunch of project related documents to local machines and work on them. Due to projects being large-scale, usually number of related documents <half second pause effect> A LOT! 🙂

In order to get all documents to your local drive, as of now, you need to download those documents one-by-one.

However, imagine the flexibility of downloading your documents as a zip file, wouldn’t that be nice?! I think it would 🙂 

Well, let’s not think small here, not only individual documents, but we also want to be able to ‘zip’ a folder, which contains bunch of project related documents, right? Hmm, now it starts to sound more useful..

Ok, let’s imagine more. What about (don’t get too excited, that’s the last one) uploading a zip file of your choice and as soon as it’s upload, it’s extracted automatically and all zipped files are inserted into SharePoint document library?!?!

I think so far we have enough motivation for such a solution. Here is how it’s going to look like.

Download File as a Zip file:

Functionality is tied to ECB menu. Simply, right click document you want to download as zip and select ‘Download as a Zip file‘ option as seen below.

 Once you select that option, file is zipped and you are prompted file download dialog box.

Download Folder as a Zip file:

Functionality is also tied to ECB menu. Actualy you do same clicks for downloading a folder as a zip file. Only difference is you right click folder itself instead of going into that folder.

Based on your selection’s internal type – being either file or folder – ecb menu item is calling associated code piece to execute.

Here is an example: We have a test folder called ‘My Test Folder’ as seen below and two test documents in it, namely TestDOC and TestEXCEL.

 Test Folder:

 Test files in test folder:

Just, right click ‘My Test Folder’ and select ‘Download as a Zip file’. Doing so will zip test folder with all files in it and you will be again prompted File Download dialog box.

 That’s it!!! I’ll update the post when I’m done with upload option.

Note: I’ll post wsp solution for this soon!!!

Please share your thoughts, suggestions …etc.

Zieglers