Appointment Lifecycle

Overview

This document provides a comprehensive guide to the appointment lifecycle in KiviCare, covering all stages from creation to completion, including status management, payment processing, and related workflows.

Appointment Status Management

KiviCare uses five distinct status levels for appointment management:

• Cancelled (0) – Appointment has been cancelled
• Booked (1) – Appointment is confirmed and scheduled
• Pending (2) – Appointment awaiting confirmation (usually payment)
• Check-Out (3) – Patient has completed the appointment
• Check-In (4) – Patient has arrived and appointment is in progress

Appointment Creation Workflow

Form Submission Process

Required Information:

• Clinic selection (auto-selected for clinic staff)
• Doctor selection (auto-selected for doctor users)
• Patient selection (auto-selected for patient users)
• Service selection with pricing
• Appointment date and time slot
• Initial status based on user role and payment requirements

Optional Information:

• Appointment description
• Custom fields (Pro version)
• Additional forms (Pro version)
• File attachments (if enabled in settings)

Processing Workflow

Validation Steps:

1. Verify all required entities exist and are active
2. Check selected time slot availability
3. Validate appointment booking restrictions
4. Confirm service availability for selected doctor

Service Duration Management:

• Calculate total duration from all selected services
• Determine appointment end time automatically
• Block appropriate time slots for the appointment

Payment Handling:

• Patients with paid services must select payment method
• Free appointments are automatically confirmed
• Staff users can optionally process payments
• Payment status determines initial appointment status

Final Processing:

• Create appointment record with all details
• Link selected services to appointment
• Process payment if required
• Save any custom field data
• Generate telemed meeting links if applicable
• Create medical encounter for completed appointments
• Send confirmation notifications
• Sync with external calendars (Pro version)

Appointment Status Lifecycle

Status Transitions

PENDING → BOOKED → CHECK_IN → CHECK_OUT
   ↓         ↓         ↓
CANCELLED ← CANCELLED ← CANCELLED

Status Management Rules

PENDING → BOOKED

• Triggered by successful payment
• Manual confirmation by staff
• Auto-confirmation for free appointments

BOOKED → CHECK_IN

• Only on appointment date
• Staff action required
• Creates encounter if not exists

CHECK_IN → CHECK_OUT

• Completes the appointment
• Creates billing records
• Closes encounter

Any Status → CANCELLED

• Patient cancellation (with buffer restrictions)
• Staff cancellation
• Payment failure

Cancellation Buffer System

• Configurable time buffer before appointment (e.g., 2 hours)
• Prevents patient cancellation within buffer period
• Calculated using server timezone for accuracy
• Only applies to patient users, staff can cancel anytime

Payment Integration

Payment Gateways Supported

• PayPal
• Stripe
• Razorpay
• WooCommerce
• Knit Pay (dynamic gateway support)
• Manual/Offline payments

Payment Workflow

Payment Gateway Selection

• Required for patients booking paid services
• Optional for staff users creating appointments
• Automatically set to offline for free appointments

Payment Processing

• Secure payment processing through selected gateway
• Includes appointment details, service costs, and patient information
• Supports multiple currencies based on gateway configuration
• Automatic tax calculation (Pro version)

Payment Status Tracking

• Pending – Payment initiated but not completed
• Completed – Payment successful, appointment confirmed
• Failed – Payment unsuccessful, appointment remains pending
• Cancelled – Payment cancelled by user

Payment Result Handling

• Success redirects to confirmation page
• Failure redirects to retry or cancellation page
• Automatic status updates based on payment results
• Email notifications for payment confirmations

Slot Management

Slot Generation Process

Data Collection

• Doctor’s working sessions for the selected day
• Existing appointments and their durations
• Selected service duration requirements
• Clinic and doctor availability schedules

Slot Calculation

• Generate available time slots based on doctor sessions
• Remove time slots occupied by existing appointments
• Consider total service duration for proper slot blocking
• Account for buffer time between appointments

Availability Validation

• Check for doctor leaves and unavailability
• Verify clinic holiday schedules
• Apply booking restriction rules
• Ensure slots meet minimum advance booking requirements

Slot Validation Rules

• Same-day booking restrictions
• Pre-booking and post-booking limits
• Holiday and off-day restrictions
• Doctor availability schedules

Service Management

Service Types

1. Regular Services – Standard medical services
2. Telemed Services – Video consultation services
3. Multiple Services – Services that can be combined

