Version: Next

GraphQL API

The Energy Workbench Server also offers limited support for GraphQL queries. This documentation only provides a basic overview - more information on GraphQL can be found at https://graphql.org/learn/.

Getting started with GraphQL

The Energy Workbench Server GraphQL endpoint provides its own documentation of the queries and fields available in its schema. Some API development tools, such as Insomnia, allow you to view this schema as you build your queries. Using one of these tools is strongly advised to allow full use of the GraphQL functionality, as this page only covers the basics.

There are two GraphQL endpoints:

Type	Path	Description
POST	/ewb/api/graphql	The endpoint for all network or diagram related GraphQL queries.
POST	/ewb/api/graphql/customers	Endpoint for customer data - any type that is captured by the `CustomerService`.

This endpoint is also composed around the Evolve CIM Profile. As such, the queries below will return objects from this profile.

GraphQL Queries

Available on the /ewb/api/graphql endpoint:

Lookup queries:

Query	Description
`getIdentifiedObject(mRID: string)`	Request an IdentifiedObject by mRID.
`getIdentifiedObjects(mRIDs: [string])`	Request many IdentifiedObjects by their mRID. The maximum number that can be requested per query is 100. If the list contains more than this the response will be truncated to the first 100 MRIDs that are found. If a requested MRID cannot be found it will be ignored and will not cause an error.
`findIdentifiedObjects(criteria: [FindIdentifiedObjectCriteriaInput])`	Find all IdentifiedObjects that match the provided criteria. Available criteria are listed below.
`findIdentifiedObjectsByName(criteria: [NameSearchInput], includeClasses: [string])`	Find all IdentifiedObjects that match the provided name search criteria. Available criteria are listed below.
`getAssetInfo(types: [string])`	Retrieve all AssetInfo and PerLengthLineParameter by class type. `types` must be valid descendant classes of `AssetInfo` or `PerLengthLineParameter`.
`getNetworkHierarchy()`	Retrieve the network hierarchy of the currently running server, containing the `GeographicalRegions`, `Circuits`, `Loops`, and down to the `LvFeeders`.
`getMetadata()`	Retrieve the metadata for the currently running network, including the running server and version, plus the data sources used to produce the model.
`getGeoViewConfig()`	Retrieve the GeoView configuration for this server. Contains zoom and visibility rules for the map.
`getNetworkModels()`	Retrieve the network-model databases available to be loaded on this server.

Network tracing queries:

