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.
redcap_metadata_read(
redcap_uri,
token,
forms = NULL,
fields = NULL,
verbose = TRUE,
config_options = NULL,
handle_httr = NULL
)The uri/url of the REDCap server typically formatted as "https://server.org/apps/redcap/api/". Required.
The user-specific string that serves as the password for a project. Required.
An array, where each element corresponds to the REDCap form of the desired fields. Optional.
An array, where each element corresponds to a desired project field. Optional.
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.
A list of options passed to httr::POST().
See details at httr::httr_options(). Optional.
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.
Currently, a list is returned with the following elements:
data: An R tibble::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.
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.
# \dontrun{
uri <- "https://bbmc.ouhsc.edu/redcap/api/"
# A simple project (pid 153)
token <- "9A81268476645C4E5F03428B8AC3AA7B"
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The data dictionary describing 17 fields was read from REDCap in 0.2 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.2 seconds. The http status code was 200."
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.179333
#>
#> $raw_text
#> [1] ""
#>
# A longitudinal project (pid 212)
token <- "0434F0E9CF53ED0587847AB6E51DE762"
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The data dictionary describing 95 fields was read from REDCap in 0.2 seconds. The http status code was 200.
#> $data
#> # A tibble: 95 × 18
#> field_name form_name section_header field_type field_label
#> <chr> <chr> <chr> <chr> <chr>
#> 1 study_id demographics NA text Study ID
#> 2 date_enrolled demographics Consent Information text Date subject si…
#> 3 patient_document demographics NA file Upload the pati…
#> 4 first_name demographics Contact Information text First Name
#> 5 last_name demographics NA text Last Name
#> 6 telephone_1 demographics NA text Phone number
#> 7 email demographics NA text E-mail
#> 8 dob demographics NA text Date of birth
#> 9 age demographics NA calc Age (years)
#> 10 ethnicity demographics NA radio Ethnicity
#> # ℹ 85 more rows
#> # ℹ 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 95 fields was read from REDCap in 0.2 seconds. The http status code was 200."
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.184201
#>
#> $raw_text
#> [1] ""
#>
# A repeating measures (pid 3181)
token <- "22C3FF1C8B08899FB6F86D91D874A159"
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The data dictionary describing 8 fields was read from REDCap in 0.2 seconds. The http status code was 200.
#> $data
#> # A tibble: 8 × 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 pressure
#> 7 lab laboratory NA text lab value
#> 8 conc laboratory NA text concentration
#> # ℹ 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 8 fields was read from REDCap in 0.2 seconds. The http status code was 200."
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.1886129
#>
#> $raw_text
#> [1] ""
#>
# }