Data Operations

NGSI-LD and Stellio

This package is the core of the library: the NGSI-LD Builder converts arbitrary JSON data into normalised NGSI-LD entities based on Smart Data Models, Post to Stellio writes them into the context broker, and six Stellio nodes query or manage entities, types and subscriptions. All nodes are designed for the Stellio context broker but speak the standardised NGSI-LD API.

• NGSI-LD
• Smart Data Models
• Stellio
• Source code on GitLab

Package

@htag/node-red-contrib-hypertegrity-ngsi-ld

Version

0.3.1

Nodes

8

Licence

EUPL-1.2

Included nodes

The nodes cover the whole path from raw record to managed entity in the broker. In the palette you find the builder in the DataOps category and the remaining nodes in the Stellio category.

Build and publish entities

ngsi-builder

NGSI-LD Builder

Turns flat JSON objects into NGSI-LD entities based on a Smart Data Model, with URN id, @context, GeoProperty, Relationship and observedAt.

Open node →

post-to-stellio

Post to Stellio

Transfers an entity array via batch upsert into a tenant of the Stellio context broker.

Open node →

Query entities

stellio-entities

Stellio Entities

Queries entities by type, filter and id pattern, reads single entities, counts matches and deletes individually or in batches.

Open node →

stellio-types

Stellio Types

Discovers read-only which entity types and attributes exist in the broker, including details and instance counts.

Open node →

Manage subscriptions

stellio-subscriptions

Stellio Subscriptions

Lists, reads, activates, deactivates and deletes subscriptions with a single node including a Browser tab.

Open node →

stellio-create-subscription

Stellio Create Subscription

Creates a subscription for an entity type if none exists yet, for example to connect a time series database.

Open node →

stellio-get-subscriptions

Stellio Get Subscriptions

Retrieves the list of all subscriptions of a tenant.

Open node →

stellio-delete-subscription

Stellio Delete Subscription

Deletes a single subscription by its id.

Open node →

Installation

npm install @htag/node-red-contrib-hypertegrity-ngsi-ld

Alternatively install the package in the Node-RED editor via Menu → Manage palette → Install and search for @htag/node-red-contrib-hypertegrity-ngsi-ld. The package requires Node-RED 4.0.5 or newer and Node.js 20.18 or newer.

Shared connection settings

All Stellio nodes talk to the same broker and use a common scheme of broker URL, tenant and context. Values from the message always take precedence over the node configuration, which in turn takes precedence over environment variables.

Broker URL

Setting	Meaning
Field API URL (Post to Stellio: Stellio API URL)	Base URL of the broker, for example https://stellio.exampletown.example. The node appends the path /ngsi-ld/v1/… itself.
Placeholder ${STELLIO_API_URL}	Default value of most dialogs. Placeholders of the form ${VAR} are replaced at runtime from the environment variable of the same name of the Node-RED process.
Environment variable STELLIO_API_URL	Fallback when neither message nor configuration supplies a URL.
msg.apiUrl	Overrides the URL per message. For Post to Stellio the property is named msg.stellioApiUrl.

Tenant

The tenant separates data spaces within one broker. All nodes send it as the HTTP header NGSILD-Tenant; msg.tenant overrides the configured value. For Post to Stellio, Stellio Create Subscription, Stellio Get Subscriptions and Stellio Delete Subscription the tenant is a required field. For Stellio Entities, Stellio Types and Stellio Subscriptions it may stay empty; then no header is sent and the broker uses its default tenant.

Authentication

The nodes of this package send no authentication headers; access to the broker is protected by the network or an upstream gateway. The Browser tabs of Stellio Entities, Stellio Types and Stellio Subscriptions are protected by the Node-RED permissions stellio.read (view) and stellio.write (delete, activate, deactivate); the NGSI-LD Builder uses ngsi-builder.read and ngsi-builder.write for schema fetching and cache clearing.

JSON-LD context (@context)

Node	Handling of the context
NGSI-LD Builder	Writes the Context URL as an array into the @context field of every generated entity and loads the schema for mapping and validation from it. Default: https://context.${DOMAIN}/main-context.
Post to Stellio	Sends the payload as application/ld+json; the context must be included in the entities. No Link header is set.
Stellio Entities, Stellio Types, Stellio Subscriptions	Send the Context field as the HTTP header Link with rel="http://www.w3.org/ns/json-ld#context". The context determines whether type and attribute names in the response appear short or as full URIs. msg.contextUrl overrides the value. Default: https://context.${DOMAIN}/main-context.jsonld.
Stellio Create Subscription	Writes the Context URL into the @context field of the created subscription.
Stellio Get Subscriptions, Stellio Delete Subscription	Send no context.

Use the same context for reading as for writing so that attribute names match. The placeholder ${DOMAIN} must be set as an environment variable.

Further shared properties

• Response format: All Stellio nodes write the broker response to msg.payload, the HTTP status to msg.statusCode and the response headers to msg.headers. Stellio Entities, Stellio Types and Stellio Subscriptions forward the message even on error statuses and show the status as a yellow ring.
• Timeout: Stellio Entities, Stellio Types and Stellio Subscriptions abort requests after 30 seconds.
• Placeholders: The default values use ${STELLIO_API_URL}, ${DOMAIN} and ${QL_LD_API_URL}. Set these environment variables for the Node-RED process.

Shared notes

• Dependencies: The package requires the library axios (version 1.13 or newer), which is installed automatically. In the editor, the NGSI-LD Builder additionally loads the Leaflet map library from unpkg.com; without internet access from the browser only the map preview is missing.
• Server network access: The Node-RED server must be able to reach the context URL, the schema URLs of the Smart Data Models and the broker. Behind a proxy, set the usual proxy environment variables.
• Example flows: The package contains the examples ngsi-builder and stellio-helper-nodes (Menu → Import → Examples). The example flow for the builder contains several thousand air quality records from a satellite service and is correspondingly large.
• Data protection: The nodes remove no content and log complete messages in debug mode. Before publishing, check whether entities contain personal data (names, addresses, vehicle registrations) and choose the target tenant accordingly.
• Units: The nodes pass values through unchanged and set no unitCode. Convert measurements to metric units before the builder.