Home Blog Exploring Acumatica Field Service and Appointments

Exploring Acumatica Field Service and Appointments

Chris Hardgrove | December 23, 2020

Introduction

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:

  1. Gain a better understanding of how service orders and appointments are related
  2. Explore common functions and their impact
  3. Extend the Reopen Appointment method

A closer look at the DAC declaration for FSServiceOrder, we notice the composite key

  • SrvOrdType
  • RefNbr

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.

GIST: https://gist.github.com/tocohara/5865a6822b57758c947eadfefb2257b8

GIST: https://gist.github.com/tocohara/74db2312568daa394293c30dc934c8d6

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

  • SrvOrderTyp
  • RefNbr

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].

GIST: https://gist.github.com/tocohara/527b824cbfd007733c919e913199bbc0

Digging deeper, notice the attribute above inherits AlternateAutoNumberAttribute class. In particular, the method GetNextRefNbr provides us the method which generates the next reference number.

GIST: https://gist.github.com/tocohara/19b3875a11d703438f25b6b30d7f057a

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.

GIST: https://gist.github.com/tocohara/58502c8c149f71079b99f6a67bff8018

 

  • 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.

 

GIST: https://gist.github.com/tocohara/71e398397fb17b170d5e8ed5b3f363ac

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. 

  1. Create an event handler for the RowDeleting event of the Log cache.
  2. Create an extension for the ReopenAppointment method and insert the handler.

The new delegate for the event handler is defined below:

GIST: https://gist.github.com/tocohara/e0eed64468a00f5a8019b4b966332b51

ReopenAppointment is extended below.  Notice in the try & finally, the event handler is added.  This code snippet prevents the appointment logs from being deleted.

GIST: https://gist.github.com/tocohara/ac8a37ddc3cea4037716672b8abdfc8e

Summary

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.

Happy Coding!

Chris Hardgrove

Chris has been developing solutions on the Acumatica xRP Platform since 2012. In those early years for Acumatica, he received “countless” one-on-one instruction from “the” Mikhail Chtchelkonogov via Skype, learning all about the Acumatica and the xRP Development Framework. In 2018, Chris joined NexTech as a developer consultant.

Categories: Developers

Subscribe to our bi-weekly newsletter