Skip to content

Quick Start

This guide walks you through creating your first study in Metricis.

Prerequisites

  • Metricis installed and running locally (see Installation)
  • Server running on port 8000
  • Portal running on port 3000

Step 1: Create Admin Account

  1. Visit http://localhost:3000
  2. Click "Sign Up" (or use the /api/auth/register endpoint)
  3. Create an account with:
  4. Email: admin@example.com
  5. Password: (your secure password)
  6. Name: Admin User

Step 2: Create a Study

  1. Log in to the portal
  2. Click "Create Study" on the dashboard
  3. Fill in study details:
  4. Study Name: "My First Study"
  5. Study Code: "STUDY-001"
  6. Description: "A test study for getting started"
  7. Study Type: Select appropriate type
  8. Click "Create Study"

Step 3: Configure Forms

Option A: Use Templates

  1. Navigate to the study overview
  2. Click "Apply Template"
  3. Choose a pre-configured template (e.g., "Basic Neurology Study")
  4. Review and confirm the template application

Option B: Create Custom Forms

  1. Go to Configure → Batteries
  2. Click "Create Battery"
  3. Add cognitive tasks or questionnaires
  4. Save the battery

Step 4: Set Up Visit Schedule

  1. Go to Configure → Schedule
  2. Click "Add Visit Window"
  3. Define visits (e.g., "Baseline", "Week 4", "Month 3")
  4. Assign forms to each visit
  5. Set visit windows (e.g., ±7 days)

Step 5: Enroll Participants

Manual Enrollment

  1. Go to Operate → Participants
  2. Click "Add Participant"
  3. Enter participant details:
  4. Participant ID
  5. Date of enrollment
  6. Contact information (optional)
  7. Click "Enroll"

Bulk Import

  1. Go to Operate → Participants
  2. Click "Import Participants"
  3. Download the template CSV
  4. Fill in participant data
  5. Upload the CSV file

Step 6: Assign Forms

Forms are automatically assigned based on visit windows, but you can manually assign:

  1. Go to Operate → Visits
  2. Select a participant
  3. Click on a visit
  4. Review assigned forms
  5. Manually assign additional forms if needed

Step 7: Complete Assessments

As a Participant (Patient Portal)

  1. Participant receives magic link via email/SMS
  2. Opens link in mobile browser or native app
  3. Completes consent (if configured)
  4. Views assigned assessments
  5. Completes assessments (works offline)
  6. Submits data (syncs when online)

Test Mode (Portal)

  1. Go to Operate → Sessions
  2. Click "Start Test Session"
  3. Select a participant and battery
  4. Complete the assessment
  5. View results in Data Entry

Step 8: Review Data

  1. Go to Operate → Data Entry
  2. View the data entry grid
  3. Review form statuses:
  4. Not Started
  5. In Progress
  6. Complete
  7. Signed
  8. Locked
  9. Check quality badges:
  10. Errors (red)
  11. Warnings (yellow)
  12. Queries (blue)
  13. Review (purple)
  14. SDV (orange)

Step 9: Validation & Queries

View Validation Results

  1. Click on a completed form
  2. View validation findings
  3. Resolve errors and warnings
  4. Mark as reviewed if needed

Manage Queries

  1. Open a form with queries
  2. View query details
  3. Respond to queries
  4. Close resolved queries

Step 10: Export Data

  1. Go to Analyze → Export
  2. Select export format:
  3. CSV
  4. Excel
  5. ODM XML
  6. Choose data to export:
  7. All participants
  8. Selected participants
  9. Date range
  10. Download export file

Next Steps

Common Tasks

Add Validation Rules

  1. Go to form definition
  2. Navigate to "Validation Rules"
  3. Create custom rules:
  4. Required fields
  5. Range checks
  6. Pattern validation
  7. Cross-field validation

Configure REDCap Sync

  1. Go to Configure → REDCap
  2. Enter REDCap API URL and token
  3. Map study events to batteries
  4. Enable bidirectional sync
  5. Test connection

Set Up Notifications

  1. Configure Twilio for SMS (optional)
  2. Configure Firebase for push notifications (optional)
  3. Set up visit reminders
  4. Configure notification cadence

Troubleshooting

Assessments Not Loading

  • Check browser console for errors
  • Verify server is running on port 8000
  • Check CORS configuration in server/.env

Data Not Syncing

  • Check network connection
  • Verify API credentials
  • Check background task status (Celery)

Validation Errors

  • Review validation rules configuration
  • Check SurveyJS schema
  • Verify field names match schema

Getting Help