Security Group Operations In SharePoint 2016 Using REST API

SharePoint 2016 general availability had been announced in the Future Of SharePoint conference in May 2016. The series, which discusses the installation of SharePoint 2016 in Azure, can be found at C# Corner from the links, given below:

In this article, we will see how to interact with Security Groups in SharePoint, using REST API. As an initial prerequisite, ensure that the user running the scripts, given below, has Site Collection administrator privileges.

We will use REST to connect to SharePoint to perform the group operations.The scope of the article involves the operations, given below, using REST:

Create a new SharePoint Group.
Fetch a particular Security Group Properties.
Update the Group Properties.
Delete an existing security Group.

Create SharePoint Security Group

We can create a SharePoint group by issuing a POST AJAX request. The REST URL endpoint used for the operation is:

/_api/web/sitegroups

We will be creating a key value pair of the information, which will be used to create the Sharepoint group. The group creation information property is shown below. It will send as JSON in the ‘data’ attribute of the AJAX REST call.

var metadata = {
'__metadata': {
'type': 'SP.Group'
},
'Title': 'Employee Group',
'Description': 'This is a new Employees group'
}

Within the _metadata attribute, we have to specify the value for ‘type’, which will specify what object is being created. In our case, it is a group. Hence, we will be specifying ‘SP.Group’.The header section will look like:

headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"content-Type": "application/json;odata=verbose"
},

Here ‘accept’ attribute specifies the data type for the return value and ‘content-type’ defines the data type for the data required to be sent to the Server. In POST request, we have to send the X-RequestDigest value along with the request for form validation without which we will get a validation error. To fulfil it, we will be assigning the $("#__REQUESTDIGEST"). val() sets the value of the form digest control , present within the page to X-RequestDigest key.

Output

The console output shows a custom successful group creation message, as shown below:

Output

Going to the ‘People and Groups’ page, we can see the newly created group.

Full Code

The full code for the group creation operation is given below:

<script language="javascript" type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script>
<script language="javascript" type="text/javascript">
$(document).ready(function() {
var newGroupUrl = "/_api/web/sitegroups";
var metadata = {
'__metadata': {
'type': 'SP.Group'
},
'Title': 'Employee Group',
'Description': 'This is a new Employees group'
}
addNewGroup(newGroupUrl, metadata)
});
function addNewGroup(newGroupUrl, metadata) {
$.ajax({
url: _spPageContextInfo.webAbsoluteUrl + newGroupUrl,
type: "POST",
headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"content-Type": "application/json;odata=verbose"
},
data: JSON.stringify(metadata),
success: function(data) {
console.log(data);
console.log("The group has been created successfully.");
},
error: function(error) {
alert(JSON.stringify(error));
}
});
}
</script>

Retrieve Group Properties

In order to get the property values of the group, we can issue a GET request to the SharePoint Group. The REST URL endpoint is used for AJAXrequest will be of the format :

/_api/web/sitegroups/getbyname('Employee Group')

The method used to send the request will be a GET request. In the headers attribute, we specify the type of return data expected, which is JSON here.The result returned will be parsed in the success call back function.The header of AJAX GET request will be plain and simple, as shown below:

headers: {
"accept": "application/json;odata=verbose",
},

Output

We are trying to retrieve the Group owner property and the value for the property “OnlyAllowMembersViewMembership”, which has come up in the console. Similarly, the other properties can be parsed.

Output

Full Code

The full code for the retrieve operation is given below:

<script language="javascript" type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script>
<script language="javascript" type="text/javascript">
$(document).ready(function() {
var newGroupUrl = "/_api/web/sitegroups/getbyname('Employee Group')";
retrieveGroup(newGroupUrl)
});
function retrieveGroup(newGroupUrl) {
$.ajax({
url: _spPageContextInfo.webAbsoluteUrl + newGroupUrl,
type: "GET",
headers: {
"accept": "application/json;odata=verbose",
},
success: function(data) {
console.log("The group owner is :" + data.d["OwnerTitle"]);
console.log("OnlyAllowMembersViewMembership ? " + data.d["OnlyAllowMembersViewMembership"]);
},
error: function(error) {
alert(JSON.stringify(error));
}
});
}
</script>