Query	Description
`getDownstreamEquipmentTree(mRID: string, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request a tree from a downstream equipment trace, given the MRID of a conducting equipment to be used as the root. A depth-first sorted list of nodes is returned.
`getDownstreamEquipment(mRID: string, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request the downstream equipment from the given `mRID` for the desired `NetworkState` (default `NORMAL`).
`findUpstreamEquipment(mRID: string, type: string, networkState: [NetworkState])`	Request a list of equipment of a specific CIM type encountered in an upstream trace starting at a given equipment, usage point, or meter, and stopping at matching equipment. Loops in the upstream network result in multiple branches in this trace, in which case more than one matching equipment may be returned.
`getUpstreamEquipment(mRID: string, stopType: string, stopMRID: string, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request a list of equipment from an upstream equipment trace, given the MRID of a conducting equipment to be used as the starting point, and tracing to the feeder head, A reversed depth-first sorted list of equipment is returned. Optionally specify a type and/or an mRID as a stopping point rather than the feeder head.
`getConnectedEquipment(mRID: string, steps: Int?, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request a list of equipment connected to a specific piece of equipment by a maximum number of steps in a given direction.
`getIsolatedEquipment(isolationPoints: [IsolationQueryExtent], insideIsolation: [IsolationQueryExtent]?, maxSwitches: Int, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request the equipment that belongs to an isolation area. You can optionally request only equipment of a specified type.

Available on the /ewb/api/graphql/customers endpoint:

Query	Description
`getIdentifiedObject(mRID: string)`	Request an IdentifiedObject by mRID.
`getIdentifiedObjects(mRIDs: [string])`	Request many IdentifiedObjects by their mRID. The maximum number that can be requested per query is 100. If the list contains more than this the response will be truncated to the first 100 MRIDs that are found. If a requested MRID cannot be found it will be ignored and will not cause an error.
`findIdentifiedObjects(criteria: [FindIdentifiedObjectCriteriaInput])`	Find all IdentifiedObjects that match the provided criteria. Available criteria are listed below.
`findIdentifiedObjectsByName(criteria: [NameSearchInput], includeClasses: [string])`	Find all IdentifiedObjects that match the provided name search criteria. Available criteria are listed below.
`getMetadata()`	Retrieve the metadata for the currently running network, including the running server and version, plus the data sources used to produce the model.

FindIdentifiedObjectCriteriaInput fields

Field	Description	Required?
`includeClasses: [string]`	A list of IdentifiedObject class names that the results will be filtered by.	No
`includeNameTypes: [string]`	A list of NameType class names that the results will be filtered by.	No
`inDiagrams: [string]`	The MRIDs of diagrams IdentifiedObjects must have an associated DiagramObject in.	No
`limit: int`	The maximum number of results to return. This is currently limited to a maximum of 100. If set to larger than 100 results will be capped at 100.	Yes
`toMatch: string`	The value to match to an IdentifiedObject MRID or name.	Yes

NameSearchInput fields

Field	Description	Required?
`nameType: string`	The NameType name that the results will be filtered by.	Yes
`names: [string]`	All possible names to search for.	Yes

IsolationQueryExtent fields

Field	Description	Required?
`mRID: string`	The mRID of the isolating equipment.	Yes
`longitude: Double?`	An optional longitude on the isolating equipment where the isolation occurs. This is only used by an [AcLineSegment], and will be ignored for any other equipment type. If provided, a [latitude] must also be provided	No
`latitude: Double?`	An optional latitude on the isolating equipment where the isolation occurs. This is only used by an [AcLineSegment], and will be ignored for any other equipment type. If provided, a [longitude] must also be provided	No

Other GraphQL features

Meta fields

GraphQL provides introspective fields that provide information on the GraphQL schema itself. One of these fields is __typename, which will return the name of the object type. This is useful when requesting IdentifiedObjects, as it returns the specific CIM object type (e.g. AcLineSegment).

Inline fragments

Because many of the GraphQL queries return IdentifiedObjects, only IdentifiedObject attributes (mRID, name, description) and meta fields (__typename, type, numDiagramObjects) can be requested and returned by default. To request data from other object types, inline fragments can be used. Inline fragments allow you to query certain fields depending on the type of object returned, using the syntax ... on <typename>{fields}. It's easiest to understand this by looking at the examples included below.

Bounding Boxes

All GraphQL responses include a BoundingBox which defines a rectangular geographic area defined by the most south-west and north-east corners of the IdentifiedObjects returned within the GqlResponse. This bounding box can be used to identify geographic areas and speed up the process of visualising the network on a geographic map.

Example queries

Here we are requesting the name and description for three mRIDs, as well as requesting the mRID in the body so we can easily tell which returned object is which. We're also requesting the object type using __typename.

Query:
{
  getIdentifiedObjects(mRIDs: ["abc123", "def456", "ghi789"]){
    name
    description
    mRID
    __typename
  }
}

Response:
{
  "data": {
    "getIdentifiedObjects": [
      {
        "name": "TestObject123",
        "description": "This is a test object"
        "mRID": "abc123"
        "__typename": "Feeder"
      },
      {
        "name": "TestObject456",
        "description": "This is a different test object"
        "mRID": "def456"
        "__typename": "AcLineSegment"
      },
      {
        "name": "TestObject789",
        "description": "And another test object"
        "mRID": "ghi789"
        "__typename": "Breaker"
      }
    ]
  }
}

Once we know the object types, we can start to retrieve specific fields depending on the object type.

Query:
{
  getIdentifiedObjects(mRIDs: ["abc123", "def456", "ghi789"]){
    name
    mRID
    __typename
    # For returned Feeder objects, also request a list of their child equipment objects 
    # that are either Junctions or Disconnectors
    ... on Feeder {
      currentEquipment(types: ["Junction", "Disconnector"]){
        mRID
        name
        __typename
      }
    }
    
    # For returned AcLineSegments, also request the length, the parent feeder(s) mRIDs, 
    # and check if it is underground 
    ... on AcLineSegment{
      length
      currentFeeders{
        mRID
      }
      isUnderground
    }
    
    # For returned Breakers, also check whether the breaker is open 
    ... on Breaker{
      isOpen
    }
  }
}

Response:
{
  "data": {
    "getIdentifiedObjects": [
      {
        "name": "TestObject123",
        "mRID": "abc123",
        "__typename": "Feeder",
        "currentEquipment": [
          {
            "mRID": "junc1",
            "name": "TestJunction1",
            "__typename": "Junction"
          },
          {
            "mRID": "disc1",
            "name": "TestDisconnector1",
            "__typename": "Disconnector"
          },
          {
            "mRID": "junc2",
            "name": "TestJunction2",
            "__typename": "Junction"
          },
          {
            "mRID": "disc2",
            "name": "TestDisconnector2",
            "__typename": "Disconnector"
          },
          {
            "mRID": "junc3",
            "name": "TestJunction3",
            "__typename": "Junction"
          }
        ]
      },
      {
        "name": "TestObject456",
        "mRID": "def456",
        "__typename": "AcLineSegment",
        "length": 4.97348017,
        "currentFeeders": [
          {
            "mRID": "feeder2468"
          }
        ],
        "isUnderground": true
      },
      {
        "name": "TestObject789",
        "mRID": "ghi789",
        "__typename": "Breaker",
        "isOpen": false
      }
    ]
  }
}

Getting started with GraphQL​

GraphQL Queries​

FindIdentifiedObjectCriteriaInput fields​

NameSearchInput fields​

IsolationQueryExtent fields​

Other GraphQL features​

Meta fields​

Inline fragments​

Bounding Boxes​

Example queries​