API Developer Guide

Energy Platform Data API

User Starter Guide
DOCA0339EN-00
01/2024

www.se.com
 API Developer Guide – User Starter Guide

Legal Information
The information provided in this document contains general descriptions,
technical characteristics and/or recommendations related to products/solutions.

This document is not intended as a substitute for a detailed study or operational

and site-specific development or schematic plan. It is not to be used for
determining suitability or reliability of the products/solutions for specific user
applications. It is the duty of any such user to perform or have any professional
expert of its choice (integrator, specifier or the like) perform the appropriate and
comprehensive risk analysis, evaluation, and testing of the products/solutions with
respect to the relevant specific application or use thereof.

The Schneider Electric brand and any trademarks of Schneider Electric SE and
its subsidiaries referred to in this document are the property of Schneider Electric
SE or its subsidiaries. All other brands may be trademarks of their respective
owner.

This document and its content are protected under applicable copyright laws and
provided for informative use only. No part of this document may be reproduced or
transmitted in any form or by any means (electronic, mechanical, photocopying,
recording, or otherwise), for any purpose, without the prior written permission of
Schneider Electric.

Schneider Electric does not grant any right or license for commercial use of the
document or its content, except for a non-exclusive and personal license to
consult it on an "as is" basis.

Schneider Electric reserves the right to make changes or updates with respect to
or in the content of this document or the format thereof, at any time without notice.

To the extent permitted by applicable law, no responsibility or liability is

assumed by Schneider Electric and its subsidiaries for any errors or
omissions in the informational content of this document, as well as any
non-intended use or misuse of the content thereof.

DOCA0339EN-00 2
 API Developer Guide – User Starter Guide

Table of Contents
Legal Information ............................................................................. 2
Table of Contents ............................................................................. 3
Safety Information ............................................................................ 4
Important Information ........................................................................................ 4
Please Note ....................................................................................................... 4
About the Book................................................................................. 5
Document Scope ............................................................................................... 5
Validity Note ...................................................................................................... 5
Online Information ............................................................................................. 5
Pre-requisites .................................................................................................... 5
Introduction ...................................................................................... 6
Purpose ............................................................................................................. 6
Architecture Introduction .................................................................. 7
EcoStruxure Power Architecture for Non-critical Small or Medium Sites ........ 7
EcoStruxure Power Architecture for Critical Installations.................................. 8
Using the API ................................................................................. 10
GraphQL .......................................................................................................... 10
Useful GraphQL Tools .................................................................................... 10
EcoStruxure Energy Data Model ..................................................................... 11
Basic Steps to Use APIs ................................................................................. 11
Quick Start Guide ........................................................................... 14
Goal ................................................................................................................. 14
Step 1: Query to Get Tenants ......................................................................... 14
Step 2: Query to Get the Energy Hierarchy .................................................... 15
Step 3: Query to Get Energy Usages.............................................................. 19
Step 3: Query to Get Energy per Zone ........................................................... 23
Step 4: Query to Retrieve Alarms ................................................................... 26
Conclusion ....................................................................................................... 29

DOCA0339EN-00 3
Safety Information API Developer Guide – User Starter Guide

Safety Information
Important Information
Read these instructions carefully, and look at the equipment to become familiar
with the device before trying to install, operate, service, or maintain it. The
following special messages may appear throughout this documentation or on the
equipment to warn of potential hazards or to call attention to information that
clarifies or simplifies a procedure.

The addition of this symbol to a “Danger” or “Warning” safety label indicates that an
electrical hazard exists which will result in personal injury if the instructions are not
followed.

This is the safety alert symbol. It is used to alert you to potential personal injury
hazards. Obey all safety messages that follow this symbol to avoid possible injury or
death.

! DANGER
DANGER indicates a hazardous situation which, if not avoided, will result in death or serious
injury.

! WARNING
WARNING indicates a hazardous situation which, if not avoided, could result in death or
serious injury.

! CAUTION
CAUTION indicates a hazardous situation which, if not avoided, could result in minor or
moderate injury.

NOTICE
NOTICE is used to address practices not related to physical injury.

Please Note
Electrical equipment should be installed, operated, serviced, and maintained by
qualified personnel only. No responsibility is assumed by Schneider Electric for
any consequences arising out of the use of this material.

A qualified person is one who has skills and knowledge related to the construction
and operation of electrical equipment and its installation. He has received safety
training to recognize and avoid the hazards involved.

