The openHES application allows you to efficiently collect data from devices through bulk operations. This allows you to simultaneously read data from multiple devices or device groups. You can:
Important
All requests in this documentation follow this endpoint structure:
/io.clbs.openhes.services.svcapi.ApiService/{endpoint}
Replace {endpoint} with the specific API action listed in each section.
A bulk request allows you to read data from multiple devices. You can request data from:
- For details about device groups, see Create Device Groups.
- You can use variables to specify the exact registers to read from every device. For details, see Variables in openHES.
To read data from individual devices, send a request with the device IDs to the CreateBulk endpoint.
Example request:
{
"spec": {
"actions": [
{
"getPeriodicalProfile": {
"to": "2025-03-16T00:00:00.000000000Z",
"from": "2025-03-15T00:00:00.000000000Z"
}
}
],
"devices": {
"list": [
{
"deviceId": "4c42859a-39ea-415f-ae0e-d642224a9eb5",
"jobId": "4c42859a-39ea-415f-ae1e-d642224a9eb5"
},
{
"deviceId": "d4c3ce45-2081-40e6-8e60-b2ac5b3db356",
"jobId": "d4c3ce45-2081-49e6-8e60-b2ac5b3db356"
}
],
},
"settings": {
"attempts": [
2
],
"priority": 0,
"expiresAt": "2025-03-17T23:00:00.000000000Z",
"retryDelay": "30s",
"maxDuration": "3600s"
},
"correlationId": "unicorn-jeb-correlation-id-73036d0c-0ff5-43f4-8037-0a0906fea6a1"
},
"metadata": {
"name": "another 600k"
}
}
→ API OBJECT documentation (Create Bulk)
If devices are organized into groups, you can request data from all devices in the group simultaneously.
To read the data from a device group, send a request with the group ID to the CreateBulk endpoint.
Example request:
{
"spec": {
"actions": [
{
"getPeriodicalProfile": {
"to": "2025-03-16T00:00:00.000000000Z",
"from": "2025-03-15T00:00:00.000000000Z"
}
}
],
"deviceGroupId": "01959ecb-6c9b-7664-85ec-d3a754ada88b",
"settings": {
"attempts": [
2
],
"priority": 0,
"expiresAt": "2025-03-17T23:00:00.000000000Z",
"retryDelay": "30s",
"maxDuration": "3600s"
},
"correlationId": "unicorn-jeb-correlation-id-73036d0c-0ff5-43f4-8037-0a0906fea6a1"
},
"metadata": {
"name": "another 600k"
}
}
→ API OBJECT documentation (Create Bulk)
Proxy bulk requests allow you to read data without adding the devices to openHES. You provide a complete definition of devices directly within the request.
- Only device definitions are allowed in the proxy bulk (not device groups), and all devices must be compatible with the same driver.
- Variables are not allowed.
To read data using a proxy bulk, send the device definition to the CreateProxyBulk endpoint.
{
"spec": {
"correlationId": "test-proxy-job-correlation-id-001",
"driverType": "LANDISGYR_GENERIC_DLMS_SN",
"devices": {
"list": [
{
"jobId": "81958f30-9b30-752b-b917-533a55831c99",
"deviceId": "01958f30-9b30-752b-b917-533a55831c87",
"externalId": "extenal-id-01958f30-9b30-752b-b917-533a55831c87",
"deviceAttributes": {
"acclevel": {
"integerValue": 32
},
"password": {
"stringValue": "000000"
},
"physical": {
"integerValue": "7000"
}
},
"connectionInfo": [
{
"tcpip": {
"host": "10.77.1.160",
"port": 200000,
"timeout": "30s"
},
"linkProtocol": "LINKPROTO_HDLC"
},
{
"tcpip": {
"host": "10.77.5.240",
"port": 20153,
"timeout": "30s"
},
"linkProtocol": "LINKPROTO_MBUS"
}
],
"appProtocol": "APPPROTO_DLMS_SN",
"timezone": "europe/prague"
},
{
"jobId": "3fa7c5b9-b577-4fde-94bc-b71a5eeb8b78",
"deviceId": "5fa7c5b9-b577-4fde-94bc-b71a5eeb8b70",
"externalId": "extenal-id-5fa7c5b9-b577-4fde-94bc-b71a5eeb8b70",
"deviceAttributes": {
"acclevel": {
"integerValue": 32
},
"password": {
"stringValue": "000000"
},
"physical": {
"integerValue": "7000"
}
},
"connectionInfo": [
{
"tcpip": {
"host": "10.77.2.245",
"port": 150006,
"timeout": "30s"
},
"linkProtocol": "LINKPROTO_HDLC"
},
{
"tcpip": {
"host": "10.77.1.240",
"port": 26103,
"timeout": "30s"
},
"linkProtocol": "LINKPROTO_MBUS"
}
],
"appProtocol": "APPPROTO_DLMS_SN",
"timezone": "europe/prague"
}
]
},
"settings": {
"priority": "JOB_PRIORITY_5",
"attempts": [2],
"expiresAt": "2025-03-31T22:00:00.000000000Z"
},
"actions": [
{
"attributes": {
"obis": {
"stringValue": "1-1:1.8.0.255"
},
"buffer": {
"stringValue": "1-0:99.1.0.255"
}
},
"getPeriodicalProfile": {
"from": "2025-01-01T00:00:00.000000000Z",
"to": "2025-01-02T00:01:00.000000000Z"
}
},
{
"attributes": {
"obis": {
"stringValue": "1-1:1.8.1.255"
},
"buffer": {
"stringValue": "1-0:99.1.0.255"
}
},
"getPeriodicalProfile": {
"from": "2025-01-01T00:00:00.000000000Z",
"to": "2025-01-02T01:00:00.000000000Z"
}
},
{
"attributes": {
"obis": {
"stringValue": "1-1:32.7.0.255"
},
"buffer": {
"stringValue": "1-0:99.2.0.255"
}
},
"getIrregularProfile": {
"from": "2025-01-01T00:00:00Z",
"to": "2025-02-01T00:00:00Z"
}
},
{
"attributes": {
"obis": {
"stringValue": "1-1:52.7.0.255"
},
"buffer": {
"stringValue": "1-0:99.2.0.255"
}
},
"getIrregularProfile": {
"from": "2025-01-01T00:00:00Z",
"to": "2025-02-01T00:00:00Z"
}
}
]
},
"metadata": {
"name": "Proxy bulk 0001"
}
}
→ API OBJECT documentation (Create Proxy Bulk)