Streamline appointment management with comprehensive booking operations, automated scheduling workflows, and real-time appointment monitoring.

Quick Reference¶

Available Operations¶

Booking Data Structure¶

Core Fields¶

# Primary Identification
id: "string"                    # Unique booking identifier
appointmentNumber: "string"     # Human-readable appointment number
status: "string"                # Booking status (see status types)

# Scheduling Information
appointmentDate: "ISO 8601 date"      # Appointment date
appointmentTime: "HH:MM"              # Start time
endTime: "HH:MM"                      # End time  
duration: "number"                    # Duration in minutes

# Participants
patientId: "string"                   # Patient identifier
staffId: "string"                     # Assigned staff member
appointmentTypeId: "string"           # Type of appointment

Scheduling Details¶

# Location Information
locationId: "string"                  # Practice location
roomId: "string"                      # Specific room/clinic
roomName: "string"                    # Room display name

# Appointment Configuration
appointmentType: {
  id: "string"                        # Type identifier
  name: "string"                      # Type name (e.g., "Consultation")
  duration: "number"                  # Default duration
  colour: "string"                    # Calendar colour
  category: "string"                  # Appointment category
}

# Staff Assignment
staff: {
  id: "string"                        # Staff identifier
  firstName: "string"                 # Staff first name
  lastName: "string"                  # Staff surname
  title: "string"                     # Professional title
  speciality: "string"                # Medical speciality
}

Patient Information¶

# Patient Details (embedded)
patient: {
  id: "string"                        # Patient identifier
  firstName: "string"                 # Patient first name
  lastName: "string"                  # Patient surname
  email: "string"                     # Patient email
  phone: "string"                     # Patient phone
  dateOfBirth: "ISO 8601 date"        # Patient DOB
}

# Contact Preferences
contactMethod: "email|sms|phone"      # Preferred contact method
reminderSent: "boolean"               # Reminder status
confirmationRequired: "boolean"       # Confirmation needed

Status Management¶

# Status Types
status: 
  - "Pending"                         # Awaiting confirmation
  - "Confirmed"                       # Confirmed by patient
  - "Arrived"                         # Patient checked in
  - "In Progress"                     # Appointment started
  - "Completed"                       # Appointment finished
  - "Cancelled"                       # Cancelled appointment
  - "No Show"                         # Patient didn't attend
  - "Rescheduled"                     # Moved to different time

# Status Metadata
statusChangedAt: "ISO 8601 datetime"  # Last status change
statusChangedBy: "string"             # Who changed status
cancellationReason: "string"          # Reason for cancellation

Administrative Fields¶

# Timestamps
dateCreated: "ISO 8601 datetime"      # Booking creation time
dateUpdated: "ISO 8601 datetime"      # Last modification time
lastModifiedBy: "string"              # User who last modified

# Notes and Documentation
notes: "string"                       # Administrative notes
patientNotes: "string"                # Patient-visible notes
clinicalNotes: "string"               # Clinical observations
internalNotes: "string"               # Internal staff notes

# Financial Information
fee: "number"                         # Appointment fee
paid: "boolean"                       # Payment status
paymentMethod: "string"               # How payment was made
invoiceId: "string"                   # Associated invoice

Action Node Operations¶

Get Single Booking¶

Retrieve detailed information for a specific appointment.

Configuration¶

Resource: "Booking"
Action: "Get"
Booking ID: "booking_id_here"

Example Output¶

{
  "id": "bkg_123456789",
  "appointmentNumber": "A240215001",
  "status": "Confirmed",
  "appointmentDate": "2024-02-20",
  "appointmentTime": "14:30",
  "duration": 30,
  "patient": {
    "id": "pat_987654321",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "email": "sarah.johnson@email.com",
    "phone": "+44 20 7946 0958"
  },
  "staff": {
    "id": "staff_111",
    "firstName": "Dr. James",
    "lastName": "Smith",
    "title": "General Practitioner"
  },
  "appointmentType": {
    "id": "apt_001",
    "name": "General Consultation",
    "duration": 30,
    "fee": 85.00
  }
}

Use Cases¶

• Appointment confirmation workflows
• Patient arrival management
• Appointment details for staff
• Integration with calendar systems