DOCA0339EN-00 4
About the Book API Developer Guide – User Starter Guide

About the Book

Document Scope
This guide explains how to start with GraphQL APIs used with the cloud Energy
Platform

Validity Note
This guide applies to EcoStruxure Energy Hub Advanced data API 1.0 or greater.
For every new version, a specific release note is available inside the API
documentation release. This release note will describe all the changes made
between one version and the next.

Online Information
The information contained in this guide is likely to be updated at any time.
Schneider Electric strongly recommends that you have the most recent and up-to-
date version available on.www.exchange.se.com/

The technical characteristics of the devices described in this guide also appear
online. To access the information online, go to the Schneider Electric home page
at www.se.com.

Pre-requisites
Pre-requisites to make the most of this document are:

(1) prior knowledge of EcoStruxure™ Power solutions,

(2) prior experience working with REST or GraphQL APIs.

Using the API assumes a pre-existing system of sensors and devices connected
to the

Schneider cloud platform. These connected sensors and devices are the primary
source of data

provided through the API. You will also need to have an active subscription to
these API access.

DOCA0339EN-00 5
Introduction API Developer Guide – User Starter Guide

Introduction
Purpose
This document is for software developers who want to consume data from
EcoStruxure™ Energy platform.

These API has been designed to give access to all Energy and Power data
coming from an EcoStruxure Power system. It allows external applications to
request data of connected energy sensors and electrical devices including the
utility counters like water and gas. Advanced queries can also be used for better
understanding sites contextualized information, site topology, electrical and
metering hierarchy information. It includes electrical monitoring data with
alarming.
With these APIs, external Applications can gain visibility on relevant energy data
to reduce consumption and improve site’s performance, on energy analysis
understanding for efficiency improvements. Applications can also monitor
remotely the electrical installation with remote maintenance.

DOCA0339EN-00 6
Architecture Introduction API Developer Guide – User Starter Guide

Architecture Introduction

EcoStruxure Power Architecture

for Non-critical Small or Medium Sites

Example of Reference Architectures designed to support both small and medium

commercial or industrial buildings:

DOCA0339EN-00 7
Architecture Introduction API Developer Guide – User Starter Guide

For simple installations, the architecture can be based on:

• PowerTag Energy Sensors

• EcoStruxure Panel Server, a cloud-connectable gateway with embedded web

pages for commissioning

• Our Energy cloud-based platform with all data needed for external
applications.

These devices are equipment installed by electrician. Once set up, the panel
Server gateway communicates through the securely stored data to the Energy
cloud-based platform

With this type of installation, both Energy and Electrical data can be accessible on
the cloud platform. And these API enable an automatic data access to all
electrical and energy data coming from this EcoStruxure Power system

EcoStruxure Power Architecture for Critical Installations

For critical power installations where power downtime is not possible partially or
totally, the installation must be monitored and controlled. Software like
EcoStruxure Power Monitoring Expert or EcoStruxure Power Operation can be
used at site level. And these SCADA applications can be connected to our Energy
cloud-based platform with all data required by external applications

After the setup, these on-premises software communicate through the securely
stored data to the Energy cloud-based platform

Like simple installations, both Energy and Electrical data can be accessible on the
cloud platform. And these API enable an automatic data access to all electrical
and energy data coming from this EcoStruxure Power system

Example of Reference Architectures designed to support large and critical

commercial or industrial buildings

DOCA0339EN-00 8
Architecture Introduction API Developer Guide – User Starter Guide

DOCA0339EN-00 9
Using the API API Developer Guide – User Starter Guide

Using the API

GraphQL
Graph Energy Hub uses a GraphQL API to share data externally. GraphQL was
created by Facebook and is often used as a modern alternative to REST APIs.
With the REST API, multiple requests must be made to different endpoints to
obtain the same data. In GraphQL, you can specify exactly the data you need and
get only that data back. GraphQL makes the performance of your application
more efficient, since the GraphQL API reduces the amount of unnecessary data
being transferred over the network. GraphQL allows clients to request specific
data from an API rather than getting a fixed set of data, as is the case with REST
APIs. Employing GraphQL allows application logic to be much simpler.
• The GraphQL API consists of a:

• Type system,

• Query language and execution semantics,

• Static validation, and

• Type introspection.

