Checklist Requirements Capture Guide

Checklists in Avni are scheduled Immunization activities for children. This guide helps you capture complete and accurate business requirements for implementing checklists in Avni.

Understanding Checklist Components

1. Checklist Definition

A checklist is a collection of scheduled items that need to be completed within specific timeframes.

Key Attributes:

• Checklist Name: E.g., "Child Immunization Schedule"
• Applicable Program/Subject Type: Which subjects this checklist applies to
• Trigger Event: What event starts the checklist (e.g., child birth)

2. Checklist Items

Individual items within a checklist that need to be tracked.

Key Attributes:

• Item Name: E.g., "BCG", "OPV 1"
• Timing Information: When the item is due (see timing details below)
• Dependencies: Items that must be completed before this one
• Status Logic: How the system determines if item is completed, overdue, expired, etc.

Requirement Collection Format

Basic Format (Simplified)

Use this format for simple checklists without complex dependencies:

Column Definitions:

• Due by (days): Number of days from the trigger event when the item is due
  • Can be a single value (e.g., 42) or a range (e.g., 252-365)
  • Use "Birth" for items due immediately at the trigger event
• Critical (days): Last day when the item can be completed with normal effectiveness
• Overdue (days): Beyond this day, the item is considered overdue but still valid
• Expired (days): After this day, the item is expired and cannot/should not be completed

Advanced Format (Comprehensive)

Use this format for complex checklists with dependencies, multiple time units, and gaps:

Additional Column Definitions:

• Name of Vaccine: The vaccine or immunization name (e.g., "Polio", "BCG", "Measles")
• # Doses of vaccination: If the same vaccine has multiple doses, specify which dose (e.g., "Polio-0", "Polio-1", "Measles-1", "Measles-2")
• Days: Number of days from the trigger event (usually date of birth) when this vaccine is due - helps with precise calculations
• Weeks: Same timing represented in weeks - helps with verification and cross-checking
• Months: Same timing represented in months - helps with verification and cross-checking
• Start Days at the age of child: The age (in days) when the vaccine becomes eligible/due. Can be "At birth" for birth vaccines or a specific number of days (e.g., 42, 70, 270)
• Expiry after (days): Number of days after which the vaccine is no longer valid or recommended (e.g., 15 days, 1095 days). Leave empty if the vaccine doesn't expire within the program timeline
• Weeks (completed) During the Months: For monthly tracking systems, indicates which week within the month the vaccine should be completed (e.g., week 6, week 10, week 39)
• Minimum gap in days from previous vaccination: Minimum number of days that must pass since the dependent vaccination before this one can be given (e.g., 28 days between Polio doses, 180 days between Measles doses)
• Dependencies: Which checklist items must be completed before this one can be administered (e.g., "dependent on Polio-0", "dependent on Measles-1")
• Special Notes: Any additional business logic, contraindications, special handling instructions, or clarifications (e.g., "Within 3 years of age", "28 days after Polio-0")

When to Use Each Format

Use Basic Format when:

• Simple vaccination schedules with minimal dependencies
• Straightforward timing (single due dates, not ranges)
• Limited cross-validation needed between different time units
• Small number of vaccines with clear scheduling

Use Advanced Format when:

• Complex vaccination schedules with multiple dependencies
• Need to track timing in multiple units (days, weeks, months) for verification
• Monthly reporting requirements that need week-based tracking
• Multiple doses of the same vaccine with specific gap requirements
• Need to capture detailed business rules and special handling

Example Conversion: The basic format entry:

| BCG | Birth | 56 | 365 | 366 | Given at birth |

Becomes this in advanced format:

| BCG | BCG | 0 | 0 | 0 | At birth | 1095 | 0 | 0 | None | Within 3 years of age when given |

Step-by-Step Requirements Gathering

Step 1: Identify Checklist Type and Scope

Questions to Ask:

1. What is the name of this checklist?
2. What subject type does it apply to? (Individual, Household, Group)
3. What program or enrollment triggers this checklist?
4. What event starts the checklist timeline? (e.g., date of birth, date of enrollment, date of diagnosis)

Example:

• Checklist Name: Child Immunization Schedule
• Subject Type: Individual (Child)
• Program: Child Health Program
• Trigger Event: Date of Birth

Step 2: List All Checklist Items

Questions to Ask:

1. What are all the items that need to be tracked?
2. Are there multiple doses/visits of the same item?
3. What is the official/medical name for each item?
4. Are there alternative names or abbreviations used?

Example:

- BCG (Bacillus Calmette-Guérin)
- Hepatitis B (Hep B)
- OPV (Oral Polio Vaccine) - Doses: 0, 1, 2, 3, Booster
- Pentavalent (Penta) - Doses: 1, 2, 3
- Rotavirus - Doses: 1, 2, 3
- IPV (Inactivated Polio Vaccine) - Doses: 1, 2
- Measles/MR - Doses: 1, 2
- Vitamin A - Multiple doses
- DPT Booster - Doses: 1, 2
- TT Booster - Doses: 1, 2

Step 3: Define Timing for Each Item

Questions to Ask for Each Item:

1. When is it due?
   • Days/weeks/months from trigger event?
   • Specific age?
   • Range of acceptable timing?
2. When does it become critical?
   • Last day for optimal effectiveness
   • Last day within recommended window
3. When is it overdue?
   • When should the system alert that it's late?
   • Is it still valid if overdue?
4. When does it expire?
   • After what point should it not be given?
   • Are there medical reasons for expiration?

Example - OPV 1:

• Due: 42 days after birth (6 weeks)
• Critical: 49 days (7 weeks) - last day of recommended window
• Overdue: 365 days (1 year) - still valid but late
• Expired: 1826 days (5 years) - no longer applicable

Step 4: Document Dependencies

Questions to Ask:

1. Are there items that must be completed before this one?
2. What is the minimum gap required between dependent items?
3. Are there items that must be completed together?
4. Are there alternative dependencies (either A or B must be done first)?

Example:

• Polio-1 depends on Polio-0
• Polio-2 depends on Polio-1 (minimum 28 days gap)
• Measles-2 depends on Measles-1 (minimum 180 days gap)
• DPT Booster 1 depends on Penta 3

Step 5: Capture Business Rules

Questions to Ask:

1. Are there conditions when an item should be skipped?
2. Are there alternative items (e.g., Measles OR MR)?
3. How is completion determined? (observation, form submission, external verification)
4. What data should be captured when completing an item?
5. Are there any special calculations or validations?

Example Rules:

// Skip Vitamin A if child is severely malnourished
if (child.nutritionStatus === 'SAM') {
  skipVitaminA = true;
}

// BCG scar verification after 3 months
if (daysSinceBCG > 90 && !scarVerified) {
  showScarVerificationTask = true;
}

// Calculate next due date based on last completed dose
nextDueDate = lastCompletedDate + minimumGapDays;

Step 6: Define Status Colors and Alerts

Questions to Ask:

1. How should each status be displayed to field workers?
2. What alerts/notifications should be triggered?
3. Should there be reminders before due date?

Example:

Example: Complete Requirements Document

Checklist: Child Immunization Schedule

Metadata:

• Checklist Name: Child Immunization Schedule
• Applicable Subject Type: Individual (Child)
• Applicable Program: Child Health Program
• Trigger Event: Date of Birth (DOB)
• Timeline Unit: Days from DOB
• Active Duration: 0-7000 days (approximately 19 years)

Checklist Items:

Business Rules:

1. Completion Logic:

   • Item is marked complete when the corresponding encounter form is submitted
   • Completion date is the date of vaccine administration (not form submission date)

2. Alternative Vaccines:

   • Measles and MR are alternatives - completing either satisfies the requirement
   • If MR is given, mark it as Measles 1 or Measles 2 as appropriate

3. Vitamin A Recurring:

   • After initial dose at 9 months, Vitamin A should be given every 6 months
   • Create recurring checklist items or handle via rules

4. Late Vaccination Protocol:

   • If OPV 1 is given after expiry, don't create subsequent OPV items
   • If Measles 1 is given after 365 days, adjust Measles 2 due date accordingly