Service-Doctor Relationships

• Each service is linked to specific doctors who can provide it
• Pricing can vary per doctor for the same service
• Service duration is defined per doctor-service combination
• Telemed capabilities are managed per service offering

Service Selection Rules

• Single service selection (default)
• Multiple service selection (if service allows)
• Telemed services require addon activation
• Price calculation based on doctor-service mapping

Notification System

Email Notifications

• Appointment confirmation
• Appointment reminders (configurable timing)
• Status change notifications
• Cancellation notifications

SMS/WhatsApp Notifications (Pro)

• Appointment reminders
• Status updates
• Payment confirmations

Push Notifications (API addon)

• Real-time appointment updates
• Mobile app notifications

Telemed Integration

Supported Platforms

• Zoom (KiviCare Telemed Addon)
• Google Meet (KiviCare Google Meet Addon)

Telemed Workflow

1. Service Selection – Choose from telemed-enabled services
2. Meeting Creation – Video meeting automatically created upon appointment confirmation
3. Link Distribution – Meeting links sent via email and SMS notifications
4. Meeting Management – Separate start/join links provided to doctors and patients
5. Meeting Updates – Links can be regenerated if needed

Meeting Information

• Meeting topic based on selected service name
• Scheduled for appointment date and time
• Duration matches total service time
• Unique meeting room for each appointment
• Automatic reminders with meeting links

Encounter & Billing

Encounter Creation

Triggers:

• Appointment status change to CHECK_IN
• Appointment status change to CHECK_OUT

Encounter Data:

• Links to appointment
• Patient and doctor information
• Encounter date and status
• Description and notes

Billing Process

Bill Creation

• Automatically linked to medical encounter
• Total calculated from all selected services
• Payment status reflects current payment state

Bill Items

• Individual line items for each service
• Quantity and per-service pricing
• Service descriptions and categories

Tax Calculation (Pro Version)

• Taxes applied based on clinic configuration
• Support for multiple tax types and rates
• Automatic calculation and inclusion in totals

Configuration Settings

Appointment Booking Restrictions

• Same-day booking only
• Pre-booking limit (default: 0 days)
• Post-booking limit (default: 365 days)

File Upload Settings

• Enable file attachments
• Multiple file support

Reminder Configuration

• Email reminders
• Reminder timing (default: 24 hours)
• SMS reminders (Pro version)
• WhatsApp reminders (Pro version)

Cancellation Settings

• Cancellation buffer
• Buffer enforcement
• Timezone handling

Description Settings

• Appointment descriptions
• Required descriptions

User Role Permissions

Patient Users

• Create appointments for themselves
• Must use payment gateway for paid services
• Can cancel appointments (subject to buffer restrictions)
• View only their own appointments

Doctor Users

• Create appointments for any patient
• Automatically assigned as the appointment doctor
• Manage appointment status
• Access appointments assigned to them only

Clinic Admin / Receptionist

• Create appointments for any patient in their clinic
• Assign any doctor within their clinic
• Full appointment management within clinic scope
• Access all appointments for their clinic

System Administrator

• Full access to all appointments across all clinics
• Manage global appointment settings
• System-wide appointment reporting and analytics

Best Practices

Appointment Management

• Always verify slot availability before confirming appointments
• Use appropriate status transitions
• Maintain clear communication through notifications
• Regular backup of appointment data

Payment Processing

• Ensure secure payment gateway configuration
• Test payment flows regularly
• Monitor payment status and handle failures gracefully
• Maintain payment audit trails

Data Security

• Protect patient information according to healthcare regulations
• Use secure connections for payment processing
• Regular security audits
• Proper user access controls

Performance Optimization

• Regular database maintenance
• Monitor peak booking times
• Implement caching
• Clean up old appointment data

Troubleshooting Common Issues

Slot Generation Problems

• Verify doctor session schedules
• Check service duration settings
• Validate clinic schedules and holidays
• Review booking restrictions

Payment Processing Issues

• Verify gateway credentials
• Check webhooks and SSL
• Test in sandbox mode
• Monitor gateway status

Notification Delivery Problems

• Verify email configuration
• Check SMS/WhatsApp API settings
• Test templates
• Monitor delivery logs

Telemed Integration Issues

• Confirm addon activation
• Verify API credentials
• Test meeting creation
• Check network/firewall settings