Skip to contents

Setup or Load RosyREDCap Project

Source: R/DB_setup.R
setup-load.Rd

Setup or Load the `DB` object with the necessary REDCap API token and other configurations.

Usage

setup_DB(
  short_name,
  dir_path,
  redcap_base,
  force = F,
  merge_form_name = "merged",
  use_csv = F,
  auto_check_token = T
)

load_DB(short_name, validate = T)

load_DB_from_path(DB_path, validate = T)

load_test_DB(short_name = "TEST_repeating", with_data = F)

Arguments

short_name

A character string with no spaces or symbols representing the unique short name for the REDCap project.

dir_path

Optional character string representing the directory path where you want the REDCap project data to be stored. If missing, DB object will only be in current R session.

redcap_base

A character string representing the base URL of the REDCap server.

force

Logical (TRUE/FALSE). If TRUE, forces the setup even if the `DB` object already exists. Default is `FALSE`.

merge_form_name

A character string representing the name of the merged form. Default is "merged".

use_csv

Logical (TRUE/FALSE). If TRUE, uses CSV files for data storage. Default is `FALSE`.

auto_check_token

Logical (TRUE/FALSE). If TRUE, automatically checks the validity of the REDCap API token. Default is `TRUE`.

validate

Logical (TRUE/FALSE). If TRUE, validates DB object based on current rules. Default is `TRUE`.

DB_path

A character string representing the file path of the exact `<short_name>_RosyREDCap.rdata` file to be loaded.

with_data

Logical (TRUE/FALSE). If TRUE, loads the test DB object with data as if user ran `update_DB`. Default is `FALSE`.

Value

RosyREDCap `DB` list object.

Details

This function sets up the `DB` object by storing the REDCap API token and other configurations required for interacting with the REDCap server. It ensures that the token is valid and ready for use in subsequent API calls. Neither function directly attempts communication with REDCap.

`setup_DB` is used the first time you initialize/link a REDCap project. Mainly, it sets your unique `short_name` and your intended directory. Unless you run force = TRUE the default will first try load_DB. dir_path is technically optional but without it the user cannot save/load/update projects.

`load_DB` can be used with just the `short_name` parameter after you have already run `setup_DB` in the past with an established directory. `dir_path` is optional for this function but can be used if you relocated the directory.

See also

get_projects for retrieving a list of projects from the directory cache.

Other DB object: save_DB()

Examples

if (FALSE) {
# Initialize the DB object with the REDCap API token and URL
DB <- setup_DB(
  short_name = "TEST",
  dir_path = "path/to/secure/file/storage",
  redcap_base = "https://redcap.yourinstitution.edu/"
)
DB <- load_DB("TEST")
}