Export the metadata (as a data dictionary) of a REDCap project
as a tibble::tibble(). Each row in the data dictionary corresponds to
one field in the project's dataset.
Usage
redcap_metadata_read(
redcap_uri,
token,
forms = NULL,
fields = NULL,
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.
- forms
An array, where each element corresponds to the REDCap form of the desired fields. Optional.
- fields
An array, where each element corresponds to a desired project field. Optional.
- 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 athttr::httr_options(). Optional.- handle_httr
The value passed to the
handleparameter ofhttr::POST(). This is useful for only unconventional authentication approaches. It should beNULLfor most institutions. Optional.
Value
Currently, a list is returned with the following elements:
data: An Rtibble::tibble()of the desired fields (as rows).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.forms_collapsed: The desired records IDs, collapsed into a single string, separated by commas.fields_collapsed: The desired field names, collapsed into a single string, separated by commas.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.
Examples
# \dontrun{
uri <- "https://redcap-dev-2.ouhsc.edu/redcap/api/"
# A simple project
token <- "9A068C425B1341D69E83064A2D273A70" # simple
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The data dictionary describing 17 fields was read from REDCap in 0.1 seconds. The http status code was 200.
#> $data
#> # A tibble: 17 × 18
#> field_name form_name section_header field_type field_label
#> <chr> <chr> <chr> <chr> <chr>
#> 1 record_id demographics NA text Study ID
#> 2 name_first demographics Contact Informa… text First Name
#> 3 name_last demographics NA text Last Name
#> 4 address demographics NA notes Street, Ci…
#> 5 telephone demographics NA text Phone numb…
#> 6 email demographics NA text E-mail
#> 7 dob demographics NA text Date of bi…
#> 8 age demographics NA text Age (years)
#> 9 sex demographics NA radio Gender
#> 10 height health NA text Height (cm)
#> 11 weight health NA text Weight (ki…
#> 12 bmi health NA calc BMI
#> 13 comments health General Comments notes Comments
#> 14 mugshot health NA file Mugshot
#> 15 race race_and_ethnicity NA checkbox Race (Sele…
#> 16 ethnicity race_and_ethnicity NA radio Ethnicity
#> 17 interpreter_needed race_and_ethnicity NA truefalse Are interp…
#> # ℹ 13 more variables: select_choices_or_calculations <chr>, field_note <chr>,
#> # text_validation_type_or_show_slider_number <chr>,
#> # text_validation_min <chr>, text_validation_max <chr>, identifier <chr>,
#> # branching_logic <chr>, required_field <chr>, custom_alignment <chr>,
#> # question_number <chr>, matrix_group_name <chr>, matrix_ranking <chr>,
#> # field_annotation <chr>
#>
#> $success
#> [1] TRUE
#>
#> $status_code
#> [1] 200
#>
#> $outcome_message
#> [1] "The data dictionary describing 17 fields was read from REDCap in 0.1 seconds. The http status code was 200."
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.125581
#>
#> $raw_text
#> [1] ""
#>
# A longitudinal project
token <- "0434F0E9CF53ED0587847AB6E51DE762" # longitudinal
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The REDCapR metadata export operation was not successful. The error message was:
#> {"error":"You do not have permissions to use the API"}
#> $data
#> # A tibble: 0 × 0
#>
#> $success
#> [1] FALSE
#>
#> $status_code
#> [1] 403
#>
#> $outcome_message
#> [1] "The REDCapR metadata export operation was not successful. The error message was:\n{\"error\":\"You do not have permissions to use the API\"}"
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.09817386
#>
#> $raw_text
#> [1] "{\"error\":\"You do not have permissions to use the API\"}"
#>
# A repeating measures
token <- "77842BD8C18D3408819A21DD0154CCF4" # vignette-repeating
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The data dictionary describing 9 fields was read from REDCap in 0.1 seconds. The http status code was 200.
#> $data
#> # A tibble: 9 × 18
#> field_name form_name section_header field_type field_label
#> <chr> <chr> <chr> <chr> <chr>
#> 1 record_id intake NA text Record ID
#> 2 height intake NA text patient height
#> 3 weight intake NA text patient weight
#> 4 bmi intake NA text patient bmi
#> 5 sbp blood_pressure NA text systolic blood pressure
#> 6 dbp blood_pressure NA text diastolic blood pressu…
#> 7 lab laboratory NA text lab value
#> 8 conc laboratory NA text concentration
#> 9 image_profile image NA file Picture of Patient
#> # ℹ 13 more variables: select_choices_or_calculations <chr>, field_note <chr>,
#> # text_validation_type_or_show_slider_number <chr>,
#> # text_validation_min <chr>, text_validation_max <chr>, identifier <chr>,
#> # branching_logic <chr>, required_field <chr>, custom_alignment <chr>,
#> # question_number <chr>, matrix_group_name <chr>, matrix_ranking <chr>,
#> # field_annotation <chr>
#>
#> $success
#> [1] TRUE
#>
#> $status_code
#> [1] 200
#>
#> $outcome_message
#> [1] "The data dictionary describing 9 fields was read from REDCap in 0.1 seconds. The http status code was 200."
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.122807
#>
#> $raw_text
#> [1] ""
#>
# }