The result of a single query or mutation is returned in JSON (JavaScript Object

Notation) format. Queries are composed of nodes, edges, and fields. Typically,
you use nodes to get data about a specific object, use edges to get collections of
objects on a single object, and use fields to get data about a single object or each
object in a collection. Throughout our documentation, we may refer to both a node
and edge as an "endpoint". Queries can traverse related objects and their fields,
which allows clients to fetch related data in one request, instead of making
several roundtrip requests.

All data transfers conform to HTTP/1. All endpoints need HTTPS. Because the
Graph API is HTTP-based, Graph API works with any language that has an HTTP
library, such as cURL and urllib. This means you can use the Graph API directly
in your browser.

Useful GraphQL Tools

Using the recommended GraphQL tools, client application developers can easily
discover GraphQL schema via introspections.
Altair

A comprehensive GraphQL client tool that helps to explore, organize, and test
queries as well as mutations.
https://altair.sirmuel.design/
A chrome extension is also available:
https://chrome.google.com/webstore/detail/altair-graphql-
client/flnheeellpciglgpaodhkhmapeljopja

GraphiQL Explorer

Plugin for Altair (and other clients) to help create queries and mutations.
https://www.npmjs.com/package/graphiql-explorer

DOCA0339EN-00 10
Using the API API Developer Guide – User Starter Guide
Postman

Postman can make HTTP calls using GraphQL, an open-source data query and
manipulation language for APIs.

https://learning.postman.com/docs/sending-requests/graphql/graphql/

GraphQL Voyager

Helps the user to visualize the whole GraphQL schema and the links between
entities.

https://apis.guru/graphql-voyager/

EcoStruxure Energy Data Model

Within our platform, data is stored using our EcoStruxureTM Energy Data Model
(E²DM). The E²DM is projected onto the GraphQL API in the form of types in a
GraphQL schema. Projections allow API developers to serve parts of an entity
data in response to a GraphQL request. The GraphQL API services expose
queries to read data and mutations to manipulate data, that are often collocated in
the same schema with types

Basic Steps to Use APIs

Using the API consists of the following basic steps:

• Get a token.
• Generate the first GraphQL request.

• Create queries.

These steps will be detailed in the following sections.

1 Get a Token
To make the first GraphQL request, the user must be authenticated, for that the
user will have to use the the "Authorization Service" to get a valid - JSON Web
Token (JWT) for the incoming request.

A client_id and a client_secret are both mandatory to generate a token.

For directions on how to get the client_id and client_secret, refer to the
"Configuring Systems Integration" section in the Integrations management
documentation of the Energy Hub Platform.

With Postman, for example, to retrieve the document, the following procedure will
allow you to do it:

1. Create the request with the following URL:

https://ecostruxure-energy-one.se.app/api/auth/token

DOCA0339EN-00 11
Using the API API Developer Guide – User Starter Guide
2. Paste the following content under the "Headers" tab in the "KEY/VALUE"
section:

Content-Type : application/x-www-form-urlencoded

Accept : application/json

3. Paste the following content under the "Body" tab in the "KEY/VALUE" section:

grant_type: client_credentials

client_id: Client_ID value transmitted by the Site Manager

client_secret: Cliend_Secret value transmitted by the Site Manager.

4. Once the above steps are completed, click the Send button to make the
query. The JWT token will populate, which will allow access to the GraphQL
gateway and access to the GraphQL APIs. The token response is presented
like as follow:

{
"token_type": "bearer",
"access_token": "ey […] nzP-I",
"expires_in": 3600
}

This token is valid for 1 Hour.

2 Generate the First GraphQL Request

For example with Altair to generate of first GraphQL call.

1. Enter the following GraphQL URL in the specific section:

2. Click the Headers Icon.

3. Place the previously generated token in the Bearer field like this is done on
DOCA0339EN-00 12
Using the API API Developer Guide – User Starter Guide
the following image. (It might be necessary to create the labels and save this
Header the first time).

3 Create Queries
Then the user can make a query, here is an example of how to get the Tenants id
and Tenants label:

DOCA0339EN-00 13
Quick Start Guide API Developer Guide – User Starter Guide

Quick Start Guide

Goal
This quick start covers the steps and queries required to get energy consumption
data for a site, namely:

• Query for the Tenant.

• Query for the Site.

• Query for time series data for the Site’s energy hierarchy.

• Query for Usage and Node labels.

