Skip to main content

End Device Groups Configuration

endDeviceGroups.json is a static JSON configuration file that defines logical groupings of end devices (DERs, ESS units, etc.) within a region. It is loaded at runtime by the GMS UI applications via a plain HTTP GET request, there is no database or API backing it. The file must be present and accessible at the expected URL path for the application to load groups correctly.

If the file is missing, the application logs a warning and continues without groups (no hard failure). If the file is malformed (not a JSON array), the application throws an error surfaced as a notification to the user.

Affected Applications​

Two GMS UI applications currently consume this file:

Both apps fetch the file from /config/endDeviceGroups.json, which is relative to the application's served origin, so it resolves to wherever the app is hosted (e.g., https://your-host/config/endDeviceGroups.json).

Docker Compose Deployment​

In an OpenDSO Docker Compose deployment, endDeviceGroups.json is not baked into the image, it is mounted in from the deployment repo so the same image can be reused across environments.

Source location​

The file lives in the deployment repo's config tree:

<deployment-repo>/
├── config/
│   └── ui-app/config/endDeviceGroups.json   ← edit this file
└── opendso-docker-compose/
    └── compose.yaml

From compose.yaml, the relative path is ../config/ui-app/config/endDeviceGroups.json.

Mount​

The Schedule Dispatch UI service (edo-adr-app in the compose file) volume-mounts the file read-only into the nginx web root:

volumes:
  - ../config/ui-app/config/endDeviceGroups.json:/usr/share/nginx/html/config/endDeviceGroups.json:ro

It is then served to the browser at GET /config/endDeviceGroups.json. Edits to the file on the host are picked up on the next request by the user's web browser. You shouldn't need to restart the container for edits to be picked up by the next GET request (but your browser may cache the file, requiring a 'clear cache' operation on your browser).

File Format​

The file must be a JSON array of EndDeviceGroup objects. Each object represents one logical grouping.

[
  {
    "mrid": "499ea957-268d-458b-9cd6-d70f505097ad",
    "name": "DER Grouping 1",
    "equipmentType": "endDeviceGroup",
    "regions": [
      "290347ae-a0a6-4036-8d0c-0b45bd052376"
    ],
    "endDevices": [
      "a5bb4b08-ca31-40f6-bc5d-8477452ea162"
    ],
    "location": [{ "x": -8, "y": -8 }],
    "spec": "medium-compute",
    "description": "Schedule DER Nodes",
    "services": ["schedule service"]
  }
]
FieldTypeRequiredDescription
mridstring (UUID)YesUnique identifier. Must match the MRID of the corresponding device/grouping-of-der-equipment that the DER Dispatch Services (ie. VTN Service) are configured to expect. This MRID will be used as the MRID for the OpenFMB Schedules produced and consumed by the Schedule Dispatch UI.
namestringYesDisplay name shown in the UI for this EndDeviceGroup (ex. "EdoNode").
equipmentTypestringYesMust be "endDeviceGroup".
regionsstring[]YesOne or more region MRIDs this group belongs to. Controls which region's topology it appears under (useful for filtering what EndDeviceGroups are rendered on the UI Apps).
endDevicesstring[]YesMRIDs of the devices/equipment that belong to this group. Can reference other EndDeviceGroups (nesting is supported).
location[{x, y}]NoCoordinates used to position the group on the one-line diagram.
specstringNoHardware or compute spec label (e.g. "medium-compute", "ESS-Equipment").
descriptionstringNoFreeform description shown in device details. Useful for documentation or custom data fields.
servicesstring[]NoLabels for the services associated with this group (e.g. "ADR VTN Service", "customer dispatch schedule service", "FLISR").

Troubleshooting​

Groups do not appear in the UI

The browser console will show:

FetchEndDeviceGroups : /config/endDeviceGroups.json was not found or found unexpected HTML at /config/endDeviceGroups.json. If you're expecting end device groups, verify the deployment configuration.

This means either the file is missing from the served path, or the web server is returning an HTML error page (404/500) instead of JSON. Verify the file is reachable at the /config/endDeviceGroups.json URL of the running application. In a Docker Compose deployment, also confirm that the edo-adr-app container configuration has the correct mounted path for the endDeviceGroups.json.

Notification error in the UI

If the file exists but is not a JSON array (e.g., it is a single object {}), the app surfaces a user-visible error: endDeviceGroups json needs to be an array. Ensure the top-level structure is [...].