Manage your Sessions

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.

# 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).

# 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.

# 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.

# 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
#> [1] 1

# 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.

# 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.

# 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.

# 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")