ClinSpark Extension — Vinh Truong

The Problem

ClinSpark build and maintenance work involves repeated UI tasks: selecting rows, opening records, filling related fields, saving pages, waiting for redirects, checking mapping status, copying forms, adjusting windows, previewing forms, and validating item metadata. On studies with many forms or activity-plan rows, manual work becomes slow and easy to mis-click.

Study builders repeat the same careful configuration steps across dozens or hundreds of records.
Multi-page workflows must survive redirects, slow tables, modals, Select2 widgets, and delayed saves.
Automation needs visible progress, confirmation prompts, cancellation, and recovery so users stay in control.
Production and test ClinSpark environments need different tools while keeping browser permissions narrow.

Solution Overview

Docked Panel

In-page automation panel with right-side and bottom-dock layouts
Persistent width, height, dock choice, theme, logs, hotkey, button order, and button visibility
Floating launcher, pause/resume, clear logs, hide/show logs, settings, and searchable help

Build Workflows

PLAP Builder, Copy A-Plan, Import From Library, Copy Activity Forms, Archive/Update Forms, Edit Forms, and Activity Plan Removal
Selection panels, source/target form handling, segment grouping, saved windows, progress tracking, and recovery state
Safer add/update flows that preserve fields unless a workflow explicitly needs to change them

Mapping & Review

Import I/E, Clear Mapping, Set Visibility Condition, Edit Item Reference, Item Method Forms, Parse Study Event, and Parse Forms
Duplicate detection, filtered Select All behavior, row verification, staged edits, and detailed result reporting
Form Preview renders unlocked library forms for review before locking, importing, or mapping

Subject & Test Tools

Run Form, Collect All, Add Cohort Subjects, Import Cohort Subjects, Add Existing Subject, Run ICF Consent, Lock Activity Plans, Lock Sample Paths, and Update Study Status
Barcode and lab barcode tools, print barcode workflows, cohort/subject eligibility lookup, and study setup pipelines
Run-mode routing and queue state continue safely after navigation and refreshes

Complete Feature Catalog

The extension exposes different button sets for ClinSpark production and test environments while sharing the same docked panel, logging, settings, pause/resume, and workflow recovery infrastructure.

Production Panel Features

Pull Barcode and Pull Lab Barcode
PLAP Builder and Activity Plan Removal
Import From Library, Archive/Update Forms, Edit Forms, Copy Activity Forms, and Copy A-Plan
Search Methods, Item Method Forms, Find Form & Events, Parse Study Event, Parse Forms, and Parse Deviation
Import I/E, Clear Mapping, Set Visibility Condition, Edit Item Reference, Form Preview, and Edit Study Events List
Cohort Eligibility and Subject Eligibility
Download DTS Report, Print Barcodes, and Auto-Resaver
Pause, Clear Logs, Hide Logs / Show Logs, panel settings, searchable help guide, docked panel hotkey, and floating blue lightning launcher

Test Panel Features

Lock Activity Plans, Lock Sample Paths, Update Study Status, and Run Study Setup
Add Cohort Subjects, Import Cohort Subjects, Add Existing Subject, and Run ICF Consent
Run Form and Collect All for test data-collection workflows
Pull Barcode and Pull Lab Barcode
PLAP Builder, Import From Library, Archive/Update Forms, Copy Activity Forms, Copy A-Plan, and Activity Plan Removal
Import I/E, Clear Mapping, Edit Item Reference, Set Visibility Condition, Item Method Forms, Find Form & Events, Edit Study Events List, Search Methods, and Download DTS Report
Pause, Clear Logs, Hide Logs / Show Logs, panel settings, searchable help guide, docked panel hotkey, and floating blue lightning launcher

Feature Details

Panel & Controls

Injects a right-side or bottom-docked ClinSpark panel and offsets the host page so the extension does not cover important content.
Persists layout, theme, button ordering, button visibility, named loadouts, logs preference, and configurable hide/show hotkey.
Provides fullscreen dialogs, warning/confirmation/progress/success/failure popups, wrong-page links, searchable help, and a floating launcher.

Activity Plan Automation

PLAP Builder builds and edits procedure log activity plan rows with source/target form selection, segment grouping, saved windows, time calculations, and add/update modes.
Copy A-Plan copies one form or all forms from a selected source segment into a selected target segment while preserving required timing fields.
Activity Plan Removal scans rows, marks archive status, supports search and filtered Select All, and tracks success, skipped, and failed removals.

Library & Form Tools

