---
title: "Manage your Runs"
description: "Create, configure, export, and delete runs using the API"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Manage your Runs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(formr)

# So this vignette runs offline, API calls are replayed from pre-recorded
# responses (vcr cassettes shipped with the package). With a real server you
# would instead call formr_api_authenticate() with your own host/credentials.
.formr_vcr <- requireNamespace("vcr", quietly = TRUE) &&
  nzchar(system.file("extdata/vcr_cassettes", package = "formr"))

if (.formr_vcr) {
  vcr::vcr_configure(
    dir = system.file("extdata/vcr_cassettes", package = "formr"),
    filter_sensitive_data = list(
      "formr-client-id-redacted"     = "dummy_client_id",
      "formr-client-secret-redacted" = "dummy_client_secret",
      "formr-host-redacted"          = "api.localhost"
    )
  )
  vcr::use_cassette("formr_api_authenticate", {
    formr_api_authenticate(host = "http://api.localhost",
      client_id = "dummy_client_id", client_secret = "dummy_client_secret",
      verbose = FALSE)
  })
}
```

While the `formr_api_push_project` and `formr_api_pull_project` functions are excellent for managing file-based assets (surveys, CSS, images), sometimes you need direct control over the run's configuration on the server.

The `formr` package provides a suite of lower-level functions to create, configure, inspect, and delete runs programmatically.

## Listing Your Runs

To see an overview of all studies you have access to, use `formr_api_runs()`. This returns a tidy data frame containing the run ID, name, and status flags (whether it is public, locked, or has active cron jobs).

```{r, eval = .formr_vcr}
# List all runs and their status
vcr::use_cassette("formr_api_runs_list", {
  runs <- formr_api_runs()
})

# Quickly check which runs are currently active/public
subset(runs, public == TRUE)
```

## Creating a New Run

You can create a new, empty run directly from R. This is useful if you are setting up a battery of studies programmatically.

```{r, eval = .formr_vcr}
# Create a new run named "test-run"
vcr::use_cassette("formr_api_runs_create", {
  formr_api_create_run("test-run", verbose = FALSE)
})
```

The function returns the public link to your new run upon success.

## Configuring Run Settings

Once a run exists, you often need to toggle its settings—for example, locking it to prevent accidental edits during data collection or making it public for participants.

The `formr_api_run_settings()` function handles this.

-   **GET:** If you provide only the run name, it returns the current settings.

-   **PATCH:** If you provide a `settings` list, it updates the run.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# 1. View current settings
settings <- formr_api_run_settings("pilot-study-v1")

# 2. Update settings: Lock the run and make it public
formr_api_run_settings("pilot-study-v1", settings = list(
  locked = TRUE,     # Prevent structure changes
  public = 2,      # Allow participants to access via Link
  expiresOn = "2026-12-31" 
  # Set Data Expiration Date (required to make your Run public)
))
```

## Managing Run Structure (JSON)

The "Structure" of a run is the ordered list of units (surveys, emails, pauses, jumps) that determines the participant's path. You can export this structure to JSON for safekeeping or import it to replicate a study design.

### Exporting Structure

You can inspect the structure as an R list or save it directly to a JSON file to create a 1:1 backup of the runs configuration.

```{r, eval = .formr_vcr}
# Inspect structure in R
vcr::use_cassette("formr_api_run_structure_import", {
  struct <- formr_api_run_structure("test-run")
})
print(struct)
```

```{r, eval = FALSE}
# Not run: writes a file and needs a live server.
# Save to file (Backup)
formr_api_run_structure("pilot-study-v1", file = "pilot_v1_structure.json")
```

### Importing Structure

You can upload a JSON file to replace the current run structure. This is useful for creating templates: you can define a complex flow once and apply it to multiple runs. If they are part of your JSON file, this will also create the necessary surveys for the run.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Overwrite the run's structure with a local JSON file
formr_api_run_structure("pilot-study-v1", structure_json_path = "pilot_v1_structure.json")
```

## Deleting a Run

You can permanently delete a run if it was created by mistake or is no longer needed.

**Warning:** This will remove everything associated with the run, including the structure, attached files, and all collected results. However, the surveys used in the run will be kept.

```{r, eval = .formr_vcr}
# Delete a run (prompts for confirmation by default)
vcr::use_cassette("formr_api_runs_delete", {
  formr_api_delete_run("test-run", prompt = FALSE)
})
```

```{r, eval = FALSE}
# Force delete without confirmation (for automated scripts)
formr_api_delete_run("pilot-study-v1", prompt = FALSE)
```