---
title: "Manage your Sessions"
description: "List, create, and control participant sessions in your runs"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Manage your Sessions}
  %\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)
  })
}
```

Managing sessions is a critical part of maintaining a study. Whether you are debugging an issue with a participant, cleaning up test data, or generating codes for participants, the formr package provides tools to inspect and control sessions directly from R.

## Listing Sessions

To get an overview of who is currently in your study, use `formr_api_sessions()`. This function returns a tidy data frame containing session codes, their current position in the run, and timestamps.

### Filter by Status

You can filter sessions to see only those that are currently active or those marked as test sessions.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# List all active sessions (participants currently in the study)
active_users <- formr_api_sessions("my-run-name", active = TRUE)

# List all test sessions (e.g., generated by you)
test_users <- formr_api_sessions("my-run-name", testing = TRUE)
```

### Pagination

For runs with many sessions, use `limit` and `offset` to page through results (default limit is 1000).

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Get sessions 101-200
sessions_page <- formr_api_sessions("my-run-name", limit = 100, offset = 100)
```

### Find Specific Participants

If you know a participant's session code (e.g., from a user report), you can fetch their details directly to see exactly where they are.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Inspect a specific user
user_status <- formr_api_sessions("my-run-name", session_codes = "USER_CODE_123")
dplyr::glimpse(user_status)
```

## Creating Sessions

While users typically create their own sessions by clicking a link, you might need to generate sessions programmatically. This is common for:

1.  **Laboratory Studies:** Pre-generating codes to hand out to participants.
2.  **Automated Testing:** Creating dummy users to test your study flow.

```{r, eval = .formr_vcr}
# Create a random session code for testing
vcr::use_cassette("formr_api_create_session_basic", {
  new_sessions <- formr_api_create_session("test-run", testing = TRUE, verbose = FALSE)
})
new_sessions$count_created
```

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Create a session with a specific code (e.g., for a specific ID)
# Please be sure that your session codes are in an allowed format on your server.
formr_api_create_session("my-run-name", codes = c("LAB_001", "LAB_002"))
```

## Controlling Sessions (Actions)

Sometimes you need to intervene in a participant's progress. The `formr_api_session_action()` function allows you to modify the state of one or more sessions.

### Use Case 1: Unsticking a User (Move Position)

If a bug or logic error causes a user to get stuck at a specific point, you can manually move them to a different unit in the run.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Move user to position 10 (e.g., the next survey)
formr_api_session_action("my-run-name",
                     session_codes = "STUCK_USER_CODE", 
                     action = "move_to_position", 
                     position = 10)
```

### Use Case 2: Cleaning Data (Toggle Testing)

If you accidentally performed a self-test with a "real" session code, or if a real participant used a test code, you can toggle the testing flag. This helps keep your data clean/separate.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Mark a real session as a test session
formr_api_session_action("my-run-name",
                     session_codes = "REAL_USER_CODE", 
                     action = "toggle_testing")
```

### Use Case 3: Ending Sessions

If you want to manually finish an external module for a session, you can do it with the "end_external" action.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# End a session
formr_api_session_action("my-run-name",
                     session_codes = "WITHDRAWN_USER_Code", 
                     action = "end_external")
```