Ngsijs is the JavaScript library used by WireCloud for adding FIWARE NGSI capabilities to widgets and operators. However, this library has also been designed to be used in other environments as normal web pages and clients/servers running on Node.js.
This library has been developed following the FIWARE NGSI v1 and NGSI v2 specifications and has been tested to work against version 0.26.0+ of the Orion Context Broker.
Reference documentation of the API is available at http://conwetlab.github.io/ngsijs/stable/NGSI.html.
Note: Support for Cross-Origin Resource Sharing (CORS) has been added on orion 1.10.0. This support must be enabled to access the context broker from a web page in a different domain than the context broker.
You can access any context broker server (without requiring CORS support and regardless of the context broker version) if the context broker is accessible throught the same domain as the web page. How to create such configuration is out of the scope of this documentation.
Just include a <script>
element linking to the NGSI.min.js
file:
<script type="text/javascript" src="url_to_NGSI.js"></script>
Once added the <script>
element, you will be able to use all the features
provided by the ngsijs library (except receiving notifications):
var connection = new NGSI.Connection("http://orion.example.com:1026");
connection.v2.listEntities().then((result) => {
response.results.forEach((entity) => {
console.log(entity.id);
});
});
This example will display the id
of the first 20 entities. See the
documentation of the listEntities
method for more info.
To be able to receive notifications inside a web browser the library requires
the use of a ngsi-proxy server. You
can use your own instance or the ngsi-proxy
instance available at
https://ngsiproxy.lab.fiware.org
.
var connection = new NGSI.Connection("http://orion.example.com:1026", {
ngsi_proxy_url: "https://ngsiproxy.lab.fiware.org"
});
$ npm install ngsijs
After installing the ngsijs node module, you will be able to use the API as usual:
var NGSI = require('ngsijs');
var connection = new NGSI.Connection("http://orion.example.com:1026");
Note: Node.js doesn't require the usage of a ngsi-proxy as you can create an HTTP endpoint easily (e.g. using express). Anyway, you can use it if you want, you only have to take into account that is better to directly provide the HTTP endpoint to reduce the overhead.
WireCloud already provides some components (widgets, operators and mashups) allowing NGSI connectivity. E.g.:
Anyway, WireCloud uses ngsijs as the binding for connecting to context brokers. If you need to create a new specific component you can take a look into the "3.2.1. Using Orion Context Broker" tutorial available at the FIWARE Academy.