exportFieldNames: Export the Complete Field Names for a REDCap Project

Description

This method enables the user to access the complete field names utilized during export and import methods. These are expecially relevant when working with checkbox fields.

Usage

exportFieldNames(rcon, ...)
# S3 method for redcapApiConnection
exportFieldNames(
  rcon,
  fields = character(0),
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

Value

exportFieldNames returns a data frame with the columns:


`original_field_name`	The field name as recorded in the data dictionary
`choice_value`	represents the raw coded value for a checkbox choice. For non-checkbox fields, this will always be `NA`.
`export_field_name`	The field name specific to the field. For non-checkbox fields, this is the same as `original_field_name`. For checkbox fields, it is the field name appended with `___[choice_value]`.

Arguments

rcon: A redcapConnection object.
fields: NULL or character(1). Field name to be returned. By default, all fields are returned.
...: Arguments to pass to other methods
error_handling: character(1). One of c("error", "null"). An option for how to handle errors returned by the API. see redcapError().
config: A named list. Additional configuration parameters to pass to httr::POST(). These are appended to any parameters in rcon$config.
api_param: A named list. Additional API parameters to pass into the body of the API call. This provides users to execute calls with options that may not otherwise be supported by redcapAPI.

Details

exportFieldNames returns a data frame of the field names the user may use when performing export and import functions. This is most useful when working with checkbox fields, which have a different field name than the one used in the Meta Data. The exported/imported field names for checkbox fields have the pattern [field_name]___[coded_checkbox_value] (there are exactly three underscores separating the field name and the coded value).

Fields of types "calc", "file", and "descriptive" are not included in the export. (Signature fields also have the "file" type and are not included)

Examples

Run this code

if (FALSE) {
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export all of the field names
exportFieldNames(rcon)

# Export MetaData for a specific field
exportFieldNames(rcon, 
                 fields = "checkbox_test")
}