Retrieving Users By Role¶

Description¶

All users have different roles assigned to them, those can be default system roles assigned by the system and also custom roles. By invoking this operation you can find users by a custom role; the result of this operation is an array of BackendlessUser objects found by a specific role. This operation works only with custom roles, otherwise an error message will be returned in response.

Method¶

Non-blocking Method 1: With the Callback

public void Backendless.UserService.FindByRole( String roleName, Boolean loadRoles, DataQueryBuilder queryBuilder, AsyncCallback<IList<BackendlessUser>> callback )

Non-blocking Method 2:

public async Task<IList<BackendlessUser>> Backendless.UserService.FindByRoleAsync( String roleName, Boolean loadRoles, DataQueryBuilder queryBuilder )

Blocking API

public IList<BackendlessUser> Backendless.UserService.FindByRole( String roleName, Boolean loadRoles, DataQueryBuilder queryBuilder )

where

Argument	Description
`roleName`	is a string name of a particular role. String value.
`loadRoles`	Optional parameter. When set to `true`, each user in a returned value will have a list of roles associated with that user account. Boolean value.
`queryBuilder`	Optional parameter. Must be an instance of `Backendless.DataQueryBuilder`. The returned list of users will satisfy the query.

Refer to the General Object Retrieval API topic to learn more about the queryBuilderobject.

Return Value¶

An array containing multiple BackendlessUser objects.

Example¶

The example below retrieves all users associated with the user role "TrialUser".

Non-Blocking Method 1: With the Callback

Backendless.UserService.FindByRole("TrialUser", loadRoles, queryBuilder, new AsyncCallback<IList<BackendlessUser>>(
  result =>
  {
    foreach (BackendlessUser user in result)
      Console.WriteLine(user.Email); // work with all users who have the specified role.
  },
  fault =>
  {
    Console.WriteLine($"server reported an error: {fault.Message}");
  }
));

Non-Blocking Method 2:

var result = await Backendless.UserService.FindByRoleAsync("TrialUser", loadRoles, queryBuilder);

foreach (BackendlessUser user in result)
        Console.WriteLine(user.Email); // work with all users who have the specified role.

Blocking API

var result = Backendless.UserService.FindByRole("TrialUser", loadRoles, queryBuilder);

foreach (BackendlessUser user in result)
        Console.WriteLine(user.Email); // works with all users who have a specific role.

Codeless Reference¶

user_service_codeless_get_users_by_role

where:

Argument	Description
`role name`	A string name of a particular role.
`load roles`	Optional parameter. When set to `true`, this operation returns a list containing all security roles associated with every returned user.
`relations`	Optional parameter. Sets an array of related columns names. Objects from the related columns are included into the response.
`properties`	Optional parameter. Sets the names of the properties which values to include into the response.
`relations depth`	Optional parameter. Sets the number of "levels" in the hierarchy of related objects to include into the response.
`page size`	Sets the page size - which is the number of objects to return in the response. Maximum value is 100.
`page offset`	Optional parameter. Sets the offset - an index in the server-side storage from where the data objects should be retrieved.

Returns a list containing multiple BackendlessUser objects.

Consider the following records in the Users data table:

user_service_example_get_users_by_role_new_1

Suppose the Alice and Charlie records both have the "TrialUser" role assigned to them; the example below retrieves users by role "TrialUser".

user_service_example_get_users_by_role_new_2

The result of this operation is a list containing two objects, representing the Alice and Charlie records in the data table. These records have the "TrialUser" role assigned to them:

user_service_example_get_users_by_role_new_3

For more details about the related data tables refer to the Relations Overview topic.

Sometimes you may want to retrieve additional data from the related table using the relations property. This argument expects a list containing column(s) that reference records in the related data table.

Consider the following records in the Users data table. Note that the data column is related to the UserData table where additional user information is stored. You need to use relation values stored in the data column in your requests to retrieve additional information from the UserData table.

user_service_codeless_example_get_users_by_role_1

Consider the UserData table below, it is the custom data table where additional information is stored. Every single record in this data table is related(linked) to another record stored in the Users data table presented above.

user_service_codeless_example_get_users_by_role_4

In the context of this example the email column represents the identity. The UserData table contains information stored in the age, address and phone columns.

The example below obtains users from the Users data table that have the "TrialUser" role assigned to them. Pay attention how additional user information is obtained from the custom table called UserData: the relations parameter expects the column name that has relations to the UserData table; In this case the name of the column that has relations is data.

To limit the number of columns returned in the response, you must pass a list to the properties parameter, containing column names that you want to have in the response (e.g. email, name).

user_service_codeless_example_get_users_by_role_2

The output will look as shown below after the Codeless logic runs:
user_service_codeless_example_get_users_by_role_3

As you can see the operation has returned two BackendlessUser objects containing user information. In the "userData" property you can find an object containing additional(related) user information returned from the UserData table.