Friday, January 27, 2012

How to Create a Workflow to Change Item Level Permissions

Yesterday in our ShareLabs session a question was asked on how to display and/or secure data in a list based on criteria other than the author.  I am going to use colors as the criteria for the purposes of this post.  So the scenario is that we want to build a list to track something like, say.... oh I don’t know…. how about bicycles.  We only want to display certain colors to certain groups for whatever reason.  There are multiple ways to accomplish this, one of them being that we create views that filter the colors that we want to display, then create a page and drop a web part for each filtered view, and then apply Audience Targeting on each web part.  At first blush this looks like it would accomplish what we want it to but what happens when a user goes to the list itself instead of our web part page?  They are going to be able to see all entries in the list regardless of color, because of the permissions that they have on that list.
In SharePoint 2010 there are item level permissions that can be applied on lists.  Essentially you can mouse over each item, click on the drop down arrow, and choose Manage Permissions.

On the permissions page you can choose the Stop Inheriting Permissions button on the ribbon and then customize the permissions on that item.

Now you have the desired results across the board without needing to setup web parts with Audience Targeting.  However, this approach has a couple of flaws.  First, this method can be very daunting to manage especially for large lists.  Think of breaking the permission inheritance on each and every item in the list and then customizing the permissions.  Also think about managing it going forward, what happens when you have to add a new user to permissions?  Since inheritance is broken on the item you will have to manually add that new user to each item that they should have access to.  You could and should use groups to assign permissions to but it can still be a very time consuming process to get your permissions just right.
There is an easier way to accomplish this task and it comes in the form of a SharePoint Designer workflow that uses impersonation steps to change the permissions on the items in your list.  I will walk you through creating such a workflow as well as discussing some of the potential trouble spots.  Before we dive into SharePoint Designer to build the workflow we have some decisions to make and some preliminary work to do.
1.       We will need a list for our data.  This will also work for Document Libraries but for this example I am creating a list called Bikes with the following columns; Serial Number, Color, Manufacturer, Bike Type, and Suspension.

2.       What criteria do we want to use to set up the permissions?  For this example we are going to use the color column.


3.       How many different sets of users are we going to have?  In my list I am using 3 colors; red, blue, and green but I am going to have more sets of users than colors.  Our sets are going to be; red, blue, green, red and blue, red and green, blue and green, and all.

4.       On my site I am going to create a group for each set, 7 groups total.  Bikes-Red, Bikes-Green, Bikes-Blue, Bikes-Red and Blue, Bikes-Red and Green, Bikes-Blue and Green, and Bikes-All will be the group names.  As a side note, if I am going to be in Designer anyways and if I need to make multiple groups, I prefer to make my groups in Designer as the navigation is easier with the buttons on the ribbon always being present where in the browser it takes a few extra clicks for each group that you create.  Both methods work so use whichever one you prefer.
This is what the permissions look like for all entries in my list before running the workflow:

Now that we have all of the prep work out of the way let’s build a workflow.  If you haven’t done so already, open your site in SharePoint Designer 2010. 
What’s that?  You don’t have SharePoint Designer 2010 installed on your computer?  OK, we’ll wait while you go to http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=16573 to download and install SharePoint Designer 2010.
1.       Once your site is opened in SharePoint Designer (SPD), click on Workflows in the Site Objects pane on the left.  In the New section of the ribbon, click on List Workflow and choose the list that you want to create the workflow for, in this case Bikes.

2.       Give your workflow a Name and optionally a Description then click OK.


3.       You will now be in the workflow editor screen with a blinking orange cursor in the Step 1 window.  Changing permissions through a workflow requires that we use an impersonation step so the first thing that we need to do is click above the Step 1 window so that the blinking cursor is above Step 1 and then click on  Impersonation Step in the Insert section of the ribbon menu.

After you have an Impersonation Step window you can click on the Step 1 window and delete it.  If you are creating a more complex workflow that will use multiple steps then feel free to leave the Step 1 window there so that you can use it in the future.
4.       Now that we have an Impersonation Step, the first thing that we need to do is set a condition that compares the value of the color column.  Click on Condition and choose If current item field equals value from the drop down menu.

5.       Click on field and choose Color then click on value and choose Red.  You screen should look like this:

6.       Next click on the Action button on the ribbon, scroll down to the List Actions section and choose Replace List Item Permissions.

7.       Click on the these permissions link to launch the Replace List Item Permissions window.  Click Add.

8.       Click on the Choose… button and select the following groups; Bikes-All, Bikes-Red, Bikes-Red and Blue, and Bikes-Red and Green then click OK.


9.       Next select the permissions that you want to grant to these groups.  To keep things simple I am going to grant all groups Contribute permissions so I select the Contribute checkbox and then click OK. 