Get Multiple Bookings¶

Retrieve appointment lists with powerful filtering and scheduling options.

Configuration¶

Resource: "Booking"
Action: "Get All"
Limit: 50                        # Number of records
Return All: false                # Pagination control

Date-Based Filtering¶

# Date range options
Date Field: "appointmentDate"
Date Period: "Next 7 days"       # Future appointments
Custom Start Date: "2024-02-20"
Custom End Date: "2024-02-27"

# Time-based filters
Time Filter: "Morning"           # 09:00-12:00
Time Range: "14:00-17:00"        # Custom time range
Include Weekends: false          # Exclude weekends

Advanced Filtering¶

# Status filtering
Status: "Confirmed"              # Specific status
Include Multiple: ["Confirmed", "Pending"]
Exclude Cancelled: true          # Hide cancelled appointments

# Staff filtering
Staff ID: "staff_123"            # Specific practitioner
Department: "General Practice"   # Department-based
Speciality: "Cardiology"         # Speciality filtering

# Patient filtering  
Patient ID: "pat_456"            # Specific patient
Patient Status: "Active"         # Active patients only
New Patients: true               # First-time patients

# Appointment type filtering
Appointment Type: "Consultation" # Specific type
Category: "Clinical"             # Appointment category
Duration: "30"                   # Specific duration

Example Filtered Query¶

# Today's confirmed appointments for Dr. Smith
Filters:
  appointmentDate: "2024-02-20"
  status: "Confirmed"
  staff.id: "staff_111"

Order By: "appointmentTime ASC"
Limit: 100

Use Cases¶

• Daily appointment schedules
• Staff workload planning
• Patient appointment history
• Clinic utilization reports

Create New Booking¶

Schedule new appointments with comprehensive validation and conflict checking.

Required Fields¶

Resource: "Booking"
Action: "Create"

# Minimum required data
patientId: "pat_123456789"
staffId: "staff_111"
appointmentDate: "2024-02-25"
appointmentTime: "10:30"
appointmentTypeId: "apt_001"

Complete Booking Creation¶

# Core Scheduling
patientId: "pat_123456789"
staffId: "staff_111"
appointmentDate: "2024-02-25"
appointmentTime: "10:30"
duration: 30
appointmentTypeId: "apt_001"

# Location Details
locationId: "loc_001"
roomId: "room_a1"

# Administrative
notes: "Follow-up consultation"
patientNotes: "Please arrive 10 minutes early"
priority: "Standard"

Validation and Conflict Checking¶

Automatic Validations:
  - Staff availability check
  - Room availability verification
  - Patient double-booking prevention
  - Opening hours validation
  - Holiday/closure checking

Conflict Resolution:
  - Suggest alternative times
  - Show available slots
  - Automatic waiting list option
  - Override capabilities for urgent cases

Example Response¶

{
  "success": true,
  "data": {
    "id": "bkg_987654321",
    "appointmentNumber": "A240225010",
    "status": "Pending",
    "appointmentDate": "2024-02-25",
    "appointmentTime": "10:30",
    "confirmation": {
      "emailSent": true,
      "smsSent": false,
      "confirmationCode": "ABC123"
    }
  },
  "warnings": [
    "Staff has another appointment ending at 10:25 - short gap"
  ]
}

Use Cases¶

• Online booking systems
• Phone booking workflows
• Bulk appointment scheduling
• Recurring appointment creation

Update Booking¶

Modify existing appointments with change tracking and notifications.

Configuration¶

Resource: "Booking"
Action: "Update"
Booking ID: "bkg_123456789"

# Fields to update
appointmentDate: "2024-02-26"
appointmentTime: "15:00"
status: "Confirmed"
notes: "Rescheduled at patient request"

Common Update Scenarios¶

Reschedule Appointment¶

Updates:
  appointmentDate: "2024-03-01"
  appointmentTime: "14:00"
  status: "Confirmed"
  notes: "Rescheduled from 2024-02-25"

Notifications:
  notifyPatient: true
  notifyStaff: true
  sendNewReminder: true

Change Status¶

Updates:
  status: "Arrived"
  checkedInAt: "2024-02-20T14:25:00Z"
  checkedInBy: "reception_user_001"

