% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/setup.R
\name{setup_project}
\alias{setup_project}
\alias{load_project}
\title{Setup or Load REDCapSync Project}
\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{
\item{project_name}{Character scalar. Unique uppercase project name with no
spaces or symbols.}

\item{dir_path}{Optional character scalar. Directory where REDCap project
files are stored. If omitted, the project is only available in the current R
session and cannot be persisted to disk.}

\item{redcap_uri}{Character scalar. Base URL of the REDCap API endpoint.}

\item{token_name}{Optional character scalar. Environment variable name used
to store the REDCap token. Defaults to \verb{REDCAPSYNC_<project_name>}.}

\item{sync_frequency}{Character scalar. Allowed values are "always",
"hourly", "daily", "weekly", "monthly", "once", and "never". This
setting controls how often future syncs are considered due.}

\item{labelled}{Logical scalar. If \code{TRUE}, data will be preserved as labelled
values. Default is \code{TRUE}.}

\item{get_type}{Character scalar. REDCap API export type. One of
"identified", "deidentified", "deidentified_strict", or
"deidentified_super_strict". Default is "identified".}

\item{records}{Optional character vector of record IDs to request.}

\item{fields}{Optional character vector of field names to request.}

\item{forms}{Optional character vector of form names to request.}

\item{events}{Optional character vector of event names to request.}

\item{filter_logic}{Optional character scalar. REDCap filter logic used to
limit returned records or record-events.}

\item{id_position}{Integer scalar of the variable that uniquely identifies
the subject (typically record_id). This defaults to the first variable in the
data dictionary.}

\item{get_users}{Logical scalar. If \code{TRUE}, the project will be configured to
retrieve REDCap users during sync.}

\item{get_data}{Logical scalar. If \code{TRUE}, the project will be configured to
retrieve REDCap data during sync.}

\item{batch_size_download}{Integer scalar. Number of records to request per
download batch. Default is \code{1000}.}

\item{batch_size_upload}{Integer scalar. Number of records to process per
upload batch. Default is \code{500}.}

\item{get_entire_log}{Logical scalar. If \code{TRUE}, REDCap activity logs are
retrieved in full. Default is \code{FALSE}.}

\item{log_days}{Integer scalar. Number of days of log history to consider
when a new project is being set up or a hard reset occurs. Default is \code{10}.}

\item{log_drop_details}{Logical scalar. If \code{TRUE}, the log details are
excluded.}

\item{log_drop_exports}{Logical scalar. If \code{TRUE}, the log export events are
excluded.}

\item{get_files}{Logical scalar. If \code{TRUE}, file attachments are configured
to be retrieved from REDCap. Default is \code{FALSE}.}

\item{get_file_repository}{Logical scalar. If \code{TRUE}, the file repository is
configured to be retrieved from REDCap. Default is \code{FALSE}.}

\item{original_file_names}{Logical scalar. If \code{TRUE}, retrieved files keep
their original names. Default is \code{FALSE}.}

\item{add_default_datasets}{Logical scalar. If \code{TRUE}, dataset templates are
added to a new project. Default is \code{TRUE}.}

\item{timezone}{Optional character scalar. Time zone used for REDCap data
timestamps. Defaults to \code{Sys.timezone()}.}

\item{hard_reset}{Logical scalar. If \code{TRUE}, any existing project with the
same \code{project_name} is ignored and a fresh project object is initialized.
Default is \code{FALSE}.}
}
\value{
R6 project object with \link{REDCapSyncProject} class.
}
\description{
Setup or load a REDCapSync \link{project} object.
Prepares a new REDCapSync project by recording the REDCap URI,
token name, sync settings, and optional data selection preferences.
}
\details{
Unless \code{hard_reset = TRUE}, it will first attempt to load an
existing project from cache or the supplied \code{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. \code{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.
}
\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")

}
\seealso{
\code{vignette("REDCapSync", package = "REDCapSync")}
\code{vignette("Tokens", package = "REDCapSync")}
\link{projects} for shortcuts of cached setup projects
\link{project} for using the project objects
\code{vignette("Cache", package = "REDCapSync")}
}
