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

Objective-CSwift

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

Objective-CSwift

[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

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:

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

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:

Retrieving Related Data

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.

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.

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

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

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.