BAH-3869 - Document the date when an appointment was issued to a patient

api/src/main/java/org/openmrs/module/appointments/model/Appointment.java

@@ -23,6 +23,12 @@ public class Appointment extends BaseOpenmrsData implements Serializable {
     private Integer appointmentId;
     private String appointmentNumber;
     private Date dateCreated;
+    /**
+     * The date when the appointment was scheduled. This can be today or in the past (for retrospective entry), but not in the future.
+     * This property is useful for documenting the visit when the patient booked the appointment or when the patient called to book the appointment
+     * NOTE: This is *not* the date the appointment is scheduled to take place. We use startDateTime for this
+     */
+    private Date dateAppointmentScheduled = new Date();
     private Patient patient;
     private AppointmentServiceDefinition service;
     private AppointmentServiceType serviceType;
@@ -250,6 +256,14 @@ public Date getDateCreated() {
         return dateCreated;
     }
 
+    public Date getDateAppointmentScheduled() {
+        return dateAppointmentScheduled;
+    }
+
+    public void setDateAppointmentScheduled(Date dateAppointmentScheduled) {
+        this.dateAppointmentScheduled = dateAppointmentScheduled;
+    }
+
     @Override
     public void setDateCreated(Date dateCreated) {
         this.dateCreated = dateCreated;

api/src/main/resources/Appointment.hbm.xml

@@ -45,6 +45,7 @@
         <property name="comments" type="java.lang.String" column="comments"/>
 
         <property name="dateCreated" type="java.util.Date" column="date_created"/>
+        <property name="dateAppointmentScheduled" type="java.util.Date" column="date_appointment_scheduled"/>
         <property name="dateChanged" type="java.util.Date" column="date_changed"/>
         <property name="uuid" type="java.lang.String" column="uuid" length="38" unique="true"/>
         <property name="voided" type="java.lang.Boolean" column="voided" length="1" not-null="true" />

api/src/main/resources/liquibase.xml

@@ -731,4 +731,22 @@
         <addForeignKeyConstraint constraintName="patient_appointment_fulfilling_encounter_map_patient_appointment" baseTableName="patient_appointment_fulfilling_encounter_map" baseColumnNames="patient_appointment_id" referencedTableName="patient_appointment" referencedColumnNames="patient_appointment_id"/>
         <addForeignKeyConstraint constraintName="patient_appointment_fulfilling_encounter_map_encounter" baseTableName="patient_appointment_fulfilling_encounter_map" baseColumnNames="fulfilling_encounter_id" referencedTableName="encounter" referencedColumnNames="encounter_id"/>
     </changeSet>
+    <changeSet id="add_date_appointment_scheduled_20240528" author="aojwang">
+        <preConditions onFail="MARK_RAN">
+            <not>
+                <columnExists columnName="date_appointment_scheduled" tableName="patient_appointment"/>
+            </not>
+        </preConditions>
+        <comment>add a column to record the date an appointment was issued</comment>
+        <addColumn tableName="patient_appointment">
+            <column name="date_appointment_scheduled" type="DATETIME">
+            </column>
+        </addColumn>
+    </changeSet>
+    <changeSet id="fill_date_appointment_scheduled_20240603" author="aojwang">
+        <comment>Default the date an appointment was issued to the appointment date_created</comment>
+        <sql>
+            update patient_appointment set date_appointment_scheduled = date_created where date_appointment_scheduled is null;
+        </sql>
+    </changeSet>
 </databaseChangeLog>

omod/src/main/java/org/openmrs/module/appointments/web/contract/AppointmentDefaultResponse.java

@@ -9,6 +9,7 @@ public class AppointmentDefaultResponse {
 	private String uuid;
 	private String appointmentNumber;
 	private Date dateCreated;
+	private Date dateAppointmentScheduled;
 	private Map patient;
 	private AppointmentServiceDefaultResponse service;
 	private Map serviceType;
@@ -194,4 +195,12 @@ public Date getDateCreated() {
 	public void setDateCreated(Date dateCreated) {
 		this.dateCreated = dateCreated;
 	}
+
+	public Date getDateAppointmentScheduled() {
+		return dateAppointmentScheduled;
+	}
+
+	public void setDateAppointmentScheduled(Date dateAppointmentScheduled) {
+		this.dateAppointmentScheduled = dateAppointmentScheduled;
+	}
 }

omod/src/main/java/org/openmrs/module/appointments/web/contract/AppointmentRequest.java

@@ -16,6 +16,7 @@ public class AppointmentRequest {
     private String serviceTypeUuid;
     private String providerUuid;
     private String locationUuid;
+    private Date dateAppointmentScheduled;
     private Date startDateTime;
     private Date endDateTime;
     private String status;
@@ -135,4 +136,12 @@ public String getPriority() {
     public void setPriority(String priority) {
         this.priority = priority;
     }
+
+    public Date getDateAppointmentScheduled() {
+        return dateAppointmentScheduled;
+    }
+
+    public void setDateAppointmentScheduled(Date dateAppointmentScheduled) {
+        this.dateAppointmentScheduled = dateAppointmentScheduled;
+    }
 }

omod/src/main/java/org/openmrs/module/appointments/web/mapper/AppointmentMapper.java

@@ -99,6 +99,10 @@ public void mapAppointmentRequestToAppointment(AppointmentRequest appointmentReq
         if (StringUtils.isNotBlank(appointmentRequest.getStatus())){
             appointment.setStatus(AppointmentStatus.valueOf(appointmentRequest.getStatus()));
         }
+
+        if (appointmentRequest.getDateAppointmentScheduled() != null) {
+            appointment.setDateAppointmentScheduled(appointmentRequest.getDateAppointmentScheduled());
+        }
         appointment.setServiceType(appointmentServiceType);
         appointment.setService(appointmentServiceDefinition);
         //appointment.setProvider(identifyAppointmentProvider(appointmentRequest.getProviderUuid()));
@@ -199,6 +203,7 @@ private AppointmentDefaultResponse mapToDefaultResponse(Appointment a, Appointme
         response.setUuid(a.getUuid());
         response.setAppointmentNumber(a.getAppointmentNumber());
         response.setDateCreated(a.getDateCreated());
+        response.setDateAppointmentScheduled(a.getDateAppointmentScheduled());
         response.setPatient(createPatientMap(a.getPatient()));
         response.setService(appointmentServiceMapper.constructDefaultResponse(a.getService()));
         response.setServiceType(createServiceTypeMap(a.getServiceType()));