Package {REDCapSync}

Title:	Encapsulated 'REDCap' Projects for Synchronized Data Pipelines
Version:	0.1.0
Description:	Wraps dozens of 'REDCap' API endpoints into a standardized R6 object. Research Electronic Data Capture ('REDCap') is a survey and database web application software maintained by Vanderbilt University. It has a robust application programming interface (API) utilized by several R packages. 'REDCapSync' uses 'redcapAPI' and 'REDCapR' behind-the-scenes to retrieve all metadata, data, and log details for a project. To minimize unnecessary server calls, the interim 'REDCap' log is analyzed and used to only update necessary records. Furthermore, the user can define custom datasets that save to a directory. Those datasets continue to refresh when projects are synced. Having a secure, standardized, API-efficient, project-agnostic R object for 'REDCap' projects, streamlines downstream use in scripts, functions, and shiny applications.
License:	GPL (≥ 3)
URL:	https://github.com/thecodingdocs/REDCapSync, https://thecodingdocs.github.io/REDCapSync/
BugReports:	https://github.com/thecodingdocs/REDCapSync/issues
Depends:	R (≥ 4.1)
Imports:	checkmate, cli, dplyr, hoardr, lubridate, openxlsx, R6, readxl, redcapAPI, REDCapR, skimr, stats, stringr, utils
Suggests:	keyring, knitr, listviewer, rmarkdown, spelling, testthat (≥ 3.3.0), withr
VignetteBuilder:	knitr
Config/roxygen2/version:	8.0.0
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
NeedsCompilation:	no
Packaged:	2026-05-18 03:19:43 UTC; brandonrose
Author:	Brandon Rose [cre, aut, cph], Natalie Goulett [ctb]
Maintainer:	Brandon Rose <thecodingdocs@gmail.com>
Repository:	CRAN
Date/Publication:	2026-05-21 12:40:02 UTC

REDCapSync: Encapsulated 'REDCap' Projects for Synchronized Data Pipelines

Description

Wraps dozens of 'REDCap' API endpoints into a standardized R6 object. Research Electronic Data Capture ('REDCap') is a survey and database web application software maintained by Vanderbilt University. It has a robust application programming interface (API) utilized by several R packages. 'REDCapSync' uses 'redcapAPI' and 'REDCapR' behind-the-scenes to retrieve all metadata, data, and log details for a project. To minimize unnecessary server calls, the interim 'REDCap' log is analyzed and used to only update necessary records. Furthermore, the user can define custom datasets that save to a directory. Those datasets continue to refresh when projects are synced. Having a secure, standardized, API-efficient, project-agnostic R object for 'REDCap' projects, streamlines downstream use in scripts, functions, and shiny applications.

Author(s)

Maintainer: Brandon Rose thecodingdocs@gmail.com (ORCID) [copyright holder]

Authors:

• Brandon Rose thecodingdocs@gmail.com (ORCID) [copyright holder]

Other contributors:

• Natalie Goulett [contributor]

See Also

Useful links:

• https://github.com/thecodingdocs/REDCapSync

• https://thecodingdocs.github.io/REDCapSync/

• Report bugs at https://github.com/thecodingdocs/REDCapSync/issues

Clear your cached projects

Description

Finds the location of the cache established by hoard and deletes stored project information (not data)! If you provide project_names, it will remove only those projects from the cache. If you want to truly delete the project files, you must do so at the project directory you set up.

Usage

cache_clear(project_names = NULL)

Arguments

Details

The cache only stores information like project_name, token_name, directory location, and other details from setup_project().The default location of the cache location is defined by using R_USER_CACHE_DIR if set. Otherwise, it follows platform conventions via hoardr, saving a file "R/REDCapSync/projects.rds". No direct project data is stored in the cache. Notably, tokens and data are not stored here. The key variables stored in the cache are...

• project_name - unique identifier for REDCapSync package

• redcap_uri - server location

• token_name - where to find token environment with Sys.getenv()

• dir_path - where to saved project and associated files locally

• project_id - obtained from API call and "locks-in" the connection

• redcap_version - obtained from API call and affects links

• last_sync and sync_frequency - informs REDCap sync of when to update

• other variables from project info and some internal package mechanics

Value

Message of outcome and invisible NULL.

See Also

