% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/user_list.R
\name{user_list}
\alias{user_list}
\title{List all users.}
\usage{
user_list(
  qry = NULL,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  orders = get_default_orders(),
  tz = get_default_tz(),
  verbose = get_ru_verbose()
)
}
\arguments{
\item{qry}{A query string to filter users by. The query string is not case
sensitive and can contain special characters, such as \code{@}.

The query string must be at least 5 alphabetic characters long to
return good enough matches.
E.g. \code{janet} will match a user with display name \verb{Janette Doe}.
E.g., \verb{@dbca.wa} will match users with an email from \code{dbca.wa.gov.au},
whereas \verb{@dbca.w} or \verb{@dbca} will return no matches.

Default: \code{NULL}.}

\item{url}{The ODK Central base URL without trailing slash.

Default: \code{\link{get_default_url}}.

Set default \code{url} through \code{ru_setup(url="...")}.

See \code{vignette("Setup", package = "ruODK")}.}

\item{un}{The ODK Central username (an email address).
Default: \code{\link{get_default_un}}.
Set default \code{un} through \code{ru_setup(un="...")}.
See \code{vignette("Setup", package = "ruODK")}.}

\item{pw}{The ODK Central password.
Default: \code{\link{get_default_pw}}.
Set default \code{pw} through \code{ru_setup(pw="...")}.
See \code{vignette("Setup", package = "ruODK")}.}

\item{retries}{The number of attempts to retrieve a web resource.

This parameter is given to \code{\link[httr]{RETRY}(times = retries)}.

Default: 3.}

\item{orders}{(vector of character) Orders of datetime elements for
lubridate.

Default:
\code{c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd")}.}

\item{tz}{A timezone to convert dates and times to.

Read \code{vignette("setup", package = "ruODK")} to learn how \code{ruODK}'s
timezone can be set globally or per function.}

\item{verbose}{Whether to display debug messages or not.

Read \code{vignette("setup", package = "ruODK")} to learn how \code{ruODK}'s
verbosity can be set globally or per function.}
}
\value{
A tibble with user details as per the ODK Central API docs.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#maturing}{\figure{lifecycle-maturing.svg}{options: alt='[Maturing]'}}}{\strong{[Maturing]}}
}
\details{
Currently, there are no paging or filtering options, so listing Users will
get you every User in the system, every time.
Optionally, a q query string parameter may be provided to filter the returned
users by any given string.
The search is performed via a trigram similarity index over both the Email
and Display Name fields, and results are ordered by match score, best matches
first.
If a q parameter is given, and it exactly matches an email address that
exists in the system, that user's details will always be returned,
even for actors who cannot user.list.
The request must still authenticate as a valid Actor.
This allows non-Administrators to choose a user for an action
(e.g. grant rights) without allowing full search.

Actors who cannot \code{user.list} will always receive [] with a 200 OK response.
ruODK does not (yet) warn if this is the case, and you (the requesting Actor)
have no permission to \code{user.list}.
}
\examples{
\dontrun{
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...")

# All users
ul <- user_list()

# Search users
# Given a user with display name "Janette Doe" and email "@org.com.au"
user_list(qry = "jan") # no results, query string too short
user_list(qry = "jane") # no results, query string too short
user_list(qry = "janet") # returns Janette
user_list(qry = "@org") # no results, query string too short
user_list(qry = "@org.c") # no results, query string too short
user_list(qry = "@org.co") # returns all users matching "@org.co"

# Actor not allowed to user.list
user_list() # If this is empty, you might not have permissions to list users
}
}
\seealso{
\url{https://docs.getodk.org/central-api-accounts-and-users/#listing-all-users}

\url{https://www.postgresql.org/docs/9.6/pgtrgm.html}
}
\concept{user-management}
