Skywise SDK

Skywise SDK serves as a wrapper on Skywise APIs, it was built due to the complexity of interacting with these APIs and reduce efforts to maintain the code later on. In the following sections, you will be introduced to all features Skywise has to offer and how using Skywise SDK benefits you while implementing them into your application.

The Skywise SDK is written and fully available with Nodejs.

Language Maintained? Parity?
NodeJS Yes Full

Maintained: Fully maintained projects are actively developed by Box. They receive the latest security updates and new features. For support with these projects please visit GitHub or our Platform support forum.

API Parity: Projects with full API parity are actively updated with all platform functionalities as soon as they are available on the Box Platform. Projects with partial API parity lack some functionality while we work on bringing these projects to full parity.

Required setup steps.

Install the Skywise SDK in your preferred language.

Then configure your Skywise SDK environment. Required for all SDK integrations

Skywise SDK Feature Support

Skywise SDK provides features, which serve as bridges between Skywise Core and other services:

Skywise SDK Architecture

Overview

As a wrapper, SDK must follow strictly the design of REST API. This document present the role of SDK in the ecosystem and the design of Skywise application.

Supported HTTP methods

Method Description
GET Retrieve list of data or get detail of a record from the Skywise platform, such as the list of aircrafts, view an aircraft details by its PK.
POST Send details to the Skywise platform, such as an authorization or settlement request. POST is also used to create a new entity e.g. a customer's address.
DELETE Delete a record or transaction from the Skywise platform.
PUT Change or update an existing record on the Skywise platform.

How SDK works

How SDK Works

Skywise SDK Environment

Overview

Skywise SDK is a part of the Skywise ecosystem and users gain access to Skywise data through it, for that, a few environment variables need to be prepared before going any further.

Notes: You are only supported if you have an official contract with Airbus and have the right to use Skywise SDK

Security Headers

Coarse-grain security headers: client_id / client_secret

API CI(client_id) and CS(client_secret) play a role as keys for SDK to integrate with Skywise APIs which are published via MuleSoft, through that, we can have your identity, permission and your scope.

At the moment, users are not able to generate CI, CS by themselves without contacting Skywise's support.

Fine-grain security header: Authorization

Also known as Access Token, which provides authentication and authorization to retrieve your data. By following these steps, you can manually claim your Token. Note that you are only able to do this if you have access to Skywise core account and the token should not be shared with others.

After login Skywise core, navigate to Account > Settings

Account Settings

At the Settings window, navigate to Tokens tab

Token page

Functions Creating token

Create Token

Will return a token with uniquely defined name, this is due to that each application should have it's unique Token. And the token's duration could be set suitable to your demand.

When the token is created, it will pop up only one time, and users must save it in a secured place by themselves.

Token Created

Now users are able to use access token for APIs or SDK.

Moreover, user can suspend token separately and switch them on anytime:

Disable Token

Or revoke it. Note: this is irreversible, so think carefully before choosing to take this step:

Revoke Token

Props: easily to obtain the token via Foundry account management site.
Cons: it’s a long time duration (up to 6 months) to expire. Risk on security concern for leak data by using this kind of token. Manually monitor and maintain this token.

Skywise OAuth2:

Instead of manually generating the token, Skywise SDK provides a wrapper component to execute Authorization Code Grant mechanism of OAuth2 to obtain the end user’s access token via a third party application authorized with Skywise. Currently, Skywise SDK is supported on confidential client and “public client” pattern flows to authorize users. There’s 2 steps require to archive the token by yourself:

Obtain the authorization code

To obtain the Skywise authorization code, the client has to generate a redirect url to Skywise OAuth2 Authorization page: https://core.skywise.com/foundry-multipass/api/oauth2/authorize and included these parameters:

To registered and enabled your application with Skywise OAuth2, see Secure Third-party application with Foundry for the process.

In the case configuration of your application is public client, the code_challenge and code_challenge_method (PKCE) are required.

The application’s scope is defined and relies on Skywise OAuth2’s definition. Below are some examples of commonly-used scopes:

Scope Description
compass:discover Permission to discover resources with Compass service
compass:view Permission to view resources with Compass service
compass:edit Permission to edit resources with Compass service
lime:search-index Permission to search indexed data with Phonograph2 services
offline_access Required to for the client to receive a refresh token

Exchange the access token (Bearer Token)

After receiving the authentication code responsed, your client should send a POST request to this end point to exchange the access_token: https://core.skywise.com/foundry-multipass/api/oauth2/token, including:

Integrate Skywise OAuth2 using SDK’s Simple Login Component:

Skywise offers a React based component - “SkywiseOAuth2Login” to adapt the authentication and authorization process between Third-party application and Skywise OAuth2.

You can download this component via our Airbus’s Git repository: https://github.airbus.corp/Airbus/2j17-skywise-simple-login

Basically, this component supported application to generate a Login <button/>. When the user click on it, it will open the Skywise Login page, in a popup. After user successfully login with their account, it will return to the application the user's access_token

