return to index

Web hooks: General information


Web hooks are configurable inside Nomadia Field Service GeoScheduling to call your public endpoints and inform your server of occurring actions with many configurable events through the circulation module (on appointments, customers, unavailabilities, events that are transforming on resource calendar : Apply new JobType, workedWeek, DutyPeriod (mostly invoked from Attendance Module)...)
Events triggable on monitoring:
Each event can be monitored in real time by an inside-listener from the circulation. It will inject the event in the circulation context.
Then, there are two ways to send that information to your web hook:
IMPORTANT NOTE : The requests sent to your web hook are not stored in any case in Nomadia Field Service database.
If it fails to reach your web hook endpoint for any reason (internal error, network error), an error log will be logged on Nomadia Field Service's side, and an application alert log will be stored too.
The administrator of OptiTime will have to subscribe to application alerts for "Export errors" and "Communication errors" to be able to consult those errors in the application alerts of the callcenter.
A single endpoint is needed to synch as many entity kinds as wanted, but for streaming supervision, the solution of one endpoint dedicated to one entity kind should be prefered.
We therefore encourage you to define as many endpoints as necessary to manage your business entities.

How to synch Nomadia Field Service entities with a send-entities-processor



The schema of the circulation send-entities-processor is available in (the circulation documentation)
The output-medium will define an http-connection with the following characteristics:

How to call your web hooks by configuring a rest-output-medium


The rest-output-medium is designed to be able to call almost any kind of web hook, with either direct authentication or with a first pass connection through a token retrieval (OAuth2).
The token is then available through a "X-auth-token" HTTP header that will be available in subsequent requests.
Its life duration is indifferent to Opti-Time : a new authentication request will be issued as soon as a previous request will have received a 401 Unauthorized error code (HTTP/1.0 - RFC 1945).
After 3 tries of authentication, if the token still can't be retrieved, the web hook request will be abandoned.
The schema of the circulation rest-output-medium is available in (the circulation documentation)
Here are the parameters to configure it
The rest-output-medium can define an http-connection with the following characteristics (BTW: same elements as for the http-init-connection):

Build the request parameters with query-params


A set of request parameters can be defined with as many query-params as needed. Each query-param is defined by 3 elements:

Sample notifier.properties resource to define a JSON request


notifier.properties is a ressource file that can be tuned in the Opti-Time config\param\resources subdirectory.
Remind that every exchange model field between brackets "[]" will be replaced with its subsequent value retrieved in the circulation context:
Here is the documentation of the exchange model out of which placeholders can be used.
One can use some indirections with the fields whose type are ID_FOREIGN or IDS_LIST, to access the linked entity's fields too.
For instance, suppose an appointment was put in the circulation context by an appointment-inside-listener, as an action on the appointment was done anywhere on Opti-Time.
Then one can access its customer's name through a placeholder [CUSTOMER.CUSTOMERNAME] (dotted notation to access fields of linked entities).
For IDS_LIST fields, they refers to a list of foreign entities ID. To export only a single ID, one can give its index between parenthesis: "TASKTYPES(2)" will only export the 3rd ID of the appointment's tasktypes (0 indexed).
Therefore, one can access the 3rd tasktype name of an appointment with "TASKTYPES(2).TASKTYPENAME"
And to retrieve every tasktype names, the notation with parenthesis without any index will do the trick "TASKTYPES().TASKTYPENAME"
An indirection on an IDS_LIST field without any parenthesis like "TASKTYPES.TASKTYPENAME", will only export the first item value, hence, the first tasktype's name only. 
notifier.restoutputmedium.appointment.create = {"myJsonAppointmentObject" : {"myappointmentId" : "[APPOINTMENTID]", "mycustomerId" : "[CUSTOMERID]","minimumBeginDate" : "[DATEMINBEGIN]","maximumEndDate" : "[DATEMAXEND]","status" : "confirmed", "myworkers" : "[ASSIGNEDRESOURCES]","beginDate" : "[DATETIME_APPOINTMENT]","endDate" : "[DATETIME_APPOINTMENT_END]"}} 
notifier.restoutputmedium.appointment.update = {"myJsonAppointmentObject" : {"myappointmentId" : "[APPOINTMENTID]", "mycustomerId" : "[CUSTOMERID]","minimumBeginDate" : "[DATEMINBEGIN]","maximumEndDate" : "[DATEMAXEND]","status" : "confirmed", "myworkers" : "[ASSIGNEDRESOURCES]","beginDate" : "[DATETIME_APPOINTMENT]","endDate" : "[DATETIME_APPOINTMENT_END]"}} 
notifier.restoutputmedium.appointment.delete = {"myJsonAppointmentObject" : {"myappointmentId" : "[APPOINTMENTID]"}}

Sample circulation_config.xml file to call 2 kinds of web hooks on any action on confirmed appointments upon their tasktype


This circulation configuration file can by set in the circulation_config.xml file under Opti-Time config/param directory.
Its name "circulation_config.xml" should be defined in the application_init.xml file under Opti-Time config/param directory.