Export the metadata of a REDCap project

Source: R/redcap-metadata-read.R

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
)

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 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: 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.

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

Will Beasley

Examples

# \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.1 seconds.  The http status code was 200.
#> $data
#> # A tibble: 17 × 18
#>    field_name    form_…¹ secti…² field…³ field…⁴ selec…⁵ field…⁶ text_…⁷ text_…⁸
#>    <chr>         <chr>   <chr>   <chr>   <chr>   <chr>   <chr>   <chr>   <chr>  
#>  1 record_id     demogr… NA      text    Study … NA      NA      NA      NA     
#>  2 name_first    demogr… Contac… text    First … NA      NA      NA      NA     
#>  3 name_last     demogr… NA      text    Last N… NA      NA      NA      NA     
#>  4 address       demogr… NA      notes   Street… NA      NA      NA      NA     
#>  5 telephone     demogr… NA      text    Phone … NA      Includ… phone   NA     
#>  6 email         demogr… NA      text    E-mail  NA      NA      email   NA     
#>  7 dob           demogr… NA      text    Date o… NA      NA      date_y… NA     
#>  8 age           demogr… NA      text    Age (y… NA      NA      NA      NA     
#>  9 sex           demogr… NA      radio   Gender  0, Fem… NA      NA      NA     
#> 10 height        health  NA      text    Height… NA      NA      number  130    
#> 11 weight        health  NA      text    Weight… NA      NA      integer 35     
#> 12 bmi           health  NA      calc    BMI     round(… NA      NA      NA     
#> 13 comments      health  Genera… notes   Commen… NA      NA      NA      NA     
#> 14 mugshot       health  NA      file    Mugshot NA      NA      NA      NA     
#> 15 race          race_a… NA      checkb… Race (… 1, Ame… NA      NA      NA     
#> 16 ethnicity     race_a… NA      radio   Ethnic… 0, Unk… NA      NA      NA     
#> 17 interpreter_… race_a… NA      truefa… Are in… NA      NA      NA      NA     
#> # … with 9 more variables: 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>, and abbreviated variable names ¹​form_name,
#> #   ²​section_header, ³​field_type, ⁴​field_label,
#> #   ⁵​select_choices_or_calculations, ⁶​field_note,
#> #   ⁷​text_validation_type_or_show_slider_number, ⁸​text_validation_min
#> 
#> $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.1349728
#> 
#> $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.1 seconds.  The http status code was 200.
#> $data
#> # A tibble: 95 × 18
#>    field_name    form_…¹ secti…² field…³ field…⁴ selec…⁵ field…⁶ text_…⁷ text_…⁸
#>    <chr>         <chr>   <chr>   <chr>   <chr>   <chr>   <chr>   <chr>   <chr>  
#>  1 study_id      demogr… NA      text    Study … NA      NA      NA      NA     
#>  2 date_enrolled demogr… Consen… text    Date s… NA      YYYY-M… date_y… NA     
#>  3 patient_docu… demogr… NA      file    Upload… NA      NA      NA      NA     
#>  4 first_name    demogr… Contac… text    First … NA      NA      NA      NA     
#>  5 last_name     demogr… NA      text    Last N… NA      NA      NA      NA     
#>  6 telephone_1   demogr… NA      text    Phone … NA      Includ… phone   NA     
#>  7 email         demogr… NA      text    E-mail  NA      NA      email   NA     
#>  8 dob           demogr… NA      text    Date o… NA      NA      date_y… NA     
#>  9 age           demogr… NA      calc    Age (y… roundd… NA      NA      NA     
#> 10 ethnicity     demogr… NA      radio   Ethnic… 0, His… NA      NA      NA     
#> # … with 85 more rows, 9 more variables: 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>, and abbreviated variable
#> #   names ¹​form_name, ²​section_header, ³​field_type, ⁴​field_label,
#> #   ⁵​select_choices_or_calculations, ⁶​field_note,
#> #   ⁷​text_validation_type_or_show_slider_number, ⁸​text_validation_min
#> 
#> $success
#> [1] TRUE
#> 
#> $status_code
#> [1] 200
#> 
#> $outcome_message
#> [1] "The data dictionary describing 95 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.1465471
#> 
#> $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.1 seconds.  The http status code was 200.
#> $data
#> # A tibble: 8 × 18
#>   field_name form_name   secti…¹ field…² field…³ selec…⁴ field…⁵ text_…⁶ text_…⁷
#>   <chr>      <chr>       <chr>   <chr>   <chr>   <chr>   <chr>   <chr>   <chr>  
#> 1 record_id  intake      NA      text    Record… NA      NA      NA      NA     
#> 2 height     intake      NA      text    patien… NA      NA      number… 1      
#> 3 weight     intake      NA      text    patien… NA      NA      number… 1      
#> 4 bmi        intake      NA      text    patien… NA      NA      number… 0      
#> 5 sbp        blood_pres… NA      text    systol… NA      NA      number  1      
#> 6 dbp        blood_pres… NA      text    diasto… NA      NA      number  1      
#> 7 lab        laboratory  NA      text    lab va… NA      NA      NA      NA     
#> 8 conc       laboratory  NA      text    concen… NA      NA      NA      NA     
#> # … with 9 more variables: 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>, and abbreviated variable names ¹​section_header,
#> #   ²​field_type, ³​field_label, ⁴​select_choices_or_calculations, ⁵​field_note,
#> #   ⁶​text_validation_type_or_show_slider_number, ⁷​text_validation_min
#> 
#> $success
#> [1] TRUE
#> 
#> $status_code
#> [1] 200
#> 
#> $outcome_message
#> [1] "The data dictionary describing 8 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.132216
#> 
#> $raw_text
#> [1] ""
#> 
# }