COVID Sample Tracker

About

COVIDTrack was developed to provide a kiosk user interface for submitting blood samples and to track sample status during processing.

COVIDTrack is written with the Symfony Framework and uses a MySQL database.

Workflow

• Participant and sample identification

  • Participants in the study were assigned a unique QR code to be used for sample submission.
  • A unique 1D barcode was generated by COVIDTrack and added to blood collection tubes during kit assembly.
  • Participants returned collected blood samples to a COVIDTrack kiosk and scanned their participant QR code and the tube ID.

• Sample Check-In

  • Submitted sample tubes were individually inspected and classified as Accepted or Rejected.
    • Samples with volume at or above the pre-printed line on the tube were Accepted.
    • Samples with leaks or volume below the pre-printed line were Rejected.
  • A Bluetooth barcode scanner was used inside a biosafety cabinet to scan the tube ID on the sample tube and place it in a 96-well tube rack.
  • A 2D barcode on a 0.3 ml Biobank tube is scanned to assign the blood sample to a storage tube and placed in a matching well coordinate of a Biobank well plate frame.
  • The Biobank well plate frame barcode is scanned, and the well location recorded.
  • Once all tubes have been scanned and designated as Accepted or Rejected, the scanned data is imported in COVIDTrack to update the location and status of samples.

• Tube ID to Specimen ID conversion

  • To support deidentified sample processing, the Tube ID is converted to a Specimen ID following the sample check-in import.
  • Well plate information including Specimen ID and well coordinates are downloaded for use in off-line processing.

• Test Results

  • Specimen ID and Biobank ID are assigned a test conclusion (Positive, Negative, Non-Negative)
  • Data is imported into COVIDTrack to assign results to the submitted sample.

Development Environment - Docker

1. Download and install Docker
2. docker-compose up -d
3. docker-compose exec app /app/bin/setup.php --local-env-from=.env.docker --rebuild-database – This configures .env, creates database, loads fake data
4. Open Docker Application URL http://localhost:8880/specimens/

Enter the container before running any PHP, Symfony, or yarn commands:

docker-compose exec app /bin/bash

If changing Dockerfile, rebuild the containers:

docker-compose up --build -d

Docker JS and CSS assets

Recompile frontend assets after changing package.json, using yarn add, or changing CSS:

$ docker-compose exec app yarn dev

Alternatively you can run yarn watch for automatic recompiling.

Docker Environment Variables

Such as configuring for LDAP or setup.php script. Edit docker-compose.yml in each service's environment section:

# docker-compose.yml
services:
    app:
        environment:
            SFAPP_NOT_PRODUCTION: "true"

Development Environment - Symfony Server

Instead of using Docker, develop with tools installed directly on the host machine:

• PHP 7.1.3+ configured with support for sqlite
• Composer v1
• Symfony CLI application
• SQLite
• yarn command

1. Copy .env.sqlite.dist to .env.local

   cp .env.sqlite.dist .env.local

2. Install dependencies with composer

   composer install

3. Install dependencies with yarn and run initial build

   yarn install
   yarn dev
   

4. Create database

   bin/console doctrine:schema:create
   

5. Start the Symfony web server

   symfony serve

6. Access at http://localhost:8080/ (or wherever symfony serve indicates)

Running Automated Tests

Tests written using PHPUnit and executed using Symfony PHPUnit Bridge.

Run test suite from command-line of a local development environment:

$ bin/run-tests.sh

To run on a CI server, create a fresh local development environment then run:

$ git clone ...
$ bin/setup.php --for-local-development
$ bin/run-tests.sh

Data Fixtures

Fake data is managed by DoctrineFixturesBundle.

To load fake data and clear out all existing database data:

$ bin/console doctrine:fixtures:load -n

Or add the --append flag to keep existing database data and append fake data:

$ bin/console doctrine:fixtures:load -n --append

Create new fixtures in src/DataFixtures/AppFixtures.php

Login to dev environment with fixtures loaded

These users are available when fixtures are loaded. Same username/password:

• ctadmin - Sysadmin / Developer
• coordinator - Study Coordinator
• mediaprep - Media Prep Team (specimen collection kit management)
• samplecollection - Sample Collection Team
• testingtech - Viral Testing Team / Results
• analysistech - Viral Analysis Team
• kiosk - Kiosk UI

Development Environment - Monitoring Sent Email

Use Mailhog as a Docker image to see email sent by the application:

$ docker run --rm -p8025:8025 -p1025:1025 mailhog/mailhog

Add environment var MAILER_DSN to file .env.local:

# .env.local
MAILER_DSN=smtp://127.0.0.1:1025

Perform actions that would normally send an application email.

View mail in Mailhog: http://0.0.0.0:8025

Configuration

Enabling LDAP / Active Directory Authentication

The following environment variables are available:

• LDAP_HOST (required) LDAP server hostname
• LDAP_PORT (default 389) port to communicate on
• LDAP_ENCRYPTION (default none) Valid values are none, ssl, tls
• LDAP_PROTOCOL_VERSION (default 3)
• LDAP_REFERRALS (default false)
• LDAP_AUTH_BASE_DN DN to use when searching for users
• LDAP_AUTH_SEARCH_DN User to log in as when checking if a user or their credentials are valid (eg. "user@EXAMPLE.COM" or "cn=read-only-admin,dc=example,dc=com")
• LDAP_AUTH_SEARCH_PASSWORD Password to use when authenticating as LDAP_AUTH_SEARCH_DN
• LDAP_AUTH_USER_DN_FORMAT DN to use when looking up a user to authenticate. For example: {username}@company.com

Active Directory Example

Add to .env.local or otherwise define them in the environment.

LDAP_HOST=directory.contoso.com
LDAP_AUTH_BASE_DN=DC=contoso,DC=com
LDAP_AUTH_SEARCH_DN=serviceaccount@CONTOSO.COM
LDAP_AUTH_SEARCH_PASSWORD=hunter2
LDAP_AUTH_USER_DN_FORMAT={username}@CONTOSO.COM

Frontend Frameworks

• AdminLTE Theme 2.4.18 application theme – Documentation
• Bootstrap 3.4.1 has built-in styles and components
• Font Awesome 5.13 for extra icons