feat: filter users by account_status, user_role

NEWS.md

@@ -1,5 +1,11 @@
 # connectapi (development version)
 
+## New features
+
+- `get_users()` now supports filtering users with the `account_status` and
+  `user_role` parameters. For example, this allows you to find all licensed
+  users on a Connect server. (#311)
+
 # connectapi 0.4.0
 
 ## New features

R/connect.R

@@ -506,12 +506,28 @@ Connect <- R6::R6Class(
     #' @param page_number The page number.
     #' @param prefix The search term.
     #' @param page_size The page size.
-    users = function(page_number = 1, prefix = NULL, page_size = 500) {
+    #' @param user_role Filter by user role.
+    #' @param account_status Filter by account status.
+    users = function(
+      page_number = 1,
+      prefix = NULL,
+      page_size = 500,
+      user_role = NULL,
+      account_status = NULL
+    ) {
       path <- v1_url("users")
+      if (!is.null(user_role)) {
+        user_role <- paste(user_role, collapse = "|")
+      }
+      if (!is.null(account_status)) {
+        account_status <- paste(account_status, collapse = "|")
+      }
       query <- list(
         page_number = page_number,
         page_size = valid_page_size(page_size),
-        prefix = prefix
+        prefix = prefix,
+        user_role = user_role,
+        account_status = account_status
       )
       self$GET(path, query = query)
     },

R/get.R

@@ -5,6 +5,13 @@
 #' @param prefix Filters users by prefix (username, first name, or last name).
 #' The filter is case insensitive.
 #' @param limit The max number of records to return
+#' @param user_role Optionally filter by user role ("administrator",
+#' "publisher", "viewer"). Pass in a vector of multiple roles to match any value
+#' (boolean OR). When `NULL` (the default), results are not filtered.
+#' @param account_status Optionally filter by account status ("locked",
+#' "licensed", "inactive"). Pass a vector of multiple statuses to match any
+#' value (boolean OR). When `NULL` (the default), results are not filtered.
+
 #'
 #' @return
 #' A tibble with the following columns:
@@ -34,17 +41,35 @@
 #' library(connectapi)
 #' client <- connect()
 #'
-#' # get all users
-#' get_users(client, limit = Inf)
+#' # Get all users
+#' get_users(client)
+#'
+#' # Get all licensed users
+#' get_users(client, account_status = "licensed")
+#'
+#' # Get all users who are administrators or publishers
+#' get_users(client, user_role = c("administrator", "publisher"))
 #' }
 #'
 #' @export
-get_users <- function(src, page_size = 500, prefix = NULL, limit = Inf) {
+get_users <- function(
+  src,
+  page_size = 500,
+  prefix = NULL,
+  limit = Inf,
+  user_role = NULL,
+  account_status = NULL
+) {
   validate_R6_class(src, "Connect")
 
   res <- page_offset(
     src,
-    src$users(page_size = page_size, prefix = prefix),
+    src$users(
+      page_size = page_size,
+      prefix = prefix,
+      user_role = user_role,
+      account_status = account_status
+    ),
     limit = limit
   )
 

tests/integrated/test-get.R

@@ -14,6 +14,14 @@ test_that("get_users works", {
     purrr::map_chr(vctrs::vec_ptype(users), typeof),
     purrr::map_chr(vctrs::vec_ptype(connectapi_ptypes$users), typeof)
   )
+
+  # Other tests create users, so specifying the exact number here is conditional
+  # on the contents of other tests and the order that tests run in.
+  admins <- get_users(test_conn_1, user_role = "administrator")
+  expect_true(nrow(admins) > 0)
+
+  licensed <- get_users(test_conn_1, account_status = "licensed")
+  expect_true(nrow(licensed) > 0)
 })
 
 test_that("get_groups works", {

tests/testthat/test-get.R

@@ -140,3 +140,33 @@ with_mock_api({
     expect_identical(result$name, c("connect_dev", "cool_kids_of_the_dmv"))
   })
 })
+
+without_internet({
+  client <- Connect$new(server = "https://connect.example", api_key = "fake")
+  test_that("get_users() works with user_role and account_status", {
+    # No filter parameters specified
+    expect_GET(
+      get_users(client),
+      "https://connect.example/__api__/v1/users?page_number=1&page_size=500"
+    )
+
+    # Filter just on one parameter
+    expect_GET(
+      get_users(client, user_role = "administrator"),
+      "https://connect.example/__api__/v1/users?page_number=1&page_size=500&user_role=administrator"
+    )
+
+    # Filter on two parameters, one requiring concatenation
+    expect_GET(
+      get_users(
+        client,
+        user_role = c("administrator", "publisher"),
+        account_status = "licensed"
+      ),
+      paste0(
+        "https://connect.example/__api__/v1/users?page_number=1&page_size=500&",
+        "user_role=administrator%7Cpublisher&account_status=licensed"
+      )
+    )
+  })
+})