Creating SOPs in SAM¶

Overview¶

This guide provides step-by-step instructions for creating Standard Operating Procedures (SOPs) in SAM that can be rendered as interactive data collection forms in CLAIRE.

Understanding SOP Structure¶

Core Components¶

Every SOP consists of three main parts:

Metadata: Basic information about the SOP (ID, version, author, etc.)
Task Groups: Logical groupings of related tasks (rendered as cards in CLAIRE)
Fields: Data input elements within tasks

Hierarchical Organization¶

SOP
├── Metadata
├── Task Groups (Cards)
│   ├── Tasks (Tabs)
│   │   ├── Fields (Input Elements)
│   │   └── Nested Tasks (Recursive Cards)
└── Configuration Objects

Step-by-Step Creation Process¶

Step 1: Access SAM Editor¶

Navigate to SAM application
Click “New SOP” or “Create SOP”
The editor will open with a blank template

Step 2: Define Metadata¶

Fill in the required metadata fields:

id: "SOP_001"
name: "Cell Culture Protocol"
title: "Standard Cell Culture Maintenance Protocol"
version: "1.0.0"
author: "Dr. Jane Smith"
approver: "Lab Director"
date-published: "2024-01-15"
status: "draft"
url: "https://example.com/sops/cell-culture"
license: "MIT"
keywords: ["cell culture", "maintenance", "protocol"]
applicationCategory: "Laboratory Protocol"

Metadata Best Practices¶

ID: Use a consistent naming convention (e.g., “SOP_XXX” or “DEPT_PROTOCOL_XXX”)
Version: Follow semantic versioning (MAJOR.MINOR.PATCH)
Status: Start with “draft”, change to “published” when approved
Keywords: Include searchable terms for easy discovery

Step 3: Create Task Groups¶

Task groups organize your SOP into logical sections. Each group becomes a card in CLAIRE.

taskgroups:
  - id: general_info_group
    name: "General Information"
    title: "Experiment General Information"
    description: "Basic information about the experiment"
    ordinal: 1
    children:
      # Tasks go here

Step 4: Add Tasks¶

Tasks are the immediate children of task groups and render as tabs in CLAIRE:

children:
  - id: project_info_task
    '@type': Task
    name: "Project Info"
    title: "Project Information"
    description: "Project and experiment details"
    ordinal: 1
    children:
      # Fields go here

Step 5: Define Fields¶

Fields are the actual data input elements:

children:
  - id: project_id_field
    '@type': Field
    name: "Project ID"
    title: "Project Identifier"
    description: "Unique identifier for this project"
    type: "string"
    required: true
    validation:
      pattern: "^PROJ-[0-9]{4}$"
      message: "Must follow format: PROJ-XXXX"

Field Types and Configuration¶

Basic Field Types¶

Type	Usage	Example Configuration
`string`	Text input	`type: "string"`
`number`	Numeric values	`type: "number", min: 0, max: 100`
`boolean`	Yes/No checkbox	`type: "boolean"`
`date`	Date picker	`type: "string", format: "date"`
`datetime`	Date and time	`type: "string", format: "datetime"`
`file`	File upload	`type: "file", file_config: { accept: ".pdf" }`

Advanced Field Configuration¶

Numeric Fields with Units¶

- id: temperature_field
  '@type': Field
  name: "Temperature"
  type: "number"
  unit: "°C"
  min: -80
  max: 100
  description: "Storage temperature in Celsius"

Array Fields (Multiple Values)¶

- id: reagents_field
  '@type': Field
  name: "Reagents Used"
  type: "array"
  items:
    type: "string"
  minItems: 1
  maxItems: 10

File Upload Fields¶

- id: protocol_doc_field
  '@type': Field
  name: "Protocol Document"
  type: "file"
  file_config:
    accept: ".pdf,.docx"
    maxSize: 10485760  # 10MB in bytes
    multiple: false

Special Configuration Objects¶

ELN Filename Components¶

To include field values in the generated ELN filename:

- id: patient_id_field
  '@type': Field
  name: "Patient ID"
  type: "string"
  children:
    - id: patient_id_filename
      '@type': ELNFilenameComponent
      order: 1
      filename_component: true

Export Configuration¶

To control how fields are exported:

- id: sensitive_data_field
  '@type': Field
  name: "Sensitive Data"
  type: "string"
  children:
    - id: sensitive_export_config
      '@type': ExportConfiguration
      enabled: false  # Don't export this field
      value_immutable: true

Tables¶

For tabular data entry:

- id: sample_table
  '@type': Table
  name: "Sample Information"
  columns:
    - name: "Sample ID"
      type: "string"
      required: true
    - name: "Volume (mL)"
      type: "number"
      min: 0
    - name: "Concentration (mg/mL)"
      type: "number"
      min: 0
  minRows: 1
  maxRows: 20

