How to: Work with Roles Using JavaScript

Article
10/20/2016

Applies to: SharePoint Foundation 2010

Through the client object model, you can create custom role definitions within site collections, and you can assign new or existing users and groups to specific roles for websites, lists, and list items. Similar to the way you use the SPRoleDefinitionBindingCollection class in the server object model, you add a user or group, together with a RoleDefinitionBindingCollection object, to the collection of role assignments for a specific object.

Creating a Role Definition Using JavaScript

To create a role definition in the collection of role definitions for a site collection using ECMAScript (JavaScript, JScript), use the BasePermissions object to define a permission set, use the RoleDefinitionCreationInformation object to define a role that includes the permission set, and then add the new role to the collection of role definitions. The following example shows how to create a role for creating and managing alerts. The order property specifies that the new role be displayed fourth in order among custom role definitions listed on the Permissions Levels page of the site collection.

siteUrl = '/sites/MySiteCollection';

function createRoleDefinition() {

    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();

    var permissions = new SP.BasePermissions();
    permissions.set(SP.PermissionKind.createAlerts);
    permissions.set(SP.PermissionKind.manageAlerts);

    var roleCreationInfo = new SP.RoleDefinitionCreationInformation();
    roleCreationInfo.set_basePermissions(permissions);
    roleCreationInfo.set_description('A new role with create and manage alerts permission');
    roleCreationInfo.set_name('Create and Manage AlertsT');
    roleCreationInfo.set_order(4);

    this.oRoleDefinition = oWebsite.get_roleDefinitions().add(roleCreationInfo);

    clientContext.load(oRoleDefinition);

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded() {

    var roleInfo = oRoleDefinition.get_name() + ' role created.';
    alert(roleInfo);
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Assigning a User to a Role on a Website Using JavaScript

To assign a user to a particular role on a website, you create a RoleDefinitionBindingCollection object for the website context, add a role definition to the binding collection object, and then use the add(principal, roleBindings) function to add the user together with the binding collection to the role assignments for the website. The following example assigns an existing site collection user to the role that was defined in the previous example.

siteUrl = '/sites/MySiteCollection/MyWebSite';

function addUserToRole() {

    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();

    this.oUser = oWebsite.get_siteUsers().getByLoginName('DOMAIN\\alias');
    this.oRoleDefinition = oWebsite.get_roleDefinitions().getByName('Create and Manage Alerts');

    var collRoleDefinitionBinding = SP.RoleDefinitionBindingCollection.newObject(clientContext);        

    collRoleDefinitionBinding.add(oRoleDefinition);

    var oRoleAssignment = oWebsite.get_roleAssignments().add(oUser, collRoleDefinitionBinding);

    clientContext.load(oUser, 'Title');
    clientContext.load(oRoleDefinition, 'Name');

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded() {

    var roleInfo = oUser.get_title() + ' assigned to ' + oRoleDefinition.get_name();
    alert(roleInfo);
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Creating a SharePoint Group and Adding the Group to a Role Using JavaScript

In the same way that you create most other objects through the client object model, use the GroupCreationInformation object to define a new group, and then use the add(parameters) function to add the group to the collection of site groups in a site collection. And just as you assign users to a role, you assign a group to a particular role on a website by creating a RoleDefinitionBindingCollection object for the website context, adding a role definition to the binding collection object, and then using the add(principal, roleBindings) function to add the group together with the binding collection to the role assignments for the website. The following example creates a group and assigns it the Contribute role on the website.

var siteUrl = '/sites/MySiteCollection/MyWebSite';

function createGroupAddToRole() {

    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

    var groupCreationInfo = new SP.GroupCreationInformation();
    groupCreationInfo.set_title('My New GroupT');
    groupCreationInfo.set_description('Description of new group.');
    this.oGroup = oWebsite.get_siteGroups().add(groupCreationInfo);

    var collRoleDefinitionBinding = SP.RoleDefinitionBindingCollection.newObject(clientContext);

    this.oRoleDefinition = oWebsite.get_roleDefinitions().getByType(SP.RoleType.contributor);
    collRoleDefinitionBinding.add(oRoleDefinition);

    var collRollAssignment = oWebsite.get_roleAssignments();
    collRollAssignment.add(oGroup, collRoleDefinitionBinding);

    clientContext.load(oGroup, 'Title');
    clientContext.load(oRoleDefinition, 'Name');

    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded), 
        Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded() {

    var roleInfo = oGroup.get_title() + ' created and assigned to ' + oRoleDefinition.get_name();
    alert(roleInfo);
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

How to: Work with Roles Using JavaScript

Creating a Role Definition Using JavaScript

Assigning a User to a Role on a Website Using JavaScript

Creating a SharePoint Group and Adding the Group to a Role Using JavaScript

See Also

Concepts

Other Resources

Additional resources