redcapAPI (version 2.8.0)

mappingMethods: Export and Import Instrument-Event Mappings

Description

These methods enable the user to export and add/modify the mappings between instruments and events. The information provided with the methods corresponds to what is provided in the 'Designate Instruments for My Events' page in the user interface.

Usage

exportMappings(rcon, arms, ...)
importMappings(rcon, data, refresh = TRUE, ...)
# S3 method for redcapApiConnection
exportMappings(
  rcon,
  arms = NULL,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)
# S3 method for redcapApiConnection
importMappings(
  rcon,
  data,
  refresh = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

Value

exportMappings returns a data frame with the columns:

arm_num	The arm number for the unique event mapped to the instrument.
unique_event_name	The unique event name to which the instrument is assigned.
form	The REDCap assigned instrument name mapped to the event.

Arguments

rcon

A redcapConnection object.

arms

integerish or character. A vector of arm numbers. When given, mappings are only exported for the given arms.

data

data.frame with columns arm_num, unique_event_name, and form. See Details

refresh

logical(1). When TRUE, cached mappings in the rcon object are refreshed after the import.

...

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

• exportMappings(): Export instrument-event mappings.

• importMappings(): Import instrument-event mappings to the project.

Details

These methods are only applicable to longitudinal projects. If the project information reports that the project is not longitudinal, a data frame with 0 rows is returned without calling the API.

See Also

exportFieldNames(),
exportInstruments(),
exportMetaData(),
importMetaData(),
exportPdf()

Examples

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

# Export all mappings
exportMappings(rcon)

# Export mappings for a specific arm
exportMappings(rcon, 
               arms = 1)
               
# Import mappings
NewMapping <- 
  data.frame(arm_num = c(1, 1, 2), 
             unique_event_name = c("event_1_arm_1", 
                                   "event_2_arm_1", 
                                   "event_1_arm_2"), 
             form = c("registration", 
                      "follow_up", 
                      "registration"))

importMapping(rcon, 
              data = NewMapping)
}