Skip to content
development
Switch branches/tags
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
img
Apr 8, 2020
Apr 6, 2021
Dec 13, 2021

Scorpio NGSI-LD Broker

FIWARE Core License: BSD-3-Clause Docker fiware NGSI-LD badge
Documentation badge Status NGSI-LD Test Suite PMD CII Best Practices

ATTENTION!!!
There is an existing security exploit in all versions older than 2.15 of Log4J. Scorpio uses Log4j for logging as well and so we are affected by this exploit as well.
What now?

We have replaced log4j in the development branch with the Spring-Boot-Logging which relies on Slf4J. We released a new version 1.1.3 on dockerhub. Also latest is -updated already.
Please update them as soon as possible.

But i have an older version running and don't want to update. What now?

You should still update!

However in case you really really really can't do it.
You can deactivate the feature of Log4J which is responsible for the exploit.

For people running Scorpio natively with java -jar. Add -Dlog4j2.formatMsgNoLookups=true before the -jar. So e.g. java -Dlog4j2.formatMsgNoLookups=true -jar myapp.jar

If you are running the docker-aaio version:
Download the run_replacement.sh file and place it on your docker host.
In your docker-compose file modify the scorpio entry like this 
  scorpio:
    image: scorpiobroker/scorpio:scorpio-aaio_1.0.8
    ports:
      - "9090:9090"
    depends_on:
      - kafka
      - postgres
    volumes:
      - /<path>/<to>/run_replacement.sh:/usr/src/scorpio/run.sh

If you are running the docker-dist version:
Go to your docker-compose file and place this in every Scorpio service definition.
  command: java -Dlog4j2.formatMsgNoLookups=true -jar $JAR_FILE_RUN ${spring_args}

Scorpio is an NGSI-LD compliant context broker developed by NEC Laboratories Europe and NEC Technologies India. It implements the full NGSI-LD API as specified by the ETSI Industry Specification Group on cross cutting Context Information Management (ETSI ISG CIM).

The NGSI-LD API enables the management, access and discovery of context information. Context information consists of entities (e.g. a building) and their properties (e.g. address and geographic location) and relationships (e.g. owner). Thus Scorpio enables applications and services to request context information – what they need, when they need it and how they need it.

The functionalities of the NGSI-LD API include:

  • Create, update, append and delete context infomration.
  • Query context information, including filtering, geographic scoping and paging.
  • Subscribe to changes in context information and receive asynchronous notifications.
  • Register and discover sources of context information, which allows building distributed and federated deployments.

Scorpio is a FIWARE Generic Enabler. Therefore, it can be integrated as part of any platform “Powered by FIWARE”. FIWARE is a curated framework of open source platform components which can be assembled together with other third-party platform components to accelerate the development of Smart Solutions. The roadmap of this FIWARE GE is described here.

You can find more info at the FIWARE developers website and the FIWARE website. The complete list of FIWARE GEs and Incubated FIWARE GEs can be found in the FIWARE Catalogue.

📚 Documentation 🎓 Academy 🐳 Docker Hub 🎯 Roadmap

Content

Background

Scorpio is an NGSI-LD Broker that allows managing and requesting context information. It supports the following functionalities:

  • Context Producers can manage their context – creating, updating, appending and deleting context information.
  • Context Consumers can request the context information they require, either identifying the entity or discover relevant entities by providing the entity type, possibly filtering according to property value, existing relationship and/or geographic scope provided as a GeoJSON feature.
  • Two interaction styles are supported, a synchronous query-response, and an asynchronous subscribe / notify, where notifications can be based on a change in property or relationship, or on a fixed time interval.
  • Scorpio implements NGSI-LD’s optional temporal interface for requesting historic information, e.g. the property values measured within a specified time interval.
  • Scorpio supports multiple deployment configurations including centralized, distributed and federated ones. In addition to the Context Producers mentioned above, there can be Context Sources that themselves implement the NGSI-LD interface. These Context Sources can register themselves with the information they can provide on request (not the information (values) itself). A Scorpio Broker in a distributed setting can then discover the Context Sources that may have information for answering a request based on their registrations, request and aggregate the information from different Context Sources and provide it to the requesting Context Consumer.
  • In a federated setting the Context Source can itself be an NGSI-LD Broker. Federations can be used to combine information from multiple providers that want to (partially) share information. An important difference is then typically in the granularity of the registration, e.g. “I have information about entities of entity type building within a geographic area”, instead of “I have information about Building A”
  • Scorpio supports all the mentioned deployment configurations. Thus it provides scalability and the possibility of extending scenarios in an evolutionary way. For example two separate deployments can be combined or for scalability reasons different brokers can be used – completely transparent to Context Consumers that can still use a single point of access.