5. Scar Verification:

   • BCG scar should be verified 3 months after vaccination
   • If no scar is visible, refer to health facility for re-vaccination

6. Concurrent Administration:

   • Multiple vaccines can be given on the same day if they are due
   • Document all vaccines given in a single visit

Data Format for Upload

Checklist Configuration JSON Structure

Based on the Avni checklist format, your requirements will be translated into JSON like this:

{
  "name": "Child Immunization Schedule",
  "uuid": "unique-uuid-here",
  "items": [
    {
      "name": "BCG",
      "uuid": "item-uuid-1",
      "scheduleOnExpiryOfDependency": false,
      "minDaysFromStartDate": 0,
      "maxDaysFromStartDate": 56,
      "expiresAfter": 366,
      "dependentOn": null
    },
    {
      "name": "OPV 1",
      "uuid": "item-uuid-4",
      "scheduleOnExpiryOfDependency": false,
      "minDaysFromStartDate": 42,
      "maxDaysFromStartDate": 49,
      "expiresAfter": 1826,
      "dependentOn": "OPV 0"
    }
  ]
}

Concept Definitions

Vaccines also need to be defined as concepts:

{
  "name": "BCG",
  "uuid": "concept-uuid-1",
  "dataType": "Coded",
  "answers": [
    {
      "name": "Given",
      "uuid": "answer-uuid-1"
    },
    {
      "name": "Not Given",
      "uuid": "answer-uuid-2"
    }
  ]
}

Validation Checklist

Before finalizing requirements, verify:

• All checklist items are listed with unique names
• All timing values (due, critical, overdue, expired) are defined
• Dependencies between items are clearly documented
• Minimum gaps between dependent items are specified
• Alternative items (if any) are identified
• Business rules for special cases are documented
• Completion criteria for each item is defined
• Status colors and alerts are specified
• Any recurring items are handled (separate checklist or rules)
• Edge cases and late administration scenarios are covered
• Data to be collected on completion is defined
• Integration with other program schedules is considered

Common Patterns and Best Practices

1. Use Clear Naming Conventions

• Good: "OPV 1", "OPV 2", "OPV 3"
• Avoid: "OPV First Dose", "Second OPV", "OPV III"

2. Document Ranges Explicitly

• If an item can be given in a range (e.g., 252-365 days), specify:
  • Earliest acceptable date (252)
  • Latest optimal date (365)
  • Overdue cutoff
  • Expired cutoff

3. Handle Dependent Chains

• For chains like OPV 0 → OPV 1 → OPV 2 → OPV 3:
  • Each item depends on the previous one
  • Specify minimum gaps between each
  • Consider what happens if the chain is broken (late vaccination)

4. Account for Real-World Scenarios

• What if a child misses the window for a vaccine?
• What if a child comes for catch-up vaccination?
• What if vaccines are given in a different order?
• What if there are stock-outs or unavailability?

5. Recurring Items

• For items like Vitamin A (every 6 months):
  • Option 1: Create multiple checklist items (Vit A 1, Vit A 2, etc.)
  • Option 2: Use rules to create new checklist items after completion
  • Document which approach is preferred

Additional Resources

• Avni Checklist Documentation: https://avni.readme.io/docs/upload-checklist
• Checklist Rules Guide: https://avni.readme.io/docs/writing-rules#/9-checklists-rule
• Example Vaccination Concepts: https://github.com/avniproject/avni-health-modules/blob/master/src/health_modules/child/metadata/vaccinationConcepts.json
• Example Checklist JSON: https://github.com/avniproject/calcutta-kids/blob/master/child/checklist.json

Template for Stakeholder Discussions

Use this template when meeting with program managers, doctors, or other stakeholders:

Meeting Date: __________
Stakeholders Present: __________

1. Checklist Overview
   - Name: __________
   - Purpose: __________
   - Applies to: __________
   - Starts when: __________

2. List of Items (one per row)
   Name of Vaccine | Due by (days) | Critical (days) | Overdue (days) | Expired (days) | Notes

3. Special Rules or Conditions
   - 
   - 
   - 

4. Questions/Clarifications Needed
   - 
   - 
   - 

5. Next Steps
   - 
   -