The Nomadia Field Service API
An external web API.
Nomadia Field Service GeoScheduling is a server application offering to external programs many ways to interact with it.
This guide describes the functions currently available for external programming.
The NFS API is a web-based API. Programs send HTTP or HTTPS requests to the NFS server, which returns standard HTTP responses.
Depending on the type of services and options selected, the resulting data is returned in a JSON, XML, or HTML formatted response
XML or JSON are the most commonly used formats for services to read / update data or perform a back-end optimization process. HTML responses are used in the graphical user interface management services
There are other ways to interact with NFS by programming that are not covered by this guide:
Using "circulation"": NFS can be configured to receive and send messages in different protocols.
The sender or receiver of these messages can be connected to dedicated programs (see Circulation Guide)
Internal extensions: NFS can be extended by including Java or JSP source code in certain predefined situations such as:
Participate in appointment updates yourself,
Intercept incoming flows to adapt them to a business logic,
Integrate Web pages into some application frameworks, ...
Contact the NFS service team to discover these other advanced integration techniques
Services and Documentation organization
Available services are grouped in six main services groups or families. These Groups are designed for classification and understanding but does not necessarly have a technical meaning in terms of common charactestics or naming.
Each of the group contains a list of actual web services, named accordingly to their tecnhical invocation process.
Each of this service can provide one or several web service method, defined as an individual entry point for an external program. Each Service Method is described by a documentation page in this guide.
The documentation page for method of a service describes :
technical aspects, such as name,available format,available version,specific url
functionnal aspects : description of behavior and information model (expected input data and ouptut data )
When possible, the service method page provide a example of use and a try service form.
For services having SOAP implemtation, the service is self-describing to external program by the way of its WSDL. WSDL is the service contract listing its complete capabilities.
In this case, the documentation page contain a link to this self-described information model.
stateless or statefull services
Most of the service's methods are stateless, meaning they can be run individualy without any requirement regarding preceding or next methods invoked.
They may affect the content of the data, but not the state of the application itself.
However, some service's methods are statefull.
They should be run in conjunction and in a specific sequence with other services.
This is for instance the case of the request of Scheduling proposal :
- A first service is used to get list of appointment'scheduling proposals. This list of proposals is kept on server
- The caller invoke another service to notify which proposal to select and apply.
- An ultimate call may be required, to inform the system that the dialog can be abandoned
This suit of request and response forms a dialog, which is identified and maintained on server side between client calls.
In NFS Api, these statefull service's methods are always parts of a one and unique service, and the information model of responses provides a identitier for this service session that must be provided in further requests.
Services groups
- MANAGING ENTITIES : This family of services groups services dedicated to extract , create update and delete all entities of the model, according to the NFS exchange model.
- MANAGING THE APPLICATION : This family of services groups services dedicated to monitor application , extract metadata, and run sequences of processes.
- MANAGING THE USER INTERFACE : This family of services groups url requests that can be used to command the display of NFS pages in a tiers web-application.
- SCHEDULING : This family of services groups services, generally statefull, dedicated to run a scheduling process (unitary or batch).
- GEOGRAPHICAL SERVICES : This family of services groups geographical services such as geocoding, routing, coordinates conversion. They mostly consists en shortcut to the analog services used by NFS internally (services provided by geoconcept solutions like "gcis","smartrouting jee","ugc jee", "geoconcept web"").
- MANAGING MOBILES : This family of services groups all rest services used by Geoconcept OptiTime Mobile Application. They may be used by another application assuming this application simulate the ID-based session dialog used by OTMobile.
Address, Format and version
each method of NFS services have an unique address on the server. For the same method, several addresses can exists
One adress specific for each Service protocol and format (SOAP, raw XML, or REST JSON). The format expected is usually described as a virtual forder in the service method address
One adress specific for each version of the service , usually through a virtual folder in the service method address
Example : in the service method address http://test-serveur5:8080/otgs/rest/v2/exportEntities/rest/getEntitiesProperties.json
v2 indicates that we call the second version of the method getEntitiesProperties of service exportEntities using rest protocol and json format
The available protocol, format and version are described at each service documentation page
The documentation only documents the last version of each service, when several version exists.
When releasing a new major version of the application, NFS ensure the application is still capable to serve the current and the previous version of each Service's method. Functionning of n-2 version is not guarantee.
Information Model
NFS Services are following common conventions to express the content of expected and returned information.
Note that services that provided as SOAP services are natively auto-described by their WSDL.
Common information
The inputs data for most of services can contain an optional "CommonInfo" section, used to provides login, password and ApiKey if required. Requirement of these data depends on the server configuration.
Response and error handling
The response of most of service usually contains a "result" section ,in addition to the actual resulting data expected from the feature. THis section indicates if methods is successful, and if not, provides a detail section to describes the errors.
Exchange Model
Each time the API requires the designation of an NFS entity or FIELD , in input or output data , the names and datatype used are extracted from the NFS Exchange Model described in this documentation.