findUsersByQuery method

Future<PageBeanUser> findUsersByQuery({
  1. required String query,
  2. int? startAt,
  3. int? maxResults,
})

Finds users with a structured query and returns a paginated list of user details.

This operation takes the users in the range defined by startAt and maxResults, up to the thousandth user, and then returns only the users from that range that match the structured query. This means the operation usually returns fewer users than specified in maxResults. To get all the users who match the structured query, use Get all users and filter the records in your code.

Permissions required: Browse users and groups global permission.

The query statements are:

  • is assignee of PROJ Returns the users that are assignees of at least one issue in project PROJ.
  • is assignee of (PROJ-1, PROJ-2) Returns users that are assignees on the issues PROJ-1 or PROJ-2.
  • is reporter of (PROJ-1, PROJ-2) Returns users that are reporters on the issues PROJ-1 or PROJ-2.
  • is watcher of (PROJ-1, PROJ-2) Returns users that are watchers on the issues PROJ-1 or PROJ-2.
  • is voter of (PROJ-1, PROJ-2) Returns users that are voters on the issues PROJ-1 or PROJ-2.
  • is commenter of (PROJ-1, PROJ-2) Returns users that have posted a comment on the issues PROJ-1 or PROJ-2.
  • is transitioner of (PROJ-1, PROJ-2) Returns users that have performed a transition on issues PROJ-1 or PROJ-2.
  • [propertyKey].entity.property.path is "property value" Returns users with the entity property value.

The list of issues can be extended as needed, as in (PROJ-1, PROJ-2, ... PROJ-n). Statements can be combined using the AND and OR operators to form more complex queries. For example:

is assignee of PROJ AND [propertyKey].entity.property.path is "property value"

Implementation

Future<PageBeanUser> findUsersByQuery(
    {required String query, int? startAt, int? maxResults}) async {
  return PageBeanUser.fromJson(await _client.send(
    'get',
    'rest/api/3/user/search/query',
    queryParameters: {
      'query': query,
      if (startAt != null) 'startAt': '$startAt',
      if (maxResults != null) 'maxResults': '$maxResults',
    },
  ));
}