Learn R Programming

redcapAPI (version 2.8.0)

redcapConnection: 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 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 )

# S3 method for 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.

version

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

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.

Details

redcapConnection objects will retrieve and cache various forms of project information. This can make metadata, arms, dags, events, instruments, fieldnames, arm-event mappings, users, version, project information, fileRepository, and repeating instruments 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 typePurposeExample
[info_type]Returns the information from the connection objectrcon$metadata()
has_[info_type]Returns a boolean indicating if the information is cachedrcon$has_metadata()
flush_[info_type]Purges the information from the connection objectrcon$flush_metadata()
refresh_[info_type]Replaces the information with a new call to the APIrcon$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

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

The redcapConnection 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.