SAM (by SYNDI) Environment Setup Guide

This guide walks you through setting up SAM (SOP Authoring to Models) on your local system, including configuration, dependencies, and starting the development server.

What is SAM?

SAM is a web-based SOP authoring tool that:

  • Creates structured, validated SOPs

  • Ensures consistency across procedures

  • Integrates with CLAIRE for data collection

  • Supports regulatory compliance requirements

Prerequisites

Before using SAM, you need to set up the development environment:

# 1. Set up local environment (first time only)
make setup-local ENV=dev
# This creates local S3 simulation directories and deploys existing configs
# Note: Config files must already exist in infra/.config/ (webapp, lambda)
# If missing, copy from infra/example-.config/ and customize (see 'Frontend Configuration Guide' below)

# 2. Install dependencies
cd frontend
npm install
cd ..

# 3. Start the development server
ENV=dev ORG=any make start-frontend
# Or for full stack (frontend + backend):
ENV=dev ORG=any make start-dev

The server will start on http://localhost:3000

For detailed configuration instructions, see:

Default Development Credentials

When authentication is enabled, use these default development credentials:

  • Email: dev_user@local.dev

  • Password: dev123

Quick Start (5 Minutes)

Step 1: Access SAM

After starting the development server, open your web browser and navigate to:

  • Development: http://localhost:3000/sam

  • Production: Your organization’s SAM URL

Step 2: Create Your First SOP

  1. Click “New SOP” button

  2. Fill in the basic information:

    ID: TEST_001
Name: My First SOP
Title: Test Protocol for Learning SAM
Version: 0.1.0
Author: Your Name
Approver: Supervisor Name

  3. Click “Add Task Group” to create a section

  4. Click “Add Task” to create a tab

  5. Click “Add Field” to add an input field

  6. Click “Validate” to check your work

  7. Click “Export” to save as YAML

Congratulations! You’ve created your first SOP.

System Requirements

Browser Requirements

  • Supported Browsers:

    • Chrome 90+ (Recommended)

    • Firefox 88+

    • Edge 90+

    • Safari 14+

  • JavaScript: Must be enabled

  • Cookies: Must be enabled for autosave

  • Screen Resolution: 1280x720 minimum

User Requirements

  • Basic understanding of forms and data entry

  • Familiarity with your laboratory procedures

  • Access credentials (if required)

Understanding the Workflow

        graph LR
    A[Create SOP in SAM] --> B[Validate]
    B --> C[Export YAML]
    C --> D[Deploy to S3]
    D --> E[Use in CLAIRE]
    E --> F[Collect Data]
    F --> G[Generate ELN]

Key Concepts

1. SOPs (Standard Operating Procedures)

Structured documents that define step-by-step procedures for laboratory processes.

2. Task Groups

Top-level containers that organize related tasks. Rendered as cards in CLAIRE.

3. Tasks

Sections within task groups. Immediate children render as tabs in CLAIRE.

4. Fields

Individual data input elements (text, numbers, dates, files, etc.).

5. Validation

Automatic checking to ensure SOPs meet schema requirements.

6. Deployment

Publishing validated SOPs for use in CLAIRE data collection.

First Full Example

Let’s create a simple but complete SOP for a basic laboratory procedure:

1. Start with Metadata

id: LAB_BASIC_001
name: "Basic Lab Procedure"
title: "Basic Laboratory Data Collection"
version: "1.0.0"
author: "Lab Tech"
approver: "Lab Manager"
date-published: "2024-01-20"
status: "draft"

2. Add a Task Group

taskgroups:
  - id: main_procedure
    name: "Main Procedure"
    title: "Laboratory Procedure Steps"
    ordinal: 1

3. Add Tasks (Tabs)

children:
  - id: setup_task
    '@type': Task
    name: "Setup"
    title: "Experiment Setup"
    ordinal: 1

4. Add Fields

