redcapConnection {redcapAPI}

Connect to a REDCap Database

Description

These methods enable the user to create a connection object used to access the database.

Usage

redcapConnection(
  url = getOption("redcap_api_url"),
  token,
  config = httr::config(),
  retries = 5,
  retry_interval = 2^(seq_len(retries)),
  retry_quietly = TRUE
)

## S3 method for class 'redcapApiConnection'
print(x, ...)

offlineConnection(
  meta_data = NULL,
  arms = NULL,
  events = NULL,
  instruments = NULL,
  field_names = NULL,
  mapping = NULL,
  repeat_instrument = NULL,
  users = NULL,
  user_roles = NULL,
  user_role_assignment = NULL,
  dags = NULL,
  dag_assignment = NULL,
  project_info = NULL,
  version = NULL,
  file_repo = NULL,
  records = NULL,
  url = NULL,
  external_coding = list()
)

## S3 method for class 'redcapOfflineConnection'
print(x, ...)

Arguments

url

character(1). URL for the user's REDCap database API.

token

character(1) REDCap API token

config

A list to be passed to httr::POST(). This allows the user to set additional configurations for the API calls, such as certificates, SSL version, etc. For the majority of users, this does not need to be altered.

retries

integerish(1). Sets the number of attempts to make to the API if a timeout error is encountered. Must be a positive value.

retry_interval

numeric. Sets the intervals (in seconds) at which retries are attempted. By default, set at a 2^r where r is the rth retry (ie, 2, 4, 8, 16, ...). For fixed intervals, provide a single value. Values will be recycled to match the number of retries.

retry_quietly

logical(1). When FALSE, messages will be shown giving the status of the API calls. Defaults to TRUE.

x

redcapConnection object to be printed

...

arguments to pass to other methods

meta_data

Either a character giving the file from which the metadata can be read, or a data.frame.

arms

Either a character giving the file from which the arms can be read, or a data.frame.

events

Either a character giving the file from which the events can be read, or a data.frame.

instruments

Either a character giving the file from which the instruments can be read, or a data.frame.

field_names

Either a character giving the file from which the field names can be read, or a data.frame.

mapping

Either a character giving the file from which the Event Instrument mappings can be read, or a data.frame.

repeat_instrument

Either a character giving the file from which the Repeating Instruments and Events settings can be read, or a data.frame. Note: The REDCap GUI does not offer a download file of these settings (at the time of this writing).

users

Either a character giving the file from which the User settings can be read, or a data.frame.

user_roles

Either a character giving the file from which the User Roles can be read, or a data.frame.

user_role_assignment

Either a character giving the file from which the User-Role Assignments can be read, or a data.frame.

dags

Either a character giving the file from which the Data Access Groups can be read, or a data.frame.

dag_assignment

Either a character giving the file from which the Data Access Group Assignments can be read, or a data.frame.

project_info

Either a character giving the file from which the Project Information can be read, or a data.frame. See Details.

version

character(1) giving the instance's REDCap version number.

file_repo

Either a character giving the file from which the File Repository Listing can be read, or a data.frame.

records

Either a character giving the file from which the Records can be read, or a data.frame. This should be the raw data as downloaded from the API, for instance. Using labeled or formatted data is likely to result in errors when passed to other functions.

external_coding

Named list of named character vectors or a character giving the file from which the external coding may be read. The list is generally obtained from the API using exportExternalCoding(). The name of the list element should be a field name in the data that is of type bioportal or sql. The named vectors are code-label pairings where the value of the vector is the code and the name is the label. If passing a file name, it should be a file with the list saved via dput.

Details

redcapConnection objects will retrieve and cache various forms of project information. This can make metadata, arms, events, etc. available directly from the redcapConnection object. The retrieval of these objects uses the default values of the respective export functions (excepting the file repository, which uses recursive = TRUE).

For each of these objects, there are four methods that can be called from the redcapConnection object:

Function type	Purpose	Example
⁠[info_type]⁠	Returns the information from the connection object	rcon$metadata()
has_[info_type]	Returns a boolean indicating if the information is cached	rcon$has_metadata()
flush_[info_type]	Purges the information from the connection object	rcon$flush_metadata()
refresh_[info_type]	Replaces the information with a new call to the API	rcon$refresh_metadata()

Information is cached for

• metadata

• arms

• events

• instruments

• fieldnames

• mapping (field-event mappings)

• repeatInstrumentEvent

• users

• user_roles

• user_role_assignment

• dags

• dag_assignment

• projectInformation

• version

• fileRepository

• externalCoding

There is also a flush_all and refresh_all method that will purge the entire cache and refresh the entire cache, respectively.

The externalCoding elements relate to the code-label mappings of text fields with the external validation types (such as sql fields or text fields with BioPortal Ontology modules enabled).

Specific to API Connections

The redcapApiConnection object also stores the user preferences for handling repeated attempts to call the API. In the event of a timeout error or server unavailability, these settings allow a system pause before attempting another API call. In the event all of the retries fail, the error message of the last attempt will be returned. These settings may be altered at any time using the methods rcon$set_retries(r), rcon$set_retry_interval(ri), and rcon$set_retry_quietly(rq). The argument to these functions have the same requirements as the corresponding arguments to redcapConnection.

Tokens are specific to a project, and a token must be created for each project for which the user wishes to use the API.

Additional Curl option can be set in the config argument. See the documentation for httr::config() and httr::httr_options() for more Curl options.

Specific to Offline Connections

"Offline connections" are a tool designed to provide the users without API privileges with at least a subset of the functionality available to API users. The offline connections are typically constructed from the comma separated value (CSV) files downloaded from the REDCap user interface. Alternatively, data frames may be provided with the necessary data.

Not all of the components of an offline connection are needed for most operations. Rather, the object was built to accept the same components available to the redcapApiConnection in order to provide a consistent interface and simplify future development.

The meta data will be required for nearly all operations. For validating and casting data, the records data must be provided, and works best if the data are the raw, unlabeled data downloaded from the REDCap user interface.

Other components that may prove useful when casting records are the url, version, events (if the project is longitudinal), and a subset of the project information. The user is encouraged to review the vignette for working with offline connections for more details.

With offline connections, the refresh methods have an important difference. The user may pass the refresh method a file path or data frame which will be used to replace the existing component. See examples.

See Also

For establishing connections using secure token storage.
unlockREDCap()
vignette("redcapAPI-getting-started-connecting", package = "redcapAPI")

For working with offline connections. vignette("redcapAPI-offline-connection", package = "redcapAPI")

To prepare data for an offline user, see preserveProject() and readPreservedProject().

Examples

## Not run: 
rcon <- redcapConnection(url = [YOUR_REDCAP_URL], 
                         token = [API_TOKEN])

exportRecords(rcon)

# Get the complete metadata for the project
rcon$metadata()

# Get the fieldnames for a project
rcon$fieldnames()

# remove a cached value for fieldnames
rcon$flush_fieldnames()
rcon$has_fieldnames()


# Using offline connections

meta_data_file <- "path/to/meta_data_file.csv"
records_file <- "path/to/records_file.csv"
events_file <- "path/to/events_file.csv"

ProjectInfo <- data.frame(project_id = 12345, 
                          is_longitudinal = 1)

off_conn <- offlineConnection(meta_data = meta_data_file, 
                              records = records_file,
                              project_info = ProjectInfo, 
                              version = [YOUR_REDCAP_VERSION_NUMBER], 
                              url = [YOUR_REDCAP_URL])
                              
off_conn$metadata()
off_conn$records()
off_conn$projectInformation()
off_conn$version()

# Add or replace the data in the events component.
off_conn$refresh_events(events_file)
off_conn$events()

## End(Not run)