% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/entity_versions.R
\name{entity_versions}
\alias{entity_versions}
\title{List versions of one Entity.}
\usage{
entity_versions(
  pid = get_default_pid(),
  did = "",
  eid = "",
  conflict = FALSE,
  url = get_default_url(),
  un = get_default_un(),
  pw = get_default_pw(),
  retries = get_retries(),
  odkc_version = get_default_odkc_version(),
  orders = get_default_orders(),
  tz = get_default_tz()
)
}
\arguments{
\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{did}{(chr) The name of the Entity List, internally called Dataset.
The function will error if this parameter is not given.
Default: "".}

\item{eid}{(chr) The UUID of an Entity, which can be retrieved by
\code{entity_list()}.
The function will error if this parameter is not given.
Default: "".}

\item{conflict}{(lgl) Whether to return all versions (\code{FALSE}) or
whether to returns the subset of past versions of an Entity that are
relevant to the Entity's current conflict (\code{TRUE}).
This includes the latest version, the base version, the previous
server version, and any other versions since the last time the Entity was
in a conflict-free state. If the Entity is not in conflict, zero versions
are returned.
Default: \code{FALSE} (return all versions)}

\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{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{orders}{(vector of character) Orders of datetime elements for
lubridate.

Default:
\code{c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd")}.}

\item{tz}{A timezone to convert dates and times to.

Read \code{vignette("setup", package = "ruODK")} to learn how \code{ruODK}'s
timezone can be set globally or per function.}
}
\value{
A tibble with one row per version. List columns contain unstructured
data.
See \url{https://docs.getodk.org/central-api-entity-management/#listing-versions}
for the full schema.
Top level list elements are renamed from ODK's \code{camelCase} to \code{snake_case}.
Nested list elements have the original \code{camelCase}.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#maturing}{\figure{lifecycle-maturing.svg}{options: alt='[Maturing]'}}}{\strong{[Maturing]}}
}
\details{
This returns the Entity metadata and data for every version of this Entity
in ascending creation order.

The ODK Central endpoint supports retrieving extended metadata which this
function always returns.

There is an optional query flag \code{relevantToConflict} that returns the subset
of past versions of an Entity that are relevant to the Entity's current
conflict. This includes the latest version, the base version, the previous
server version, and any other versions since the last time the Entity was
in a conflict-free state. If the Entity is not in conflict, zero versions
are returned.
}
\examples{
\dontrun{
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...")

el <- entitylist_list()

# Entity List name (dataset ID, did)
did <- el$name[1]

# All Entities of Entity List
en <- entity_list(did = did)

ed <- entity_detail(did = did, eid = en$uuid[1])

# The current version of the first Entity
ev <- en$current_version_version[1]
}
}
\seealso{
\url{https://docs.getodk.org/central-api-entity-management/#listing-versions}

Other entity-management: 
\code{\link{entity_audits}()},
\code{\link{entity_changes}()},
\code{\link{entity_create}()},
\code{\link{entity_delete}()},
\code{\link{entity_detail}()},
\code{\link{entity_list}()},
\code{\link{entity_update}()},
\code{\link{entitylist_detail}()},
\code{\link{entitylist_download}()},
\code{\link{entitylist_list}()},
\code{\link{entitylist_update}()}
}
\concept{entity-management}