This component supported on both public and confidential client application.

After downloading this component, you can simply import it:

				
import React from 'react';
import SkywiseOAuth2Login from '2j17-skywise-simple-login';

class SkywiseLogin extends React.Component{

	onSuccess(response){
		// console.info(response.access_token);
		...
	}
	
	onFailure(error){
		...
	}

}
				
			

Using this component for public client application with client_id and PKCE:

				
<SkywiseOAuth2Login
	clientId={YOUR_CLIENT_ID}
	redirectUri={YOUR_REDIRECT_URI}
	scope="offline_access compass:view"
	pkceEnable="true"
	onSuccess={(res) => this.onSuccess(res)}
	onFailure={(err) => this.setError(err)} />

				
			

for confidential application:

				
<SkywiseOAuth2Login
	clientId={YOUR_CLIENT_ID}
	clientSecret={YOUR_CLIENT_SECRET}
	redirectUri={YOUR_REDIRECT_URI}
	scope="offline_access compass:view"
	onSuccess={(res) => this.onSuccess(res)}
	onFailure={(err) => this.setError(err)} />
				
			

List of parameters to initialize this component:

clientId– {string} - requiredThe client ID for application, is given by after finished the registering and enabling with Skywise OAuth2.

clientSecret – {string}: The client Secret for application, also given after finished the registering and enabling with Skywise OAuth2. Required if configuration for server side otherwise it’s optional for client side

