​
Overview

This example demonstrates scheduling home health care visits where patients require multiple types of therapy over a two-week treatment plan. The solution matches therapist skills to patient needs, ensures continuity of care, and optimizes travel routes while respecting therapy schedules and therapist availability.
This example showcases advanced VRP features including skill-based matching, recurring visits, job relations for continuity of care, and multi-week planning horizons.

​
Business Scenario

A home health agency manages:
  • 15 therapists with different specializations (physical therapy, occupational therapy, speech therapy)
  • 30+ patients requiring various combinations of therapies
  • 2-week treatment plans with multiple visits per week
  • Requirements for continuity of care (same therapist for same therapy type)
  • Travel time optimization between patient homes
  • Therapist work-life balance with maximum daily patient loads

​
Complete Implementation

{
  "resources": [
    // Physical Therapist
    {
      "name": "PT-Sarah",
      "start": {
        "locationId": "clinic",
        "latitude": 40.7614,
        "longitude": -73.9776
      },
      "end": {
        "locationId": "home-sarah",
        "latitude": 40.7489,
        "longitude": -73.9442
      },
      "shifts": [
        // Week 1
        {"from": "2024-03-18T08:00:00", "to": "2024-03-18T17:00:00"},
        {"from": "2024-03-19T08:00:00", "to": "2024-03-19T17:00:00"},
        {"from": "2024-03-20T08:00:00", "to": "2024-03-20T17:00:00"},
        {"from": "2024-03-21T08:00:00", "to": "2024-03-21T17:00:00"},
        {"from": "2024-03-22T08:00:00", "to": "2024-03-22T13:00:00"},
        // Week 2
        {"from": "2024-03-25T08:00:00", "to": "2024-03-25T17:00:00"},
        {"from": "2024-03-26T08:00:00", "to": "2024-03-26T17:00:00"},
        {"from": "2024-03-27T08:00:00", "to": "2024-03-27T17:00:00"},
        {"from": "2024-03-28T08:00:00", "to": "2024-03-28T17:00:00"},
        {"from": "2024-03-29T08:00:00", "to": "2024-03-29T13:00:00"}
      ],
      "tags": [
        "physical-therapy",
        "certified-PT", 
        "pediatric"
      ],
      "rules": [{
        "maxWorkTimeInSeconds": 32400  // 9 hours max per day
      }],
      "hourlyCost": 75
    },
    // Occupational Therapist
    {
      "name": "OT-Michael",
      "start": {"locationId": "clinic"},
      "end": {
        "locationId": "home-michael",
        "latitude": 40.7829,
        "longitude": -73.9654
      },
      "shifts": [
        // Similar 2-week schedule
        {"from": "2024-03-18T09:00:00", "to": "2024-03-18T18:00:00"},
        {"from": "2024-03-19T09:00:00", "to": "2024-03-19T18:00:00"}
        // ... remaining days
      ],
      "tags": [
        "occupational-therapy",
        "certified-OT",
        "hand-therapy",
        "geriatric"
      ],
      "hourlyCost": 70
    },
    // Speech Therapist
    {
      "name": "ST-Jennifer",
      "start": {"locationId": "clinic"},
      "end": {"locationId": "home-jennifer"},
      "shifts": [
        // Part-time schedule (3 days/week)
        {"from": "2024-03-18T08:00:00", "to": "2024-03-18T14:00:00"},
        {"from": "2024-03-20T08:00:00", "to": "2024-03-20T14:00:00"},
        {"from": "2024-03-22T08:00:00", "to": "2024-03-22T14:00:00"},
        {"from": "2024-03-25T08:00:00", "to": "2024-03-25T14:00:00"},
        {"from": "2024-03-27T08:00:00", "to": "2024-03-27T14:00:00"},
        {"from": "2024-03-29T08:00:00", "to": "2024-03-29T14:00:00"}
      ],
      "tags": [
        "speech-therapy",
        "certified-ST",
        "pediatric",
        "dysphagia"
      ],
      "hourlyCost": 80
    },
    // Multi-disciplinary Therapist
    {
      "name": "MDT-Robert",
      "start": {"locationId": "clinic"},
      "shifts": [
        // Full 2-week schedule
      ],
      "tags": [
        "physical-therapy",
        "occupational-therapy",
        "certified-PT",
        "certified-OT"
      ],
      "hourlyCost": 85
    }
    // Additional therapists...
  ],
  "jobs": [
    // Patient 1: Stroke recovery - needs PT and OT
    {
      "name": "patient-001-PT-week1-visit1",
      "location": {
        "latitude": 40.7580,
        "longitude": -73.9855
      },
      "duration": 3600,  // 1 hour
      "windows": [{
        "from": "2024-03-18T09:00:00",
        "to": "2024-03-18T11:00:00",
        "hard": true
      }],
      "tags": [
        {"name": "physical-therapy", "hard": true},
        {"name": "geriatric"}
      ],
      "priority": 80
    },
    {
      "name": "patient-001-PT-week1-visit2",
      "location": {
        "latitude": 40.7580,
        "longitude": -73.9855
      },
      "duration": 3600,
      "windows": [{
        "from": "2024-03-20T09:00:00",
        "to": "2024-03-20T11:00:00",
        "hard": true
      }],
      "tags": [
        {"name": "physical-therapy", "hard": true},
        {"name": "geriatric"}
      ]
    },
    {
      "name": "patient-001-PT-week1-visit3",
      "location": {
        "latitude": 40.7580,
        "longitude": -73.9855
      },
      "duration": 3600,
      "windows": [{
        "from": "2024-03-22T09:00:00",
        "to": "2024-03-22T11:00:00",
        "hard": true
      }],
      "tags": [
        {"name": "physical-therapy", "hard": true},
        {"name": "geriatric"}
      ]
    },
    // Week 2 PT visits for patient-001
    {
      "name": "patient-001-PT-week2-visit1",
      "location": {
        "latitude": 40.7580,
        "longitude": -73.9855
      },
      "duration": 3600,
      "windows": [{
        "from": "2024-03-25T09:00:00",
        "to": "2024-03-25T11:00:00",
        "hard": true
      }],
      "tags": [
        {"name": "physical-therapy", "hard": true},
        {"name": "geriatric"}
      ]
    },
    // OT visits for patient-001
    {
      "name": "patient-001-OT-week1-visit1",
      "location": {
        "latitude": 40.7580,
        "longitude": -73.9855
      },
      "duration": 2700,  // 45 minutes
      "windows": [{
        "from": "2024-03-19T14:00:00",
        "to": "2024-03-19T16:00:00",
        "hard": true
      }],
      "tags": [
        {"name": "occupational-therapy", "hard": true},
        {"name": "geriatric"}
      ]
    },
    // Patient 2: Child with speech delays - needs ST
    {
      "name": "patient-002-ST-week1-visit1",
      "location": {
        "latitude": 40.7489,
        "longitude": -73.9680
      },
      "duration": 1800,  // 30 minutes
      "windows": [{
        "from": "2024-03-18T10:00:00",
        "to": "2024-03-18T12:00:00",
        "hard": false,
        "weight": 50
      }],
      "tags": [
        {"name": "speech-therapy", "hard": true},
        {"name": "pediatric", "hard": true}
      ],
      "priority": 90
    },
    // Patient 3: Post-surgery rehab - needs PT, OT, and wound care
    {
      "name": "patient-003-PT-week1-visit1",
      "location": {
        "latitude": 40.7282,
        "longitude": -73.9942
      },
      "duration": 3600,
      "windows": [{
        "from": "2024-03-18T13:00:00",
        "to": "2024-03-18T15:00:00",
        "hard": true
      }],
      "tags": [
        {"name": "physical-therapy", "hard": true}
      ],
      "priority": 85,
      "padding": 600  // 10 min documentation time
    }
    // Additional patients and visits...
  ],
  "relations": [
    // Ensure same PT therapist for patient-001 throughout treatment
    {
      "type": "SAME_RESOURCE",
      "jobs": [
        "patient-001-PT-week1-visit1",
        "patient-001-PT-week1-visit2",
        "patient-001-PT-week1-visit3",
        "patient-001-PT-week2-visit1"
      ]
    },
    // Ensure same OT therapist for patient-001
    {
      "type": "SAME_RESOURCE",
      "jobs": [
        "patient-001-OT-week1-visit1",
        "patient-001-OT-week2-visit1"
      ]
    },
    // Sequence PT before OT on same day if possible
    {
      "type": "SEQUENCE",
      "jobs": [
        "patient-001-PT-week1-visit1",
        "patient-001-OT-week1-visit1"
      ],
      "partialPlanning": true
    },
    // Keep pediatric patients in morning for therapist preference
    {
      "type": "SEQUENCE",
      "tags": ["pediatric"],
      "weight": 30
    }
  ],
  "options": {
    "traffic": 1.1,
    "partialPlanning": false,
    "fairness": {
      "workloadPerResource": true,
      "workloadSensitivity": 0.8
    },
    "weights": {
      "travelTimeWeight": 2,
      "workloadWeight": 3,
      "priorityWeight": 5,
      "tagWeight": 10  // High weight for skill matching
    }
  }
}

