REDCapR (version 0.9.3)

retrieve_token: Read a token from a (non-REDCap) database.

Description

These functions are not essential to calling the REDCap API, but instead are functions that help manage tokens securely.

Usage

retrieve_token_mssql(dsn, project_name, channel = NULL, schema_name = "[Redcap]", procedure_name = "[prcToken]", variable_name_project = "@RedcapProjectName", field_name_token = "Token")

Arguments

dsn

A DSN on the local machine that points to the desired MSSQL database. Required.

project_name

The friendly/shortened name given to the REDCap project in the MSSQL table. Notice this isn't necessarily the same name used by REDCap. Required

channel

An optional connection handle as returned by RODBC::odbcConnect. See Details below. Optional.

schema_name

The schema used within the database. Note that MSSQL uses the more conventional definition of schema than MySQL. Defaults to '[Redcap]'. Optional.

procedure_name

The stored procedure called to retrieve the token. Defaults to '[prcToken]'. Optional.

variable_name_project

The variable declared within the stored procedure that contains the desired project name. Optional.

field_name_token

The field/column/variable name in the database table containing the token values. Defaults to 'Token'. Optional.

Value

The token, which is a 32 character string.

Details

If no channel is passed, one will be created at the beginning of the function, and destroyed at the end. However if a channel is created, it's the caller's responsibility to destroy this resource. If you're making successive calls to the database, it might be quicker to create a single channel object and batch the calls together. Otherwise, the performance should be equivalent.

If you create the channel object yourself, consider wrapping calls in a base::tryCatch block, and closing the channel in its finally expression; this helps ensure the expensive database resource isn't held open unnecessarily. See the internals of retrieve_token_mssql for an example of closing the channel in a tryCatch block.

If the database elements are create with the script provided in package's `Security Database' vignette, the default values will work.

Examples

## Not run: 
# library(REDCapR) #Load the package into the current R session.
# 
# ##
# ## Rely on `retrieve_token()` to create & destory the channel.
# ##
# dsn <- "TokenSecurity"
# project <- "DiabetesSurveyProject"
# token <- retrieve_token(dsn=dsn, project_name=project)
# 
# ##
# ## Create & close the channel yourself, to optimize repeated calls.
# ##
# dsn <- "TokenSecurity"
# project1 <- "DiabetesSurveyProject1"
# project2 <- "DiabetesSurveyProject2"
# project3 <- "DiabetesSurveyProject3"
# 
# channel <- RODBC::odbcConnect(dsn=dsn)
# token1 <- retrieve_token(dsn=dsn, project_name=project1)
# token2 <- retrieve_token(dsn=dsn, project_name=project2)
# token3 <- retrieve_token(dsn=dsn, project_name=project3)
# RODBC::odbcClose(channel)
# ## End(Not run)