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:
- Create Bulk operations to read data from pre-defined devices.
- Create Proxy Bulk operations to read data using a complete device definition.
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.
Create Bulk
A bulk request allows you to read data from multiple devices. You can request data from:
- A specific list of devices using their device IDs.
- All devices withing a specific device group.
- 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.
Read Data Using Device IDs
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)
Read Data from a Device Group
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)
Create Proxy 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.
Expand to see an example request:
{
"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)