10.   If you want to mix things up and give all groups Contribute and the Bikes-All group Full Control then simply add another entry to the List Item Permissions window and choose Bikes-All and grant them Full Control permissions.  This is probably a good place to talk about the potential for locking yourself out of being able to access items in this list.  If you are a Site Collection Administrator you have less to fear as you will still have access to the list items.  However, if you are a Site Owner and not a member of any of the groups that we created earlier on, then guess what…. after this workflow runs you will no longer have access to items in this list.  Make sure that this does not happen to you by either adding the site’s Site Owner Group or making sure that you and/or other site owners are in a group that you are specifying to have Full Control permissions on the item.  Don’t say I didn’t warn you!  Once you have all of the permissions granted to the right groups or users, click OK.

11.   Click on the this list link, leave Current Item in the List field and click OK.

12.   In the Insert section of the ribbon click on Else-If Branch then click on Condition and choose If current item field equals value.

13.   Click on field and choose Color then click on value and choose Blue.  You screen should look like this:

14.   Repeat steps 6-11 from above to add the Replace List Item Permissions action to the workflow, only this time for the Blue set of users.

15.   Repeat steps 6-14 for the Green users set.  When you are done your Impersonation Step should look something like this:


16.   Click on the Check for Errors button on the ribbon to verify that there are not any logic errors in the workflow.  This check does not ensure that your workflow will work as perfectly as you have envisioned, only that there are no infinite loops, dead ends, etc… in your workflow logic.

17.   If there were no errors, click Save.

18.   On the bread crumb trail just below the tabs under the ribbon, click on the name of your workflow to exit the editor and to get to the workflow settings page.


19.   On the workflow settings page find the Start Options section and choose the Start workflow automatically when an item is created and the Start workflow automatically when an item is changed checkboxes.  This will ensure that if someone changes the color field then the proper permissions will be applied.

20.   Save the workflow again after choosing your start options.

21.   The last step in SPD is to publish the workflow.  This is where things can get a little tricky because we are using an Impersonation Step.  This workflow is going to run under the security context of the user who publishes the workflow.  In most cases this fine but let’s explore a couple of possible scenarios that could render this workflow useless.  Suppose that in the future you are assigned to another team and your permissions are removed from the site.  At that point the workflow will no longer work and all new items will revert back to inheriting the permissions from the list.  Ok who are we kidding, no goes into the site settings and clears up permissions right?  Chances are that John who used to be on your team a year ago but has since moved over to Accounting is still a member of your site.  True, that does happen all too often so let’s take another approach, let’s say that in 6 months you take a job at another company.  It is very likely that your account will, at the very least, be disabled before you make it to your car in the parking lot.  At that point your workflow is broken.  I know, you’re thinking if that’s the case then why do I care, I don’t work there anymore.  That’s not going to win you friends and glowing references in the future so let’s do this right.  It is always a good idea to publish workflows that contain Impersonation Steps as a service account.  Service accounts generally don’t go away and your administrator can setup a policy on the backend so that the permissions of said account are not ever removed from the site.  So either risk alienating your coworkers by publishing the workflow as yourself or contact your SharePoint Administrator and have them publish it using a service account.
Now that your workflow has been published to your brand new, not populated with items, list - you are finished.  As you add items to the list, the workflow will run and set your permissions as you configured the workflow to do it. 
Oh, but your list already has a few entries?
No biggie, just mouse over each item, click on the drop down list, choose Workflows, and select your workflow name and click Start.
Huh?  Oh you meant there are a few hundred items in the list?  Ah, well check out my earlier post on creating a workflow to run on an entire list, the poor man's way for the answer to that problem.
Ok, your workflow has ran and now the permissions for your items should look similar to this:

If you see additional entries on the permissions list that have a permission level of Limited Access you don’t need to worry about them per se.  The Limited Access permission level is a system permission that acts as a place holder.  It could indicate that those entities have access to something either lower in the hierarchy or at a peer level such as a content type.  Limited Access does not indicate that they have any access to this specific item.  However, if you want to be sure that they do not have permissions to this item, click the Check Permissions button on the ribbon, put the user name or group name into the field and click Check Now.

That about wraps things up, until next time….