​
Key Features for Home Health Care

​
Multi-Week Planning

The VRP solver handles extended planning horizons: 
{
  "shifts": [
    // Week 1
    {"from": "2024-03-18T08:00:00", "to": "2024-03-18T17:00:00"},
    {"from": "2024-03-19T08:00:00", "to": "2024-03-19T17:00:00"},
    // ... all days
    // Week 2
    {"from": "2024-03-25T08:00:00", "to": "2024-03-25T17:00:00"},
    {"from": "2024-03-26T08:00:00", "to": "2024-03-26T17:00:00"}
    // ... all days
  ]
}

​
Skill-Based Matching

Ensure therapists have required certifications: 
// Therapist capabilities (in resources)
"tags": [
  "physical-therapy",
  "certified-PT",
  "pediatric"
]

// Patient requirements (in jobs)
"tags": [
  {"name": "physical-therapy", "hard": true},
  {"name": "pediatric", "hard": true}  // Must have pediatric certification
]

​
Continuity of Care Relations

Maintain same therapist throughout treatment: 
{
  "type": "SAME_RESOURCE",
  "jobs": [
    "patient-001-PT-week1-visit1",
    "patient-001-PT-week1-visit2",
    "patient-001-PT-week1-visit3",
    "patient-001-PT-week2-visit1",
    "patient-001-PT-week2-visit2",
    "patient-001-PT-week2-visit3"
  ]
}

