Introduction
This page presents an in-dept documentation of the Tokai Web Service.
Background Information
The TOKAI (Toolkit for ATM Occurrence Investigation) tool supports the entire process of safety occurrence investigation – ATS notification reporting, occurrence investigation, data gathering, risk assessment, conclusions, issuing of safety recommendations, querying, and statistics and reporting.
Taxonomy and Layout Engine
The Tokai web application is built on top of a Taxonomy and enables the users (ANSPs) to build their forms for notification, facts gathering and reporting from scratch. The process of building forms is simple and highly customizable and consists of adding fields from the Taxonomy on top of a design surface, adjust the appearance, edit names of sections, alignment, colors of the labels, etc. The component that embeds this functionality is the Layout Engine.
A Layout Template is built from a collection of Layouts, each of them of a certain Layout Category. Some Layout Categories are multipliable – Aircraft, Unit, Sector, Working Position, etc., enabling the User to add more layouts of the same type when he creates the Occurrence in the Web HMI, if case. The structure of the final template is then serialized to JSON and embedded in the Occurrence object on the server. This object is then de-serialized and used for future Update operations with the Occurrence.
Taxonomy Terminology
The TOKAI Taxonomy contains the following:
- A collection of Terms. Each Term has a collection of Inputs. Each Input has a certain Result Type – TextResult, NumberResult, DateResult, etc. These are TOKAI custom data types.
- A collection of TreeControls
- A collection of ExplanatoryFactorsOps
- A collection of ExplanatoryFactorsAso
Information gathering and storing
The ATS Notification System and Data Gathering System depend on the Layout Template produced by the Layout Engine component. Each Layout Template becomes one ATS Notification form or a Data Gathering form, respectively. These forms are used to collect the information which is then processed, stored, queried and analyzed.
The data filled in the ATS Notification form is saved and submitted. At that step, it becomes an ATS Notification, which represents the entry point of an incident into Tokai.
The Data Gathering System is responsible with starting an investigation, either based on an ATS Notification, or without it. All the factual information is fed into the system using this component. The risk assessment of the occurrence is realized through the Risk Analysis Tool component.
The Risk Analysis Tool together with the Risk Analysis Statistics function as a separate, independent subsystem. ANSPs can opt to use this subsystem decoupled from the tool itself. Each time a new risk analysis is created using RAT, the system also creates a main occurrence investigation and attaches the Risk Analysis to it, behind the scenes.
What is a Web Service?
According to Webopedia, a web service is
a standardized way of integrating Web-based applications using the XML, JSON, SOAP, WSDL or UDDI open standards over an Internet protocol backbone. Used primarily as a means for businesses to communicate with each other and with clients, Web services allow organizations to communicate data without intimate knowledge of each other's IT systems behind the firewall.
Unlike traditional client/server models, such as a Web server/Web page system, Web services do not provide the user with a GUI. Web services instead share business logic, data and processes through a programmatic interface across a network.
Web Service Approach
The TOKAI Web Service shall enable users (Organizations) to feed in data concerning ATS Notifications, Data Gathering and RAT into the TOKAI Database via a JSON based HTTP API.
The JSON format is preferred over XML for data exchange because it has a more efficient encoding mechanism and is easy to integrate in JavaScript applications.
The process of importing/ exporting data into/from TOKAI Database via TOKAI Web Service will consist of making a HTTP POST request to a certain endpoint with a custom JSON Request Payload, which will be described in the following paragraphs.
All requests sent to Tokai Web Service should contain an authentication token, otherwise, the access will be denied.
Access Token
In order to get access rights for the functionalities available in the Tokai Web Service, the following actions should be perfomed: An user account with Web Service permissions should be created in the current Organization. The credentials set for this used will be needed in order to access the Tokai Web Service functionalities.
Thus, a HTTP POST request should be sent to the following endpoint on the server. http://localhost:5001/ is the base url for a localhost installation. This base url should be changed according to the base url of your installation.
Access Token Request
POST http://localhost:5001/token HTTP/1.1
Host: localhost:5001
Connection: keep-alive
Content-Length: 146
Accept: application/json, text/plain, */*
Origin: http://localhost:5001
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.99 Safari/537.36
Content-Type: application/x-www-form-urlencoded
DNT: 1
Referer: http://localhost:5001/
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.8,ro;q=0.6
Cookie: _ga=GA1.1.1667362886.1471356366; __atuvc=0%7C38%2C0%7C39%2C0%7C40%2C0%7C41%2C2%7C42;
grant_type=password&username=ws_jlg&client_id=tokai_clientId&client_secret=tokai_secret&password=ws_jlg&orgId=ada0ce1c-12e7-4f26-9aa5-a62c0105533b
Request information displayed by the browser:
Sending the same request using Postman:
Access Token Response
If login is successful, the auth token is returned:
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 676
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/8.0
Access-Control-Allow-Origin: *
X-SourceFiles: =?UTF-8?B?QzpcV09SS1xUT0tBSVxTb3VyY2VcV2ViVUlcdG9rZW4=?=
X-Powered-By: ASP.NET
Date: Wed, 14 Dec 2016 14:34:30 GMT
{
"access_token":"fnn21hIKx_b1o92Z_lhrYhC5A6bj5K3B3AE0pQsfBABOE96X-79uci0kYZ1rzA0kwf-akeH04JZjvCXXbRsNSd_zNWjamzxd7FMqQH12QlWL03WbuS0higdRN-tYhT-T9phFGq4MhYhCDkQMeBmRInhrsROX9hZdaOBJi5WQlT4Dxr2KrLRvCTbHDvKXXdMS1sAud7kLvft6aqLMkOb4EyprmySvofw5SuTpkBM6HfsIxbtBx0C6g5csJdHDO9mg3Dio_4kxI3KwgGqwMVpY6Jpegdj86UjGmZZeKn99GlFm35U41iXX1UbasyHMyUgVIwWNOnCYGlPeFecorwBZBe04viuBU1-BEeLHVMUO86wCxhVbH-DqSYx-YWHNg2Z9lcKBmfQmhZwcnFn0s_sLcaGA6gagremPQfVydsDLSNI",
"token_type":"bearer",
"expires_in":604799,
"refresh_token":"5a79b70ef8184808ae9b621cfd817d2f",
"as:client_id":"tokai_clientId",
"userName":"ws_jlg",
".issued":"Wed, 14 Dec 2016 15:10:49 GMT",
".expires":"Wed, 21 Dec 2016 15:10:49 GMT"
}
Log out
In order to Log out, the user has to send a HTTP Post request to the url: http://localhost:5001/Profile/Account/LogOut. The request is illustrated below:
Log Out Request
POST http://localhost:5001/Profile/Account/LogOut HTTP/1.1
Host: localhost:5001
Connection: keep-alive
Content-Length: 0
Accept: application/json, text/plain, */*
Origin: http://localhost:5001
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.99 Safari/537.36
Authorization: Bearer fnn21hIKx_b1o92Z_lhrYhC5A6bj5K3B3AE0pQsfBABOE96X-79uci0kYZ1rzA0kwf-akeH04JZjvCXXbRsNSd_zNWjamzxd7FMqQH12QlWL03WbuS0higdRN-tYhT-T9phFGq4MhYhCDkQMeBmRInhrsROX9hZdaOBJi5WQlT4Dxr2KrLRvCTbHDvKXXdMS1sAud7kLvft6aqLMkOb4EyprmySvofw5SuTpkBM6HfsIxbtBx0C6g5csJdHDO9mg3Dio_4kxI3KwgGqwMVpY6Jpegdj86UjGmZZeKn99GlFm35U41iXX1UbasyHMyUgVIwWNOnCYGlPeFecorwBZBe04viuBU1-BEeLHVMUO86wCxhVbH-DqSYx-YWHNg2Z9lcKBmfQmhZwcnFn0s_sLcaGA6gagremPQfVydsDLSNI
DNT: 1
Referer: http://localhost:5001/
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.8,ro;q=0.6
Cookie: _ga=GA1.1.1667362886.1471356366; __atuvc=0%7C38%2C0%7C39%2C0%7C40%2C0%7C41%2C2%7C42;
Log Out Response
HTTP/1.1 200 OK
Cache-Control: private, s-maxage=0
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
X-AspNetMvc-Version: 5.2
X-AspNet-Version: 4.0.30319
X-SourceFiles: =?UTF-8?B?QzpcV09SS1xUT0tBSVxTb3VyY2VcV2ViVUlcUHJvZmlsZVxBY2NvdW50XExvZ091dA==?=
X-Powered-By: ASP.NET
Date: Wed, 15 Feb 2017 10:44:30 GMT
Content-Length: 16
{"success":true}