47 comments:

  1. great Post!but, what would happend if i change the color of one item?. The security level will change? or i must do another workflow?

    ReplyDelete
    Replies
    1. That would depend on how you set up the trigger action for the workflow. If you set it to only fire off when an item is created then changing the value of the column will not cause the workflow to run therefore the security would stay the same. However, if you set the trigger of the workflow to fire off when an item is changed, then the workflow would kick off when the value is changed and your permissions will change as a result of the workflow running against the item.

      Delete
  2. Excellent Post!! Just what I was looking for

    ReplyDelete
  3. Thanks man... you saved a day.. nice Topic and perfect explanation..

    ReplyDelete
  4. I am following your example somewhat, but with mine, I need to change permissions on a folder. It seems to work fine with the first two scenarios, but the one that the condition is based on two separate fields, it adds the first impersonation step's permissions. I am not sure what it going wrong. I've even put in a Stop Workflow after each impersonation step.

    ReplyDelete
  5. This comment has been removed by the author.

    ReplyDelete
  6. I used this action and it was working as shown here till few days back, however since past few days i observed that it does not clean up permissions for others users on the list item. So basically initially it gives permission to all users and based on the users and permissions mentioned in this action it only gives permissions to selected users and CLEAN up others users. But from last few days the clean up action is not being performed

    ReplyDelete
    Replies
    1. You could try doing this in 2 actions, first, Remove List Item Permission and second, Add List Item Permission instead of just the Replace List Item Permission.

      Delete
  7. I used this action on a 2010 workflow, but it does not seem to work when running SharePoint 2013. I set the entire thing up exactly as specified here, and was able to publish the workflow with no errors, but when someone adds a new item to the list, the permissions are not affected at all. Could this have anything to do with the permissions I set on the list in SharePoint 2013? I did use the advanced feature to limit view and update rights only to the user who created the item.

    ReplyDelete
    Replies
    1. On SharePoint 2013 are you creating the workflow as a 2010 workflow or a 2013 workflow? If it is a 2013 workflow then the Impersonation Step is not available and you will not be able to change the permissions. You can get around this by creating 2 workflows, a 2010 workflow that has the impersonation step, and a 2013 workflow that has the rest of the workflow. In the 2013 workflow you can add the Start a List Workflow action to start the 2010 workflow to change the permissions.

      Delete
  8. I all,
    thanks for this good article ! But on my side, working with Sharepoint 2010 Server and Sharepoint Designer 2010, I can't find this specified action. Do I have to active some feature ?
    Thanks & Regards

    ReplyDelete
    Replies
    1. You should create an Impersonation Step as described in 3rd bullet.

      Delete
  9. I am facing this error

    Load Workflow Class: System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. System.Collections.Generic.KeyNotFoundException

    Any clue?

    Regards,
    Khushi

    ReplyDelete
    Replies
    1. Not sure what is going on there, but this post might get you headed in the right direction. http://blogs.msdn.com/b/wael/archive/2008/01/11/workflow-failed-on-start-retrying.aspx?CommentPosted=true

      Delete
  10. Awesome article. Thanks for sharing!

    ReplyDelete
  11. can the same method be applied to change folder permissions of a library? If not is there an alternate approach in SP 2013 workflows or using CSOM/JSOM?

    ReplyDelete
    Replies
    1. I haven't tried it with folders as I try to stay away from folders and use metadata, document sets, etc... instead.

      I would imagine that you could, provided that you are able to set metadata on the folder on create.

      Delete
  12. Hi Burden,

    Great article, I have done same thing in my local stand alone server SP2010 its working fine for the Farm Admin And Site Adimn, when I tired the same in QA its not working for Farm Admin. it through error while add list item permissions to user groups.
    in log history list getting "Error Occurred" description "An error has occurred in ItemLevelPermissionsWF"

    ReplyDelete
    Replies
    1. I would check to verify that the account that is publishing the workflow has the necessary permissions on the site collection.

      Delete
  13. Thanks and great article, I have created the same but, while giving the item level permissions it is by default add workflow users to that item, every one is able to see the items so could you please help me in resolving the same

    ReplyDelete
    Replies
    1. After the workflow runs check the item level permissions to see if the permissions have been replaced with only the users specified or are the original permissions still there. If the latter then try using the Remove List Item Permissions action first followed by the Add List Item Permissions action.

      Delete
  14. I cannot get it to stop inheriting permissions from the list.

    ReplyDelete
    Replies
    1. Instead of the Replace List Item Permissions action, try using the Remove List Item Permissions action first followed by the Add List Item Permissions action.

      Delete
  15. SharePoint Solutions.NET is a virtual company provide SharePoint Services Globally. We offer a wide array of Services covering the entire range of Microsoft SharePoint capabilities.

    ReplyDelete
  16. Awesome article, thanks a lot, its working for me

    ReplyDelete
  17. Currently i'm trying to create a workflow in SharePoint 2013 workflow platform that sets item level permission, trying to set read item level permission to "XYZ" group in SharePoint 2013 workflow, I have found that " Impersonation Step" not available in SharePoint workflow 2013.
    so how to set item level permission in SharePoint workflow 2013

    ReplyDelete
    Replies
    1. 2013 workflows have 2 actions that will help you get around this. They are Start a List Workflow and Start a Site Workflow. You will need to create 2 workflows, a 2010 workflow that has the impersonation step, and your 2013 workflow that you have already built. The 2010 workflow should probably be a list workflow if you are using a value in the column to determine the condition. Once you have the 2010 workflow built with the impersonation step, add the Start a List Workflow action into the appropriate place in the 2013 workflow and configure it to start the 2010 workflow. When the 2010 workflow is called, your 2013 workflow will pause and wait for the 2010 workflow to complete before continuing onto the next action or stage of your 2013 workflow.

      Delete
  18. This comment has been removed by the author.

    ReplyDelete
  19. This comment has been removed by the author.

    ReplyDelete
  20. I have an impersonation workflow I've been using and modifying for years (we are now in 2013). My issue is now, for some reason, when the workflow runs and goes through the step to "inherit parent permissions" for item... the workflow is set to canceled with the following error: "The workflow could not update the item, possibly because one or more columns for the item require a different type of information." The thing is all my testing confirms the workflow has executed the step properly - permissions are updated as expected but there must be something causing the workflow not make it to the next action (which is a simple logging action).

    ReplyDelete
  21. Using the 'Require content approval for submitted items' option on the library settings seems to break the workflow that you have written about.
    As a draft the workflow runs and removes the permissions, however as soon as the document is approved, the 'removed' permissions come back.
    I have tried using 'if current item equals 0#; Approved' as the first step in the impersonation step however this doesn't seem to fix it either.
    Do you have any advice on getting this to run when content approval is set?
    Thank you.

    ReplyDelete
  22. I keep getting 'failed on start' when trying to run the workflow on an item. I am a site collection administrator so don't think it has to do with that. Any thoughts?

    ReplyDelete
  23. This comment has been removed by the author.

    ReplyDelete
  24. Hi, tankhs for the great article. It helped me alot.
    I just have one question. How can I replace only the permissions that are already active on an item?
    e.g. I have two groups A and B. A has contribute permission on an item and B doesn't have any. After updating the item, A should have read only and B should still have none.
    Is that possible to achieve using a workflow?

    ReplyDelete
  25. very neat explanation keep it up
    http://www.staygreenacademy.com/sharepoint-2013-training-online/

    ReplyDelete
  26. Great article Adam,
    Is there a way to update site permissions with workflow, picking users from a list residing in same site?
    I have a pressing issue to resolve, please advise.
    Thanks
    Dig

    ReplyDelete
  27. It is not possible to put an Impersonation Step into a approval workflow. How do I can do change permission into the appoval workflow??? or it is impossible???

    Daniel

    ReplyDelete
  28. Adam, This is great. 2 quick questions: 1. Does this workflow generate a task in the site task list? 2. Has this been tested in O365 SharePoint?

    ReplyDelete
  29. This article saved me a great deal of time to change permissions quickly. Perhaps it is already mentioned, but a quick way to run the work flow on a list is to add a new column (i.e. WorkFlowPermissions) Then filter a spreadsheet view to any items that need the workflow applied. Then just make an entry in the new Column and drag it down the list. This allowed me to easily update over 100 items from edit only by the "created by" person to provide edit rights to All Users in the group "Minnesota Staff".

    ReplyDelete
  30. Hi Adam. Thank you for the info. Do you know some way to remove the permissions for all users once, that is, remove permissions without know what and how many users have permissions in a certain moment?

    ReplyDelete
  31. Sorry, in the question above, I refer to a workflow 2010/1013 solution.

    ReplyDelete
  32. This is exactly what I have been wanting to do for months now and finally got it to work. It also works with the "contains" function. This also works better with the replace permissions rather than add. Again, awesome post!

    ReplyDelete
  33. We have two way approval workflow and similar setup as above article

    As a first level approver, user wanted to view the the travel request even after approving the item.

    At present, once the request is approved in level 1 and moved to level 2, the level 1 approver is not able to view the item since the permission is revoked as per the workflow.

    Please suggest how can we achieve this and approved item be visible through out

    ReplyDelete
  34. We have two way approval workflow and similar setup as above article

    As a first level approver, user wanted to view the the travel request even after approving the item.

    At present, once the request is approved in level 1 and moved to level 2, the level 1 approver is not able to view the item since the permission is revoked as per the workflow.

    Please suggest how can we achieve this and approved item be visible through out

    ReplyDelete
  35. Great post! Thank you very much. I implemented item level permissions workflow giving contribute to people column values for that row item. When I update a people column value and run the workflow, the new person receives the permission but the replaced person retains his permission. How do I strip item level permissions? Is there a way to cycle thru who has permission on an item?

    ReplyDelete