​
Documentation Time

Add padding for post-visit documentation: 
{
  "name": "patient-visit",
  "duration": 3600,     // 1 hour therapy
  "padding": 600        // 10 minutes documentation/travel buffer
}

​
Therapy Plan Patterns

​
Standard Rehabilitation Plan

{
  // 3x per week PT, 2x per week OT, 1x per week ST
  "physicalTherapy": {
    "frequency": 3,
    "duration": 3600,
    "weeks": 2
  },
  "occupationalTherapy": {
    "frequency": 2,
    "duration": 2700,
    "weeks": 2
  },
  "speechTherapy": {
    "frequency": 1,
    "duration": 1800,
    "weeks": 2
  }
}

​
Intensive Post-Surgery Plan

{
  // Daily PT for week 1, 3x for week 2
  "week1": {
    "physicalTherapy": {
      "monday": true, "tuesday": true, "wednesday": true,
      "thursday": true, "friday": true
    }
  },
  "week2": {
    "physicalTherapy": {
      "monday": true, "wednesday": true, "friday": true
    }
  }
}

​
Best Practices for Home Health Scheduling

1

Define clear skill requirements

Use specific tags for certifications, specializations, and patient populations (pediatric, geriatric, etc.).
2

Implement continuity constraints

Use SAME_RESOURCE relations to maintain therapist-patient relationships throughout treatment plans.
3

Balance workload fairly

Enable fairness options to prevent therapist burnout and ensure equitable case distribution.
4

Allow flexible scheduling