Import From Library scans and caches library forms, stages form/item renames, supports duplicate imports, controls lock-on-save behavior, and resumes after navigation.
Form Preview renders unlocked library forms in read-only collection-style previews with prompts, item groups, codelists, decoded values, roles, help text, and upload controls.
Edit Forms and Archive/Update Forms support batch review, changed-form detection, non-lock versus lock changes, visibility properties, modal verification, progress tracking, and failure reporting.

Mappings & References

Import I/E parses eligibility item pool codes, detects existing mappings, applies sex-related defaults, supports ignore keywords, and tracks completed, failed, and excluded items.
Clear Mapping verifies row identity before deletion, extracts delete URLs, supports searchable selection, and applies filtered Select All only to visible rows.
Edit Item Reference stages Name, Prompt, SAS Field Name, and Code List updates, including I/E renumbering and inclusion/exclusion codelist targeting.

Study Event & Parsing Tools

Edit Study Events List collects rows, supports natural sorting, adds and updates study event data, resumes after reload, and reports added/updated/error counts.
Parse Study Event extracts day numbers, group labels, affixes, screening events, subject events, and structured output columns.
Parse Forms and Parse Deviation generate copyable structured outputs from form lists and paginated deviation result tables.

Find, Search & Eligibility

Search Methods opens the methods library, searches by identifier or item name, displays matches, and tracks recent method lookups.
Item Method Forms locates methods and related forms for a requested item while using extension-compatible request logic.
Find Form & Events, Cohort Eligibility, and Subject Eligibility search subject and data-collection pages, apply status filters, open matched results, and clear stale state.

Barcode & Report Tools

Barcode tools pull subject and lab barcode values, open data-entry modals, fill barcode dialogs sequentially, track progress, and clean stale state.
Print Barcodes supports label and barcode run modes, label scan/auto-fill workflows, subject tracking, stale-state detection, and run-mode cleanup.
Download DTS Report lets users select studies and report types, generates clinical data and mapping reports, opens result links, and reports completed and failed downloads.

Test & Subject Setup

Run Form and Collect All process selected forms, item groups, repeating item groups, value modes, range specs, exclusions, and failures.
Lock Activity Plans, Lock Sample Paths, and Update Study Status participate in a larger Run Study Setup pipeline with continuation state.
Add Cohort Subjects, Import Cohort Subjects, Add Existing Subject, and Run ICF Consent automate cohort, epoch, subject, activation, and consent barcode flows.

State & Recovery Infrastructure

Maintains localStorage run modes, pending IDs, selected volunteer IDs, cohort guards, continuation epochs, eligibility state, mapping state, and after-refresh flags.
Parses HTML responses, waits for required elements, automates Select2 dropdowns, normalizes visible text, opens pages in tabs, and provides close-tab fallbacks.
Detects stale workflow state, clears completed runs, logs workflow actions, and lets long workflows pause, resume, cancel, or recover after redirects.

Technical Highlights

Chrome Manifest V3 extension with environment-scoped content scripts for ClinSpark production and test.
Vanilla JavaScript UI injection, DOM automation, Select2 dropdown handling, modal automation, and local browser storage.
Queue-based batch processing across navigation events with defensive waits for slow pages, large tables, redirects, and delayed saves.
Narrow ClinSpark-only host permissions, no broad browser access, no remote code loading, and no external data collection.

Tech Stack

JavaScriptChrome Extension APIManifest V3Content ScriptsDOM AutomationSelect2MutationObserverlocalStorage

Screenshots

ClinSpark Extension docked panel inside ClinSpark showing automation buttons and controls — Docked panel inside ClinSpark

ClinSpark Extension function list showing available automation workflows — Function catalog and workflow controls

Challenges & Solutions

Slow enterprise pages: The extension waits for tables, modals, async dropdowns, redirects, and delayed saves before moving to the next action.
Workflow continuity: localStorage run modes, pending queues, and cleanup guards let long workflows resume or recover after page navigation.
Automation safety: Confirmation dialogs, filtered selection, destructive-action warnings, row validation, cancellation, and detailed logs reduce accidental broad edits.
Extension migration: Userscript-style automation was adapted for MV3 content scripts, replacing unsupported userscript APIs and preparing versioned deployable ZIPs.

Outcomes & Impact

Turned a collection of custom ClinSpark automations into a packaged, versioned, installable productivity tool.
Reduced repetitive manual configuration across forms, activity plans, eligibility mappings, item references, subjects, and barcode workflows.
Improved consistency and review quality through form previews, scoped selection panels, logs, and safer batch operations.
Kept permissions narrow and workflow state local to the browser while supporting production and test environments.