Skip to content

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

- (void)findByRoleWithRoleName:(NSString *)roleName responseHandler:^(NSArray<BackendlessUser *> *)responseHandler errorHandler:^(Fault *)errorHandler;

- (void)findByRoleWithRoleName:(NSString *)roleName loadRoles:(BOOL)loadRoles responseHandler:^(NSArray<BackendlessUser *> *)responseHandler errorHandler:^(Fault *)errorHandler;

- (void)findByRoleWithRoleName:(NSString *)roleName queryBuilder:(DataQueryBuilder *)queryBuilder responseHandler:^(NSArray<BackendlessUser *> *)responseHandler errorHandler:^(Fault *)errorHandler;

- (void) findByRoleWithRoleName:(NSString *)roleName loadRoles:(BOOL)loadRoles queryBuilder:(DataQueryBuilder *)queryBuilder responseHandler:^(NSArray *)responseHandler errorHandler:^(Fault *)errorHandler;
func findByRole(roleName: String, responseHandler: (([BackendlessUser]) -> Void)!, errorHandler: ((Fault) -> Void)!)

func findByRole(roleName: String, loadRoles: Bool, responseHandler: (([BackendlessUser]) -> Void)!, errorHandler: ((Fault) -> Void)!)

func findByRole(roleName: String, queryBuilder: DataQueryBuilder, responseHandler: (([BackendlessUser]) -> Void)!, errorHandler: ((Fault) -> Void)!)

func findByRole(roleName: String, loadRoles: Bool, queryBuilder: DataQueryBuilder, responseHandler: (([BackendlessUser]) -> Void)!, errorHandler: ((Fault) -> Void)!)

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.
responseHandler Handles successful result of an asynchronous call.
errorHandler Handles fault result of an asynchronous call.

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".

[Backendless.shared.userService findByRoleWithRoleName:@"TrialUser" responseHandler:^(NSArray<BackendlessUser *> *users) {
    NSLog(@"Users with specified role: %@", users);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

[Backendless.shared.userService findByRoleWithRoleName:@"TrialUser" loadRoles:true responseHandler:^(NSArray<BackendlessUser *> *users) {
    NSLog(@"Users with specified role: %@", users);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

DataQueryBuilder *queryBuilder = [DataQueryBuilder new];
queryBuilder.properties = @[@"propertyName1", @"propertyName2"'];    
[Backendless.shared.userService findByRoleWithRoleName:@"TrialUser" queryBuilder:queryBuilder responseHandler:^(NSArray<BackendlessUser *> *users) {
    NSLog(@"Users with specified role: %@", users);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

DataQueryBuilder *queryBuilder = [DataQueryBuilder new];
queryBuilder.properties = @[@"propertyName1", @"propertyName2"'];
[Backendless.shared.userService findByRoleWithRoleName:@"TrialUser" loadRoles:true queryBuilder:queryBuilder responseHandler:^(NSArray<BackendlessUser *> *users) {
    NSLog(@"Users with specified role: %@", users);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
Backendless.shared.userService.findByRole(roleName: "TrialUser", responseHandler: { users in
    print("Users with specified role: \(users)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

Backendless.shared.userService.findByRole(roleName: "TrialUser", loadRoles: true, responseHandler: { users in
    print("Users with specified role: \(users)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

let queryBuilder = DataQueryBuilder()
queryBuilder.properties = ["propertyName1", "propertyName2"]    
Backendless.shared.userService.findByRole(roleName: "TrialUser", queryBuilder: queryBuilder, responseHandler: { users in
    print("Users with specified role: \(users)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

let queryBuilder = DataQueryBuilder()
queryBuilder.properties = ["propertyName1", "propertyName2"]    
Backendless.shared.userService.findByRole(roleName: "TrialUser", loadRoles: true, queryBuilder: queryBuilder, responseHandler: { users in
    print("Users with specified role: \(users)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

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.