children:
  - id: date_field
    '@type': Field
    name: "Date"
    type: "string"
    format: "date"
    required: true
    
  - id: operator_field
    '@type': Field
    name: "Operator"
    type: "string"
    required: true

5. Complete SOP

Put it all together:

'@context': https://schema.org
'@type': SoftwareApplication
id: LAB_BASIC_001
name: "Basic Lab Procedure"
title: "Basic Laboratory Data Collection"
version: "1.0.0"
author: "Lab Tech"
approver: "Lab Manager"
date-published: "2024-01-20"
status: "draft"
url: "https://example.com/sops/basic"
license: "MIT"
keywords: ["basic", "laboratory", "training"]
applicationCategory: "Laboratory Protocol"

taskgroups:
  - id: main_procedure
    name: "Main Procedure"
    title: "Laboratory Procedure Steps"
    ordinal: 1
    children:
      - id: setup_task
        '@type': Task
        name: "Setup"
        title: "Experiment Setup"
        ordinal: 1
        children:
          - id: date_field
            '@type': Field
            name: "Date"
            type: "string"
            format: "date"
            required: true
            
          - id: operator_field
            '@type': Field
            name: "Operator"
            type: "string"
            required: true
            
      - id: data_task
        '@type': Task
        name: "Data"
        title: "Data Collection"
        ordinal: 2
        children:
          - id: sample_id_field
            '@type': Field
            name: "Sample ID"
            type: "string"
            required: true
            
          - id: result_field
            '@type': Field
            name: "Result"
            type: "number"
            unit: "mg/mL"
            required: true

Using the SAM Editor

Main Interface Components

  1. Toolbar

    • New SOP

    • Open/Load

    • Save/Export

    • Validate

    • Preview

  2. Form Builder

    • Drag-and-drop interface

    • Property panels

    • Field configuration

  3. Preview Panel

    • Real-time preview

    • Test interactions

    • Responsive view

  4. Debug Panel

    • YAML/JSON view

    • Validation errors

    • Schema compliance

Keyboard Shortcuts

Shortcut

Action

Ctrl+S

Save/Autosave

Ctrl+N

New SOP

Ctrl+O

Open SOP

Ctrl+E

Export

Ctrl+V

Validate

Ctrl+P

Preview

Ctrl+Z

Undo

Ctrl+Y

Redo

Common Tasks

Adding a Text Field

  1. Click “Add Field” button

  2. Set properties:

    • ID: unique_field_id

    • Name: “Display Name”

    • Type: “string”

    • Required: true/false

Adding a Dropdown

  1. Add field with type “string”

  2. Add enum property:

    enum: ["Option 1", "Option 2", "Option 3"]

Adding a Number Field

  1. Add field with type “number”

  2. Set constraints:

    min: 0
max: 100
unit: "mg"

Adding a Date Field

  1. Add field with type “string”

  2. Set format:

    format: "date"

Creating a Table

  1. Add Table object

  2. Define columns:

    columns:
  - name: "Sample ID"
    type: "string"
  - name: "Value"
    type: "number"

Validation Basics

What Gets Validated?

  • Required fields present

  • Field types correct

  • IDs are unique

  • Structure is valid

  • References resolve

Reading Validation Errors

Field: [taskgroups.0.children.0.type]
Error: Required property missing
Solution: Add '@type': Task to the object

Quick Fixes

  1. Missing @type: Add appropriate type annotation

  2. Duplicate IDs: Make all IDs unique

  3. Type mismatch: Check quotes on numbers

  4. Missing required: Add all required fields

Testing Your SOP

In SAM

  1. Use Preview mode

  2. Enter test data

  3. Check all tabs work

  4. Verify validations trigger

Local Testing

  1. Export SOP as YAML

  2. Save to .local/s3/forms/sops/

  3. Start CLAIRE: make start-claire

  4. Test form in CLAIRE

Deployment Overview

Development Workflow