Use soft time windows where possible to give schedulers more options while meeting patient preferences.
5

Plan for documentation

Include padding for each visit to account for required documentation and travel buffer time.
6

Consider therapist preferences

Use rankings to match therapists with preferred patient types or geographic areas.

​
Advanced Scheduling Strategies

​
Geographic Clustering by Day

Assign therapists to specific regions on different days: 
{
  "resources": [{
    "name": "PT-Sarah",
    "regions": [
      {"day": "monday", "postcodes": ["10001", "10002", "10003"]},
      {"day": "tuesday", "postcodes": ["10010", "10011", "10012"]}
    ]
  }]
}

​
Therapy Sequencing

Ensure proper order of therapies when multiple are needed: 
{
  "relations": [
    {
      "type": "SEQUENCE",
      "jobs": ["evaluation", "treatment-plan", "therapy-start"],
      "timeInterval": 86400  // 24 hours between steps
    }
  ]
}

​
Emergency Visit Handling

Reserve capacity for urgent additions: 
{
  "resources": [{
    "name": "on-call-therapist",
    "shifts": [{
      "from": "2024-03-18T12:00:00",
      "to": "2024-03-18T20:00:00"
    }],
    "tags": ["emergency-response"]
  }]
}

​
Schedule Visualization

​
Common Challenges and Solutions

Challenge: Sick days, vacations, or schedule changes disrupting continuitySolution:
  • Define backup therapists with similar skills
  • Use “preferred” vs “required” for continuity relations
  • Implement therapist ranking with primary/backup assignments
Challenge: Patients canceling visits affects daily routesSolution:
  • Use the suggest API to find alternative patients for freed time slots
  • Maintain a waitlist of patients needing additional visits
  • Allow flexible rescheduling within the same week
Challenge: Coordinating multiple therapists for the same patientSolution:
  • Use SAME_DAY relations for coordinated visits
  • Schedule case conferences using SAME_TIME relations
  • Implement minimum time gaps between different therapies
Challenge: Specific visit frequencies and durations required by insuranceSolution:
  • Use hard time windows for insurance-mandated schedules
  • Track visit counts with custom constraints
  • Generate compliance reports from solution data

​
Integration with EMR Systems

Integrate with Electronic Medical Records (EMR) for real-time patient data and automated scheduling.
// Example EMR integration
async function scheduleTherapyPlans() {
  // 1. Fetch active therapy orders from EMR
  const therapyOrders = await emr.getActiveTherapyOrders({
    startDate: '2024-03-18',
    endDate: '2024-03-31'
  });
  
  // 2. Transform to VRP jobs
  const jobs = therapyOrders.flatMap(order => 
    generateVisitsFromOrder(order)
  );
  
  // 3. Get therapist availability
  const therapists = await emr.getTherapistSchedules();
  
  // 4. Add continuity constraints
  const relations = generateContinuityRelations(therapyOrders);
  
  // 5. Optimize schedule
  const solution = await solviceApi.solve({
    resources: therapists,
    jobs: jobs,
    relations: relations,
    options: homeHealthOptions
  });
  
  // 6. Push back to EMR
  await emr.updateTherapistSchedules(solution);
  
  return solution;
}

function generateVisitsFromOrder(order) {
  const visits = [];
  const { frequency, duration, startDate, endDate } = order;
  
  // Generate visits based on frequency
  let currentDate = new Date(startDate);
  while (currentDate <= new Date(endDate)) {
    for (let i = 0; i < frequency.perWeek; i++) {
      visits.push({
        name: `${order.patientId}-${order.therapyType}-${currentDate}`,
        location: order.patientLocation,
        duration: duration,
        windows: generateTimeWindows(order.preferences),
        tags: [
          {name: order.therapyType, required: true},
          ...order.specialRequirements
        ]
      });
    }
    currentDate.setDate(currentDate.getDate() + 7);
  }
  
  return visits;
}

Service Appointments

Time-windowed home services

Skill Matching

Advanced tag-based assignments

Job Relations

Continuity and sequencing constraints

Workload Fairness

Equitable work distribution