SP.RoleAssignmentCollection.add(principal, roleBindings) Method

Article
07/24/2014

Applies to: SharePoint Foundation 2010

In this article
Return Value
Remarks
Applies To

Adds a new role assignment with the specified principal and role definitions to the collection.

var value = SP.RoleAssignmentCollection.add(principal, roleBindings);

Parameters

principal
A user or group that can be assigned permissions in Microsoft SharePoint Foundation to control security.

Type: SP.Principal

roleBindings
The role definitions that are bound to the role assignment object.

Type: SP.RoleDefinitionBindingCollection

Return Value

Type: SP.RoleAssignment

The role assignment for a user or group.

Remarks

This method creates a new role assignment from the specified principal and role definitions, adds the new role assignment to the collection, and returns the new role assignment object.

Applies To

SP.RoleAssignmentCollection Class

Exceptions

InvalidOperationException
The parent securable object does not have unique permissions.

UnauthorizedAccessException
The current user does not have sufficient permissions to manage permissions on the parent securable object.

Example

The following example creates an input button on an application page that creates a new permission level and adds a user to a specific list with that permission level.

<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
<script type="text/ecmascript" language="ecmascript">

   function runCode() {

       var clientContext = new SP.ClientContext();
       var siteColl = clientContext.get_site();
       var site = clientContext.get_web();

       // Set up permissions.
       var permissions = new SP.BasePermissions();
       permissions.set(SP.PermissionKind.viewListItems);
       permissions.set(SP.PermissionKind.addListItems);
       permissions.set(SP.PermissionKind.editListItems);
       permissions.set(SP.PermissionKind.deleteListItems);

       // Create a new role definition.
       var roleDefinitionCreationInfo = new SP.RoleDefinitionCreationInformation();
       roleDefinitionCreationInfo.set_name('Manage List Items');
       roleDefinitionCreationInfo.set_description('Allows a user to manage list items');
       roleDefinitionCreationInfo.set_basePermissions(permissions);
       var roleDefinition = siteColl.get_rootWeb().get_roleDefinitions().add(roleDefinitionCreationInfo);

       // Create a new RoleDefinitionBindingCollection.
       var newBindings = SP.RoleDefinitionBindingCollection.newObject(clientContext);
       // Add the role to the collection.
       newBindings.add(roleDefinition);

       // Get the list to work with and break permissions so its permissions can be managed directly.
       var targetList = site.get_lists().getByTitle('Announcements');
       targetList.breakRoleInheritance(true, false);

       // Get the RoleAssignmentCollection for the target list.
       var assignments = targetList.get_roleAssignments();
       // Add the user to the target list and assign the use to the new RoleDefinitionBindingCollection.
       var roleAssignment = assignments.add(site.get_currentUser(), newBindings);
       clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded),Function.createDelegate(this, this.onQueryFailed));
   }

   function onQuerySucceeded() {
       alert('Security modified');
   }

   function onQueryFailed(sender, args) {
       alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
   }

</script>

    <input id="Button1" type="button" value="Run Code" onclick="runCode()" />

</asp:Content>