Appointments Module


The module provides possibility to create appointments. Each appointment is associated with a specific person and contains information about the planned visit. This module does not store the information about patients, or does not specify the way in which the patient receives a reminders about their appointments. The Appointments module creates for each appointment scheduled reminders which sends events at a specified time period. So the way in which patient is informed depends only on the manner in which you handled the event. You decide when reminder will start and how often event will be fired, you must simply set the appropriate parameters.


This module requires an installed and enabled Scheduler module for scheduling reminders.


Appointment fields

Each appointment contains following fields:

Field Description Type
externalId External id of the person who is associated with this appointment. This is an arbitrary value controlled by your application. It allows tying appointment reminders with patients at their fire time. String
apptId Appointment id generated by the system String
appointmentDate Date for the appointment, events after this date will no longer be sent org.joda.time.DateTime
visitedDate Date of the fulfilled visit org.joda.time.DateTime
status Appointment status org.motechproject.appointments.domain.AppointmentStatus
sendReminders Flag to activate or deactivate sending reminders bool
reminderInterval Reminder interval org.joda.time.Period
reminderStartTime Time to start firing the reminder events org.joda.time.DateTime

Appointment status

Status can take one of the following values:

  • NONE - default value for the appointment.
  • MISSED - missed appointment.
  • UNSCHEDULED - unscheduled visit to the clinic.
  • VISITED - patient visited the clinic.
  • CONFIRMED - appointment confirmed before the visit.
  • REMOVED - appointment was canceled by the patient or provider.

Creating and Updating appointments

The obligation to create and update an appointments is on the side of implementation. The Appointment module provides the OSGI service to perform this operations. When appointmentDate or status will be changed then the old version of the appointment will be saved to the appointments logs.


Please note that when you update sendReminders to false value then reminders for this appointments will not be send

Scheduled reminders

For each created appointment Scheduler module performs a period repeating job (job will start if value of the sendReminders parameter is true). This job is built on the basis of information contained in each appointment:

  • appointmentDate - planned date of the visit(reminder end time).
  • reminderStartTime - reminder start time.
  • reminderInterval - the interval at which the reminders will be fired by the Scheduler module.

When a reminder triggers, an event will be sent with the Scheduler module will send event(org.motechproject.event.MotechEvent) with following subject Appointment.Reminder.{1}.{2}. First parameter is patient external id, second is appointment id generated by the system.

OSGI Service API

The Appointments module exposes an OSGi services org.motechproject.appointments.service.AppointmentService to perform common operations on patients appointments. The service provides the following API:

  • Appointment addAppointment(Appointment appointment) - create a new appointment, externalId param can’t be null(it associates appointment with the patient).
  • List<Appointment> addAppointments(List<Appointment> appointments) - create a new appointments.
  • void removeAppointment(String appointmentId) - remove appointment with given ID, and remove reminder created for it.
  • void removeAppointments(List<String> appointmentId) - remove appointments with given IDs.
  • Appointment updateAppointment(Appointment appointment) - update an appointment.
  • List<Appointment> updateAppointments(List<Appointment> appointments) - updates the list of appointments.
  • Appointment getAppointment(String appointmentId) - get the appointment with given ID.
  • List<Appointment> findAppointmentsByExternalId(String externalId) - get the appointments which are associated with person externalId.
  • List<Appointment> findAppointmentsByExternalId(String externalId, AppointmentStatus status) - get the appointments which are associated with person externalId and which have given status.
  • void toggleReminders(String externalId, boolean sendReminders) - toggle the reminders for a patient with externalId. If sendReminders == true then send reminders for patient, otherwise stop reminders for patient.

The following is an example of creating a new appointment.

Appointment appointment = new Appointment();
DateTime reminderStartTime =; // start send events tomorrow
DateTime appointmentDate = new DateTime(2014, 6, 30, 17, 0, 0, 0); // 2014-06-30 17:00:00
Period reminderInterval = new Period(24, 0, 0, 0); //reminder will be sent every 24 hours from reminderStartTime to appointmentDate

appointment.setStatus(AppointmentStatus.CONFIRMED); // Visit is confirmed
appointment.setSendReminders(true); // Enable reminders

appointmentService.addAppointment(appointment); // add new appointment


This module does not require any custom configuration.