Today we take a deeper look at Acumatica Field Service Orders & Appointments, to gain a better understanding of how they interact. Also, we will extend the appointments to employee timecard entries. Our goal for today is to accomplish three tasks:
- Gain a better understanding of how service orders and appointments are related
- Explore common functions and their impact
- Extend the Reopen Appointment method
A closer look at the DAC declaration for FSServiceOrder, we notice the composite key
This follows the similar approach Acumatica uses to describe other documents by a document type as well as a reference number in the following code.
Upon exploring the database, we notice the index SOID.
Note this field is marked as an integer with an identity seed in the database. In the DAC declaration, the field is marked with the PXIdentity attribute.
Upon inspection of the FSAppointment DAC, we notice the same fields
However, there is a slight deviation, when comparing the values of the reference number between FSServiceOrder & FSAppointment. When a new appointment is added to the service order, framework assigns the same service order reference number, & appends the string “-1”. As new appointments are added to the service order later, the Reference number is assigned, and the “1” string is incremented. Therefore, the second appointment will append “-2” to the RefNbr, and so forth. Why does this happen? An investigation of the field in the DAC point to an interesting attribute [AppointmentAutoNumberAttribute].
Digging deeper, notice the attribute above inherits AlternateAutoNumberAttribute class. In particular, the method GetNextRefNbr provides us the method which generates the next reference number.
Note that all appointments are related to a single service order. In this way, we understand a 1:N relationship between service orders and appointments.
One of the most common functions used in service appointments is to Reopen the appointment. By utilizing this action, the user can return the appointment status to “Not Started”. But there is more which occurs to the appointment. Let’s take a look at the code & discover what happens.
By utilizing this action, the user can return the appointment status to Not Started. But there is more which occurs to the appointment. Let us take a look at the code & discover what happens.
In the AppointmentEntry graph, notice the method ReopenAppointment. In the code of the method, we see some interesting points and method calls:
- ProcessReOpenItemLine – this method loops through the appointment line details, creates a copy of the details line, assigns the status as “Not Started”. Finally, the details view is updated with the new copy.
- ClearAppointmentLog – pay attention to this method. It will delete all of the log records which are NOT marked as Travel items.
- UpdateAppointmentDetActualFields – this method loops through the appointment details records. If the detail record has a service item or a stock item, and is related to a staff member, the SetDefaultExt method is called for the field ActualDuration. Also impacted is the Estimated and Actual quantities on the record. This will impact the totals for the appointment and the related service order.
Extending the Reopen Appointment Method
In a business case scenario, it was identified that the standard functionality of the Reopen Appointment method deletes the appointment log records. Consequently, those records are removed from the UI. A real-world scenario was raised, so that the client wishes to retain the log records, rather than delete them. This was necessary since the users preferred visual reminders of the logs, in the appointment screen. In order to accomplish this, two tasks must be completed. For this real-world scenario, we will override the OOTB functionality that is associated with the ReopenAppointment method.
- Create an event handler for the RowDeleting event of the Log cache.
- Create an extension for the ReopenAppointment method and insert the handler.
The new delegate for the event handler is defined below:
ReopenAppointment is extended below. Notice in the try & finally, the event handler is added. This code snippet prevents the appointment logs from being deleted.
In summary, service orders and appointments are shared greatly throughout the field service module. We have taken a closer look and see how these entities are related. Also, we have learned about a heavily-used function (Reopen Appointment) in the appointment entry screen, and several end-results which may appear unexpected. Finally, we learned how to override the function, in order to inject our own custom logic.