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

Hypertegrity NodeRED NGSI-LD Nodes.

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

Hypertegrity Node-RED NGSI-LD Nodes

A collection of Node-RED nodes for building and publishing NGSI-LD entities to the Stellio context broker.

📝 Introduction

This package provides nodes for integrating data into NGSI-LD–based platforms. While primarily focused on the Stellio Context Broker, the nodes are designed to work with any NGSI-LD–compliant system.

The nodes in this package enable you to:

• Build entities — create Smart Data Model–compliant entities from standard Node-RED message payloads.
• Publish data — send entities to a Stellio context broker.
• Query and manage entities — search, inspect, count and delete entities.
• Manage subscriptions — create, list, inspect, activate/deactivate and delete NGSI-LD subscriptions.
• Explore the data model — discover the entity types and attributes available on a broker.

Included Nodes

Building & publishing

Entities

Subscriptions

Data model discovery

Note: All stellio-* nodes can be configured entirely in the editor or driven at runtime via msg properties (e.g. msg.apiUrl, msg.tenant, msg.contextUrl, msg.operation; post-to-stellio uses msg.stellioApiUrl or msg.apiUrl). Values from msg take precedence over the node configuration. Each node returns the broker response in msg.payload together with msg.statusCode and msg.headers, except stellio-create-subscription, which only sets msg.payload ({ id, status, response, location }).

Configuration by message

Every node accepts an optional msg.config object. Its properties have the names of the editor settings and override them for this message only; they take precedence over the msg properties listed above. The help of each node lists the supported keys. The transformation script of the ngsi-builder cannot be set by message, so that no code from message content is executed. Invalid values raise an error (Catch node). msg.config is not part of the output message.

Settings (settings.js)

The editor dialogs load schemas and broker data via the Node-RED server. Internal hosts are only allowed for the context URLs of deployed ngsi-builder nodes, for the API URLs of deployed Stellio nodes and for STELLIO_API_URL. Further hosts can be allowed in settings.js:

hypertegrity: { allowedHosts: ["context.internal", "stellio-api-gateway"] }

Authentication at the broker (token, Keycloak) is not supported yet; the broker must be reachable without login or through a gateway.

Notes on upgrading to 0.3.2

• ngsi-builder: the output is unchanged; messages are processed one after another (stable order). New opt-in options "omit null values" and "context/schema not loadable: drop". Valid geometries that were rejected before (two-point lines, polygons with holes, 3D positions) are now kept, 3D positions are swapped correctly, an input ID 0 is used instead of a random ID. With validation and "skip", id/type are never removed and relationships are no longer removed as "type mismatch". Topic filters support flags (/expression/i). Dropped items are always reported.
• stellio-create-subscription: without context URL the subscription is sent as application/json without @context (before: "@context": [] with application/ld+json, which Stellio rejects with HTTP 400).
• stellio-entities (and its editor browser): a query or count without type, q and attrs adds local=true; Stellio answers such queries with HTTP 400 otherwise (an ID pattern alone is no filter for Stellio).
• stellio-create-subscription: payload.id now contains the subscription URN also for newly created subscriptions (before: the Location path); the path is available as payload.location. The duplicate check compares the type exactly over all subscriptions (before: substring of the first type of the first 100 subscriptions).
• post-to-stellio: HTTP errors are reported to Catch nodes (the message is still sent); a single entity is sent as an array with one element.
• List operations send count=true; msg.count is now set (the response header was read under a wrong name before).
• New opt-in options in the Stellio nodes: "Load all pages" and "Report HTTP errors to Catch".
• Requests of all Stellio nodes time out after 30 s.
• The configured context URL is sent again as JSON-LD Link header (@context); axios ≥ 1.16 had dropped it, so short type and attribute names were interpreted with the core context (e.g. type=Device found no entities).
• msg.headers has the same type as in 0.3.1 again: a plain object for post-to-stellio, stellio-get-subscriptions and stellio-delete-subscription, the axios header object for stellio-entities, stellio-types and stellio-subscriptions; msg.headers.hasOwnProperty() works in all of them.
• On redeploy or stop running Stellio requests are aborted; the old node sends no message and sets no status afterwards.
• Stellio nodes: a tenant with characters outside Latin-1 or with control characters raises an error before the request (before, axios silently removed such characters and another tenant was addressed).
• stellio-entities, stellio-types, stellio-subscriptions: an unknown msg.operation still runs the default operation (query, listTypes, list), but a warning lists the valid operations. An unresolved ${…} in the API URL is reported by name before the request (before: "Invalid URL" or a request to a wrong path).
• stellio-entities batchDelete: HTTP 207 (some IDs failed) shows a yellow status and a warning, like post-to-stellio.
• stellio-subscriptions setActive: msg.active accepts only true/false/"true"/"false"; other values (e.g. "yes", 1, null) raise an error instead of deactivating the subscription.
• stellio-subscriptions / stellio-delete-subscription: a subscription ID starting with urn: is never cut, even if it contains /. An NGSILD-Results-Count header that is no non-negative integer no longer sets msg.count (before: NaN).
• All Stellio nodes: an empty API URL uses STELLIO_API_URL from the flow, group or global environment first, then from the process environment (before: only the process environment; unchanged if only the process environment sets it). stellio-create-subscription now has this fallback too (before: error). stellio-get-subscriptions sets msg.statusCode, msg.headers and msg.count also for answers that are no JSON.
• Editor browser of the Stellio nodes: entities and types whose ID contains / can be shown and deleted; paths with backslashes, control characters or (encoded) dot segments are rejected, and the assembled request URL is checked again. Network errors are answered with the generic code request_failed (details in the Node-RED log).
• msg.config.limit / msg.config.offset accept only numbers or numeric strings (true, [5] now raise an error).
• Editor browser of the Stellio nodes: ${VAR} in the context URL is only resolved for values of deployed nodes (otherwise "deploy first"). Editor requests to hosts that are not trusted also check the address actually connected to (DNS rebinding); IPv4 addresses embedded in IPv6 and fec0::/10 count as internal.
• ngsi-builder: a context or schema with broken JSON counts as "not loadable" (with "drop" the entity is discarded); like any failed download it is remembered for 60 s and then loaded again (it is never cached as a valid document). Source paths with __proto__, constructor or prototype are never read; in msg.config they raise an error. Switches inside msg.config (mappings[].required/addObservedAt, customMappings[].addObservedAt, locationConfig.enabled) accept only true/false/"true"/"false" (before, e.g. "false" counted as on).
• ngsi-builder: an ID built by the node (urn:ngsi-ld:{type}:…) uses the final entity type: when a mapping, the script or an overwrite sets the type, the prefix follows it (before it always used the configured entity type). IDs from the input (urn:…), from the script or from an id overwrite are unchanged. Flows that map or overwrite the type create entities with new IDs.
• ngsi-builder: configuration errors reported on deploy (unresolved ${…} in the context URL, script syntax error, forbidden target paths) also reach Catch nodes with every processed message; the messages are still processed.
• ngsi-builder validation: JSON-Schema integer accepts only whole numbers, number only finite numbers, and lists of types (e.g. ["number", "null"]) are evaluated. A mandatory field with an invalid value drops the entity like a missing one (before, "skip" removed it). id, type and @context never count as extra fields. Type IRIs with # from standard contexts are not downloaded ("validation not possible"; before, an unreachable IRI host counted as "not loadable" and "drop" discarded every entity). Dropped entities are reported by one warning with the number at most once per minute (per entity only in debug mode).
• ngsi-builder simple mode: location must be a complete GeoJSON geometry (known type, nesting, closed rings with at least 4 positions), otherwise it is left out with a warning. Location tab: coordinates are always converted into numbers with strict parsing (also with the order lon,lat; "49,44" is 49.44, "49.44°" is invalid); a Point from an array with three values keeps the altitude. Impossible dates such as 2026-02-29 in the observedAt field count as invalid (warning, processing time).
• ngsi-builder: a missing context URL is a configuration error like a missing entity type (before: "@context": [null]). A Buffer payload is treated like a string (warning, no output). The sent entities are copies (changes in a setTimeout of the script or of the input payload no longer reach them). The help now documents that an id overwrite is the final ID and that msg in the script is a shallow copy.