redirectUri– {string} - required: Registered redirect URI for an application (where you're asked to fill in the redirect URI in Skywise OAuth2 registered).

scope– {string} - required : Reference to available client scope which describe by Palantir’s services.

state – {string} – optional: The client state used to maintain state between the request and callback.

pkceEnable – {boolean}: Part of PKCE implementation. By default, it’s set to false which applied on server side. Otherwise, true would applied on client side.

buttonText – {string} - optional: The text displayed by the button.

buttonCss – {string} – optional : CSS class to customize the UI/UX of button.

onSuccess – {function} – required: Callback success function.

onFailure – {function} – required: Callback failure function.

Cons:

Cabin defect prerequisite

For cabinDefects APIs and cabinDefectsRfid, users need to specify their dataset with Phonograph tableRID. This field is only available with datasets that are already synced to Phonograph. Follow these steps to get tableRID:

These variables are required to set up authentication function and retrieve data from Skywise core. Head over to Set up guide to understand how to use them.

Quick-start for Skywise SDK

Overview

This page will walk you through the steps of installation, configuration and implementing Skywise SDK

Installation:

After receiving the SDK package (through Email or Downloaded). Extract the package and move it into your repository. Along with the SDK, a package.json is also delivered. Run this command to install it:

Using NodeJS:

				
npm run install   
				
			

Install for using SDK on client web

				
npm run build:browser   
				
			

After installation successful, under folder output: sdk.js file is generated and ready to import under ./src/sdk at any client application space.

Import to your Application

After installation has completed, user is free to use SDK as a normal library by importing it into the scripts. For security, each SDK file was deliver to user with a default configuration stick with their account information, which helps user to construct SkywiseInterface without adding sensitive data.

In case you need to update your authentication such as ci, cs or Authorization , as these information might run out of date, function is offered setAuth( AuthObj ) to do so. With AuthObj contain one or all element ci, cs or Authorization.

Below example demonstrates how to use the function with accessToken which can be acquired as instruction

After archived the access token, can used setAuth( AuthObj ) offered function below to inject the token into SDK before persist any command to query data in Skywise.

NodeJS

				
const SkywiseSDKInterface = require('path/to/sdk.min.js');
// Authentication before using other functions
const skywiseSDK = new SkywiseSDKInterface();
// with accessToken is grant from core.Skywise.com
skywiseSDK.setAuth({
	Authorization: accessToken
});   
				
			

Using Ontology Class

NodeJS

				
const ontologyObj = skywiseSDK.ontologyClass();  
				
			

Using CabinDefect Class

Nodejs

				
const cabinDefectObj = skywiseSDK.CabinDefect('cabin_defect', tableRid);
				
			

Ontology Class

Skywise SDK offers Ontology Object as the end-point where user can retrieve data with popular SQL syntax. Although you might understand that SQL are used for traditional database system but the response data will still be in json format which support both structured and semi-structured data.

We will go deeper into how this works as you proceed further.

Constructor

skywiseSDK.ontologyClass() ⇒ Object

To invoke an Ontology object, do as follow:

				
const SkywiseSDKInterface = require('.path/to/sdk.min.js').default;
let ontologyObj;
const skywiseSDK = new SkywiseSDKInterface();
skywiseSDK.setAuth({your Auth}) 
//remember to setAuth on your skywiseSDK object before invoking ontologyClass
ontologyObj = skywiseSDK.ontologyClass();
				
			

From this point, you are ready to query data. Learn how to in the next session.

Execute

ontologyObj.execute(string) ⇒ Promise

The inputted SQL will be translated to Https request in the background, so you can just stick with the easy SQL while SDK takes care of the hard part. If you are not familiar with the SQL syntax, we highly recommend the following SQL grammar. For now, we only support a group of P0 APIs. Aware that permission is required for execution.

Supported APIs:

Supported APIs Supported APIs

In more detailed, a SQL query, which sets:

If you want to load next page, you need set token='${nextPageToken}' in SQL query - nextPageToken which will be return from the Promise data.

The condition plays a role of filter, the response only contains value that fit this condition, as it is an object, there is no limitation set on this filter.

Example simple query

			
ontologyObj.execute('select * from aircrafts').then(function({data}) { // Promises!
	console.log('get aircrafts data completed successfully', data);
}).catch(error => {
	console.log('get aircrafts data not successful', error);
})				
			
		

Example query with limit record and get nextPageToken

			
ontologyObj.execute('select * from aircrafts order by issue_time asc limit 10').callback()				
			
		

Example use nextPageToken to load next page

			
ontologyObj.execute(`select * from aircrafts where token='${nextPageToken}' limit 10`).callback()	
			
		

Example execute with condition

			
ontologyObj.execute(`select * from aircrafts`, {aircraft_type: 'a320'}).callback()
			
		

Cabin Defect Class

Introduction

Cabin Defect application

Cabin Defect analytic dashboard application is the one of most popular application on Skywise thanks to the insights it provides. The application gives an overview of defects on specific aircraft, along with it's type, date of occurrence and location of the defect.

Remarks: this services is not ready at the moment, require to reach DXDA team for set up all prerequisites to be able start working on this class.

Cabin Defect with Skywise SDK

With the help of Skywise SDK, user now has the choice to retrieve their own data and customize the application suited to their needs and liking as well as adding more complex analysis and features. Next sections will guide you through this process.

Constructor

Before you begin:

skywiseSDK.CabinDefect(className, TableRID); ⇒ Object

To start calling APIs and getting your data, you will need to define an application object which serves as endpoint to execute request handling functions.

Cabin Defects Params Example
			
const skywiseSDK = new SkywiseSDKInterface();
const cabinDefectObj = skywiseSDK.CabinDefect('cabin_defect', 'ri.phonograph2.main.table.${table RID}');
			
		

GetCategory

getCategory(startDate, endDate) ⇒ Promise

This API returns list of category of the defects with startDate and endDate as a range.

To execute a function from the object, pass in function name along with it's parameters. This will return back a response that contains a Json data. Keep in mind that all parameters should be input as below order.

Example

GetAircraftType

getAircraftType(category, startDate, endDate) ⇒ Promise

This API returns list of aircraft type which has defects in cabin of referenced category, takes startDate and endDate as a range.

To execute a function from the object, pass in function name along with required parameters. This will return back a response that contains a Json data. Keep in mind that all parameters should be input as below order.

Example

GetAircraftRegistration

getRegistration(aircraftType, category, startDate, endDate) ⇒ Promise

This API returns list of aircrafts( aircraft registration ) with pre-designed aircraft type , which have defects of referenced category ,takes startDate and endDate as a range.

To execute a function from the object, pass in function name along with it's parameters. This will return back a response that contains a Json data. Keep in mind that all parameters should be input as below order.

Example

GetSummaryDefects

getSummaryDefect(aircraftType, aircraftRegistration, category, startDate, endDate) ⇒ Promise

This API returns Number of Defects as integer, that occurs on multiple aircrafts ( aircraft registration ). The defect is counted when it match or included in category and aircraft type, and has issue_time between startDate and endDate as range.

To execute a function from the object, pass in function name along with it's parameters. This will return back a response that contains a Json data. Keep in mind that all parameters should be input as below order.

Example

GetSummaryDefectByAircraft

getSummaryDefectByAircraft(aircraftRegistration, category, startDate, endDate) ⇒ Promise

This API returns Number of Defects as integer, that occurs on one aircraft(aircraft registration) with category and has issue_time between startDate and endDate.

To execute a function from the object, pass in function name along with require parameters. This will return back a response that contains a Json data. Keep in mind that all parameters should be input as below order.

Example

GetDetailsDefect

getDetailsDefect(aircraftRegistration, category, seat, startDate, endDate, limit, token) ⇒ Promise

This API returns a list of Defect , that occurred on an aircraft (aircraft registration) in category , takes startDate and endDate as a range.

Keep in mind that all parameters should be input as below order.

Example

GetSeatMap

getSeatMap(aircraftRegistration, category, startDate, endDate) ⇒ Promise

This API returns Number of Defects of each seat , of referenced category occurs on one aircraft( aircraft registration ) , takes startDate and endDate as a range.

To execute a function from the object, pass in function name along with it's parameters. This will return back a response that contains a JSON data. Keep in mind that all parameters should be input as below order.

Example