Read data access groups from a REDCap project

This function reads all available data access groups from REDCap an returns them as a tibble::tibble().

redcap_dag_read(
  redcap_uri,
  token,
  http_response_encoding = "UTF-8",
  locale = readr::default_locale(),
  verbose = TRUE,
  config_options = NULL,
  handle_httr = NULL
)

Arguments

redcap_uri

The uri/url of the REDCap server typically formatted as "https://server.org/apps/redcap/api/". Required.

token

The user-specific string that serves as the password for a project. Required.

http_response_encoding

The encoding value passed to httr::content(). Defaults to 'UTF-8'.

locale

a readr::locale() object to specify preferences like number, date, and time formats. This object is passed to readr::read_csv(). Defaults to readr::default_locale().

verbose

A boolean value indicating if messages should be printed to the R console during the operation. The verbose output might contain sensitive information (e.g. PHI), so turn this off if the output might be visible somewhere public. Optional.

config_options

A list of options passed to httr::POST(). See details at httr::httr_options(). Optional.

handle_httr

The value passed to the handle parameter of httr::POST(). This is useful for only unconventional authentication approaches. It should be NULL for most institutions. Optional.

Value

Currently, a list is returned with the following elements:

• data: A tibble::tibble() of all data access groups of the project.

• success: A boolean value indicating if the operation was apparently successful.

• status_codes: A collection of http status codes, separated by semicolons. There is one code for each batch attempted.

• outcome_messages: A collection of human readable strings indicating the operations' semicolons. There is one code for each batch attempted. In an unsuccessful operation, it should contain diagnostic information.

• elapsed_seconds: The duration of the function.

References

The official documentation can be found on the 'API Help Page' and 'API Examples' pages on the REDCap wiki (i.e., https://community.projectredcap.org/articles/456/api-documentation.html and https://community.projectredcap.org/articles/462/api-examples.html). If you do not have an account for the wiki, please ask your campus REDCap administrator to send you the static material.

Author

Jonathan M. Mang

Examples

# \dontrun{
uri     <- "https://bbmc.ouhsc.edu/redcap/api/"
token   <- "9A81268476645C4E5F03428B8AC3AA7B"
REDCapR::redcap_dag_read(redcap_uri=uri, token=token)$data
#> 2 data access groups were read from REDCap in 0.2 seconds.  The http status code was 200.
#> # A tibble: 2 × 3
#>   data_access_group_name unique_group_name data_access_group_id
#>   <chr>                  <chr>                            <dbl>
#> 1 dag_1                  dag_1                               36
#> 2 dag_2                  dag_2                               37
# }