Update the Group properties

The Group properties can be updated by issuing AJAX MERGE call, using the REST URL endpoint:
/_api/web/sitegroups/getbyname('Employee Group')

The information to update the group property can be assigned to the metadata key and assigned to ‘data’ attribute of the AJAX call.

var metadata = {
__metadata: {
'type': SP.Group '},
OnlyAllowMembersViewMembership: false
};

Here, we are updating the “OnlyAllowMembersViewMembership” property of the group to ‘False’, which was earlier ‘True’. The header section looks similar to the previous operations.

headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"content-Type": "application/json;odata=verbose",
},

Output

Thus, the successful group updating message has come up in the console.

Output

Going to the group settings page, the property value for “OnlyAllowMembersViewMembership” has been changed from “Group Members” to “Everyone”, based on the script.

Full Code

The full code for the update operation is given below:

<script language="javascript" type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script>
<script language="javascript" type="text/javascript">
$(document).ready(function() {
var newGroupUrl = "/_api/web/sitegroups/getbyname('Employee Group')";
var metadata = {
__metadata: {
'type': 'SP.Group'
},
OnlyAllowMembersViewMembership: false
};
updateGroup(newGroupUrl, metadata)
});
function updateGroup(newGroupUrl, metadata) {
$.ajax({
url: _spPageContextInfo.webAbsoluteUrl + newGroupUrl,
type: "MERGE",
data: JSON.stringify(metadata),
headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"content-Type": "application/json;odata=verbose",
},
success: function(data) {
console.log(data);
console.log("Group membership property has been updated.");
},
error: function(error) {
alert(JSON.stringify(error));
}
});
}
</script>

Delete the SharePoint Security Group

In order to delete the SharePoint group, we cannot issue an AJAX DELETE request. Instead, we will make use of the below REST Endpoint and issue a POST request. If we issue a DELETE AJAX request, we will get an error message stating that “Delete” call is not supported with the Groups.

/_api/web/sitegroups/removebyloginname('Employee Group’)

‘RemoveByLoginName’ specifies the name of the group to be deleted. In the header section, we can specify the ‘accept’ and ‘X-RequestDigest’ attribute, which specifies the return data type and the form digest value respectively. The “IF-Match” attribute is used to check concurrency of the group to ensure that the group that is being deleted is really the one, that we intend to delete. We can either specify “*”, which will blindly skip the concurrency check, else we can specify the e-tag value (which can be obtained by issuing a GET request).

Output

On running the script for the group deletion, a success message has come up in the console, as shown below:

Output

Full Code

The full code for the delete operation is given below:

<script language="javascript" type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script>
<script language="javascript" type="text/javascript">
$(document).ready(function() {
var existingGroupUrl = "/_api/web/sitegroups/removebyloginname('Employee Group')";
deleteGroup(existingGroupUrl)
});
function deleteGroup(existingGroupUrl) {
$.ajax({
url: _spPageContextInfo.webAbsoluteUrl + existingGroupUrl,
type: "POST",
headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"IF-MATCH": "*"
},
success: function(data) {
console.log("The group has been successfully deleted.");
},
error: function(error) {
alert(JSON.stringify(error));
}
});
}
</script>

Let’s see how to implement the scripts, shown above, in SharePoint. The steps, given below, will demo, how to add the script for deleting the group. Similarly other scripts can also be tested. Save the script as a text file and upload it to the site assets library.

SharePoint Implementation

Go to the edit settings of SharePoint page and click Web part from the Insert tab
Add Content Editor Web part.
Click Edit Web art from Content Edit Web part. Assign the URL of the script text file and click Apply.
Click Apply and we can see the successful list deletion message from the console.

I had the group settings page opened in the Browser, prior to running the script. Refreshing it gives the error, shown below, stating the removal of the group.

error

Summary

Thus, we have seen how to create a SharePoint Security group, retrieve its properties, update the group properties and finally delete the existing group, using REST API in SharePoint 2016.This will work the same way in Office 365 as well.