Sample Appointment Java Class
The Appointment Java Class Interface referenced on your external system's feature configuration is responsible for interaction with the XAI real time outbound message engine to communicate with the external system for appointment logic.
The base product provides a default java class (called com.splwg.wfmi.workforce.DefaultWFMSystem) for appointment integration that may be used if it provides the logic your implementation needs.
Note: 
Oracle Utilities Mobile Workforce Management. Refer to documentation on integration for information about the java class provided for integration with Oracle Utilities Mobile Workforce Management.
The default java class provided with the base product does the following:
• Extracts additional field activity information not provided by the appointment page service
• Converts the data in the page service and the additional FA information into an XML document
• Invokes the real time outgoing message engine.
Responses received from the engine are in the form of an XML document. The java class transforms the information into a format recognized by the page data model and sends it back to the user exit.
Note: 
The CILOAPTP.xml found on the xmlMetaInfo directory describes the base structure of the Show Appointment, Book Appointment and Cancel Appointment request XML. The selected field activity to be booked or canceled has an additional faExtraInfo element. The faExtraInfo element follows the structure described by CILOEFIP.xml.
The following sections describe more detail about the logic provided by the sample base product appointment Java class interface.
• Get Available Appointments
• Book Appointment
• Cancel Appointment
Get Available Appointments
For obtaining available appointments, the user exit passes the NDS type that references the Get Available Appointments condition flag. All the data available on the page service is passed to the engine as an XML document including any user defined search fields.
The user exit expects a response to this message to return a collection of records to display in the available appointments grid on the appointment page, including any user defined result fields. Any errors received are communicated to the user.
Note: 
Translate Message. Any error message received from the external system is translated from an external message to an appropriate system error message using the message information on the external system's feature configuration.
Top of the Page
Book Appointment
Once the user has confirmed the desired appointment with the customer, the user attempts to book the appointment. The generic appointment integration java class provided with the system sends a message to books appointments real time. The user exit passes the NDS type that references the Appointment Book condition flag.
Note: 
One FA at a time. The sample user exit provided by the system only supports booking appointments for one field activity at a time. As a result, if you want to use the sample user exit, your external systems should be configured with the option Allow Multiple Reservations set to N. If your organization would like to support booking appointments for multiple field activities at once, you may create your own user exit to provide this capability.
The sample user exit provided with the product expects either a positive or negative response to this message.
• If a positive response is received, the user exit expects to be passed a reservation number and an indication of whether or not the appointment was forced. It populates the field activity characteristics collection with these values using the Reservation Characteristic Type and Appointment Forced Characteristic Type defined as options on the external system's feature configuration.
• If a negative response is received, an error message is displayed to the user.
Note: 
Translate Message. Any error message received from the external system is translated from an external message to an appropriate system error message using the message information on the external system's feature configuration.
If the message engine cannot communicate with the external system, it returns an indication to the user exit. The user exit proceeds as follows:
• If the external system indicates that Allow Manual Appointments is set to false an error is displayed to the user.
• If manual appointments are allowed, the user exit issues a warning to the user asking if the message should be logged and sent when the communication is up again. If the user agrees, the user exit invokes the java class asking it to post a near real time message.
◦ The user exit calculates a unique outgoing message ID for the external system. The message id is calculated using a database sequence whose name is referenced in the option Message ID Database Sequence Name on the external system's feature configuration. This message id is passed to the real time message engine to be populated as an NDS context entry to support an asynchronous response to the message.
◦ The user exit passes the NDS type that references the Appointment Book - Near Real Time condition flag. The FA Id is also passed to the real time message engine to be posted as an NDS context entry. The system expects that the response to this message will create an XAI upload staging record and that this record will update the field activity's characteristics with the reservation and forced appointment information (if applicable). Refer to Near Real Time NDS Messages for more information about responses to near real time messages and XAI upload staging.
◦ If the external system's configuration indicates that forced appointments are allowed, the message is sent to the external system with the forced indication set. If the external system does not allow forced appointments, it's possible that this manual appointment could be rejected by the external system.
If no error is received, the appointment page continues with the "change" action. An appointment period is created for the chosen appointment time if one doesn't already exist and the appointment period is linked to the field activity.
Note: 
that the appointment period is created and linked to the field activity even if the message is sent to the external system in near real time and no confirmation has been received. This was done to record the requested appointment in our system to cater for the situations when the customer wants to change or cancel the appointment prior to receiving the acknowledgement from the external system.
Top of the Page
Cancel Appointment
If the customer wants to cancel the appointment, the user navigates to the appointment page. The generic appointment integration java class provided with the system sends a message to cancel an appointment real time. The user exit passes the NDS type that references the Appointment Cancel condition flag. The user exit expects either a positive or negative response to this message.
• If a positive response is received, the appointment page continues with the change action. (See below).
• If a negative response is received, an error message is displayed to the user.
Note: 
Translate Message. Any error message received from the external system is translated from an external message to an appropriate system error message using the message information on the external system's feature configuration.
If the message engine cannot communicate with the external system, it returns an indication to the user exit. The user exit proceeds as follows:
• If the external system indicates that Allow Manual Appointment Cancellation is set to false an error is displayed to the user.
• If manual appointments are allowed, the user exit issues a warning to the user asking if the message should be logged and sent when the communication is up again. If the user agrees, the user exit invokes the java class asking it to post a near real time message.
◦ The user exit calculates a unique outgoing message ID for the external system. The message id is calculated using a database sequence whose name is referenced in the external option Message ID Database Sequence Name on the external system table. This message id is passed to the real time message engine to be populated as an NDS context entry to support an asynchronous response to the message.
◦ The user exit passes the NDS type that references the Appointment Cancel - Near Real Time condition flag. The FA Id is also passed to the real time message engine to be posted as an NDS context entry. A response to this message will be an acknowledgement. No further updates to field activity data are expected.
If no error is received, the appointment page continues with the "change" action. The appointment period is unlinked from the field activity and if no other field activities are linked to this appointment period, the appointment period is deleted. In addition, the field activity characteristics for the reservation number and forced appointments are removed from the FA.
Note: 
The above updates are performed even if the message is sent near real time and no response has been received. This was done to cancel the appointment in our system to cater for the situations when the customer wants to rebook the appointment prior to receiving the acknowledgement from the external system.