SAM (by SYNDI) Primer¶

A concise introduction to SAM’s core concepts, essential commands, and common patterns. This primer gives you the foundational knowledge needed to start creating SOPs effectively.

Essential Setup Commands¶

First Time Setup¶

# 1. Copy configs if they don't exist
cp -r infra/example-.config/* infra/.config/

# 2. Create local directories and deploy configs
make setup-local ENV=dev

# 3. Install dependencies
cd frontend && npm install && cd ..

# 4. Start the server
ENV=dev ORG=any make start-frontend

# 5. Access SAM at http://localhost:3000/sam
# Login: dev_user@local.dev / dev123

Essential Concepts¶

SOP Structure Hierarchy¶

SOP
├── Metadata (id, name, version, author, etc.)
├── Task Groups (rendered as cards)
│   ├── Tasks (rendered as tabs)
│   │   ├── Fields (input elements)
│   │   └── Nested Tasks (recursive cards)
└── Configuration Objects (non-rendered)

Required Metadata Fields¶

id - Unique identifier
name - Short name
title - Full title
version - Version number
author - Author name
approver - Approver name
date-published - Publication date
status - draft/published/deprecated
url - SOP URL
license - License type
keywords - Search keywords array
applicationCategory - Protocol category

Field Types Quick Reference¶

Type	Usage	Example
`string`	Text input	Names, IDs
`number`	Numeric values	Measurements
`boolean`	Checkbox	Yes/No
`date`	Date picker	Experiment date
`file`	File upload	Documents
`array`	Multiple values	Lists

Field Configuration Example¶

- id: sample_field
  '@type': Field
  name: "Sample ID"
  type: "string"
  required: true
  validation:
    pattern: "^S[0-9]{6}$"
    message: "Format: S followed by 6 digits"

Special Configuration Objects¶

ELN Filename Component¶

children:
  - id: field_filename
    '@type': ELNFilenameComponent
    order: 1
    filename_component: true

Export Configuration¶

children:
  - id: field_export
    '@type': ExportConfiguration
    enabled: true
    value_immutable: true

Understanding Validation¶

Common Validation Errors and How to Fix Them¶

Error	Cause	Solution
Missing required field	Required field not provided	Add the field
Type mismatch	Wrong data type	Fix quotes on numbers
Additional properties	Unknown fields	Remove or move to children
Invalid enum	Value not in list	Use allowed value
Pattern mismatch	Regex validation failed	Match required pattern

Validation Commands¶

# In SAM Editor
Click "Validate" button

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

# Validate all SOPs
make validate-all-sops DIR=.local/s3/forms/sops

Deployment Workflow¶

Local Development¶

# 1. Create/edit SOP in SAM
# 2. Export as YAML
# 3. Copy to local S3 simulation
cp my-sop.yaml .local/s3/forms/sops/

# 4. Test in CLAIRE
# Navigate to http://localhost:3000/claire

Production Deployment¶

# 1. Validate thoroughly
make validate-sop FILE=my-sop.yaml

# 2. Deploy to staging
make rs-deploy-stage ORG=myorg

# 3. After testing, deploy to production
make rs-deploy-prod ORG=myorg

Common Troubleshooting Solutions¶

SOP Not Appearing¶

Check file location: .local/s3/forms/sops/
Verify .yaml extension
Restart CLAIRE: make restart-claire

Validation Failures¶

Check all required fields present
Verify types (no quotes on numbers)
Ensure unique IDs
Remove extra properties

Fields Not Rendering¶

Field must have type property
Check parent-child relationships
Verify UI configuration

Keyboard Shortcuts¶

Shortcut	Action
Ctrl+S	Save/Autosave
Ctrl+N	New SOP
Ctrl+E	Export
Ctrl+V	Validate
Ctrl+Z	Undo
Ctrl+Y	Redo

Best Practices¶

DO’s¶

✅ Use descriptive IDs ✅ Validate after each section
✅ Test locally first ✅ Version appropriately ✅ Document special requirements

DON’Ts¶

❌ Hardcode field assumptions ❌ Skip validation ❌ Deploy without testing ❌ Use special characters in IDs ❌ Create huge forms (>100 fields)

Example Minimal SOP¶

'@context': https://schema.org
'@type': SoftwareApplication
id: MINIMAL_001
name: "Minimal SOP"
title: "Minimal Example SOP"
version: "1.0.0"
author: "Your Name"
approver: "Approver Name"
date-published: "2024-01-20"
status: "draft"
url: "https://example.com/sops/minimal"
license: "MIT"
keywords: ["example", "minimal"]
applicationCategory: "Laboratory Protocol"

taskgroups:
  - id: main_group
    name: "Main"
    title: "Main Procedures"
    ordinal: 1
    children:
      - id: task_1
        '@type': Task
        name: "Data Entry"
        ordinal: 1
        children:
          - id: field_1
            '@type': Field
            name: "Sample ID"
            type: "string"
            required: true

Getting Help¶

Documentation: Full guides in this directory
Examples: examples.md
Schema Reference: schema-reference.md
Troubleshooting: troubleshooting.md
Configuration: Frontend Configuration Guide