vignette("Cache", package = "REDCapSync") setup_project for initializing projects

Examples

## Not run: 
cache_clear("OLD_PROJECT")
cache_clear() # every project

## End(Not run)

Configuration

Description

Internal configuration helpers used to retrieve package configuration values from options or environment variables.

Configuration is resolved in the following order:

1. getOption("redcapsync.config.option.name")

2. Sys.getenv("REDCAPSYNC_CONFIG_OPTION_NAME") # skipped for functions

3. Default if unable to find and validate from above.

Usage

config

Details

The config function is operational but only some methods presently affect internal code. Most users will not ever need to modify default config. This is included to improve future versions of the package.

• Working configs: allow.test.names, cache.dir, keyring, keyring.service, openxlsx.header.style, openxlsx.body.style.

• Partial coverage: offline.

• Placeholder: verbose, show.api.messages

allow.test.names

Logical for setup_project() allowing project_name starting with TEST_. Default is FALSE. This is provided for developers and testing environments.

# check current value package is using...
config$allow.test.names()
# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.allow.test.names") # get
options(redcapsync.config.allow.test.names = FALSE) # set

# set with ennvar (which will be prioritized when options not defined)
Sys.getenv("REDCAPSYNC_CONFIG_ALLOW_TEST_NAMES")  # get
Sys.setenv(REDCAPSYNC_CONFIG_ALLOW_TEST_NAMES = FALSE) # or set in .Renviron

show.api.messages

Logical for showing display API messages from REDCapR and redcapAPI. Default is FALSE.

# check current value package is using...
config$show.api.messages()
# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.show.api.messages") # get
options(redcapsync.config.show.api.messages = FALSE) # set

# set with ennvar (which will be prioritized when options not defined)
Sys.getenv("REDCAPSYNC_CONFIG_SHOW_API_MESSAGES") # get
Sys.setenv(REDCAPSYNC_CONFIG_SHOW_API_MESSAGES = FALSE) # or set in .Renviron

verbose

Logical for showing display API messages from REDCapR and redcapAPI. Default is FALSE.

# check current value package is using...
config$verbose()
# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.verbose") # get
options(redcapsync.config.verbose = FALSE) # set

# set with ennvar (which will be prioritized when options not defined)
Sys.getenv("REDCAPSYNC_CONFIG_VERBOSE") # get
Sys.setenv(REDCAPSYNC_CONFIG_VERBOSE = FALSE) # or set in .Renviron

offline

Logical for offline, which if TRUE will block any API calls. Default is FALSE.

# check current value package is using...
config$offline()
# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.offline") # get
options(redcapsync.config.offline = FALSE) # set

# set with ennvar (which will be prioritized when options not defined)
Sys.getenv("REDCAPSYNC_CONFIG_OFFLINE") # get
Sys.setenv(REDCAPSYNC_CONFIG_OFFLINE = FALSE) # or set in .Renviron

cache.dir

Character file path overriding the default cache directory. Default follow system standards via rappdir, hoardr, or R_USER_CACHE_DIR

# check current value package is using...
config$cache.dir()
# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.cache.dir") # get
options(redcapsync.config.cache.dir = "file/path/to/keep/cache") # set

# set with ennvar (which will be prioritized when options not defined)
Sys.getenv("REDCAPSYNC_CONFIG_CACHE_DIR") # get
Sys.setenv(REDCAPSYNC_CONFIG_CACHE_DIR = "file/path/to/keep/cache") # set

keyring

Character keyring name (parameter from keyring package). Default is NULL, which is at the system level. For locking use a keyring like "REDCapSync"

# check current value package is using...
config$keyring()
# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.keyring") # get
options(redcapsync.config.keyring = "REDCapSync") # set

# set with ennvar (which will be prioritized when options not defined)
Sys.getenv("REDCAPSYNC_CONFIG_KEYRING") # get
Sys.setenv(REDCAPSYNC_CONFIG_KEYRING = "REDCapSync") # set in session

keyring.service

Character keyring service name (parameter from keyring package). Default is "R-REDCapSync".

# check current value package is using...
config$keyring.service()
# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.keyring.service") # get
options(redcapsync.config.keyring.service = "REDCapSync") # set

