HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket


Roles provide a means of labeling or categorizing members within your digital community. They are defined, within your application, as you see fit. They may be assigned to members of a group or span multiple groups.

Roles do not bestow any particular permission, status, or responsibility. This leaves your application free to apply meaning to roles as appropriate.

In the Optimizely Community API, a role is represented with the `Role` class.

Roles are managed through a service implementing the interface `IRoleService`. This service provides the ability to persist, retrieve, assign, and remove `Roles` that you define.

## Access an IRoleService

When the `Groups` feature is installed to an Optimizely Content Management System (CMS) site, with the feature's site integration package, you can get an instance of this service from the inversion of control (IoC) container.

Example:



When the feature is installed to a non-Optimizely CMS site, you can get an instance of a service from the default `factory` class provided within the package.

Example:



## Add a role

To add a role, use the `Add(Role)` method of the `IRoleService`. This method accepts an instance of the `Role` class and returns a reference to a new instance of that class, which is populated with any additional, system-generated, data (for example, a unique ID).



In the above example, the request to add a role is invoked synchronously. An example of adding a role asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Remove a role

To remove a specific instance of `Role`, which was previously added through the platform, use the `Remove(RoleId)` method. This method accepts an instance of the `RoleId` class, which identifies the `RoleId` to be removed. The result is the deletion of the `Role` corresponding to that ID.



In the above example, the request to remove a role is invoked synchronously. An example of removing a role asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Retrieve a role

To retrieve a specific instance of a `Role`, which was previously added through the platform, use the `Get(RoleId)` method of `IRoleService`. This method accepts an instance of the `RoleId` class, which identifies the `Role` to retrieve. It returns the instance of the `Role` class corresponding to that identifier.



If the requested `Role` cannot be found, a `RoleDoesNotExistException` is thrown.

In the above example, the request to retrieve a role is invoked synchronously. An example of retrieving a role asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



To retrieve a collection of roles, which were previously added through the platform, use the `Get(Criteria<RoleFilter>)` method. This method accepts an instance of `Criteria<RoleFilter>`, which contains specifications necessary to retrieve the desired roles.

The `Filter` property of the `Criteria<RoleFilter>` class accepts an instance of the `RoleFilter` class. This class contains the specifications, which let you refine the result set of roles you want to retrieve.

The properties of the `RoleFilter` include:

  • `Name` – Assigning a value (`String`) to this property refines a result set to Roles with the specified name.

  • `RoleIds` – Assigning a value (`IEnumerable<RoleId>`) to this property refines a result set to Roles that are identified in that collection.

The specifications of the `RoleFilter` may be applied in conjunction with one another. Each specification, which is assigned a value in the filter, further refines the result set (that is, a logical AND).

The example below demonstrates the retrieval of a result page of Roles with the name "Moderator":



In the above examples, the request to retrieve roles is invoked synchronously. An example of retrieving roles asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



The `RoleSortFields` class exposes a set of fields upon which a result set of roles may be ordered. You can apply these fields to construct sorting rules that you associate with your criteria. These fields include:

  • `RoleSortFields.Id`

  • `RoleSortFields.Name`

The example below demonstrates how to apply sorting rules to order your result set by name, alphabetically from A-Z.



For more details regarding the use of criteria, including information on paging and sorting, see _Criteria_ in [Discovering the platform](🔗).

## Assign a role

You can assign a role, which was previously added through the platform, to an existing member by using the `Assign(RoleAssignment)` method of the `IRoleService`. This method accepts an instance of the `RoleAssignment` class, which identifies the target member and the role to be assigned.



If the identified `Role` cannot be found, a `RoleDoesNotExistException` is thrown.

If the identified `Member` cannot be found, a `MemberDoesNotExistException` is thrown.

In the above example, the request to assign a role to a member is invoked synchronously. An example of assigning a role to a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Unassign a role