Assumptions:

• At least one site configured with an energy hierarchy, and

• All the authorization and authentication steps have been completed.

Step 1: Query to Get Tenants

Before going to the first query, don’t forget to get a token with the method
explained in the above pages. This token is the key to access all the information
related to your account.

All the following steps will be composed with a:

• Query

• Query Input Variables

• Query Response

First request will be querying for the organization ID that has the consumption
data you want to retrieve. In the Project Data window, the user can specify the
information about the project.

Query
query getTenants {
tenants {
id
label
}
}

Query Input Variables

None

DOCA0339EN-00 14
Quick Start Guide API Developer Guide – User Starter Guide
Query Response
{
"data": {
"tenants": [
{
"id": 23052,
"label": "Top 4 Lunch Chain"
}
]
}
}

With the id of our organization, let’s get the Energy Hierarchy behind this
organization. Query the tenant for the Energy Hierarchy to return a collection of
toponodes (assuming toponodes is correct) which will include the Site.

Step 2: Query to Get the Energy Hierarchy

Query
query SitesEnergyView(
$mode: EMCP_HierarchyMode!
$appContext: [EMCP_TopoNodeContextInput]
) {
fullSitesList: hierarchy(
mode: $mode
appContext: $appContext
includeAllParents: true
where: {
thing: {
concept: {
conceptKind: { in: [OTHER, TENANT, PRODUCT, LOAD, EQUIPMENT]
}
}
}
}
) {
level
parentId
childSite: thing {
siteId: id
label
tenantId
concept {
urn
type: conceptKind
ui
properties {
urn
__typename
}
DOCA0339EN-00 15
Quick Start Guide API Developer Guide – User Starter Guide
__typename
}
__typename
}
__typename
}
permittedSitesList: hierarchy(
mode: $mode
appContext: $appContext
includeAllParents: false
where: {
thing: {
concept: {
conceptKind: { in: [OTHER, TENANT, PRODUCT, LOAD, EQUIPMENT]
}
}
}
}
) {
level
parentId
childSite: thing {
siteId: id
label
tenantId
concept {
urn
type: conceptKind
ui
properties {
urn
__typename
}
__typename
}
__typename
}
__typename
}
}

Query Input Variables

