Skip to contents

Manage your Sessions

manage-your-sessions.Rmd
library(formr)
# Automatically finds your stored keys
formr_api_authenticate(host = "https://api.rforms.org", account = "dashboard") # or your custom URL and account name!

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.

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

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

# 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
new_sessions <- formr_api_create_session("my-run-name", testing = TRUE)

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

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

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

# End a session
formr_api_session_action("my-run-name", 
                     session_codes = "WITHDRAWN_USER_Code", 
                     action = "end_external")