Automatic Actions:
  - Update waiting list
  - Notify staff of arrival
  - Start appointment timer

Update Participants¶

Updates:
  staffId: "staff_222"           # Change practitioner
  appointmentTypeId: "apt_002"   # Change appointment type
  duration: 45                   # Extend duration
  fee: 120.00                    # Update fee

Validations:
  - New staff availability
  - Room capacity for duration
  - Fee schedule compliance

Change Tracking¶

Automatic Tracking:
  - Previous values stored
  - Change timestamp recorded
  - User/system making change
  - Reason for change (if provided)

Change History:
  - Complete audit trail
  - Notification history
  - Status progression
  - Rescheduling timeline

Use Cases¶

• Patient rescheduling requests
• Status updates (arrival, completion)
• Staff assignment changes
• Administrative corrections

Cancel/Delete Booking¶

Cancel appointments with proper notification and waiting list management.

Configuration¶

Resource: "Booking"
Action: "Delete"
Booking ID: "bkg_123456789"
Cancellation Reason: "Patient cancelled"

Cancellation Types¶

Soft Cancellation (Recommended)¶

Updates:
  status: "Cancelled"
  cancellationReason: "Patient illness"
  cancelledAt: "2024-02-20T09:15:00Z"
  cancelledBy: "patient"

Preserve Data: true
Notify Stakeholders: true
Update Waiting List: true

Hard Deletion (Restricted)¶

Action: "Delete"
Permanent: true
Reason: "Duplicate booking"
Authorization: "supervisor_override"

Effects:
  - Complete record removal
  - Cannot be restored
  - Audit log entry only

Automatic Actions¶

When Booking Cancelled:
  1. Send cancellation notifications
  2. Update staff calendar
  3. Offer slot to waiting list
  4. Process refund if applicable
  5. Update availability system
  6. Log cancellation metrics

Trigger Node Operations¶

Monitor New Bookings¶

Automatically trigger workflows when appointments are scheduled.

Configuration¶

Resource: "Booking"
Event: "New Only"
Poll Interval: "Every 15 minutes"
Date Period: "Next 7 days"       # Monitor upcoming bookings
Limit: 20

Trigger Conditions¶

# Time-based triggers
Poll Frequency: "5m|15m|30m|1h|4h"
Lookback Period: "1h|4h|24h|7d"
Future Bookings: "Next 1-30 days"

# Status-based triggers
Include Status: ["Pending", "Confirmed"]
Exclude Cancelled: true
New Patients Only: false

# Volume controls
Max Records: 50
Batch Processing: true
Priority Handling: "urgent|standard|low"

Example Workflow¶

1. New Booking Trigger
   ↓
2. Send Confirmation Email
   ↓
3. Add to Staff Calendar
   ↓
4. Schedule Reminder (24h before)
   ↓
5. Update Practice Management System

Use Cases¶

• Booking confirmation automation
• Staff notification systems
• Calendar synchronization
• Reminder scheduling
• Waiting list management

Monitor Booking Updates¶

Track changes to existing appointments and automate responses.

Configuration¶

Resource: "Booking"
Event: "Updates Only"
Poll Interval: "Every 10 minutes"
Date Period: "Next 14 days"

Change Detection¶

Tracked Changes:
  - Status modifications
  - Rescheduling events
  - Participant changes
  - Note updates
  - Payment status

Change Metadata:
  - Previous values
  - New values
  - Change timestamp
  - Modified fields list
  - Change reason/source

Example Change Data¶

{
  "id": "bkg_123456789",
  "changes": {
    "status": {
      "from": "Pending",
      "to": "Confirmed",
      "changedAt": "2024-02-20T10:15:00Z",
      "changedBy": "patient_portal"
    },
    "appointmentDate": {
      "from": "2024-02-25",
      "to": "2024-02-26", 
      "changedAt": "2024-02-20T10:15:00Z",
      "reason": "Patient requested change"
    }
  }
}

Status-Specific Triggers¶

Confirmation Received:
  - Send confirmation email
  - Update staff calendar
  - Cancel waiting list notification

Appointment Rescheduled:
  - Send new appointment details
  - Update reminders
  - Notify staff of change