# 0. Initial setup (first time only)
# Copy configs if they don't exist:
cp -r infra/example-.config/* infra/.config/
# Customize as needed - see Frontend Configuration Guide, link below
# Create local directories and deploy configs:
make setup-local ENV=dev

# 1. Start the servers if not already running
ENV=dev ORG=any make start-frontend  # SAM frontend
ENV=dev ORG=any make start-dev       # Full stack (frontend + backend)

# 2. Create SOP in SAM at http://localhost:3000/sam

# 3. Export as YAML

# 4. Deploy locally
cp my-sop.yaml .local/s3/forms/sops/

# 5. Test in CLAIRE at http://localhost:3000/claire

See Frontend Configuration Guide for help with customizing the configuration for your environment.

Production Workflow

  1. Create and validate in SAM

  2. Test in development

  3. Get approval

  4. Deploy to production S3

  5. Verify in production CLAIRE

Best Practices for Beginners

Start Simple

✅ Begin with a basic SOP ✅ Add complexity gradually ✅ Test each addition ✅ Save frequently

Use Clear Names

✅ Descriptive IDs: patient_id not field1 ✅ Clear labels: “Patient Identifier” not “ID” ✅ Helpful descriptions

Validate Often

✅ After major changes ✅ Before exporting ✅ Before deployment

Follow Examples

✅ Review example SOPs ✅ Copy working patterns ✅ Adapt to your needs

Common Beginner Mistakes

Mistake 1: Complex First SOP

Problem: Trying to create everything at once Solution: Start with 3-5 fields, then expand

Mistake 2: Ignoring Validation

Problem: Skipping validation until the end Solution: Validate after each section

Mistake 3: Poor Naming

Problem: Generic IDs like field1, field2 Solution: Use descriptive, meaningful names

Mistake 4: No Testing

Problem: Deploying without testing Solution: Always test locally first

Mistake 5: Missing Required Fields

Problem: Forgetting metadata fields Solution: Use template or checklist

Getting Help

Self-Help Resources

  1. Documentation

  2. In-App Help

    • Tooltips on hover

    • Context-sensitive help

    • Validation messages

Community Support

  • GitHub Issues

  • Discussion forums

  • User community

Direct Support

  • System administrator

  • Technical support team

  • Training sessions

Next Steps

Now that you understand the basics:

  1. Practice: Create a simple SOP following the example

  2. Explore: Try different field types and configurations

  3. Learn: Read the detailed creation guide

  4. Review: Study the examples

  5. Master: Understand the schema reference

Quick Reference Card

Essential YAML Structure

# Metadata (Required)
id: string
name: string
title: string
version: string
author: string
approver: string
date-published: YYYY-MM-DD

# Structure
taskgroups:
  - id: string
    children:
      - '@type': Task
        children:
          - '@type': Field
            type: string|number|boolean

Field Types Quick Reference

Type

Use For

Example

string

Text

Names, IDs

number

Numbers

Measurements

boolean

Yes/No

Checkboxes

date

Dates

Experiment date

file

Uploads

Documents

array

Lists

Multiple values

Validation Commands

# In SAM
Click "Validate" button

# Command line
make validate-sop FILE=my-sop.yaml

# Check deployment
ls .local/s3/forms/sops/

FAQ

Q: Can I edit deployed SOPs? A: Yes, but you should version them appropriately and redeploy.

Q: How do I delete an SOP? A: Remove from S3 bucket or mark as “deprecated” status.

Q: Can I copy an existing SOP? A: Yes, load it in SAM, modify, and save with new ID.

Q: What’s the maximum SOP size? A: Practically, keep under 100 fields for performance.

Q: Can I use special characters in IDs? A: No, use only letters, numbers, and underscores.

Congratulations!

You’re ready to start creating SOPs in SAM. Remember:

  • Start simple

  • Validate often

  • Test thoroughly

  • Ask for help when needed

Happy SOP authoring!