SP.SecurableObject.breakRoleInheritance(copyRoleAssignments, clearSubscopes) Method

Applies to: SharePoint Foundation 2010

Creates unique role assignments for the securable object.

SP.SecurableObject.breakRoleInheritance(copyRoleAssignments, clearSubscopes);

Parameters

• copyRoleAssignments
  Specifies whether to copy the role assignments from the parent securable object.

  If the value is false, the collection of role assignments must contain only 1 role assignment containing the current user after the operation.

Type: Boolean

• clearSubscopes
  If the securable object is a site, and the clearsubscopes parameter is true, the role assignments for all child securable objects in the current site and in the sites which inherit role assignments from the current site must be cleared and those securable objects will inherit role assignments from the current site after this call.

  If the securable object is a site, and the clearsubscopes parameter is false, the role assignments for all child securable objects which do not inherit role assignments from their parent object must remain unchanged.

  If the securable object is not a site, and the clearsubscopes parameter is true, the role assignments for all child securable objects must be cleared and those securable objects will inherit role assignments from the current securable object after this call.

  If the securable object is not a site, and the clearsubscopes parameter is false, the role assignments for all child securable objects which do not inherit role assignments from their parent object must remain unchanged.

Type: Boolean

Applies To

SP.SecurableObject Class

Exceptions

• [Microsoft.SharePoint.SPException]
  The current site is the top-level site. Error code: -2146232832.

• [System.InvalidOperationException]
  There are uncommitted changes for the current site. Error code: -1.

• [System.UnauthorizedAccessException]
  The current user has insufficient permissions. Error code: -2147024891.

Remarks

If the securable object already has unique role assignments, the server must not alter any role assignments.

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 a securable object to work with (the Announcements list), and use the SecurableObject.BreakPermissions method to break permissions so they can be managed directly.
       var listSecurableObject = site.get_lists().getByTitle('Announcements');
       listSecurableObject.breakRoleInheritance(true, false);

       // Use the SecurableObject.roleAssignments property to get the RoleAssignmentCollection for the list.
       var assignments = listSecurableObject.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>

See Also

Reference

SP.SecurableObject Methods

SP.SecurableObject Properties

SP Namespace