Patient Arrived:
  - Notify practitioner
  - Update waiting room display
  - Start consultation timer

Appointment Cancelled:
  - Send cancellation confirmation
  - Offer slot to waiting list
  - Process refund if needed

Use Cases¶

• Status change notifications
• Rescheduling automation
• Staff alerts and updates
• Payment processing triggers
• Waiting list management

Monitor All Booking Activity¶

Capture complete appointment lifecycle events in one trigger.

Configuration¶

Resource: "Booking"
Event: "New and Updates"
Poll Interval: "Every 20 minutes"
Date Period: "Next 30 days"

Activity Types¶

New Booking:
  - event: "created"
  - data: Complete booking record
  - metadata: Booking source, creation method

Updated Booking:
  - event: "updated"
  - data: Current booking record
  - metadata: Changed fields, change reasons

Cancelled Booking:
  - event: "cancelled"
  - data: Final booking state
  - metadata: Cancellation reason, timing

Completed Booking:
  - event: "completed"
  - data: Final appointment details
  - metadata: Duration, outcomes

Advanced Scheduling Patterns¶

Recurring Appointments¶

Weekly Recurring Schedule¶

# Create recurring appointment series
Base Appointment:
  patientId: "pat_123456789"
  staffId: "staff_111"
  appointmentTypeId: "apt_physiotherapy"
  duration: 45

Recurrence Pattern:
  frequency: "weekly"
  interval: 1                    # Every week
  dayOfWeek: "Tuesday"
  time: "14:00"
  endDate: "2024-06-01"         # End after 16 weeks

Advanced Options:
  skipHolidays: true
  allowRescheduling: true
  autoConfirmation: false

Monthly Recurring Schedule¶

# Monthly check-up appointments
Recurrence Pattern:
  frequency: "monthly"
  interval: 1                    # Every month
  dayOfMonth: 15                 # 15th of each month
  time: "10:00"
  duration: 30
  occurrences: 12               # 12 appointments total

Customization:
  adjustForWeekends: true       # Move to weekday if weekend
  skipDecember: true            # Skip holiday month
  alternateStaff: ["staff_111", "staff_222"]

Appointment Series Management¶

Create Series¶

1. Define Base Appointment
    - Patient, staff, type, duration

2. Set Recurrence Rules
    - Frequency, interval, end condition

3. Generate Series
    - Create all instances
    - Check availability conflicts
    - Apply business rules

4. Confirm Series
    - Send patient notification
    - Add to staff calendars
    - Set up reminders

Modify Series¶

Change Types:
  - Single Instance: Modify one appointment only
  - Future Instances: Modify this and all future
  - Entire Series: Modify all appointments

Common Modifications:
  - Reschedule entire series
  - Change staff for remaining appointments
  - Cancel future appointments
  - Extend or shorten series

Complex Scheduling Scenarios¶

Multi-Staff Appointments¶

# Team consultation appointment
Primary Staff: "staff_consultant"
Additional Staff: 
  - id: "staff_nurse"
    role: "Assisting Nurse"
    required: true
  - id: "staff_specialist"
    role: "Specialist Consultant"
    required: false

Room Requirements:
  - capacity: 4+
  - equipment: ["ECG", "Ultrasound"]
  - accessibility: true

Blocked Time Management¶

# Block time for administrative tasks
Block Time:
  staffId: "staff_111"
  startDate: "2024-02-20"
  endDate: "2024-02-20"
  startTime: "12:00"
  endTime: "13:00"
  reason: "Lunch Break"
  recurring: "daily"
  excludeWeekends: true

Emergency Slot Management¶

# Reserve emergency appointment slots
Emergency Slots:
  staffId: "staff_emergency"
  dailySlots: 3
  slotDuration: 20
  times: ["09:00", "13:00", "16:00"]
  bookingWindow: "Same day only"
  authorization: "clinical_staff_only"

Appointment Types and Configuration¶

Standard Appointment Types¶

General Consultation¶

appointmentType: {
  id: "apt_general",
  name: "General Consultation",
  duration: 30,
  fee: 85.00,
  category: "Primary Care",
  colour: "#4A90E2",
  bookingRules: {
    advanceBooking: "1-90 days",
    cancellationNotice: "24 hours",
    confirmationRequired: false
  }
}

