Tag : break

Workflow – Useful REST calls – Share Item

Four steps are involved in updating share permissions on a list:

  1. Breaking inheritance on the list
  2. Granting access to the list
  3. Breaking inheritance on a list item
  4. Granting access to a list item

This blog will step through all four of these steps to add share access to a particular list item. In the examples that follow, ‘FA Test’/’ListName’ refers to the text name of list you are working with, ‘ListID’ refers to the numeric ID of the list, ‘ItemID’ refers to the numeric ID of the item in the list and ‘UserID’ refers to the numeric ID of the user being granted permission. When working with REST calls, make sure that the Workflow App Permissions are scoped correctly otherwise you could receive an ‘Unauthorized’ response (See Scoping). Also note that you could specify the sharing process in 5 simple steps without having to redefine the Header each time

Many thanks to Jason Lee (Custom Workflow Activity for Granting Permissions on a SharePoint Site) and Bijay Kumar (SharePoint 2013 Add User to SharePoint group using REST API) for sharing their knowledge

Define the header dictionary

This step defines the header format that will be used by all four of the functions mentioned previously.

Create a dictionary variable that will tell the system to return values in JSON format.

203-2202-3

Click on ‘this’ and use the ‘Add …’ button to define the dictionary names ‘Accept’ and ‘Content Type’ with both having exactly the same value: ‘application/json;odata=verbose’. I replace the ‘Variable:dictionary’ with my standard ‘Header’ dictionary

203-3

Break inheritance on a list (breakroleinheritance)

Since you will be defining custom permissions for the list, you will need to break the role inheritance. This will not change permissions, but will simply change the current users to ‘specified’ rather than ‘inherited’ permissions

Define the REST call in a string variable

210-1
[%Workflow Context:Current Site URL%]_api/web/lists/GetByTitle(‘ListName’)/breakroleinheritance

Use a ‘Call HTTP Web Service’ action to make the REST call using the string previously defined with an HTTP POST method

210-2

We are still not finished with the web service.  Click on the right combo-box of the ‘Call’ action and select ‘Properties…’ Set the RequestHeaders to the ‘Header’ dictionary previously created

210-3

That is all that is needed to break the role inheritance – no results are returned. Simply check the ‘ResponseStatusCode’ variable to make sure the call functioned correctly

Grant access to the list (addroleassignement)

Once the role inheritance is broken, we need to add the user to the list permissions.  Use these actions to give a user or group access to a list (performed prior to granting unique permissions to a list item)

Define the REST call in a string variable

Once you have created the header dictionary, set a workflow variable to the string value of the REST call. In the example shown below, [%Current Item:Created By%] is returning the ‘User Id Number’

210-5
[%Workflow Context:Current Site URL%] /_api/web/lists/GetByTitle(‘ListName’)/roleassignments/addroleassignment (principalid=UserGroupID , roleDefId=1073741826)

Set the values in the string builder as follows:

principalid:          ID of the user or group receiving permissions on the list
roleDefId:           A role definition ID. The standard Microsoft 10 digit out of the box ID’s are as follows:

Full Control:        1073741829
Read:                   1073741826
Contribute:          1073741827

See my post on getting the Role ID values – useful for custom permission definitions

Use a ‘Call HTTP Web Service’ action to make the REST call using the string previously defined with an HTTP POST method

210-2

We are still not finished with the web service.  Click on the right combo-box of the ‘Call’ action and select ‘Properties…’ Set the RequestHeaders to the ‘Header’ dictionary previously created

210-3

That is all that is needed to allow the user to access the list – no results are returned. Simply check the ‘ResponseStatusCode’ variable to make sure the call functioned correctly

Break inheritance on a list item (breakroleinheritance)

You would perform this call prior to granting unique permissions to a list item. This is similar to the call to break inheritance on a list, except that here we specify the list item ID on which to break inheritance

Define the REST call in a string variable

Once you have created the header dictionary, set a workflow variable to the string value of the REST call. In the example shown below, [%Current Item:SourceID%] is returning the ID of the list item

210-6

[%Workflow Context:Current Site URL%]_api/web/lists/GetByTitle(‘ListName’)/getItemById (ItemID)/breakroleinheritance

Use a ‘Call HTTP Web Service’ action to make the REST call using the string previously defined with an HTTP POST method

210-2

We are still not finished with the web service.  Click on the right combo-box of the ‘Call’ action and select ‘Properties…’ Set the RequestHeaders to the ‘Header’ dictionary previously created

210-3

That is all that is needed to break the role inheritance – no results are returned. Simply check the ‘ResponseStatusCode’ variable to make sure the call functioned correctly

Share an item with a user

You would perform this call after you have broken permissions on the list and list items and granted the user in question access to the list. These processes were covered in the previous three HTTP Calls)

Define the REST call in a string variable

Once you have created the header dictionary, set a workflow variable to the string value of the REST call. In the example shown below, [%Current Item:SourceID%] is returning the ID of the list item while  [%FA Test:Created By%] is  returning the ‘User Id Number’

210-7

[%Workflow Context:Current Site URL%]_api/web/lists/GetByTitle(‘ListName’)/getItemById(ItemID)/roleassignments/addroleassignment (principalid=UserID, roleDefId=1073741829)

Use a ‘Call HTTP Web Service’ action to make the REST call using the string previously defined with an HTTP POST method

210-2

We are still not finished with the web service.  Click on the right combo-box of the ‘Call’ action and select ‘Properties…’ Set the RequestHeaders to the ‘Header’ dictionary previously created

210-3

That is all that is needed to allow the user to access the list item – no results are returned. Simply check the ‘ResponseStatusCode’ variable to make sure the call functioned correctly