To unassign a role from a member, which was previously assigned through the platform, use the `Unassign(RoleAssignment)` method of the `IRoleService`. This method accepts an instance of the `RoleAssignment` class, which describes the role assignment to be removed.



If the identified `Role` cannot be found, a `RoleDoesNotExistException` is thrown.

If the identified `Member` cannot be found, a `MemberDoesNotExistException` is thrown.

In the above example, the request to unassign a role from a member is invoked synchronously. An example of unassigning a role from a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Validate a role assignment

To validate that a role was assigned to a member, use the `IsAssigned(RoleAssignment)` of the `IRoleService`. This method accepts an instance of the `RoleAssignment` class, describing the assignment to be validated. The method returns a Boolean indicating whether or not the identified role was assigned to the identified member.



In the above example, the request to validate if a member is assigned a role is invoked synchronously. An example of validating a role for a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Extend roles with composites

A role is simply a label, which may be applied to members within your application. You may need to associate additional information with roles to further describe and shape them. Consider the following examples:

  • A role in your application is intended to confer permission or privilege. You might want to associate information describing access rules with it.

  • Your application gamifies status within a group. You might want to associate scoring information with a role.

Just as you can extend a `Group` with data of your design, a `Role` may also be extended by creating a `Composite`. For an introduction to Composites, see _Composites_ in [Discovering the platform](🔗).

### Add a composite role

To save a Composite Role, which you have defined, use the `Add<TExtension>(Role, TExtension)` method of the `IRoleService`. This method accepts an instance of the `Role` class and an instance of `TExtension`. It returns a new instance of `Composite\<Role,TExtension>`.

Consider the following class, which represents a sample of extension data:



In the example below, a `Role` is composed with an instance of this extension class:



In the above example, the request to add a role is invoked synchronously. An example of adding a role asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Update a composite role

To update a specific instance of a Composite Role, which was previously added through the platform, use the `Update<TExtension>(RoleId, TExtension)` method of the `IRoleService`. This method accepts an instance of the `RoleId` class and an instance of `TExtension`. It returns a new instance of `Composite\<Role,TExtension>`.

Consider the following class, which represents a sample of extension data:



In the example below, assume that the `roleService` and `existingRoleId` have been properly instantiated.



In the above example, the request to update a role is invoked synchronously. An example of updating a role asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Retrieve a composite role

To retrieve a specific instance of a Composite Role, which was previously added through the platform, use the `Get<TExtension>(RoleId)` method. This method accepts an instance of the `RoleId` class, which identifies the `Role` to retrieve. It returns the instance of the `Composite\<Role,TExtension>` class corresponding to that identifier.



If a Composite Role with the specified ID and extension type cannot be found, a `RoleDoesNotExistException` is thrown.

In the above example, the request to retrieve a role is invoked synchronously. An example of retrieving a role asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



To retrieve a collection of Composite Roles, which were previously added through the platform, use the `Get<TExtension>(CompositeCriteria\<RoleFilter,TExtension>)` method. This method accepts an instance of `CompositeCriteria\<RoleFilter,TExtension>`, which contains specifications to retrieve the desired `Roles`.

The `Filter` property of the `CompositeCriteria[RoleFilter,TExtension]` class accepts an instance of the `RoleFilter` class. This class contains the specifications which let you refine the result set of `Roles` you want to retrieve.

The `ExtensionFilter` property of the `CompositeCriteria\<RoleFilter,TExtension>` class accepts a `FilterExpression` that lets you specify a Boolean expression to further refine the result set by values represented within your extension data.

Consider the following class, which represents a sample of extension data:



In the example below, a page of `Roles` composed with `TeamStatus` is retrieved, where the status is worth more than 50 points:



In the above example, the request to retrieve roles is invoked synchronously. An example of retrieving roles asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



The fields of your extension data may also be applied when sorting a result set. The example below demonstrates the use of an extension data field in defining a sorting rule.