Specialist Consultation¶

appointmentType: {
  id: "apt_specialist",
  name: "Specialist Consultation", 
  duration: 45,
  fee: 150.00,
  category: "Specialist Care",
  colour: "#E94B3C",
  bookingRules: {
    referralRequired: true,
    advanceBooking: "7-180 days",
    confirmationRequired: true,
    reminderSchedule: ["7 days", "24 hours"]
  }
}

Procedure Appointments¶

appointmentType: {
  id: "apt_procedure",
  name: "Minor Procedure",
  duration: 60,
  fee: 200.00,
  category: "Procedures",
  colour: "#F39C12",
  requirements: {
    roomType: "procedure_room",
    equipment: ["sterilization", "monitoring"],
    preAppointment: "consultation_required",
    postAppointment: "follow_up_scheduled"
  }
}

Custom Appointment Types¶

Practice-Specific Types¶

# Vaccination appointments
appointmentType: {
  id: "apt_vaccination",
  name: "Vaccination",
  duration: 15,
  fee: 25.00,
  category: "Preventive Care",
  automation: {
    preReminders: ["1 week", "1 day"],
    postInstructions: "vaccination_aftercare",
    nextAppointment: "schedule_if_series"
  }
}

# Telephone consultations
appointmentType: {
  id: "apt_telephone",
  name: "Telephone Consultation",
  duration: 20,
  fee: 45.00,
  category: "Remote Care",
  delivery: "telephone",
  requirements: {
    patientPhone: "verified",
    documentation: "enhanced_notes"
  }
}

Integration Patterns¶

Calendar System Integration¶

Two-Way Calendar Sync¶

Semble → External Calendar:
  Trigger: New/Updated Bookings
  Action: Create/Update Calendar Events

External Calendar → Semble:
  Trigger: Calendar Event Changes
  Action: Update Semble Bookings

Conflict Resolution:
  - Semble takes precedence for patient data
  - Calendar takes precedence for practitioner availability
  - Manual review for complex conflicts

Multi-Calendar Management¶

Practice Calendar:
  - All appointments
  - Room bookings
  - Staff schedules

Individual Staff Calendars:
  - Personal appointments only
  - Cross-practice coordination
  - External commitments

Patient Calendars:
  - Patient-facing appointments
  - Reminders and preparations
  - Follow-up scheduling

Patient Communication Integration¶

Automated Messaging Workflow¶

Booking Confirmed:
  → Send confirmation email
  → Schedule SMS reminder (24h before)
  → Add to patient portal calendar

Appointment Rescheduled:
  → Send updated details
  → Cancel old reminders
  → Schedule new reminders

Appointment Day:
  → Send arrival instructions
  → Notify of any delays
  → Provide arrival guidance

Multi-Channel Communication¶

Email Notifications:
  - Confirmation messages
  - Appointment details
  - Preparation instructions
  - Follow-up information

SMS Reminders:
  - Day-before reminders
  - Arrival notifications
  - Urgent updates

Portal Notifications:
  - Appointment history
  - Upcoming appointments
  - Rescheduling options

Waiting List Management¶

Automated Waiting List Processing¶

When Appointment Cancelled:
  1. Identify suitable waiting list patients
  2. Check patient availability preferences
  3. Send appointment offers (SMS/email)
  4. Process acceptances automatically
  5. Confirm new appointments
  6. Update waiting list status

Priority Management¶

Waiting List Priorities:
  1. Emergency/urgent cases
  2. Existing patients (follow-up)
  3. Referral appointments
  4. New patient appointments
  5. Routine/preventive care

Matching Criteria:
  - Appointment type compatibility
  - Staff preferences/requirements
  - Time preferences
  - Location preferences

Performance and Optimization¶

Query Optimization¶

Efficient Date Range Queries¶

# Optimized for daily schedules
Date Range: "appointmentDate = '2024-02-20'"
Staff Filter: "staffId = 'staff_111'"
Status Filter: "status IN ['Confirmed', 'Arrived']"
Order: "appointmentTime ASC"

# Optimized for weekly planning
Date Range: "appointmentDate BETWEEN '2024-02-19' AND '2024-02-25'"
Include Status: ["Confirmed", "Pending"]
Group By: "appointmentDate, staffId"