Validation Rules¶

Field-Level Validation¶

validation:
  required: true
  minLength: 3
  maxLength: 50
  pattern: "^[A-Z][a-zA-Z0-9-]*$"
  message: "Must start with capital letter"

Cross-Field Validation¶

schema_dependencies:
  cross_field_validations:
    - name: "date_validation"
      fields: ["start_date", "end_date"]
      condition: "start_date <= end_date"
      error_message: "End date must be after start date"

UI Configuration¶

Control the appearance of elements:

ui_config:
  component_type: "card"
  variant: "outlined"
  icon: "beaker"
  collapsible: true
  defaultCollapsed: false
  className: "important-section"

Available Icons¶

Common icons for laboratory procedures:

flask - General lab work
beaker - Chemical procedures
microscope - Microscopy
dna - Molecular biology
thermometer - Temperature-related
clock - Time-sensitive procedures
alert-triangle - Warnings
info - Information sections

Complete Example¶

Here’s a complete minimal SOP:

'@context': https://schema.org
'@type': SoftwareApplication
id: EXAMPLE_001
name: "Example Protocol"
title: "Example Laboratory Protocol"
version: "1.0.0"
author: "Lab User"
approver: "Lab Manager"
date-published: "2024-01-20"
status: "draft"
url: "https://example.com/sops/example"
license: "MIT"
keywords: ["example", "template"]
applicationCategory: "Laboratory Protocol"

taskgroups:
  - id: main_group
    name: "Main Procedures"
    title: "Main Laboratory Procedures"
    ordinal: 1
    children:
      - id: setup_task
        '@type': Task
        name: "Setup"
        title: "Experiment Setup"
        ordinal: 1
        children:
          - id: exp_date_field
            '@type': Field
            name: "Experiment Date"
            type: "string"
            format: "date"
            required: true
          
          - id: operator_field
            '@type': Field
            name: "Operator"
            type: "string"
            required: true
            
      - id: procedure_task
        '@type': Task
        name: "Procedure"
        title: "Main Procedure"
        ordinal: 2
        children:
          - id: sample_id_field
            '@type': Field
            name: "Sample ID"
            type: "string"
            required: true
            children:
              - id: sample_id_filename
                '@type': ELNFilenameComponent
                order: 1
                filename_component: true
                
          - id: temperature_field
            '@type': Field
            name: "Temperature"
            type: "number"
            unit: "°C"
            min: -80
            max: 100
            required: true

Testing Your SOP¶

In SAM Editor¶

Use the Preview panel to see how your SOP will render
Click Validate to check for schema compliance
Use the Debug Panel to view the YAML/JSON structure
Test all field interactions

Local Testing¶

Export your SOP as YAML
Save to .local/s3/forms/sops/your-sop.yaml
Start CLAIRE locally: make start-dev
Navigate to CLAIRE and test the form

Common Patterns¶

Multi-Step Procedures¶

taskgroups:
  - id: procedure_group
    name: "Procedure"
    children:
      - id: step1_task
        '@type': Task
        name: "Step 1: Preparation"
        ordinal: 1
        # ... fields
      
      - id: step2_task
        '@type': Task
        name: "Step 2: Processing"
        ordinal: 2
        # ... fields
        
      - id: step3_task
        '@type': Task
        name: "Step 3: Analysis"
        ordinal: 3
        # ... fields

Conditional Fields¶

While full conditional logic is limited, you can:

Group related optional fields together
Use clear descriptions indicating when fields apply
Use validation rules to enforce dependencies

Reusable Components¶

For frequently used field sets:

Create template YAML snippets
Copy and modify IDs when reusing
Maintain consistent naming conventions

Tips and Best Practices¶

DO’s¶

✅ Use descriptive IDs: Make them meaningful and unique ✅ Add helpful descriptions: Guide users on what to enter ✅ Set appropriate validation: Prevent invalid data entry ✅ Test thoroughly: Try edge cases and invalid inputs ✅ Version appropriately: Track changes with semantic versioning ✅ Document special requirements: Use field descriptions

DON’Ts¶

❌ Don’t hardcode assumptions: Keep fields schema-independent ❌ Don’t over-nest: Keep hierarchy reasonable (max 3-4 levels) ❌ Don’t create huge forms: Split into logical sections ❌ Don’t skip validation: Always validate before deployment ❌ Don’t use special characters in IDs: Stick to alphanumeric and underscores

Next Steps¶

Getting Help¶

If you encounter issues:

Check the validation errors carefully
Compare with working examples
Use the debug panel to inspect structure
Consult the schema reference
Contact your system administrator