These methods enable the user to create a connection object used to access the database.
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, ...)
character(1). URL for the user's REDCap database API.
character(1) REDCap API token
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.
integerish(1). Sets the number of attempts to make to the
API if a timeout error is encountered. Must be a positive value.
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.
logical(1). When FALSE, messages will
be shown giving the status of the API calls. Defaults to TRUE.
redcapConnection object to be printed
arguments to pass to other methods
Either a character giving the file from which the
metadata can be read, or a data.frame.
Either a character giving the file from which the
arms can be read, or a data.frame.
Either a character giving the file from which the
events can be read, or a data.frame.
Either a character giving the file from which the
instruments can be read, or a data.frame.
Either a character giving the file from which the
field names can be read, or a data.frame.
Either a character giving the file from which the
Event Instrument mappings can be read, or a data.frame.
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).
Either a character giving the file from which the
User settings can be read, or a data.frame.
Either a character giving the file from which the
User Roles can be read, or a data.frame.
Either a character giving the file from which the
User-Role Assignments can be read, or a data.frame.
Either a character giving the file from which the
Data Access Groups can be read, or a data.frame.
Either a character giving the file from which the
Data Access Group Assignments can be read, or a data.frame.
Either a character giving the file from which the
Project Information can be read, or a data.frame.
Either a character giving the file from which the
version can be read, or a data.frame.
Either a character giving the file from which the
File Repository Listing can be read, or a data.frame.
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.
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.