cron-setup.md

Cron Job Setup for Automated Follow-ups

This guide explains how to set up automated follow-ups for the Medical Records Collection system.

Overview

The system includes automated follow-up capabilities that can:

• Send reminder emails for pending requests
• Initiate AI phone calls for no-response situations
• Create internal notifications for high-priority escalations
• Track and log all follow-up activities

API Endpoint

The follow-up cron endpoint is available at:

GET/POST /api/cron/follow-ups

Authentication

The endpoint requires authentication via a Bearer token:

Authorization: Bearer YOUR_CRON_SECRET

Set the CRON_SECRET environment variable in your .env.local:

CRON_SECRET=your-secure-random-string

Cron Schedule Recommendations

Every 4 Hours (Business Hours)

Check for follow-ups during business hours:

0 9,13,17 * * 1-5

Daily at 10 AM

Run once per day for standard follow-ups:

0 10 * * *

Every 2 Hours (Urgent Requests)

For systems with high-priority requests:

0 */2 * * *

Setup with Popular Cron Services

1. Vercel Cron Jobs

Add to vercel.json:

{
  "crons": [{
    "path": "/api/cron/follow-ups",
    "schedule": "0 10 * * *"
  }]
}

2. GitHub Actions

Create .github/workflows/follow-ups.yml:

name: Medical Records Follow-ups

on:
  schedule:
    - cron: '0 10 * * *'
  workflow_dispatch:

jobs:
  follow-up:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger follow-up checks
        run: |
          curl -X POST https://your-app.com/api/cron/follow-ups \
            -H "Authorization: Bearer ${{ secrets.CRON_SECRET }}" \
            -H "Content-Type: application/json"

3. External Cron Services

Cron-job.org

1. Create account at https://cron-job.org
2. Add new cron job:
   • URL: https://your-app.com/api/cron/follow-ups
   • Schedule: Every day at 10:00
   • Request method: GET
   • Headers: Authorization: Bearer YOUR_CRON_SECRET

EasyCron

1. Sign up at https://www.easycron.com
2. Add cron job with:
   • URL: https://your-app.com/api/cron/follow-ups
   • Method: POST
   • Headers: Add Authorization header
   • Cron Expression: 0 10 * * *

4. Railway/Render Cron

For Railway:

# railway.toml
[crons]
  [crons.follow-ups]
    schedule = "0 10 * * *"
    command = "curl -X POST $RAILWAY_STATIC_URL/api/cron/follow-ups -H 'Authorization: Bearer $CRON_SECRET'"

Follow-up Rules

The system checks for these conditions:

3-Day Follow-up

• Triggers: 3 days after request creation
• Action: Email reminder
• Applies to: Pending requests

No Response Follow-up

• Triggers: 5 days since last contact
• Action: AI phone call
• Applies to: Follow-up status requests

High Priority Escalation

• Triggers: 2 days for high/urgent requests with no documents
• Actions:
  1. Internal notification
  2. AI call (2 hours later)
• Applies to: High/urgent priority requests

Monitoring

Check Logs

Monitor follow-up executions:

# View recent webhook logs
SELECT * FROM webhook_logs 
WHERE created_at > NOW() - INTERVAL '24 hours'
ORDER BY created_at DESC;

# Check communication logs
SELECT * FROM request_communications
WHERE ai_generated = true
AND created_at > NOW() - INTERVAL '24 hours'
ORDER BY created_at DESC;

Manual Trigger

Test the endpoint manually:

curl -X POST http://localhost:3000/api/cron/follow-ups \
  -H "Authorization: Bearer your-cron-secret" \
  -H "Content-Type: application/json"

Best Practices

1. Timing: Schedule during business hours for better response rates
2. Frequency: Start with daily checks, adjust based on volume
3. Monitoring: Set up alerts for failed cron jobs
4. Rate Limiting: Implement delays between follow-ups to avoid overwhelming providers
5. Logging: Keep detailed logs of all automated actions

Customizing Follow-up Rules

To add custom rules, modify the getActiveFollowUpRules() method in followUpService.ts:

{
  id: 'custom-rule',
  name: 'Custom Follow-up',
  description: 'Your custom rule description',
  triggerConditions: {
    statusEquals: 'pending',
    daysSinceCreated: 7,
    // Add your conditions
  },
  actions: [{
    type: 'email',
    template: 'custom-template',
    delay: 0
  }],
  isActive: true
}

Troubleshooting

Cron not running

• Check CRON_SECRET is set correctly
• Verify endpoint URL is accessible
• Check service logs for errors

Follow-ups not triggering

• Verify trigger conditions match requests
• Check that rules are set to isActive: true
• Review communication logs for recent activity

Too many follow-ups

• Adjust trigger conditions (increase days)
• Add cooldown period between follow-ups
• Filter by priority or status