redcapConnection: Connect to a REDCap Database

In redcapAPI: Interface to 'REDCap'

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
)

## 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.
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 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

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.

Examples

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

options(redcap_api_url=[YOUR_REDCAP_URL])
rcon <- redcapConnection(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()

## End(Not run)

redcapAPI documentation built on Sept. 13, 2023, 1:07 a.m.