# set with ennvar (which will be prioritized when options not defined)
Sys.getenv("REDCAPSYNC_CONFIG_KEYRING_SERVICE") # get
Sys.setenv(REDCAPSYNC_CONFIG_KEYRING_SERVICE = "REDCapSync") # set in session

openxlsx.header.style

Excel sheet header using openxlsx::createStyle()

# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.openxlsx.header.style") # get
new_style <- openxlsx::createStyle(fontSize = 12L)
options(redcapsync.config.openxlsx.header.style = new_style)
# does not look up envvar due to it's function type

openxlsx.body.style

Excel sheet body using openxlsx::createStyle()

# set with options (which will be prioritized over envvar)
getOption("redcapsync.config.openxlsx.body.style") # get
new_style <- openxlsx::createStyle(fontSize = 12L)
options(redcapsync.config.openxlsx.body.style = new_style)
# does not look up envvar due to it's function type

Value

list of functions that returns config values

Option Names (searched first)

option_list <- list(
  redcapsync.config.allow.test.names = NULL,
  redcapsync.config.show.api.messages = NULL,
  redcapsync.config.verbose = NULL,
  redcapsync.config.offline = NULL,
  redcapsync.config.cache.dir = NULL,
  redcapsync.config.keyring = NULL,
  redcapsync.config.keyring.service = NULL,
  redcapsync.config.openxlsx.header.style = NULL,
  redcapsync.config.openxlsx.body.style = NULL
)

Environment Variable Names (searched second)

envvar_list <- list(
  REDCAPSYNC_CONFIG_ALLOW_TEST_NAMES = NA,
  REDCAPSYNC_CONFIG_SHOW_API_MESSAGES = NA,
  REDCAPSYNC_CONFIG_VERBOSE = NA,
  REDCAPSYNC_CONFIG_OFFLINE = NA,
  R_USER_CACHE_DIR = NA, # affects your entire cache for any package
  REDCAPSYNC_CONFIG_CACHE_DIR = NA, # affects only REDCapSync Cache
  REDCAPSYNC_CONFIG_KEYRING = NA,
  REDCAPSYNC_CONFIG_KEYRING_SERVICE = NA
)

See Also

vignette("Projects", package = "REDCapSync") setup_project for initializing projects

Examples

# disable with environment variable
Sys.setenv(REDCAPSYNC_CONFIG_OFFLINE = FALSE)

config$offline()

# change to offline
options(redcapsync.config.offline = TRUE)

config$offline()

REDCapSync Dataset Object

Description

R6 object representing a standardized dataset generated from a REDCapSync project. Use this object to inspect transformed REDCap data, export datasets, and assign prepared analysis tables into the calling environment.

Details

A REDCapSyncDataset can be created ad-hoc from a project with dataset <- project$generate_dataset(). For reusability, you can also define with project$add_dataset() and then load with dataset <- project$load_dataset().

You can add variables manually if you want them to be passed to Excel. But add_field is a feature in development.

Typical workflow

setup project from test object
project <- setup_project(
  project_name = "TEST_CLASSIC",
  dir_path = tempdir()
)
# Create and save a filtered dataset
project$add_dataset(
  dataset_name = "analysis_set",
  filter_field = "var_yesno",
  filter_choices = "Yes",
  field_names = c("ecog_at_diagnosis", "stage_at_diagnosis")
)
# generate dataset for R environment
dataset <- project$load_dataset("analysis_set")
# optional send to global environment
dataset$to_envir(globalenv()) # keep in mind potential name conflicts
# Optional modify (final save depends on what is in the dataset object)
dataset$data$merged$stage_2 <- dataset$data$merged$stage_at_diagnosis == "II"
# save to directory
dataset$save() # can specify `dir_other`, by default saves to output folder

This object is designed for users who want a stable dataset output from REDCap without modifying the underlying project. This is also used behind-the-scenes in the RosyREDCap shiny app.

Key features

• Stores a project-specific dataset definition and resulting data

• Keeps metadata, record details, user information, and comments in sync

• Saves datasets in Excel or CSV formats with optional hyperlinks

• Exports dataset components to a user-specified environment

Value

An R6 REDCapSyncDataset object containing dataset output, metadata, records, user information, and optional REDCap log data.

Public fields

Active bindings

Methods

Public methods

• REDCapSyncDataset$new()

• REDCapSyncDataset$print()