Installation

Install via the Node-RED Palette Manager or using npm:

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

🌍 About the Project / Über das Projekt

📍 Über dieses Projekt / About this Project

DE: Dieses Open Source Projekt ist im Rahmen der Förderung Modellprojekte Smart Cities entstanden und wurde durch die Initiative des Projekts Südwestcluster ermöglicht.

EN: This open source project was created as part of the Smart City Pilot Projects (Modellprojekte Smart Cities) funding and was made possible by the initiative of the Südwestcluster project.

💡 Hintergrund / Background

DE: Die Entwicklung wurde durch öffentliche Gelder im Kontext der Förderung Modellprojekte Smart Cities unterstützt. Dadurch können wir diese Lösung der gesamten Community als Open Source zur Verfügung stellen.

EN: The development was supported by public funds in the context of the Smart City Pilot Projects (Modellprojekte Smart Cities) funding. This allows us to make this solution available to the entire community as open source.

🌐 Open Source Philosophie / Open Source Philosophy

DE: Wir unterstützen aktiv die OSS-Community und fördern kollaborative Entwicklung. Durch die Veröffentlichung als Open Source profitieren alle Beteiligten:

• Community: Freier Zugang zu moderner Smart City Technologie
• Transparenz: Nachvollziehbare und überprüfbare Lösungen
• Innovation: Gemeinsame Weiterentwicklung durch verschiedene Akteure
• Nachhaltigkeit: Langfristige Verfügbarkeit und Wartbarkeit

EN: We actively support the OSS community and promote collaborative development. Releasing it as open source benefits everyone involved:

• Community: Free access to modern Smart City technology
• Transparency: Traceable and verifiable solutions
• Innovation: Collaborative development by various actors
• Sustainability: Long-term availability and maintainability

🙏 Danksagung / Acknowledgements

DE: Ein besonderer Dank gilt der Förderung Modellprojekte Smart Cities für die finanzielle Unterstützung sowie dem Projekt Südwestcluster für die Initiative und Koordination:

• Eifelkreis Bitburg-Prüm
• Stadt Kaiserslautern
• Landkreis Kusel
• Stadt und Verbandsgemeinde Linz am Rhein
• Landkreis Mayen-Koblenz
• Landkreis St. Wendel

EN: Special thanks goes to the Smart City Pilot Projects (Modellprojekte Smart Cities) funding for financial support and the Südwestcluster project for the initiative and coordination:

• Eifelkreis Bitburg-Prüm
• City of Kaiserslautern
• District of Kusel
• City and Collective Municipality of Linz am Rhein
• District of Mayen-Koblenz
• District of St. Wendel

📜 License & Contact / Lizenz & Kontakt

© 2026 HYPERTEGRITY AG. Alle Rechte vorbehalten. / All rights reserved.

⚖️ License Compatibility / Lizenz-Kompatibilität

DE: Details zur Lizenzierung und zu den Nutzungsrechten finden Sie in der beigefügten LICENSE Datei.

EN: Details on licensing and usage rights can be found in the attached LICENSE file.

📧 Contact / Kontakt: [email protected] 🌐 Website: www.hypertegrity.de