Technical Integrations & Workflows

API Integration Pattern

Every Qualtrics API call is authenticated with an X-API-TOKEN header. The token is stored as a GitHub Actions secret in the qualtrics-prod environment and is never committed to the repository. Workflows and scripts resolve the base URL and survey ID from environment variables, making it straightforward to point the automation at a different survey or datacenter.

Automated Workflows

Seven GitHub Actions workflows automate different aspects of Qualtrics management:

Annual Survey Rollover

TABS runs a 10-year data collection effort. Each year, a new copy of the survey is created so that yearly data stays cleanly separated. The recommended rollover sequence:

1. Test connectivity — Run the smoke test workflow to verify credentials.
2. Copy the survey — Use the copy workflow to clone the current survey.
3. Update the environment variable — Point QUALTRICS_SURVEY_ID at the new survey ID.
4. Verify configuration — Run the verification workflow against the new survey.
5. Apply Prolific integration — If the copy didn't preserve Survey Flow branches, re-apply them.
6. Update Prolific — Point the Prolific study's external URL at the new Qualtrics survey link.

How Prolific Connects to Qualtrics

When a Prolific participant starts the study, Prolific opens the Qualtrics survey URL and appends three URL parameters: PROLIFIC_PID, STUDY_ID, and SESSION_ID. Qualtrics captures these as Embedded Data fields, which allows us to link each survey response back to the Prolific submission.

At the end of the survey, the respondent is redirected to the appropriate destination based on the Survey Flow logic. Prolific participants are redirected to Prolific's completion page (with a completion code), while website visitors see a thank-you page on the TABS site.

Automated Data Collection

A GitHub Actions workflow (prolific.yml) runs every Monday at 9:00 AM UTC. It uses a TypeScript client library to query the Prolific API, collecting study metadata, submission statistics, and approval rates. The workflow can also be triggered manually for on-demand checks.

Why We Need This

The survey accepts respondents from two channels. Website visitors click a button on technologyadoptionbarriers.org, which opens the Qualtrics survey with SOURCE=TABS_Website in the URL. Prolific participants are launched by Prolific, which appends PROLIFIC_PID, STUDY_ID, and SESSION_ID as URL parameters.

Without the lockdown, the redirect URL (COMPLETE_URL) could be passed as a URL parameter by anyone, creating an open-redirect vulnerability. The two-branch design hard-codes COMPLETE_URL inside the Survey Flow so that inbound URLs cannot override it.

The Two Branches

After all survey question blocks, the flow contains two conditional branches:

Branch 1 is evaluated first. Because Prolific links typically include SOURCE=prolific, Branch 1 catches Prolific participants and redirects them to the website completion page. This is intentional — the website thank-you page is appropriate for all respondents, and Prolific tracks completion independently via its authenticity script.

Visual Flow Diagram

┌─────────────────────────────────────────────┐
│  Top-Level Embedded Data                    │
│  ├─ PROLIFIC_PID   (captured from URL)      │
│  ├─ STUDY_ID       (captured from URL)      │
│  ├─ SESSION_ID     (captured from URL)      │
│  └─ SOURCE         (captured from URL)      │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  Survey Question Blocks (6 blocks)          │
│  (Demographics, barriers, adoption, etc.)   │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  Branch 1: If SOURCE is not empty           │
│  ├─ Set COMPLETE_URL = website URL          │
│  └─ End Survey → Redirect to website        │
└──────────────────┬──────────────────────────┘
                   │ (only reached if SOURCE
                   │  was empty)
                   ▼
┌─────────────────────────────────────────────┐
│  Branch 2: If PROLIFIC_PID is not empty     │
│  ├─ Set SOURCE = "prolific"                 │
│  ├─ Set COMPLETE_URL = Prolific URL         │
│  └─ End Survey → Redirect to Prolific       │
└─────────────────────────────────────────────┘

The Apply Script

The branches are managed by a TypeScript script (scripts/qualtrics-apply-prolific-integration.ts) that reads the current Survey Flow, removes any existing TABS branches, rebuilds the two branches with hard-coded URLs, and writes the flow back via the Qualtrics API. The script is idempotent — running it multiple times produces the same result.

A companion workflow (qualtrics-prolific-apply.yml) runs this script in GitHub Actions with a safety gate: you must type APPLY to confirm you want to modify the live survey.

Inspecting the Live Flow

A read-only workflow (qualtrics-dump-flow.yml) exports the current Survey Flow JSON. The output is printed to the workflow log and uploaded as a downloadable artifact. This is useful for verifying that the apply script produced the expected result, or for debugging API issues.

Automated Reporting

The daily report workflow (ga-report.yml) uses a service account to authenticate with the GA4 API. It collects metrics like active users, sessions, engagement rate, and top pages, then saves the data to src/data/impact.json for display on the website. A companion script emails the report to the project team.

Verified Visitors Methodology

Raw GA4 numbers can be misleading — 99.6% of recorded traffic came from localhost (Playwright tests, CI runs, AI agents). The "Verified Visitors" metric filters to the production hostname only, showing actual human visitors.

Environments & Secrets

API tokens are stored as GitHub Actions environment secrets — encrypted at rest and never exposed in logs. Each external service has its own environment:

CI/CD Pipeline

Beyond API integrations, GitHub Actions runs the full CI/CD pipeline on every pull request: formatting checks, linting, unit tests (including accessibility tests with jest-axe), static site build, and Playwright end-to-end tests. The site deploys automatically to GitHub Pages when changes merge to the main branch.