redcapAPI (version 2.8.0)

repeatingInstrumentMethods: Export or Import Repeating Instrument and Events Settings

Description

These methods enable the user to export the existing repeating instrument and event settings, or import new settings to the project.

Usage

exportRepeatingInstrumentsEvents(rcon, ...)
importRepeatingInstrumentsEvents(rcon, data, ...)
# S3 method for redcapApiConnection
exportRepeatingInstrumentsEvents(
  rcon,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)
# S3 method for redcapApiConnection
importRepeatingInstrumentsEvents(
  rcon,
  data,
  refresh = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

Value

exportRepeatingInstrumentsEvents returns a data frame with the columns:

event_name	The unique event name.
form_name	The form name, as given in the second column of the Meta Data
custom_form_label	A custom display string for the repeating instrument/event

importRepeatingInstrumentsEvents has no return and displays a message describing the number of rows imported.

Arguments

rcon

A redcapConnection object.

data

data.frame. For classical projects, it must have the columns form_name and custom_form_label. Longitudinal projects also require a column for event_name.

refresh

logical(1). When TRUE, the cached value of repeating instruments and events on rcon will be refreshed.

...

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.

Functions

• exportRepeatingInstrumentsEvents(): Export repeating instruments and events.

• importRepeatingInstrumentsEvents(): Import repeating instruments and events.

Details

Repeating events (as opposed to repeating instruments) are provided as a row of data where the form_name column is NA.

It is not possible to update the has_repeating_instruments_or_events property of the project through importProjectInformation. Enabling of repeating instruments and events must be done through the GUI.

Although the API does not provide a delete method, it is possible to remove settings by doing an import that excludes the settings that are to be deleted. All settings can be cleared by executing importRepeatingInstrumentsEvents(rcon, REDCAP_REPEAT_INSTRUMENT_STRUCTURE).

Examples

if (FALSE) {
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Export repeating instruments and events
exportRepeatingInstrumentsEvents(rcon)

# Import repeating instruments and events
NewData <- data.frame(event_name = c("event_1_arm_1", 
                                     "event_2_arm_1"), 
                      form_name = c("field_observation", 
                                    "self_assessment"), 
                      custom_form_label = c("Instructor led field observation", 
                                            "Trainee self assessment"))
                                            
importRepeatingInstrumentsEvents(rcon, 
                                 data = NewData)
}