• REDCapSyncDataset$save()

• REDCapSyncDataset$to_envir()

REDCapSyncDataset$new()

The end user will not see dataset$new(). This is handled internally. Users should construct objects using REDCapSyncProject.

Usage

REDCapSyncDataset$new(
  project,
  dataset_name,
  transformation_type = "default",
  merge_form_name = "merged",
  filter_field = NULL,
  filter_choices = NULL,
  filter_list = NULL,
  filter_strict = TRUE,
  field_names = NULL,
  form_names = NULL,
  exclude_identifiers = FALSE,
  exclude_free_text = FALSE,
  date_handling = "none",
  labelled = TRUE,
  clean = TRUE,
  drop_blanks = FALSE,
  drop_missing_codes = FALSE,
  drop_others = NULL,
  include_metadata = TRUE,
  include_users = TRUE,
  include_records = TRUE,
  include_log = FALSE,
  annotate_from_log = TRUE,
  include_comments = FALSE
)

Arguments

REDCapSyncDataset$print()

Print some key dataset information

Usage

REDCapSyncDataset$print()

REDCapSyncDataset$save()

Return flat list

Usage

REDCapSyncDataset$save(
  with_links = TRUE,
  separate = FALSE,
  use_csv = FALSE,
  dir_other = NULL,
  file_name = NULL
)

Arguments

REDCapSyncDataset$to_envir()

export dataset to envir of your choosing. Keep in mind potential name conflicts

Usage

REDCapSyncDataset$to_envir(envir = NULL)

Arguments

See Also

project for using the project objects vignette("Datasets", package = "REDCapSync") vignette("RosyREDCap", package = "REDCapSync")

Examples

project <- load_project("TEST_CLASSIC")

dataset <- project$generate_dataset(
  dataset_name = "stage_2_patients",
  filter_field = "stage_at_diagnosis",
  filter_choices = "II",
  field_names = c("ecog_at_diagnosis", "stage_at_diagnosis")
 )

dataset$save(dir_other = tempdir())

REDCapSync Project Object

Description

R6 project object for managing REDCap data access and synchronization. The project object is your main interface to REDCap data through the REDCapSync package. It stores your REDCap configuration, data, metadata, and provides methods to sync, transform, and export your data.

Details

Workflow

Initialize a project with setup_project():

project <- setup_project(
  project_name = "FIRST_PROJECT",
  redcap_uri = "https://redcap.yourinstitution.edu/api/",
  dir_path = "~/redcap_projects"
)

Synchronize REDCap data into your project object using the REDCap API and log-based change detection:

project$sync()

Load previously saved REDCap project object using cache:

project <- load_project("FIRST_PROJECT)
projects$names() # should see "FIRST_PROJECT"

Access REDCap data, metadata, and users via read-only fields:

project$data           # Named list of REDCap forms/instruments
project$metadata       # REDCap field definitions, forms, and choices
project$redcap$users   # REDCap user information
project$redcap$log     # REDCap log information

# you can bypass read-only if needed
users <- project$redcap$users

Transform and export your data into clean, analysis-ready datasets to be used in R and/or Excel:

project$add_dataset("analysis_data", ...) # adds to project for re-use
project$save_datasets() # can save to Excel but is also part of future syncs

Upload corrected or new data back to REDCap:

project$upload(updated_data)

Design Features

The project object uses log-based sync: Since REDCap maintains a detailed change log, project$sync() only retrieves and updates records that have changed since the last sync. This dramatically reduces API calls and improves performance for large projects.

All methods use method chaining: Methods invisibly return the project object (self), allowing fluent code:

dataset <- load_project("TEST_CLASSIC")$sync()$load_dataset("REDCapSync")

Read-Only Fields

• project$project_name: Project identifier (set with setup_project)

• project$dir_path: Persistent storage directory (set with setup_project)

• project$data: Named list of synchronized REDCap forms

• project$metadata: REDCap field metadata (forms, fields, choices)

• project$redcap: REDCap project info, users, and activity log

• project$.internal: Internal project object (for advanced use)

TEST Projects

All TEST projects start with "TEST_" and by default the average user cannot create a project that starts with "TEST_". They are produced from actual server REDCap projects but never contained real data and were scrubbed of any "real" user/log data. They are subject to change in future versions as the package matures. Keep in mind there are many combinations of REDCap structures to account for.

TEST projects are meant to be used for demonstration and testing purposes. In general, try to use actual REDCap project(s) to explore the package.

This is how to load a project with or without specifying a directory.

# return the list of available test projects
REDCapSync::projects$test_names()

project <- load_project("TEST_CLASSIC")

YOUR_DIRECTORY <- getwd()
project <- setup_project("TEST_CLASSIC", dir_path = YOUR_DIRECTORY)
# now can test object functions (does not use API)
project$sync() # will also save datasets

The currently available TEST projects are as follows:

• TEST_CLASSIC: Classic project (nothing repeats). Has every data type. Contains data for survival analysis testing. Contains comments.

• TEST_REPEATING: Non-longitudinal project with repeating instruments.

• TEST_LONGITUDINAL: Longitudinal project (with events).

• TEST_MULTIARM: Multi-arm and longitudinal project.

• TEST_EDGE: Edge-case project. Meant to test things that may be uncommon but should be accounted for as package matures.

• TEST_DATA: Placeholder project meant to contain more rich test dataset.

• TEST_CANCER: Placeholder project meant to contain more rich test dataset.

• TEST_REDCAPR_SIMPLE: Borrowed with permission from REDCapR.

• TEST_REDCAPR_LONGITUDINAL: Borrowed with permission from REDCapR.

• TEST_REDCAPR_CLIN_TRIAL: Borrowed with permission from REDCapR.

Value

An R6 REDCapSyncProject class generator for internal use. Users interact with instances created by setup_project or load_project.

Active bindings

Methods

Public methods

• REDCapSyncProject$new()

• REDCapSyncProject$print()

• REDCapSyncProject$sync()

• REDCapSyncProject$add_dataset()

• REDCapSyncProject$load_dataset()

• REDCapSyncProject$remove_datasets()

• REDCapSyncProject$generate_dataset()

• REDCapSyncProject$save_datasets()

• REDCapSyncProject$save_dataset()

• REDCapSyncProject$save()

• REDCapSyncProject$set_keyring_token()

• REDCapSyncProject$test_token()

• REDCapSyncProject$url_launch()

• REDCapSyncProject$url_record_launch()

• REDCapSyncProject$upload()

REDCapSyncProject$new()

Active binding are read-only

The end user will not see project$new(). This is handled internally. Users should construct objects using setup_project(). The remain methods will be accessible to any user.

Usage

REDCapSyncProject$new(project)

Arguments

REDCapSyncProject$print()

Print some key project information

Usage

REDCapSyncProject$print()

REDCapSyncProject$sync()

Updates the REDCap data for (project object) by checking REDCap log for changes. Sync is performed according to the sync_frequency set in setup_project() by default. Use hard_check to force a check, or hard_reset to force a complete refresh. As a default, this object will be saved to your directory when necessary.

Usage

REDCapSyncProject$sync(
  save_datasets = TRUE,
  save_to_dir = TRUE,
  hard_check = FALSE,
  hard_reset = FALSE
)

Arguments

REDCapSyncProject$add_dataset()

Add a new dataset entry

Usage

REDCapSyncProject$add_dataset(
  dataset_name,
  transformation_type = "default",
  merge_form_name = "merged",
  filter_field = NULL,
  filter_choices = NULL,
  filter_list = NULL,
  filter_strict = TRUE,
  field_names = NULL,
  form_names = NULL,
  exclude_identifiers = FALSE,
  exclude_free_text = FALSE,
  date_handling = "none",
  labelled = TRUE,
  clean = TRUE,
  drop_blanks = FALSE,
  drop_missing_codes = FALSE,
  drop_others = NULL,
  include_metadata = TRUE,
  include_records = TRUE,
  include_users = TRUE,
  include_log = FALSE,
  annotate_from_log = TRUE,
  include_comments = TRUE,
  with_links = TRUE,
  separate = FALSE,
  use_csv = FALSE,
  dir_other = NULL,
  file_name = NULL,
  hard_reset = FALSE
)

Arguments

REDCapSyncProject$load_dataset()

Load dataset if previously defined with add_dataset.

Usage

REDCapSyncProject$load_dataset(dataset_name, envir = NULL)

Arguments

REDCapSyncProject$remove_datasets()

Clear all or specified datasets from the project object.

Usage

REDCapSyncProject$remove_datasets(dataset_names = NULL)

Arguments

REDCapSyncProject$generate_dataset()

Generate dataset object. This is usually handled internally for some default behavior but is provided here for ad-hoc custom datasets.

Usage

REDCapSyncProject$generate_dataset(
  dataset_name,
  envir = NULL,
  transformation_type = "default",
  merge_form_name = "merged",
  filter_field = NULL,
  filter_choices = NULL,
  filter_list = NULL,
  filter_strict = TRUE,
  field_names = NULL,
  form_names = NULL,
  exclude_identifiers = FALSE,
  exclude_free_text = FALSE,
  date_handling = "none",
  labelled = TRUE,
  clean = TRUE,
  drop_blanks = FALSE,
  drop_missing_codes = FALSE,
  drop_others = NULL,
  include_metadata = TRUE,
  include_records = TRUE,
  include_users = TRUE,
  include_log = FALSE,
  annotate_from_log = TRUE,
  include_comments = FALSE
)

Arguments

REDCapSyncProject$save_datasets()

saves datasets to Excel via setting provided to add_dataset.

Usage

REDCapSyncProject$save_datasets(hard_reset = FALSE)

Arguments

REDCapSyncProject$save_dataset()

saves dataset to Excel via setting provided to add_dataset.

Usage

REDCapSyncProject$save_dataset(dataset_name)

Arguments

REDCapSyncProject$save()

Save project object to directory chosen with setup_project.

Usage

REDCapSyncProject$save()

REDCapSyncProject$set_keyring_token()

Set keyring token. See vignette and config for detail.

Usage

REDCapSyncProject$set_keyring_token()

REDCapSyncProject$test_token()

test connection via communication with API.

Usage

REDCapSyncProject$test_token(keyring_if_error = TRUE)

Arguments

REDCapSyncProject$url_launch()

opens links in browser.

Usage

REDCapSyncProject$url_launch(link_type = "home", open_browser = TRUE)

Arguments

REDCapSyncProject$url_record_launch()

opens record links in browser.

Usage

REDCapSyncProject$url_record_launch(
  record = NULL,
  page = NULL,
  instance = NULL,
  open_browser = TRUE
)

Arguments

REDCapSyncProject$upload()

This will only overwrite and new data. It will not directly delete any data. Because this is a function that can mess up your data, use it very carefully. Remember all changes are saved in the REDCap log if there's an issue. Missing rows and columns are allowed!

Usage

REDCapSyncProject$upload(to_be_uploaded)

Arguments

See Also

vignette("REDCapSync", package = "REDCapSync") projects for shortcuts of cached setup projects vignette("Tokens", package = "REDCapSync") setup_project for initializing projects dataset for using the dataset objects vignette("Datasets", package = "REDCapSync") vignette("Uploads", package = "REDCapSync")

Examples

# Load a test project
projects$test_names() # available test projects
project <- setup_project("TEST_CLASSIC", dir_path = tempdir())

# Sync data from REDCap
project$sync()

# Access data and metadata
head(project$data$text)
project$metadata$fields[1:5, ]

forms <- project$metadata$forms # unchanged metadata
fields <- project$metadata$fields # unchanged metadata
choices <- project$metadata$choices # unchanged metadata

users <- project$redcap$users # unchanged users
log <- project$redcap$log # unchanged log

project$test_token()

dataset <- project$load_dataset("REDCapSync")

Manage REDCapSync projects

Description

projects is the central interface for managing REDCap projects in REDCapSync. It provides a convenient, persistent registry of projects that can be accessed across R sessions.

Each time a project is set up or synced, basic metadata is stored locally so that projects can be reloaded and updated without reconfiguration.

Usage

projects

Format

A named list of functions for managing REDCapSync projects.

Details

projects is implemented as a singleton list object and serves as a single entry point to the REDCapSync workflow. All project-level operations—such as setup, loading, syncing, and removal—are accessed through this object.

A key advantage of this design is support for method chaining, even without loading the namespace. Because many project methods return project objects, you can write concise, readable workflows that operate in sequence:

# load, sync, and generate dataset to global
REDCapSync::projects$load("TEST_CLASSIC")$
  sync()$
  generate_dataset(envir = globalenv(),
                   filter_field = "var_branching",
                   filter_choices = "Yes")

Methods

print()

Display a summary of all registered projects.

• Shows total number of projects

• Lists project names

• Indicates how many are due for sync

Returns the project data frame invisibly.

any()

Check whether any projects are registered.

Returns a logical scalar.

n()

Return the number of registered projects.

Returns an integer.

names()

Return the names of registered projects.

Returns a character vector.

test_names()

Return the names of test projects.

Returns a character vector.

df()

Retrieve the project registry as a data frame.

Returns a data frame containing stored project metadata.

load(project_name)

Load a project by name. This is a wrapper for load_project.

Arguments

• project_name: Character. Name of the project.

Returns a REDCapSyncProject object.

See Also

vignette("REDCapSync", package = "REDCapSync") vignette("Cache", package = "REDCapSync") vignette("RosyREDCap", package = "REDCapSync") setup_project for initializing projects project for using the project objects

Examples

project_df <- projects$df()
projects$print()
projects$any()
projects$n()
projects$names()
project <- projects$load("TEST_CLASSIC")

Setup or Load REDCapSync Project

Description

Setup or load a REDCapSync project object. Prepares a new REDCapSync project by recording the REDCap URI, token name, sync settings, and optional data selection preferences.

Usage

setup_project(
  project_name,
  dir_path,
  redcap_uri,
  token_name = paste0("REDCAPSYNC_", project_name),
  sync_frequency = "daily",
  labelled = TRUE,
  get_type = "identified",
  records = NA,
  fields = NA,
  forms = NA,
  events = NA,
  filter_logic = NA,
  id_position = 1L,
  get_users = TRUE,
  get_data = TRUE,
  batch_size_download = 1000L,
  batch_size_upload = 500L,
  get_entire_log = FALSE,
  log_days = 10L,
  log_drop_details = FALSE,
  log_drop_exports = FALSE,
  get_files = FALSE,
  get_file_repository = FALSE,
  original_file_names = FALSE,
  add_default_datasets = TRUE,
  timezone = Sys.timezone(),
  hard_reset = FALSE
)

load_project(project_name)

Arguments

Details

Unless hard_reset = TRUE, it will first attempt to load an existing project from cache or the supplied dir_path before creating a new project object. If settings differ from the loaded project, they will be used or it will trigger a hard reset with a warning. setup_project() itself does not perform a full REDCap sync. It configures the project so that subsequent sync actions may retrieve data, users, files, and logs according to the project settings.

Value

R6 project object with REDCapSyncProject class.

See Also

vignette("REDCapSync", package = "REDCapSync") vignette("Tokens", package = "REDCapSync") projects for shortcuts of cached setup projects project for using the project objects vignette("Cache", package = "REDCapSync")

Examples

# Initialize the project object with the REDCap API token and URL
save_folder <- tempdir() # replace with real folder
project <- setup_project(
  project_name = "FIRST_PROJECT",
  dir_path = save_folder,
  redcap_uri = "https://redcap.yourinstitution.edu/api/"
)

# object can be named whatever you choose to assign
# TEST projects can be loaded in addition to real projects
project_test <- load_project("TEST_CLASSIC")

Synchronize REDCap Data

Description

Syncs with REDCap via project object that user defined with setup_project

Usage

sync(
  project_names = NULL,
  save_datasets = TRUE,
  hard_check = FALSE,
  hard_reset = FALSE
)

Arguments

Details

Syncs all projects by default but can be used to hands-free sync one or defined set projects. This is not intended to return project object. User should use load_project("project_name"). However, by default will invisibly return the last project in the set of project_names.

Value

Invisibly returns last project object (R6 REDCapSyncProject class)

See Also

vignette("REDCapSync", package = "REDCapSync") vignette("Cache", package = "REDCapSync") setup_project for initializing projects project for using the project objects

Examples

## Not run: 
# if you setup 3 projects "ONE", "TWO", "THREE" using [setup_project()]...
sync() # will check all three projects for updates if due for sync
sync("TWO") # will only check and sync project TWO
project <- sync("TWO") # can also be used for invisible return ...
sync(c("ONE","THREE")) # will only check and sync projects ONE and THREE
project <- sync(c("ONE","THREE")) # invisible return of THREE ...

## End(Not run)