{
"mode": "ENERGY",
"appContext": [
{ "id": 23052, "type": "TENANT", "urn": "urn:edm-
se:em:core:pr:tenant" }
]
}

DOCA0339EN-00 16
Quick Start Guide API Developer Guide – User Starter Guide

Query Response
{
"data": {
"fullSitesList": [
{
"level": 0,
"parentId": null,
"childSite": {
"siteId": 23052,
"label": "Top 4 Lunch Chain",
"tenantId": null,
"concept": {
"urn": "urn:edm-se:em:core:oc:tenant",
"type": "TENANT",
"ui": "{\"icon\": \"user_group\", \"color\": \"#71CBE0\"}",
"properties": [
{
"urn": "urn:edm-se:em:core:pr:tenant",
"__typename": "EMCP_Property"
}
],
"__typename": "EMCP_Concept"
},
"__typename": "EMCP_Thing"
},
"__typename": "EMCP_Hierarchy"
},
{
"level": 1,
"parentId": 23052,
"childSite": {
"siteId": 23060,
"label": "France",
"tenantId": 23052,
"concept": {
"urn": "urn:edm-se:em:core:oc:region",
"type": "OTHER",
"ui": "{\"icon\": \"earth_arrow\", \"color\":\"#71CBE0\"}",
"properties": [
{
"urn": "urn:edm-se:em:core:pr:region",
"__typename": "EMCP_Property"
},
{
"urn": "urn:edm-se:em:core:pr:filter_region",
"__typename": "EMCP_Property"
}
],
"__typename": "EMCP_Concept"
},

DOCA0339EN-00 17
Quick Start Guide API Developer Guide – User Starter Guide
"__typename": "EMCP_Thing"
},
"__typename": "EMCP_Hierarchy"
},
{
"level": 2,
"parentId": 23060,
"childSite": {
"siteId": 23062,
"label": "Top 4 Lunch Eybens",
"tenantId": 23052,
"concept": {
"urn": "urn:edm-se:em:core:oc:site",
"type": "OTHER",
"ui": "{\"icon\": \"site\", \"color\": \"#71CBE0\"}",
"properties": [
{
"urn": "urn:edm-se:em:core:pr:site",
"__typename": "EMCP_Property"
},
{
"urn": "urn:edm-se:em:core:pr:filter_site",
"__typename": "EMCP_Property"
}
],
"__typename": "EMCP_Concept"
},
"__typename": "EMCP_Thing"
},
"__typename": "EMCP_Hierarchy"
},
[…]
}
In the response there will be many nodes depending on the depth of the Energy
Hierarchy. In this example we have an Organization, a Region, and a Site. You will
need the IDs for all three of those toponodes to prepare the query for Step 3.
In the response find the Site and collect the siteId field as well as the parentId
field. The parentId field may be an organization or region depending on the
Energy Hierarchy.

At the end of this step you have (up to) three (3) Ids, the Tenant Id, the Region Id,
and the Site Id.

DOCA0339EN-00 18
Quick Start Guide API Developer Guide – User Starter Guide

Step 3: Query to Get Energy Usages

In this step take the three (3) Id's from Step 2 and use them as the input variables
of the binnedUsageTrendData query. This query is used to retrieve the energy
per usage consumption.

Query
query binnedUsageTrendData(
$context: [EMCP_TopoNodeContextInput!]!
$take: Int
$skip: Int
$businessQuantityName: String!
$startTime: DateTime!
$endTime: DateTime!
$timeZone: String!
$aggregationInterval: EMCP_AggregationInterval!
$specialFilter: EMCP_SpecialFilter
) {
binnedUsageTrendData(
appContext: $context
take: $take
skip: $skip
businessQuantityName: $businessQuantityName
startTime: $startTime
endTime: $endTime
timeZone: $timeZone
aggregationInterval: $aggregationInterval
specialFilter: $specialFilter
) {
items {
measureId
usageId
thingId
measure {
label
unit {
symbol
__typename
}
__typename
}
timeSeriesValues {
startTime
value
__typename
}
__typename
}
__typename
}
}

DOCA0339EN-00 19
Quick Start Guide API Developer Guide – User Starter Guide

Query Input Variables

{
"context": [
{ "id": 23052, "urn": "urn:edm-se:em:core:pr:tenant", "type":
"TENANT" },
{ "id": 23060, "urn": "urn:edm-se:em:core:pr:region", "type":
"ID" },
{ "id": 23062, "urn": "urn:edm-se:em:core:pr:site", "type":
"ID" }
],
"take": 100,
"skip": 0,
"businessQuantityName": "ACTIVE_ENERGY",
"startTime": "2023-08-08T22:00:00.000Z",
"endTime": "2023-08-09T22:00:00.000Z",
"timeZone": "Europe/Paris",
"aggregationInterval": "HOUR",
"specialFilter": "NONE"
}
The granularity can change by choosing for example “DAY” instead of the chosen
“HOUR”.

Query Response
{
"data": {
"binnedUsageTrendData": {
"items": [
{
"measureId": 2045,
"usageId": 276,
"thingId": 23062,
"measure": {
"label": "Active energy delivered positive no reset",
"unit": {
"symbol": "Wh",
"__typename": "EMCP_Unit"
},
"__typename": "EMCP_Measure"
},
"timeSeriesValues": [
{
"startTime": "2023-08-09T00:00:00.000+02:00",
"value": -1113,
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
},
{
"startTime": "2023-08-09T01:00:00.000+02:00",
"value": -1013,
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
DOCA0339EN-00 20
Quick Start Guide API Developer Guide – User Starter Guide
},
{
"startTime": "2023-08-09T02:00:00.000+02:00",
"value": -1175,
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
},
[…]
{
"startTime": "2023-08-09T20:00:00.000+02:00",
"value": -940,
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
},
{
"startTime": "2023-08-09T21:00:00.000+02:00",
"value": -1042,
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
},
{
"startTime": "2023-08-09T22:00:00.000+02:00",
"value": -1070,
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
},
{
"startTime": "2023-08-09T23:00:00.000+02:00",
"value": -1092,
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
}
],
"__typename":
"EMCP_BusinessQuantityBinnedUsageTimeSeries"
},
{
"measureId": 2045,
"usageId": 277,
"thingId": 23062,
"measure": {
"label": "Active energy delivered positive no reset",
"unit": {
"symbol": "Wh",
"__typename": "EMCP_Unit"
},
"__typename": "EMCP_Measure"
},
"timeSeriesValues": [
{
"startTime": "2023-08-09T00:00:00.000+02:00",
"value": 343,
DOCA0339EN-00 21
Quick Start Guide API Developer Guide – User Starter Guide
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
},
{
"startTime": "2023-08-09T01:00:00.000+02:00",
"value": 342,
"__typename":
"EMCP_BusinessQuantityBinnedTimeSeriesValue"
},
[…]
}

DOCA0339EN-00 22
Quick Start Guide API Developer Guide – User Starter Guide

Step 3: Query to Get Energy per Zone

We can retrieve energy per usage, let’s try to do it per zone. Using the
rankedUsageIntensity will allows to do it.

Query
query rankedUsageIntensity(
$appContext: [EMCP_TopoNodeContextInput!]!
$input: EMCP_RankedUsageIntensityInput!
$order: [EMCP_RankedUsageIntensityValueSortInput!]
$take: Int!
$skip: Int = 0
) {
rankedUsageIntensity(
appContext: $appContext
input: $input
order: $order
take: $take
skip: $skip
) {
totalCount
items {
ranking
value
surfaceArea
usageIntensity
usagesConfigured
measure {
...GeneralMeasureFields
__typename
}
thingId
thingLabel
thingContext {
...GeneralToponodeContextFields
__typename
}
__typename
}
__typename
}
}

fragment GeneralToponodeContextFields on EMCP_TopoNodeContext {

id
type
label
name
urn
value
__typename
}

DOCA0339EN-00 23
Quick Start Guide API Developer Guide – User Starter Guide
fragment GeneralMeasureFields on EMCP_Measure {
id
label
urn
unit {
...GeneralUnitFields
__typename
}
__typename
}

fragment GeneralUnitFields on EMCP_Unit {

id
isSi
symbol
urn
quantityName
__typename
}

Query Input Variables

{
"skip": 0,
"appContext": [
{
"type": "TENANT",
"id": 23052,
"urn": "urn:edm-se:em:core:pr:tenant"
},
{
"type": "ID",
"id": 23060,
"urn": "urn:edm-se:em:core:pr:region"
},
{
"type": "ID",
"id": 23062,
"urn": "urn:edm-se:em:core:pr:site"
}
],
"input": {
"startTime": "2023-08-09T22:00:00.000Z",
"endTime": "2023-08-10T22:00:00.000Z",
"topoConceptUrn": null,
"businessQuantity": "ACTIVE_ENERGY"
},
"take": 10,
"order": [
{
"ranking": "ASC"
},

DOCA0339EN-00 24
Quick Start Guide API Developer Guide – User Starter Guide
{
"thingLabel": "ASC"
}
]
}

Query Response
{
"data": {
"enumDescriptions": [
{
"id": 4505,
"description": "Renewable power source",
"enumValueId": 9597
},
[…]
{
"ranking": 1,
"value": 18913,
"surfaceArea": null,
"usageIntensity": null,
"usagesConfigured": true,
"measure": {
"id": 2045,
"label": "Active energy delivered positive no reset",
"urn": "urn:edm-se:em:core:me:whr_i_pos_nonreset",
"unit": {
"id": 10,
"isSi": false,
"symbol": "Wh",
"urn": "urn:edm-se:em:core:ut:watt_hour",
"quantityName": "REAL_ENERGY",
"__typename": "EMCP_Unit"
},
"__typename": "EMCP_Measure"
},
"thingId": 27189,
"thingLabel": "Parking",
"thingContext": [
{
"id": 23052,
"type": "TENANT",
"label": "Top 4 Lunch Chain",
"name": "Top 4 Lunch Chain",
"urn": "urn:edm-se:em:core:pr:tenant",
"value": null,
"__typename": "EMCP_TopoNodeContext"
},
{
"id": 23060,
"type": "ID",

DOCA0339EN-00 25
Quick Start Guide API Developer Guide – User Starter Guide
"label": "France",
"name": "France",
"urn": "urn:edm-se:em:core:pr:region",
"value": "France",
"__typename": "EMCP_TopoNodeContext"
},
{
"id": 23062,
"type": "ID",
"label": "Top 4 Lunch Eybens",
"name": "Top 4 Lunch Eybens",
"urn": "urn:edm-se:em:core:pr:site",
"value": "Top 4 Lunch Eybens",
"__typename": "EMCP_TopoNodeContext"
},
{
"id": 27189,
"type": "ID",
"label": "Parking",
"name": "Parking",
"urn": "urn:edm-se:em:core:pr:area",
"value": "Parking",
"__typename": "EMCP_TopoNodeContext"
}
],
"__typename": "EMCP_RankedUsageIntensityValue"
}
],
"__typename":
"EMCP_RankedUsageIntensityValueCollectionSegment"
}
[…]
}

As this is highlighted, an energy consumption of 18913 Wh is associated to the

zone “Parking”.

Getting energy consumption per zone is now possible with the use of a simple
query.

Step 4: Query to Retrieve Alarms

The system allows the user to retrieve alarms.

There are different types of alarms that are ranked from “GREEN” to “RED”
according to the severity.
In a single query, we can get this crucial information.

Query
query alarmOccurrencesSummary(
$appContext: [EMCP_TopoNodeContextInput!]!
$enableNotificationPreferences: Boolean

DOCA0339EN-00 26
Quick Start Guide API Developer Guide – User Starter Guide
$aggregationInterval: EMCP_AggregationInterval!
$startTime: DateTime!
$endTime: DateTime!
$timeZone: String!
$alarmPriorityFilter: [EMCP_AlarmPriorityType!]
$alarmStateFilter: [EMCP_AlarmStateType!]
$alarmConceptCategoryFilter: [String!]
) {
alarmOccurrencesSummary(
appContext: $appContext
enableNotificationPreferences: $enableNotificationPreferences
interval: $aggregationInterval
startTime: $startTime
endTime: $endTime
timeZone: $timeZone
alarmPriorityFilter: $alarmPriorityFilter
alarmStateFilter: $alarmStateFilter
alarmConceptCategoryFilter: $alarmConceptCategoryFilter
) {
totalCount
details {
acknowledgedCount
unacknowledgedCount
activeCount
inactiveCount
__typename
}
alarmPrioritySummary {
priority
totalCount
details {
acknowledgedCount
unacknowledgedCount
activeCount
inactiveCount
__typename
}
__typename
}
__typename
}
}

Query Input Variables

{
"startTime": "2023-08-09T22:00:00.000Z",
"endTime": "2023-08-10T22:00:00.000Z",
"appContext": [
{
"type": "TENANT",
"id": 23052,

DOCA0339EN-00 27
Quick Start Guide API Developer Guide – User Starter Guide
"urn": "urn:edm-se:em:core:pr:tenant"
}
],
"aggregationInterval": "DAY",
"enableNotificationPreferences": false,
"timeZone": "Europe/Paris",
"alarmPriorityFilter": [
"HIGH",
"MEDIUM",
"LOW"
],
"alarmStateFilter": null,
"alarmConceptCategoryFilter": null
}

Same as we see with BinnedUsage query, a granularity can be chosen.

Query Response
{
"data": {
"alarmOccurrencesSummary": {
"totalCount": 3,
"details": {
"acknowledgedCount": 0,
"unacknowledgedCount": 3,
"activeCount": 0,
"inactiveCount": 3,
"__typename": "EMCP_BinnedAlarmOccurrenceDetails"
},
"alarmPrioritySummary": [
{
"priority": "GREEN",
"totalCount": 3,
"details": {
"acknowledgedCount": 0,
"unacknowledgedCount": 3,
"activeCount": 0,
"inactiveCount": 3,
"__typename": "EMCP_BinnedAlarmOccurrenceDetails"
},
"__typename": "EMCP_AlarmPrioritySummary"
},
{
"priority": "YELLOW",
"totalCount": 0,
[…]
}

We see a total of 3 alarms that has been raised during the period chosen and
they are now inactives.

DOCA0339EN-00 28
Quick Start Guide API Developer Guide – User Starter Guide

Conclusion
With the use of 4 simple steps, this is possible to create complex but
understandable charts to have a great overview of the alarms and the
consumption of a site, a region or an organization per usage or per zone.

DOCA0339EN-00 29
Quick Start Guide API Developer Guide – User Starter Guide

Schneider Electric
35 rue Joseph Monier
92500 Rueil Malmaison –
France
+ 33 (0) 1 41 29 70 00
www.se.com

As standards, specifications, and design change from time to time,

please ask for confirmation of the information given in this publication.

© 2024 Schneider Electric. All rights reserved.

DOCA0339EN-00