Installation and Building

Scorpio is developed in Java using SpringCloud as microservice framework and Apache Maven as build tool. It requires Apache Kafka as a message bus and Postgres with PostGIS extensions as database.

Information on how to install the software components required by Scorpio can be found in the Installation Guide. For building and running Scorpio, you find instructions in the Building and Running Scorpio Guide.

Usage

By default the broker runs on port 9090 the base URL for interaction with the broker would be than http://localhost:9090/ngsi-ld/v1/

Simple Example

Generally speaking you can Create entities by sending an HTTP POST request to http://localhost:9090/ngsi-ld/v1/entities/ with a payload like this

{
    "id": "urn:ngsi-ld:testunit:123",
    "type": "AirQualityObserved",
    "dateObserved": {
        "type": "Property",
        "value": {
            "@type": "DateTime",
            "@value": "2018-08-07T12:00:00Z"
        }
    },
    "NO2": {
        "type": "Property",
        "value": 22,
        "unitCode": "GP",
        "accuracy": {
            "type": "Property",
            "value": 0.95
        }
    },
    "refPointOfInterest": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:PointOfInterest:RZ:MainSquare"
    },
    "@context": [
        "https://schema.lab.fiware.org/ld/context",
        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"
    ]
}

In the given example the @context is in the payload therefore you have to set the ContentType header to application/ld+json

To receive entities you can send an HTTP GET to

http://localhost:9090/ngsi-ld/v1/entities/<entityId>

or run a query by sending a GET like this

http://localhost:9090/ngsi-ld/v1/entities/?type=Vehicle&limit=2
Accept: application/ld+json
Link: <http://<HOSTNAME_OF_WHERE_YOU_HAVE_AN_ATCONTEXT>/aggregatedContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context";type="application/ld+json"

API Walkthrough

More detailed examples of what you can do with the NGSI-LD API provided by Scorpio can be found in the API Walkthrough.

Tests

Scorpio has two sets of tests. We use JUnit for unit tests and the FIWARE NGSI-LD Testsuite, which is npm test based, for system tests. Further details about testing can be found in the Testing Guide.

Further resources

For more detailed explaination on NGSI-LD or JSON-LD. Please look at the

You can find a set of example calls, as a Postman collection, in the Examples folder. These examples use 2 Variables

Acknowledgements

EU Acknowledgetment

This activity has received funding from the European Union’s Horizon 2020 research and innovation programme under Grant Agreement No. 731993 (Autopilot), No. 814918 (Fed4IoT) and No. 767498 (MIDIH, Open Call (MoLe).

Credit where credit is due

We like to thank everyone who has contributed to Scorpio. This goes for the entire Scorpio Devlopment Team as well as all external contributor. For a complete list have a look at the CREDITS file.

Code of conduct

As part of the FIWARE Community we try our best to adhere to the FIWARE Code of Conduct and expect the same from contributors.

This includes pull requests, issues, comments, code and in code comments.

As owner of this repo we limit communication here purely to Scorpio and NGSI-LD related topics.

We are all humans coming from different cultural backgrounds. We all have our different quirks, habits and mannerisms. Therefor misunderstandings can happen. We will give everyone the benefit of doubt that communication is done with good intentions in mind trying to advance Scorpio and NGSI-LD. We expect the same from contributors. However if someone is repeatedly trying to provoke, attack a person, shift discussions or ridicule someone we WILL make use of our house right and put an end to this.

If there is a dispute to be resolved we as owners of this repo have the final word.

License

Scorpio is licensed under BSD-3-Clause. For contributions this contribution license applies.

© 2021 NEC

About

NGSI-LD compliant context broker named Scorpio. Developed by NEC Laboratories Europe and NEC Technologies India

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages