% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/submission_export.R
\name{submission_export}
\alias{submission_export}
\title{Export all form submissions including repeats and attachments to CSV.}
\usage{
submission_export(
  local_dir = here::here(),
  overwrite = TRUE,
  media = TRUE,
  repeats = TRUE,
  pid = get_default_pid(),
  fid = get_default_fid(),
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  pp = get_default_pp(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  verbose = get_ru_verbose()
)
}
\arguments{
\item{local_dir}{The local folder to save the downloaded files to,
default: \code{here::here}.}

\item{overwrite}{Whether to overwrite previously downloaded zip files,
default: FALSE}

\item{media}{Whether to include media attachments, default: TRUE.
This feature only has effect on ODK Central v1.1 and higher.
Setting this feature to FALSE with an odkc_version < 1.1 and will display a
verbose noop message, but still return all media attachments.}

\item{repeats}{Whether to include repeat data (if TRUE), or whether
to return the root table only (FALSE). Default: TRUE.
Requesting \code{repeats=FALSE} will also omit any media, and override the
parameter \code{media}.
Setting this feature to FALSE with an odkc_version < 1.1 and will display a
verbose noop message, but still include all repeat data.}

\item{pid}{The numeric ID of the project, e.g.: 2.

Default: \code{\link{get_default_pid}}.

Set default \code{pid} through \code{ru_setup(pid="...")}.

See \code{vignette("Setup", package = "ruODK")}.}

\item{fid}{The alphanumeric form ID, e.g. "build_Spotlighting-0-8_1559885147".

Default: \code{\link{get_default_fid}}.

Set default \code{fid} through \code{ru_setup(fid="...")}.

See \code{vignette("Setup", package = "ruODK")}.}

\item{url}{The ODK Central base URL without trailing slash.

Default: \code{\link{get_default_url}}.

Set default \code{url} through \code{ru_setup(url="...")}.

See \code{vignette("Setup", package = "ruODK")}.}

\item{un}{The ODK Central username (an email address).
Default: \code{\link{get_default_un}}.
Set default \code{un} through \code{ru_setup(un="...")}.
See \code{vignette("Setup", package = "ruODK")}.}

\item{pw}{The ODK Central password.
Default: \code{\link{get_default_pw}}.
Set default \code{pw} through \code{ru_setup(pw="...")}.
See \code{vignette("Setup", package = "ruODK")}.}

\item{pp}{The passphrase for an encrypted form.

Default: NULL.

Passphrases can be stored e.g. as environment variables.

See \code{vignette("Setup", package = "ruODK")}.}

\item{retries}{The number of attempts to retrieve a web resource.

This parameter is given to \code{\link[httr]{RETRY}(times = retries)}.

Default: 3.}

\item{odkc_version}{The ODK Central version as a semantic version string
(year.minor.patch), e.g. "2023.5.1". The version is shown on ODK Central's
version page \verb{/version.txt}. Discard the "v".
\code{ruODK} uses this parameter to adjust for breaking changes in ODK Central.

Default: \code{\link{get_default_odkc_version}} or "2023.5.1" if unset.

Set default \code{get_default_odkc_version} through
\code{ru_setup(odkc_version="2023.5.1")}.

See \code{vignette("Setup", package = "ruODK")}.}

\item{verbose}{Whether to display debug messages or not.

Read \code{vignette("setup", package = "ruODK")} to learn how \code{ruODK}'s
verbosity can be set globally or per function.}
}
\value{
The absolute path to the exported ZIP file named after the form ID.
The exported ZIP file will have the extension \code{.zip} unless only the
root table was requested (with \code{repeats=FALSE}), in which case the
exported file will have the extension \code{.csv}.
In contrast to ODK Central, which exports to \code{submissions.csv(.zip)},
the exported ZIP file is named after
the form to avoid accidentally overwriting the ZIP export from
another form.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#maturing}{\figure{lifecycle-maturing.svg}{options: alt='[Maturing]'}}}{\strong{[Maturing]}}
}
\details{
This function exports all the Submission data associated with a Form as one
zip file containing one or more CSV files, as well as all multimedia
attachments associated with the included Submissions.

For an incremental download of a subset of submissions, use
\code{\link{submission_list}} or \code{\link{odata_submission_get}} with
filter queries.
\subsection{Contents}{

The inclusion of subtables (from repeating form groups) can be toggled
through \code{repeats}, whereas the inclusion of media attachments can be toggled
through \code{media}.
}

\subsection{Download location}{

The file will be downloaded to the project root unless specified otherwise
(via \code{local_dir}). Subsequently, the zip file can be extracted.
Attachment filenames (e.g. "12345.jpg") should be prepended with \code{media}
(resulting in e.g. \verb{media/12345.jpg}) in order to represent the relative
path to the actual attachment file (as extracted from the zip file).
}

\subsection{Encryption}{

ODK Central supports two modes of encryption - learn about them
\href{https://docs.getodk.org/central-api-encryption/}{here}.
\code{ruODK} supports project managed encryption, however the support is limited
to exactly one encryption key. The supplied passphrase will be used against
the first returned encryption key. Remaining encryption keys are ignored by
\code{ruODK}.

If an incorrect passphrase is given, the request is terminated immediately.
It has been reported that multiple requests with incorrect passphrases
can crash ODK Central.
}
}
\examples{
\dontrun{
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...")

se <- submission_export()

# Unzip and inspect the loot
t <- tempdir()
f <- unzip(se, exdir = t)
fs::dir_ls(t)
fid <- get_test_fid()
sub <- fs::path(t, glue::glue("{fid}.csv")) \%>\% readr::read_csv()
sub \%>\% knitr::kable(.)
}
}
\seealso{
\url{https://docs.getodk.org/central-api-submission-management/#exporting-form-submissions-to-csv}

Other submission-management: 
\code{\link{attachment_list}()},
\code{\link{encryption_key_list}()},
\code{\link{submission_audit_get}()},
\code{\link{submission_detail}()},
\code{\link{submission_get}()},
\code{\link{submission_list}()}
}
\concept{submission-management}