Pagination for Large Datasets¶

Small Queries: 25-50 records (daily schedules)
Medium Queries: 100-200 records (weekly planning)
Large Queries: 500+ records (reporting only)

Pagination Strategy:
  - Use cursor-based pagination for real-time data
  - Use offset pagination for reporting
  - Implement virtual scrolling for large lists

Caching Strategies¶

Static Data Caching¶

Appointment Types: Cache for 1 hour
Staff Schedules: Cache for 15 minutes
Room Availability: Cache for 5 minutes
Holiday Schedules: Cache for 24 hours

Dynamic Data Caching¶

Daily Schedules: Cache for 2 minutes
Availability Slots: Cache for 30 seconds
Booking Conflicts: No caching (real-time)
Patient History: Cache for 10 minutes

Security and Compliance¶

Data Protection¶

Appointment Data Security¶

Access Control:
  - Role-based appointment access
  - Patient-specific viewing restrictions
  - Staff schedule privacy

Data Encryption:
  - All API communications encrypted
  - Sensitive notes encrypted at rest
  - Patient contact details protected

Audit Logging:
  - All booking modifications logged
  - Access attempts recorded
  - Failed operations tracked

Privacy Compliance¶

Patient Privacy:
  - Appointment details visible only to authorized staff
  - Patient consent for communications
  - Opt-out mechanisms for reminders

Staff Privacy:
  - Personal schedule information protected
  - Cross-staff schedule access controlled
  - External calendar sync permissions

Healthcare Compliance¶

Clinical Governance¶

Documentation Standards:
  - Clinical notes templates
  - Outcome recording requirements
  - Follow-up scheduling protocols

Quality Assurance:
  - Appointment outcome tracking
  - Patient satisfaction monitoring
  - Clinical indicator reporting

Regulatory Requirements¶

UK NHS Standards:
  - Choose and Book compatibility
  - NHS number validation
  - Clinical coding standards

Data Retention:
  - Appointment records: 8 years minimum
  - Clinical notes: 8-25 years (depending on type)
  - Audit logs: 7 years minimum

Troubleshooting Guide¶

Common Booking Issues¶

Double Booking Prevention¶

Symptoms: "Appointment slot already taken"
Causes:
  - Simultaneous booking attempts
  - Cache inconsistency
  - External calendar conflicts

Solutions:
  1. Implement optimistic locking
  2. Real-time availability checking
  3. Conflict resolution workflows
  4. Manual override capabilities

Staff Availability Conflicts¶

Symptoms: "Staff member not available"
Causes:
  - Conflicting appointments
  - Leave/holiday periods
  - External commitments

Solutions:
  1. Check staff schedule integration
  2. Verify holiday calendar
  3. Enable alternative staff suggestions
  4. Implement waiting list options

Patient Communication Failures¶

Symptoms: "Confirmation emails not sent"
Causes:
  - Invalid email addresses
  - SMS delivery failures
  - Communication preferences

Solutions:
  1. Validate contact information
  2. Provide multiple communication channels
  3. Implement delivery confirmation
  4. Manual contact backup procedures

Debugging Techniques¶

Booking Flow Analysis¶

1. Check Patient Eligibility
    - Active patient status
    - Contact information validity
    - Previous appointment history

2. Verify Staff Availability
    - Working hours compliance
    - Existing appointment conflicts
    - Leave/holiday schedules

3. Validate Appointment Rules
    - Appointment type requirements
    - Duration compliance
    - Fee schedule accuracy

4. Test Communication Systems
    - Email delivery
    - SMS functionality
    - Portal notifications

Performance Monitoring¶

Key Metrics:
  - Booking success rate
  - Average response time
  - Failed booking attempts
  - Communication delivery rates

Monitoring Tools:
  - API response time tracking
  - Error rate monitoring
  - User experience analytics
  - System availability metrics

Next Steps¶

Explore related booking topics:

• Patient Operations - Patient management integration
• Product Operations - Service catalog and pricing
• Trigger Workflows - Advanced automation patterns
• Common Workflows - Booking automation examples

Need help? Check our Troubleshooting Guide or join the community discussions.