REST Inbound Connector

What Is It?

The REST Inbound Connector is the inbound data gateway for external web applications, cloud platforms, and third-party services. It exposes an HTTP endpoint that accepts JSON payloads, maps the incoming data to data points using configurable mappings, and writes them into the central data store. From there, other connectors can pick up the data and deliver it to control systems.

In short: the REST Inbound Connector lets external systems push data into the platform via HTTP.

This is the counterpart to the REST Outbound Connector, which delivers data out of the platform. The Inbound Connector brings data in.

How It Works

1. An external system sends an HTTP POST request with a JSON payload and a topic identifier.
2. The connector looks up all mappings configured for that topic.
3. Each mapping extracts values from the JSON payload using configurable path expressions.
4. The extracted values are converted to the appropriate data types and written to the central data store.
5. Other connectors (e.g., IEC 104, REST Outbound) can then deliver the data to downstream systems.

External System → HTTP POST → REST Inbound Connector → Data Store → IEC 104 / other connectors

Connection Details

Setting	Default
Protocol	HTTP
Mode	Server (accepts incoming requests)

The connector operates as an HTTP server. External systems send data to it — it does not actively pull data from anywhere.

API

POST /api/datapoints

Accepts a JSON body and a required topic query parameter. The topic identifies which set of mappings should be applied to the incoming payload.

Query Parameters:

Parameter	Type	Required	Description
topic	string	Yes	Identifies the mapping group for this payload

Request Body:

Any valid JSON object. The connector extracts values from this payload using the path expressions defined in the mappings.

Example Request:

POST /api/datapoints?topic=sensors/temperature
Content-Type: application/json

{
  "data": {
    "temperature": 23.5,
    "humidity": 61.2
  },
  "timestamp": "2026-01-15T10:30:00Z"
}

Response Codes:

Status	When
200 OK	All mappings succeeded — data points written to the data store
400 Bad Request	The topic query parameter is missing or empty
404 Not Found	No mappings exist for the provided topic
422 Unprocessable Entity	One or more mappings failed — error details are returned in the response

Success Response (200):

{
  "topic": "sensors/temperature",
  "succeeded": [
    "signal/temp",
    "signal/humidity"
  ]
}

Error Response (422):

{
  "topic": "sensors/temperature",
  "message": "One or more mappings failed. Data entries were not written.",
  "failed": [
    {
      "signalId": "signal/humidity",
      "error": "Value not found at path 'data.humidity'"
    }
  ],
  "succeeded": [
    {
      "signalId": "signal/temp"
    }
  ]
}

When any mapping fails, no data entries are written — neither the successful nor the failed ones. Only error entries are recorded. This ensures data consistency.

Mappings — The Core Concept

A mapping tells the connector how to extract data from an incoming JSON payload and where to store it in the system. Each mapping is linked to a topic — when a request arrives with that topic, all associated mappings are applied.

Example

An external weather station pushes data via HTTP with this JSON payload:

{
  "data": {
    "temperature": 23.5,
    "humidity": 61.2
  },
  "timestamp": "2026-01-15T10:30:00Z"
}

To bring the temperature into the system at CASDU 225, IOA 100, you would create a mapping with:

Setting	Value	Explanation
Name	signal/temp	A descriptive name for this mapping
Topic	sensors/temperature	The topic this mapping belongs to
CASDU	225	The station address
IOA	100	The data point address
Type	Type 36 (Float)	Because temperature is a decimal number
Value Path	data.temperature	Where to find the value in the JSON
Value Type	float	The data type of the extracted value
Timestamp Path	timestamp	Where to find the timestamp in the JSON

The result: every time the weather station sends a POST request with topic=sensors/temperature, the temperature appears in the system as data point CASDU 225 / IOA 100.

Multiple Mappings per Topic

A single topic can have multiple mappings. For example, one topic sensors/temperature could map both temperature and humidity from the same JSON payload to different data points:

Mapping	CASDU	IOA	Value Path
signal/temp	225	100	data.temperature
signal/hum	225	101	data.humidity

Both mappings are applied when a POST request arrives with topic=sensors/temperature.

JSON Path Expressions

The Value Path tells the connector where to find a specific value within a JSON message. It uses a simple dot notation:

JSON Path	What It Accesses
temperature	A top-level field
data.value	A nested field
data.sensor.reading	A deeply nested field
sensors[0]	The first element of an array
readings[1].temp	A field inside an array element

Practical Examples

Given this JSON payload:

{
  "location": "Room A",
  "sensors": [
    { "type": "temperature", "value": 22.3 },
    { "type": "humidity", "value": 58.1 }
  ],
  "battery": 87
}

To extract...	Use this path
Battery level	battery
Temperature	sensors[0].value
Humidity	sensors[1].value

Supported Data Types

Each mapping specifies a data type that determines how the extracted value is stored and transmitted.

Monitoring types (inbound data):

Type	Name	Best For	Example Values
Type 1	Single Point	On/off states	true/false, 0/1
Type 13	Measured Normalized	Normalized measurements	Proportional values, percentages
Type 30	Single Point with Timestamp	On/off states with time	Switch changes
Type 32	Step Position with Timestamp	Transformer tap positions, counters	-64 to 63
Type 36	Float with Timestamp	Measurements	23.5, -10.2, 0.95

Recommendation: Use Type 36 for analog measurements and Type 30 for binary states. Both include a timestamp for traceability.

Configuration

The connector is configured in two ways:

1. Management UI / API — The primary method. When you create a REST Inbound connector in the Management UI, the configuration (listen addresses, linked mappings) is stored in the database and automatically pushed to the connector via the central data store.
2. Application settings / Environment variables — For initial startup parameters (connector ID, data store connection).

Startup Parameters

These parameters are set via application settings or environment variables:

Parameter	Description	Required	Default
Id	Unique connector ID (from the Management UI)	Yes	—
ConnectionStrings:Redis	Data store connection string	No	localhost:6379

Environment Variables

Configuration values can be overridden using environment variables. Use double underscores (__) to represent nested levels:

Id=ae2f909e-62bc-451e-a24e-4ea9e03153e3
ConnectionStrings__Redis=datastore:6379

Managed Settings (via Management UI)

The following settings are configured through the Management UI and pushed to the connector automatically:

Setting	Description
Display Name	Human-readable name for the connector
Description	Description of the connector's purpose
Log Level	Override logging level (Debug, Information, Warning, Error, Critical)
Is Active	Whether the connector is active
Host URLs	URLs the service should listen on (overrides default ports)
Mappings	Topic-to-data-point mapping configuration

Error Handling

The connector provides clear feedback for every request:

Scenario	Behavior
Missing topic	Returns 400 with an error message
Unknown topic	Returns 404 — no mappings configured for this topic
All mappings succeed	Returns 200 — data points written to the data store
Any mapping fails	Returns 422 — no data is written, errors are logged to the error stream

This all-or-nothing approach ensures that partial data does not enter the system when a mapping configuration issue exists.