Introduction

EcoStruxure Energy API

This 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 the data from the connected energy sensors and electrical devices including the utility counters like water and gas. Advanced queries can also be used for better understanding of contextualized information of the sites, site topology, electrical and metering hierarchy information. It includes electrical monitoring data with alarms.

With these APIs, external applications gain visibility of relevant energy data to reduce consumption and improve a site’s performance, and its energy analysis understanding for efficiency improvements. Applications can also remotely monitor the electrical installation for remote maintenance.

Data Model

The objective of the EcoStruxure Energy Data Model (EEDM) is to provide a unified view of information coming from different device types to the appropriate applications. The EcoStruxure Energy Data Model (EEDM) has been designed to simplify the user experience and the development of energy management applications by providing a common data model independent of the data source.

The EEDM uses

  • A limited set of generic classes, rather than domain specific ones.
  • Dictionaries to provide the semantic, rather than domain specific class attributes.

EEDM Concepts

What is a "Thing"?

  • Thing is an instance of a given concept.
  • A Thing references its associated concept via its URN.
  • A Thing has a set of property values and possibly also measurement values.

Thing can be used to represent a physical device in the installation, a location or any object which matters for the end user but that we have only an indirect access to. In other words, a Thing can be used to represent an “asset” to expose, to the customer, what is the most relevant for his application, but that we only have an indirect view of.

Note: Asset corresponds to what is sometimes called a “source”, “abstracts” or “virtual” by some teams.

For example, we may have access to instrument sensors for a motor and so be able to provide a diagnostic about the motor, yet without having any communication with the motor itself. Thing would be used to represent the motor, even if it is behind such an object and we have in fact access only to the information from the various separate sensors.

What is a dictionary?

The Dictionary API is the Interface that allows developers use to structure the data model information:

  • Concept: It is the kind of a Thing, such as a Building, Power Meter, Temperature Sensor, Tenant Bill.
  • Measure: It is the value measured by a Thing (such as a Power meter). Examples would be "Voltage Phase A", "Ambient Temperature", "Active Energy Received".
  • Property: It is the attributes of a Thing. For a building it can be an address or a building type, and for a Power Meter it can be the model or serial number.

Such generic classes and the relationships between them are sometimes called a meta model. These generic classes are containers for dictionary entries. Each entry within a dictionary is identified by its URN and corresponds to a very precise semantic.

Why is GraphQL at the top of our data model?

The EcoStruxure Energy Platform (EEP) data models are selectively projected to 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, which are often collocated in the same schema with types.

What is GraphQL?

The GraphQL API is the interface used between applications and the EEDM data model. GraphQL is an open-source language for APIs and provides a web API approach in which clients define the structure of the data to be returned by the server. GraphQL consists of:

  • Type system
  • Query language and execution semantics
  • Static validation
  • Type introspection

The result of a single query or mutation is returned in JSON format.

Queries and Mutations

GraphQL uses Queries and Mutations.

Queries can traverse related objects and their fields, which allows clients to fetch related data in one request, instead of making several roundtrip requests.

Mutations are used to modify server-side data. Like in queries, the mutation field returns an object type, which can be in nested fields.

How GraphQL works

The GraphQL API integrates with the EEDM and EEH data models through a well-defined schema in GraphQL, which serves as the foundation for both querying and manipulating data. This integration is key to how GraphQL operates within our system:

  1. Schema-Based Data Projection: The schema defines the structure of types that correspond to various aspects of the EEDM and EEH data models. This allows for selective projection of entity data, making the API versatile and responsive to specific GraphQL requests.

  2. Operation Types - Queries and Mutations:

    • Queries: Empower clients to read data efficiently. They enable traversing between related objects and fields, thus facilitating the retrieval of interconnected data in one streamlined request.
    • Mutations: Facilitate data manipulation on the server side. They return detailed object types and can include nested fields, allowing for precise and controlled data updates.

The underlying principle of this setup is to offer a responsive, flexible API that caters to the complex data retrieval and manipulation needs of our clients, all within a unified GraphQL framework.

List of Abbreviations

  • ACME – Assembling Configuration Management Environments
  • API – Application programming Interface
  • CDD – Cooling Degree Days
  • EEDM – EcoStruxure Energy Data Model
  • EEH – EcoStructure Energy Hub
  • EEO – EcoStruxure Energy One (Hub)
  • HDD – Heating Degree Days
  • HTTP – Hypertext Transfer Protocol
  • ID – Identity Document
  • IDMS – Integrated Database Management System
  • JSON – JavaScript object Notation
  • JWT – JSON Web Token
  • pvUrns – property values URN
  • SLD – Single Line Diagram
  • URL – Uniform Resource Locator
  • URN – Uniform Resource Name
  • UUID – Universal unique identifier

Get started

Authentication guide

This API supports the following authentication mechanism:

OAuth2 Authorization Code Flow

This authorization schema is intended for ISV applications that have obtained authorization from a Schneider Electric customer. Follow the steps below to initiate the authorization process, obtain an access token, and refresh the token as needed.

Step 1: Initiate Authorization and Consent Flow

Firstly, your application should initiate the Authorization and Consent flow by calling the Authorize Endpoint.

curl -X GET "https://api.exchange.se.com/ecostruxure/v1/oauth/authorize" \

     -d "client_id=YOUR_CLIENT_ID" \

     -d "response_type=code" \

     -d "redirect_uri=YOUR_REDIRECT_URI" \

     -d "scope=required_scope1 required_scope2" \

     -d "state=YOUR_STATE_STRING"

Upon successful authorization and user consent, you'll be redirected to the redirect_uri you provided, and an authorization code will be appended as a query parameter.

Step 2: Exchange Authorization Code for Token

Once you have received the authorization code, you need to exchange it for an access token by calling the Token Endpoint.

curl -X POST "https://api.exchange.se.com/ecostruxure/v1/oauth/token" \

     -d "grant_type=authorization_code" \

     -d "code=RECEIVED_AUTHORIZATION_CODE" \

     -d "redirect_uri=YOUR_REDIRECT_URI" \

     -d "client_id=YOUR_CLIENT_ID" \

     -d "client_secret=YOUR_CLIENT_SECRET"

This will return an access_token and a refresh_token.

Step 3: Refresh the Token

Your access_token will be valid for 1 hour. To get a new one without requiring the user to log in again, use the refresh_token.

curl -X POST "https://api.exchange.se.com/ecostruxure/v1/oauth/token" \

     -d "grant_type=refresh_token" \

     -d "refresh_token=YOUR_REFRESH_TOKEN" \

     -d "client_id=YOUR_CLIENT_ID" \

     -d "client_secret=YOUR_CLIENT_SECRET"

By following these steps, your ISV application can securely interact with Schneider Electric's API services, with the proper authorizations in place.

Personal Access Token Flow

This authorization mechanism is intended for end users who are using the API to access their own data in Schneider Electric's ecosystem. Upon purchasing the API, end users can generate a Personal Access Token directly from the Exchange DevPortal.

How to Generate a Personal Access Token

  1. Log in to the Exchange DevPortal.
  2. Navigate to the API product you have subscribed to.
  3. Locate the "Generate Personal Access Token" section and follow the on-screen instructions to create your token.

Your Personal Access Token serves as a credential that grants you access to your own data. Ensure that you keep it secure and never share it publicly.

How to make your first GraphQL request

User can leverage any GraphQL client application to invoke API endpoint and by passing previously generate token, either through OAuth 2 authorization flow or Personal Access Token, as bearer token.

A CURL example below,

curl -X POST "https://api.exchange.se.com/ecostruxure/energy-hub/v1/graphql" \

     -H "Authorization: Bearer <Token from previous step>"

     -d '{"query":"query getTenants{\r\n  tenants {\r\n    id\r\n    label\r\n  }\r\n}","variables":{}}'

The request body could vary based on the query, here is an example of how to get the Tenants id and label. :

query getTenants{

  tenants {

    id

    label

  }

}

{

  "data": {

    "tenants": [

      {

        "id": 87275,

        "label": "ACME Inc"

      },

      {

        "id": 87293,

        "label": "Mindt Chocolates"

      }

    ]

  }

}

Useful 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.

GraphiQL Explorer

Plugin for Altair (and other clients) to help create queries and mutations.

Postman

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

GraphQL Voyager

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

Banana Cake Pop

A powerful GraphQL IDE that joins you and your team on your GraphQL journey.

Support

Contact our Exchange support team at exchange.support@se.com and include,

- Endpoint URL

- Request/Response of the URL

- Any additional information like Screenshots, Postman collections

Get help from the community here.

Use cases

Tenant ID

What is a Tenant ID

A Tenant ID is a unique identifier for the organization in EEH.

You will need a Tenant ID as an input to get the SiteID.

Query

query getTenants{

  tenants {

    id

    label

  }

}

Query Response

{

  "data": {

    "tenants": [

      {

        "id": 12345,

        "label": "One organization"

      },

      {

        "id": 678910,

        "label": "Another organization"

      },

      {

        "id": 111213,

        "label": "A third organization"

      }

    ]

  }

}

SiteID

What is a SiteID

It is a unique identifier in EEH to represent the site under which a gateway will be commissioned.

Query

query getPhysicalHierarchy($appContext: [EMCP_TopoNodeContextInput]) {

  hierarchy(appContext: $appContext, mode: PHYSICAL) {

    level

    parentId

    thing {

      id

      label

      handle



    }

  }

}

Use the ID from the Query Response in GetTenantID Query Response as the ID for this input variable.

Query Input Variables

{

  "appContext":[

    {"id":912986,"type":"TENANT","urn":"urn:edm-se:em:core:pr:tenant"}

  ]

}

Query Response

{

  "data": {

    "hierarchy": [

      {

        "level": 0,

        "parentId": null,

        "thing": {

          "id": 912986,

          "label": "Shri Ram Hospital",

          "handle": null

        }

      },

      {

        "level": 2,

        "parentId": 912986,

        "thing": {

          "id": 1012814,

          "label": "SRH-Site",

          "handle": "Site:a07996e9-3ce4-4029-8389-f8463b5dbfdf"

        }

      },

      {

        "level": null,

        "parentId": 1012814,

        "thing": {

          "id": 1012817,

          "label": "Panel-ForAI",

          "handle": "ION:e0fdba6b-fc95-4790-b642-acb98a09fa48"

        }

      },

      {

        "level": null,

        "parentId": 1012817,

        "thing": {

          "id": 1012818,

          "label": "CircuitBreaker-ForAI",

          "handle": "eb499998-a8f8-4e35-acff-c98d93aba004"

        }

      },

      {

        "level": null,

        "parentId": 1012817,

        "thing": {

          "id": 1012819,

          "label": "TH110-A",

          "handle": "b16c809f-0ee5-46d8-82e2-46a6c9007562"

        }

      },

      {

        "level": null,

        "parentId": 1012817,

        "thing": {

          "id": 1012820,

          "label": "TH110-B",

          "handle": "d4c1c09a-f30d-4e7b-aa68-fb3ea1273715"

        }

      },

      {

        "level": null,

        "parentId": 1012817,

        "thing": {

          "id": 1012821,

          "label": "TH110-C",

          "handle": "e250c95b-cb99-4b95-a93c-636c18bb4380"

        }

      }

    ]

  }

}

Site property

This query is designed to get the properties for your site.

Overview

This site property data will cover the steps and query to get the site properties.

The high-level overview of the steps are:

  • Query for the Tenant
  • Query for the Site
  • Query for the Site Properties

Arguments

  • appContext : an Array on EMCP_TopoNodeContextInput to filter the result by topology. NOTE: To create an appContext, you will need Tenant ID and SiteID. Refer Step 1 for Tenant ID and refer Step 2 for SiteID. NOTE: appContext must be in the following order:
    • Type
    • Tenant ID
    • SiteID
  • includeAllParents: Boolean (default set to false), add the parent for thing (from appContext) if appContext is used - optional.

Behaviour

  • Site properties defines SiteName, description, address_line, Electricity rate and other properties.
  • description: Site property descriptions like street address specifying longitude and latitude of site location.
  • concept: Defines site and different types of site properties urn.
  • weather_station: Retrieves local climate data for the display of energy consumption normalized by degree days.

Step 1

What is a Tenant ID?

A Tenant ID is a unique identifier for the organization in EEH.

You will need a Tenant ID as an input in Step 2 to get the SiteID.

How to get a Tenant ID?

To get a Tenant ID, you need to perform a query as it is described in GetTenantID Query and you will receive the Response as described with Tenant ID.

Step 2

What is a SiteID?

It is a unique identifier in EEH to represent the site under which a gateway will be commissioned.

How to get a SiteID?

To get a SiteID, you need to perform a query as described in GetSiteID Query and you will receive the Response as described with SiteID.

In the Response there will be many nodes. For 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 three IDs:

  • Tenant ID
  • Region ID
  • SiteID

Step 3

In this step take the three IDs from Step 2 and use them as the input variables.

To get the site properties:

Query

fragment conceptFragment on EMCP_Concept {

  urn

  label

  description

  conceptKind

  __typename

}



fragment propertyLinks on EMCP_Property {

  propertyLinks {

    concept {

      urn

      __typename

    }

    __typename

  }

  __typename

}



fragment uiPreference on EMCP_Property {

  uiPreference {

    preference

    urn

    __typename

  }

  __typename

}



fragment unit on EMCP_Property {

  unit {

    name

    isSi

    symbol

    quantityName

    __typename

  }

  __typename

}



fragment propertyFragment on EMCP_Property {

  name

  urn

  label

  description

  mandatory

  visible

  example

  defIVal

  defFVal

  defSVal

  orderingType

  encodingType

  accessType

  facetType

  enumUrn

  concept {

    urn

    __typename

  }

  ...unit

  ...uiPreference

  ...propertyLinks

  __typename

}



fragment pvalueFragment on EMCP_PValue {

  pival

  pfval

  psval

  property {

    ...propertyFragment

    __typename

  }

  __typename

}



fragment nodeLinkFragment on EMCP_NodeLink {

  __typename

  dstId

  kind

  dst {

    __typename

    concept {

      __typename

      urn

    }

  }

}



fragment thingFragment on EMCP_Thing {

  id

  label

  handle

  concept {

    ...conceptFragment

    __typename

  }

  pvalues(where: $pvalueFilter) {

    ...pvalueFragment

    __typename

  }

  nodeLinkSrcs(where: $nodeLinkSrcsFilter) {

    ...nodeLinkFragment

    __typename

  }

  __typename

}



query infoPanel_queryThings($appContext: [EMCP_TopoNodeContextInput]!, $thingFilter: EMCP_ThingFilterInput!, $pvalueFilter: EMCP_PValueFilterInput!, $nodeLinkSrcsFilter: EMCP_NodeLinkFilterInput!) {

  things(

    appContext: $appContext

    includeLeafDevice: true

    includeAllParents: false

    where: $thingFilter

  ) {

    items {

      ...thingFragment

      __typename

    }

    __typename

  }

}

Query Input Variables

{

  "appContext": [

    {

      "id": 549010,

      "urn": "urn:edm-se:em:core:pr:tenant",

      "label": "Quest Manufacturing",

      "type": "TENANT"

    }

  ],

  "thingFilter": {

    "id": {

      "in": [

        1914464

      ]

    }

  },

  "pvalueFilter": {

    "property": {

      "or": [

        {

          "visible": {

            "neq": "NONE"

          },

          "urn": {

            "nin": [

              "urn:edm-se:em:core:pr:name",

              "urn:edm-se:em:core:pr:label",

              "urn:edm-se:em:core:pr:created_by",

              "urn:edm-se:em:core:pr:updated_by"

            ]

          }

        }

      ]

    }

  },

  "nodeLinkSrcsFilter": {

    "dst": {

      "concept": {

        "urn": {

          "in": [

            "urn:edm-se:em:core:ec:weather_station"

          ]

        }

      }

    }

  }

}

Query Response



Energy Hierarchy

This query represents organization's all site related assets, energy usages hierarchical details.

Overview

This data will cover the steps and queries to the contents of Energy Hierarchy.

The high-level overview of the steps are:

  1. Query for the Tenant
  2. Query for the Site
  3. Query for the Energy Hierarchy

Arguments

  • appContext: an Array on EMCP_TopoNodeContextInput to filter the result by topology. NOTE: To create an appContext, you will need Tenant ID and SiteID. Refer Step 1 for Tenant ID and refer Step 2 for SiteID. NOTE: appContext must be in the following order:
  1. Type
  2. Tenant ID
  3. SiteID
  • mode : enum(ENERGY, PHYSICAL, COMMUNICATION, BILLING, EQUIPMENT) to specify which type of Hierarchy is required.
  • whereClause: type EMCP_HierarchyFilterInput: allows advanced filtering capabilities – optional.
  • includeAllParents: Boolean (default set to false) add the parent for thing (from appContext) if appContext is used - optional.

Behaviour

  • The level from toponode: 0 is for site, the level starting from 0 for the root returned item and is increased for children.
  • Kinds of thing returned:
  • Thing with a LOAD linked to them with a NodelinkKind Performs or Measure.
  • Topo nodes (Site, Building, Floor, Area, Space, Production Line, Zone, Panel Board)
  • LOAD type thing label indicate usages, such as lighting, heating, or other type for energy consumers and energy sources in organization model.
  • How Parents/Child relationship is computed:
    • For topo nodes: Parent will be the lowest level of all the topo nodes, defined in the thing properties.
    • For other things: Parent will be the parent of the linked LOAD things.

Step 1

What is a Tenant ID?

A Tenant ID is a unique identifier for the organization in EEH.

You will need a Tenant ID as an input in Step 2 to get the SiteID.

How to get a Tenant ID?

To get a Tenant ID, you need to perform a query as it is described in GetTenantID Query and you will receive the Response as described with Tenant ID.

Step 2

What is a SiteID?

It is a unique identifier in EEH to represent the site under which a gateway will be commissioned.

How to get a SiteID?

To get a SiteID, you need to perform a query as described in GetSiteID Query and you will receive the Response as described with SiteID.

In the Response there will be many nodes. For 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 three IDs:

  • Tenant ID
  • Region ID
  • SiteID

Step 3

In this step take the three IDs from Step 2 and use them as the input variables.

To get the contents of Energy Hierarchy:

Query

query getHierarchyWithNodelinks(

    $appContext: [EMCP_TopoNodeContextInput],

    $mode: EMCP_HierarchyMode!,

    $whereClause: EMCP_HierarchyFilterInput,

    $includeAllParents: Boolean!,

    $includeProperties: [String!],

    $includeNodelinks: [EMCP_LinkKindType!]) {

        hierarchy(

            mode: $mode

            appContext: $appContext

            includeAllParents: $includeAllParents

            where: $whereClause

            ) {

                parentId

                thing {

                    id

                    label

                    handle

                    concept {

                        urn

                        type: conceptKind

                        __typename

                        }

                        nodeLinkDsts(where: {kind: {in: $includeNodelinks}}) {

                            ...GeneralNodeLinkFields

                            __typename

                            }

                            nodeLinkSrcs(where: {kind: {in: $includeNodelinks}}) {

                                ...GeneralNodeLinkFields

                                __typename

                                }

                                pvalues(where: {property: {urn: {in: $includeProperties}}}) {

                                pival

                                pfval

                                psval

                                property {

                                urn

                                __typename

                            }

                        __typename

                     }

                __typename

            }

        __typename

    }

}



fragment GeneralNodeLinkFields on EMCP_NodeLink {

  id

  kind

  srcId

  srcNode

  dstId

  dstNode

  percentage

  __typename

}

Query Input Variable

{

  "appContext": [

    {

      "type": "TENANT",

      "id": 549010,

      "urn": "urn:edm-se:em:core:pr:tenant"

    },

    {

      "type": "ID",

      "id": 1914464,

      "urn": "urn:edm-se:em:core:pr:site"

    }

  ],

  "mode": "ENERGY",

  "includeAllParents": false,

  "includeProperties": [

    "urn:edm-se:em:core:pr:is_asset",

    "urn:edm-se:em:core:pr:product_usage",

    "urn:edm-se:em:core:pr:last_product_usage",

    "urn:edm-se:em:core:pr:has_computed_values"

  ],

  "includeNodelinks": [

    "RESIDUAL_FEED"

  ]

}

Query Response

{

  "data": {

    "hierarchy": [

      {

        "parentId": 549010,

        "thing": {

          "id": 1914464,

          "label": "MigrationSite1",

          "handle": "Site:1bc67bea-0d34-47bd-8427-74bfd158a330",

          "concept": {

            "urn": "urn:edm-se:em:core:oc:site",

            "type": "OTHER",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": null,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914476,

        "thing": {

          "id": 1914470,

          "label": "sepam 052 - SP1           ",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:b5d105d2-d129-4135-affe-94b296cbd91a",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:protection_relay",

            "type": "PRODUCT",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": 9596,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:last_product_usage",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:has_computed_values",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914464,

        "thing": {

          "id": 1914476,

          "label": "Usage: EVID",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:b5d105d2-d129-4135-affe-94b296cbd91a.EVID",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:load",

            "type": "LOAD",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": 9596,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:product_usage",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:has_computed_values",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914486,

        "thing": {

          "id": 1914485,

          "label": "ARC iDT40 - P01",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:3de16dfb-a312-444d-a367-55fd881f81c3",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:accessory",

            "type": "PRODUCT",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:has_computed_values",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 9550,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:last_product_usage",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914464,

        "thing": {

          "id": 1914486,

          "label": "Usage: ITID",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:3de16dfb-a312-444d-a367-55fd881f81c3.ITID",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:load",

            "type": "LOAD",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": 9550,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:product_usage",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:has_computed_values",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      }

    ]

  }

}

Energy Intensity

This query is designed to get energy intensity from the site.

Overview

This data will cover the steps and queries to the contents of Energy Intensity.

The high-level overview of the steps are:

  1. Query for the Tenant
  2. Query for the Site
  3. Query for the Energy Intensity

Arguments

  • appContext: an Array on EMCP_TopoNodeContextInput to filter the result by topology. NOTE: To create an appContext, you will need Tenant ID and SiteID. Refer Step 1 for Tenant ID and refer Step 2 for SiteID. NOTE: appContext must be in the following order:
    1. Type
    2. Tenant ID
    3. SiteID

Behaviour

  • The level from toponode: 0 is for site, the level starting from 0 for the root returned item and is increased for children.
  • Kinds of thing returned:
    • Thing with a LOAD linked to them with a NodelinkKind Performs or Measure.
    • Topo nodes (Site, Building, Floor, Area, Space, Production Line, Zone, Panel Board)
  • LOAD type thing label indicate usages, such as lighting, heating, or other type for energy consumers and energy sources in organization model.
  • How Parents/Child relationship is computed:
    • For topo nodes: Parent will be the lowest level of all the topo nodes, defined in the thing properties.
    • For other things: Parent will be the parent of the linked LOAD things.

Step 1

What is a Tenant ID?

A Tenant ID is a unique identifier for the organization in EEH.

You will need a Tenant ID as an input in Step 2 to get the SiteID.

How to get a Tenant ID?

To get a Tenant ID, you need to perform a query as it is described in GetTenantID Query and you will receive the Response as described with Tenant ID.

Step 2

What is a SiteID?

It is a unique identifier in EEH to represent the site under which a gateway will be commissioned.

How to get a SiteID?

To get a SiteID, you need to perform a query as described in GetSiteID Query and you will receive the Response as described with SiteID.

In the Response there will be many nodes. For 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 three IDs:

  • Tenant ID
  • Region ID
  • SiteID

Step 3

In this step take the three IDs from Step 2 and use them as the input variables.

To get the contents of Energy Intensity:

Query

rankedEnergyIntensity(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $input: EMCP_RankedEnergyIntensityInput!

  ) {

      totalCount

    items {

      ranking

      value

      surfaceArea

      energyIntensity

      usagesConfigured

      measure {

        ...GeneralMeasureFields

      }

      thingId

      thingLabel

    }

  }





fragment GeneralMeasureFields on EMCP_Measure {

  id

  label

  urn

 }

Query Input Variable

{

    "appContext": [

    {

      "type": "TENANT",

      "id": 87293,

      "urn": "urn:edm-se:em:core:pr:tenant"    

    },

    {

       "type": "ID",

       "id": 262211,

       "urn": "urn:edm-se:em:core:pr:site"

    }

  ],

  "input": {

    "startTime": "2023-03-16T04:00:00.000Z",

    "endTime": "2023-03-17T04:00:00.000Z",

    "topoConceptUrn": null

  },

}

Raw Time Series

This query returns paginated view of AggregatedTimeSeries data, based on the parameters.

Overview

This Raw time series data will cover the steps and query to get raw time series data for a device and Business Quantity.

The high-level overview of the steps are:

  1. Query for the Tenant

  2. Query for the Site

  3. Query for the time series data for a device and Business Quantity

Arguments

  • appContext: an Array on EMCP_TopoNodeContextInput to filter the result by topology. NOTE: To create an appContext, you will need Tenant ID and SiteID. Refer Step 1 for Tenant ID and refer Step 2 for SiteID. NOTE: appContext must be in the following order:
    1. Type
    2. Tenant ID
    3. SiteID
  • startTime: a DateTime to indicate the inclusive start of the interval. For example: startTime can be "2022-10-08T18:30:00.000Z".
  • endTime: a DateTime to indicate the exclusive end of the interval. For example: endTime can be "2023-10-09T18:30:00.000Z".
  • timeZone: a String to indicate the IANA time zone the data should be aggregated in. For example: timeZone can be "Asia/Calcutta".
  • skip/take: Ints specifying pagination of the data.
  • businessQuantityNames : an Array of String indicating the business quantities to get values for.

Behaviour

  • The time series values results are returned as interval ending timestamps.
  • The value returned is always interval based to the value for that time travel.

Step 1

What is a Tenant ID?

A Tenant ID is a unique identifier for the organization in EEH.

You will need a Tenant ID as an input in Step 2 to get the SiteID.

How to get a Tenant ID?

To get a Tenant ID, you need to perform a query as it is described in GetTenantID Query and you will receive the Response as described with Tenant ID.

Step 2

What is a SiteID?

It is a unique identifier in EEH to represent the site under which a gateway will be commissioned.

How to get a SiteID?

To get a SiteID, you need to perform a query as described in GetSiteID Query and you will receive the Response as described with SiteID.

In the Response there will be many nodes. For 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 three IDs:

  • Tenant ID
  • Region ID
  • SiteID

Step 3

In this step take the three IDs from Step 2 and use them as the input variables.

To get the raw time series data for a device and business quantity:

Query

query rawTrendData(

$appContext: [EMCP_TopoNodeContextInput!]!, 

$businessQuantityNames: [String!]!, 

$startTime: DateTime!, 

$endTime: DateTime!, 

$timeZone: String!, 

$take: Int = 250, 

$skip: Int = 0) 

{

  rawTrendData(

    skip: $skip

    take: $take

    appContext: $appContext

    businessQuantityNames: $businessQuantityNames

    startTime: $startTime

    endTime: $endTime

    timeZone: $timeZone

  ) {

    totalCount

    items {

      businessQuantity {

        name

        __typename

      }

      measure {

        ...GeneralMeasureFields

        __typename

      }

      thingId

      thingLabel

      thingContext {

        ...GeneralToponodeContextFields

        __typename

      }

      timeZone

      timeSeriesValues {

        timestamp

        value

        __typename

      }

      __typename

    }

    __typename

  }

}



fragment GeneralToponodeContextFields on EMCP_TopoNodeContext {

  id

  type

  label

  name

  urn

  value

  __typename

}



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

{

  "take": 250,

  "skip": 0,

  "appContext": [

    {

      "type": "TENANT",

      "id": 912986,

      "urn": "urn:edm-se:em:core:pr:tenant"

    },

    {

      "type": "ID",

      "id": 1465060,

      "urn": "urn:edm-se:em:core:pr:site"

    },

    {

      "type": "ID",

      "id": 1465178,

      "urn": "urn:edm-se:em:core:pr:panelboard"

    },

    {

      "type": "ID",

      "id": 1465179,

      "urn": "urn:edm-se:em:core:pc:thermal_sensor"

    }

  ],

  "businessQuantityNames": [

    "RELATIVE_TEMPERATURE"

  ],

  "startTime": "2022-10-08T18:30:00.000Z",

  "endTime": "2023-10-09T18:30:00.000Z",

  "timeZone": "Asia/Calcutta"

}

Query Response

{

  "data": {

    "rawTrendData": {

      "totalCount": 1,

      "items": [

        {

          "businessQuantity": {

            "name": "RELATIVE_TEMPERATURE",

            "__typename": "EMCP_BusinessQuantity"

          },

          "measure": {

            "id": 5206,

            "label": "Temperature",

            "urn": "urn:edm-se:em:core:me:temp",

            "unit": {

              "id": 5,

              "isSi": false,

              "symbol": "°C",

              "urn": "urn:edm-se:em:core:ut:degree_celsius",

              "quantityName": "RELATIVE_TEMPERATURE",

              "__typename": "EMCP_Unit"

            },

            "__typename": "EMCP_Measure"

          },

          "thingId": 1465179,

          "thingLabel": "TH110 - TH6",

          "thingContext": [

            {

              "id": 912986,

              "type": "TENANT",

              "label": "Shri Ram Hospital",

              "name": "Shri Ram Hospital",

              "urn": "urn:edm-se:em:core:pr:tenant",

              "value": null,

              "__typename": "EMCP_TopoNodeContext"

            },

            {

              "id": 1465179,

              "type": "ID",

              "label": "TH110 - TH6",

              "name": "TH110 - TH6",

              "urn": "urn:edm-se:em:core:pc:thermal_sensor",

              "value": "CC:89e92857-76d3-424a-8765-f50dd91ff738:50fb929f-f1dc-4235-aa69-b7c35fc77206",

              "__typename": "EMCP_TopoNodeContext"

            }

          ],

          "timeZone": "Asia/Calcutta",

          "timeSeriesValues": [

            {

              "timestamp": "2023-08-09T07:15:00.000Z",

              "value": 73,

              "__typename": "EMCP_BusinessQuantityTimeSeriesValue"

            },

            {

              "timestamp": "2023-08-09T07:30:00.000Z",

              "value": 73,

              "__typename": "EMCP_BusinessQuantityTimeSeriesValue"

            },

            {

              "timestamp": "2023-08-09T07:45:00.000Z",

              "value": 73,

              "__typename": "EMCP_BusinessQuantityTimeSeriesValue"

            },

            {

              "timestamp": "2023-08-09T08:00:00.000Z",

              "value": 73,

              "__typename": "EMCP_BusinessQuantityTimeSeriesValue"

            },

            {

              "timestamp": "2023-08-09T08:18:00.000Z",

              "value": 73,

              "__typename": "EMCP_BusinessQuantityTimeSeriesValue"

            },

            {

              "timestamp": "2023-08-09T08:30:00.000Z",

              "value": 73,

              "__typename": "EMCP_BusinessQuantityTimeSeriesValue"

            },

            {

              "timestamp": "2023-08-09T08:45:00.000Z",

              "value": 73,

              "__typename": "EMCP_BusinessQuantityTimeSeriesValue"

            }

          ],

          "__typename": "EMCP_BusinessQuantityTimeSeries"

        }

      ],

      "__typename": "EMCP_BusinessQuantityTimeSeriesCollectionSegment"

    }

  }

}

Assets Hierarchy

This query represents organization's all sites related assets hierarchical details returning by Thing data showing the parent-child relationship.

Overview

This data will cover the steps and queries to the content of Asset Hierarchy.

The high-level overview of the steps are:

  1. Query for the Tenant

  2. Query for the Site

  3. Query for the Asset Hierarchy

Arguments

  • appContext: an Array on EMCP_TopoNodeContextInput to filter the result by topology. NOTE: To create an appContext, you will need Tenant ID and SiteID. Refer Step 1 for Tenant ID and refer Step 2 for SiteID. NOTE: appContext must be in the following order:
    1. Type
    2. Tenant ID
    3. SiteID
  • mode: enum (ENERGY, PHYSICAL, COMMUNICATION, BILLING, EQUIPMENT) to specify which type of Hierarchy is required.
  • whereClause: type EMCP_HierarchyFilterInput: allows advanced filtering capabilities – optional.
  • includeAllParents: Boolean (default set to false), add the parent for the thing (from appContext) if appContext is used - optional.

Behaviour

The Asset Hierarchy query looks up and returns to the list of assets based on their commissioned status.

  • Commissioned Assets: When the assets are already commissioned on EMCP, the query will return only the accessible assets via the Commissioned Assets field.
  • Uncommissioned Assets: When the asset is not commissioned yet, an internal lookup logic is applied, which is dependent on the type of asset.
  • Types of Assets: When the serialNumber or serialNumber + commercialReference are valid references, the query returns:
    1. The asset is part of uncommisionedAssets with the basic information.
    2. The topology from Cloud Commissioning (if one exists) in the Hierarchy is part of uncommissionedAssets.

Step 1

What is a Tenant ID?

A Tenant ID is a unique identifier for the organization in EEH.

You will need a Tenant ID as an input in Step 2 to get the SiteID.

How to get a Tenant ID?

To get a Tenant ID, you need to perform a query as it is described in GetTenantID Query and you will receive the Response as described with Tenant ID.

Step 2

What is a SiteID?

It is a unique identifier in EEH to represent the site under which a gateway will be commissioned.

How to get a SiteID?

To get a SiteID, you need to perform a query as described in GetSiteID Query and you will receive the Response as described with SiteID.

In the Response there will be many nodes. For 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 three IDs:

  • Tenant ID
  • Region ID
  • SiteID

Step 3

In this step take the three IDs from Step 2 and use them as the input variables.

To get the contents of Asset Hierarchy:

Query

query getHierarchyWithNodelinks(

    $appContext: [EMCP_TopoNodeContextInput],

    $mode: EMCP_HierarchyMode!,

    $whereClause: EMCP_HierarchyFilterInput,

    $includeAllParents: Boolean!,

    $includeProperties: [String!],

    $includeNodelinks: [EMCP_LinkKindType!]

    ) {

        hierarchy(

            mode: $mode

            appContext: $appContext

            includeAllParents: $includeAllParents

            where: $whereClause

            ) {

                parentId

                thing {

                    id

                    label

                    handle

                    concept

                    {

                        urn

                        type: conceptKind

                        __typename

                        }

                        nodeLinkDsts(where: {kind: {in: $includeNodelinks}})

                        {

                            ...GeneralNodeLinkFields

                            __typename

                        }

                        nodeLinkSrcs(where: {kind: {in: $includeNodelinks}})

                        {

                            ...GeneralNodeLinkFields

                            __typename

                        }

                        pvalues(where: {property: {urn: {in: $includeProperties}}})

                        {

                            pival

                            pfval

                            psval

                            property

                            {

                                urn

                                __typename

                                }

                                __typename

                                }

                                __typename

                                }

                                __typename

                               } 

} 

fragment GeneralNodeLinkFields on EMCP_NodeLink 

{   id   kind   srcId   srcNode   dstId   dstNode   percentage   __typename }

Query Input Variables

{

  "appContext": [

    {

      "type": "TENANT",

      "id": 549010,

      "urn": "urn:edm-se:em:core:pr:tenant"

    },

    {

      "type": "ID",

      "id": 1914464,

      "urn": "urn:edm-se:em:core:pr:site"

    }

  ],

  "mode": "PHYSICAL",

  "includeAllParents": false,

  "includeProperties": [ "urn:edm-se:em:core:pr:is_asset", "urn:edm-se:em:core:pr:gateway", "urn:edm-se:em:core:pr:has_computed_values" ],

  "includeNodelinks": [ "FEED", "INCOMER", "RESIDUAL_FEED" ]

}

Query Response

{

  "data": {

    "hierarchy": [

      {

        "parentId": 549010,

        "thing": {

          "id": 1914464,

          "label": "MigrationSite1",

          "handle": "Site:1bc67bea-0d34-47bd-8427-74bfd158a330",

          "concept": {

            "urn": "urn:edm-se:em:core:oc:site",

            "type": "OTHER",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": null,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914464,

        "thing": {

          "id": 1914468,

          "label": "SMNC-APAS-ESP183-0155",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:DefaultAddedPanel",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:panelboard",

            "type": "PRODUCT",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": 1914467,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:gateway",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 1,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:has_computed_values",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914468,

        "thing": {

          "id": 1914469,

          "label": "M63 1P+N B - P07",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:f2bcce73-30e1-4dfa-89c0-c977a26d0d4b",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:kilowatthourmeter",

            "type": "PRODUCT",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": 1914467,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:gateway",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:has_computed_values",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914468,

        "thing": {

          "id": 1914470,

          "label": "sepam 052 - SP1           ",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:b5d105d2-d129-4135-affe-94b296cbd91a",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:protection_relay",

            "type": "PRODUCT",

            "__typename": "EMCP_Concept"

          },

          "nodeLinkDsts": [],

          "nodeLinkSrcs": [],

          "pvalues": [

            {

              "pival": 1914467,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:gateway",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            },

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:has_computed_values",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      }

    ]

  }

}

Communication Hierarchy

This query represents organization's all sites related gateway and devices hierarchical details returning by Thing data showing the parent-child relationship.

Overview

This data will cover the steps and queries to the content of Communication Hierarchy.

The high-level overview of the steps are:

  1. Query for the Tenant

  2. Query for the Site

  3. Query for the Communication Hierarchy

Arguments

  • appContext : an Array on EMCP_TopoNodeContextInput to filter the result by topology. NOTE: To create an appContext, you will need Tenant ID and SiteID. Refer Step 1 for Tenant ID and refer Step 2 for SiteID. NOTE: appContext must be in the following order:
    1. Type
    2. Tenant ID
    3. SiteID
  • mode: enum(ENERGY, PHYSICAL, COMMUNICATION, BILLING, EQUIPMENT) to specify which type of Hierarchy is required.
  • whereClause: type EMCP_HierarchyFilterInput: allows advanced filtering capabilities – optional.
  • includeAllParents: Boolean (default set to false) add the parent for thing (from appContext) if appContext is used - optional.

Behaviour

Kind of thing returned:

  • Thing with Concept kind - Product and has the gateway ID property.
  • Toponodes will contain Site, Gateway and Asset thing IDs and properties. How Parent/Child relation is computed:
  • For toponodes and gateway: The Parent will be the lowest level of the toponodes defined in the thing properties.
  • For other PRODUCT: The parent will be the gateway targeted by the gateway ID property.

Step 1

What is a Tenant ID?

A Tenant ID is a unique identifier for the organization in EEH.

You will need a Tenant ID as an input in Step 2 to get the SiteID.

How to get a Tenant ID?

To get a Tenant ID, you need to perform a query as it is described in GetTenantID Query and you will receive the Response as described with Tenant ID.

Step 2

What is a SiteID?

It is a unique identifier in EEH to represent the site under which a gateway will be commissioned.

How to get a SiteID?

To get a SiteID, you need to perform a query as described in GetSiteID Query and you will receive the Response as described with SiteID.

In the Response there will be many nodes. For 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 three IDs:

  • Tenant ID
  • Region ID
  • SiteID

Step 3

In this step take the three IDs from Step 2 and use them as the input variables.

To get the contents of the Communication Hierarchy:

Query

query getHierarchy(

    $appContext: [EMCP_TopoNodeContextInput],

    $mode: EMCP_HierarchyMode!,

    $whereClause: EMCP_HierarchyFilterInput,

    $includeAllParents: Boolean!,

    $includeProperties: [String!]

    ) {

        hierarchy(

            mode: $mode

            appContext: $appContext

            includeAllParents: $includeAllParents

            where: $whereClause

            ) {

                parentId

                thing {

                    id

                    label

                    handle

      concept {

        urn

        type: conceptKind

        __typename

      }

      pvalues(where: {property: {urn: {in: $includeProperties}}}) {

        pival

        pfval

        psval

        property {

          urn

          __typename

        }

        __typename

      }

      __typename

    }

    __typename

  }

}

Query Input Variables

{

  "appContext": [

    {

      "type": "TENANT",

      "id": 549010,

      "urn": "urn:edm-se:em:core:pr:tenant"

    },

    {

      "type": "ID",

      "id": 1914464,

      "urn": "urn:edm-se:em:core:pr:site"

    }

  ],

  "mode": "COMMUNICATION",

  "includeAllParents": false,

  "includeProperties": [

    "urn:edm-se:em:core:pr:is_asset"

  ]

}

Query Response

{

  "data": {

    "hierarchy": [

      {

        "parentId": 549010,

        "thing": {

          "id": 1914464,

          "label": "MigrationSite1",

          "handle": "Site:1bc67bea-0d34-47bd-8427-74bfd158a330",

          "concept": {

            "urn": "urn:edm-se:em:core:oc:site",

            "type": "OTHER",

            "__typename": "EMCP_Concept"

          },

          "pvalues": [

            {

              "pival": null,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914464,

        "thing": {

          "id": 1914467,

          "label": "SMNC-APAS-ESP183-0155",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:0977e85c-d3c0-4c06-9aee-927792f49f9d",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:gateway",

            "type": "PRODUCT",

            "__typename": "EMCP_Concept"

          },

          "pvalues": [

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      },

      {

        "parentId": 1914467,

        "thing": {

          "id": 1914493,

          "label": "TH110 - TH1",

          "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:9f9b44a9-cd03-4bb6-b97f-037df773902b",

          "concept": {

            "urn": "urn:edm-se:em:core:pc:thermal_sensor",

            "type": "PRODUCT",

            "__typename": "EMCP_Concept"

          },

          "pvalues": [

            {

              "pival": 0,

              "pfval": null,

              "psval": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:is_asset",

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_PValue"

            }

          ],

          "__typename": "EMCP_Thing"

        },

        "__typename": "EMCP_Hierarchy"

      }

    ]

  }

}

Alarms

This query is designed to return a paginated view of alarms for last 30 days duration.

Overview

This site alarm data will cover the steps and query to get the site alarms for the last 30 days.

The high-level overview of the steps are:

  1. Query for the Tenant

  2. Query for the Site

  3. Query for the site alarms for the last 30 days

Arguments

  • appContext : an Array on EMCP_TopoNodeContextInput to filter the result by topology. NOTE: To create an appContext, you will need Tenant ID and SiteID. Refer Step 1 for Tenant ID and refer Step 2 for SiteID. NOTE: appContext must be in the following order:
    1. Type
    2. Tenant ID
    3. SiteID
  • whereClause : type EMCP_AlarmOccurenceFilterInput: allows advanced filtering capabilities – optional.
  • startTime : a DateTime to indicate the inclusive start of the interval. For example: startTime can be "gte": "2023-09-05T18:30:00.000Z", "lte": "2023-10-05T18:30:00.000Z".
  • enableNotificationPreferences : a Boolean indicating whether to apply the user's notification filters to the returned data. Default value false.

Behaviour

  • If a user has no required permissions to view alarms, the response is an empty array.
  • If a user has no required privileges to access the requested organization topology, the response is an empty array.
  • If the input parameter enableNotificationPreferences is set to true, the result is filtered by the user's notification preferences. Otherwise, a user's notification preferences are ignored, and the request processing continues to the next stage.
  • If the input parameter appContext is set to null or an empty array and enableNotificationPreferences is set to true, the response will be a BAD_INPUT error.

Step 1

What is a Tenant ID?

A Tenant ID is a unique identifier for the organization in EEH.

You will need a Tenant ID as an input in Step 2 to get the SiteID.

How to get a Tenant ID?

To get a Tenant ID, you need to perform a query as it is described in GetTenantID Query and you will receive the Response as described with Tenant ID.

Step 2

What is a SiteID?

It is a unique identifier in EEH to represent the site under which a gateway will be commissioned.

How to get a SiteID?

To get a SiteID, you need to perform a query as described in GetSiteID Query and you will receive the Response as described with SiteID.

In the Response there will be many nodes. For 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 three IDs:

  • Tenant ID
  • Region ID
  • SiteID

Step 3

In this step take the three IDs from Step 2 and use them as the input variables.

To get the site alarms for the last 30 days:

Query

query GetAlarms(

    $appContext: [EMCP_TopoNodeContextInput!]!, $whereClause: EMCP_AlarmOccurrenceFilterInput, $enableNotificationPreferences: Boolean, $pageSize: Int, $offset: Int) {

  alarmOccurrences(

    appContext: $appContext

    enableNotificationPreferences: $enableNotificationPreferences

    where: $whereClause

    order: {startTime: DESC, id: DESC}

    skip: $offset

    take: $pageSize

  ) {

    totalCount

    pageInfo {

      hasNextPage

      hasPreviousPage

      __typename

    }

    items {

      ...GeneralAlarmOccurrenceFields

      __typename

    }

    __typename

  }

}

 

fragment GeneralAlarmOccurrenceFields on EMCP_AlarmOccurrence {

  id

  startTime

  endTime

  alarmState

  alarmPriority

  measures

  possibleCause

  possibleProblem

  possibleRecommendation

  possibleRisk

  alarmOccurrencePValues {

    ...AlarmOccurrencePValueFields

    __typename

  }

  alarmInstance {

    id

    alarmControl

    alarmFamily

    alarmModel

    alarmState

    alarmConceptId

    thingId

    tsMath

    alarmConcept {

      ...AlarmOccurrenceConceptFields

      __typename

    }

    thing {

      handle

      label

      __typename

    }

    __typename

  }

  acknowledgementAlarmStateTransition {

    alarmState

    comment

    idmsFederatedId

    transitionTime

    __typename

  }

  __typename

}

 

fragment AlarmOccurrenceConceptFields on EMCP_AlarmConcept {

  id

  urn

  name

  label

  description

  alarmEventConceptCategory {

    id

    description

    name

    packageId

    label

    __typename

  }

  packageId

  ui

  __typename

}

 

fragment AlarmOccurrencePValueFields on EMCP_AlarmOccurrencePValue {

  pival

  pfval

  psval

  pTsVal

  property {

    ...GeneralPropertyWithUnitFields

    __typename

  }

  __typename

}

 

fragment GeneralPropertyWithUnitFields on EMCP_Property {

  urn

  label

  description

  mandatory

  visible

  defIVal

  defFVal

  defSVal

  orderingType

  encodingType

  accessType

  facetType

  enumUrn

  unit {

    ...GeneralUnitFields

    __typename

  }

  __typename

}

 

fragment GeneralUnitFields on EMCP_Unit {

  id

  isSi

  symbol

  urn

  quantityName

  __typename

}

Query Input Variables

{

  "appContext": [

    {

      "type": "TENANT",

      "id": 549010,

      "urn": "urn:edm-se:em:core:pr:tenant"

    },

    {

      "type": "ID",

      "id": 1914464,

      "urn": "urn:edm-se:em:core:pr:site"

    }

  ],

  "pageSize": 5,

  "offset": 0,

  "enableNotificationPreferences": false,

  "whereClause": {

    "startTime": {

      "gte": "2023-09-05T18:30:00.000Z",

      "lte": "2023-10-05T18:30:00.000Z"

    },

    "alarmPriority": { "in": [ "HIGH", "MEDIUM", "LOW" ] }

  }

}

Query Response

{

  "data": {

    "alarmOccurrences": {

      "totalCount": 8,

      "pageInfo": {

        "hasNextPage": true,

        "hasPreviousPage": false,

        "__typename": "CollectionSegmentInfo"

      },

      "items": [

        {

          "id": 797119,

          "startTime": "2023-10-04T12:11:03.263Z",

          "endTime": null,

          "alarmState": "UNACK",

          "alarmPriority": "HIGH",

          "measures": null,

          "possibleCause": null,

          "possibleProblem": null,

          "possibleRecommendation": null,

          "possibleRisk": null,

          "alarmOccurrencePValues": [

            {

              "pival": null,

              "pfval": null,

              "psval": "Gateway Communication loss alarm",

              "pTsVal": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:detail_text",

                "label": "Details",

                "description": "detail text",

                "mandatory": false,

                "visible": "ON_ALL",

                "defIVal": null,

                "defFVal": null,

                "defSVal": null,

                "orderingType": "VISIBLE_LEVEL3",

                "encodingType": "STRING",

                "accessType": "RW",

                "facetType": "ELECTRICAL",

                "enumUrn": null,

                "unit": {

                  "id": 7,

                  "isSi": true,

                  "symbol": "",

                  "urn": "urn:edm-se:em:core:ut:dimensionless",

                  "quantityName": "NONE",

                  "__typename": "EMCP_Unit"

                },

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_AlarmOccurrencePValue"

            },

            {

              "pival": null,

              "pfval": null,

              "psval": "Gateway Communication loss alarm",

              "pTsVal": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:summary_text",

                "label": "Summary",

                "description": "summary text",

                "mandatory": false,

                "visible": "ON_ALL",

                "defIVal": null,

                "defFVal": null,

                "defSVal": null,

                "orderingType": "VISIBLE_LEVEL3",

                "encodingType": "STRING",

                "accessType": "RW",

                "facetType": "ELECTRICAL",

                "enumUrn": null,

                "unit": {

                  "id": 7,

                  "isSi": true,

                  "symbol": "",

                  "urn": "urn:edm-se:em:core:ut:dimensionless",

                  "quantityName": "NONE",

                  "__typename": "EMCP_Unit"

                },

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_AlarmOccurrencePValue"

            }

          ],

          "alarmInstance": {

            "id": 163806,

            "alarmControl": "NA",

            "alarmFamily": null,

            "alarmModel": "ALM_WITH_ACK",

            "alarmState": "UNACK",

            "alarmConceptId": 441,

            "thingId": 1914467,

            "tsMath": "INPUT_BASED",

            "alarmConcept": {

              "id": 441,

              "urn": "urn:edm-se:em:core:al:calh1_commloss",

              "name": "Communication loss alarm",

              "label": "Communication loss alarm",

              "description": "Communication loss alarm.",

              "alarmEventConceptCategory": {

                "id": 2,

                "description": "Diagnostics information",

                "name": "Diagnostics",

                "packageId": 1,

                "label": "Diagnostics",

                "__typename": "EMCP_AlarmEventConceptCategory"

              },

              "packageId": 1,

              "ui": "{\"icon\": \"notification_on\", \"color\": \"#71CBE0\"}",

              "__typename": "EMCP_AlarmConcept"

            },

            "thing": {

              "handle": "CC:714a3f61-a097-4e23-826a-59063d606205:0977e85c-d3c0-4c06-9aee-927792f49f9d",

              "label": "SMNC-APAS-ESP183-0155",

              "__typename": "EMCP_Thing"

            },

            "__typename": "EMCP_AlarmInstance"

          },

          "acknowledgementAlarmStateTransition": null,

          "__typename": "EMCP_AlarmOccurrence"

        },

        {

          "id": 797111,

          "startTime": "2023-09-15T16:00:12.161Z",

          "endTime": null,

          "alarmState": "UNACK",

          "alarmPriority": "LOW",

          "measures": null,

          "possibleCause": null,

          "possibleProblem": null,

          "possibleRecommendation": null,

          "possibleRisk": null,

          "alarmOccurrencePValues": [

            {

              "pival": null,

              "pfval": null,

              "psval": "Data loss alarm",

              "pTsVal": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:detail_text",

                "label": "Details",

                "description": "detail text",

                "mandatory": false,

                "visible": "ON_ALL",

                "defIVal": null,

                "defFVal": null,

                "defSVal": null,

                "orderingType": "VISIBLE_LEVEL3",

                "encodingType": "STRING",

                "accessType": "RW",

                "facetType": "ELECTRICAL",

                "enumUrn": null,

                "unit": {

                  "id": 7,

                  "isSi": true,

                  "symbol": "",

                  "urn": "urn:edm-se:em:core:ut:dimensionless",

                  "quantityName": "NONE",

                  "__typename": "EMCP_Unit"

                },

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_AlarmOccurrencePValue"

            },

            {

              "pival": null,

              "pfval": null,

              "psval": "Alarm related to potential data loss, such as device data transfer issues.",

              "pTsVal": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:summary_text",

                "label": "Summary",

                "description": "summary text",

                "mandatory": false,

                "visible": "ON_ALL",

                "defIVal": null,

                "defFVal": null,

                "defSVal": null,

                "orderingType": "VISIBLE_LEVEL3",

                "encodingType": "STRING",

                "accessType": "RW",

                "facetType": "ELECTRICAL",

                "enumUrn": null,

                "unit": {

                  "id": 7,

                  "isSi": true,

                  "symbol": "",

                  "urn": "urn:edm-se:em:core:ut:dimensionless",

                  "quantityName": "NONE",

                  "__typename": "EMCP_Unit"

                },

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_AlarmOccurrencePValue"

            }

          ],

          "alarmInstance": {

            "id": 163802,

            "alarmControl": "ACK",

            "alarmFamily": null,

            "alarmModel": "ALM_WITH_ACK",

            "alarmState": "UNACK",

            "alarmConceptId": 450,

            "thingId": 1914464,

            "tsMath": "INPUT_BASED",

            "alarmConcept": {

              "id": 450,

              "urn": "urn:edm-se:em:core:al:calh1_datalossalm",

              "name": "Data loss alarm",

              "label": "Data loss alarm",

              "description": "Alarm related to potential data loss, such as device data transfer issues.",

              "alarmEventConceptCategory": {

                "id": 2,

                "description": "Diagnostics information",

                "name": "Diagnostics",

                "packageId": 1,

                "label": "Diagnostics",

                "__typename": "EMCP_AlarmEventConceptCategory"

              },

              "packageId": 1,

              "ui": "{\"icon\": \"notification_on\", \"color\": \"#71CBE0\"}",

              "__typename": "EMCP_AlarmConcept"

            },

            "thing": {

              "handle": "Site:1bc67bea-0d34-47bd-8427-74bfd158a330",

              "label": "MigrationSite1",

              "__typename": "EMCP_Thing"

            },

            "__typename": "EMCP_AlarmInstance"

          },

          "acknowledgementAlarmStateTransition": null,

          "__typename": "EMCP_AlarmOccurrence"

        },

        {

          "id": 797110,

          "startTime": "2023-09-09T06:09:13.437Z",

          "endTime": "2023-10-01T00:00:00.000Z",

          "alarmState": "RTNUN",

          "alarmPriority": "LOW",

          "measures": null,

          "possibleCause": null,

          "possibleProblem": null,

          "possibleRecommendation": null,

          "possibleRisk": null,

          "alarmOccurrencePValues": [

            {

              "pival": null,

              "pfval": null,

              "psval": "Gas overconsumption alarm.",

              "pTsVal": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:detail_text",

                "label": "Details",

                "description": "detail text",

                "mandatory": false,

                "visible": "ON_ALL",

                "defIVal": null,

                "defFVal": null,

                "defSVal": null,

                "orderingType": "VISIBLE_LEVEL3",

                "encodingType": "STRING",

                "accessType": "RW",

                "facetType": "ELECTRICAL",

                "enumUrn": null,

                "unit": {

                  "id": 7,

                  "isSi": true,

                  "symbol": "",

                  "urn": "urn:edm-se:em:core:ut:dimensionless",

                  "quantityName": "NONE",

                  "__typename": "EMCP_Unit"

                },

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_AlarmOccurrencePValue"

            },

            {

              "pival": null,

              "pfval": null,

              "psval": "Alarm raised when the cumulated gas consumption is over the expected target.",

              "pTsVal": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:summary_text",

                "label": "Summary",

                "description": "summary text",

                "mandatory": false,

                "visible": "ON_ALL",

                "defIVal": null,

                "defFVal": null,

                "defSVal": null,

                "orderingType": "VISIBLE_LEVEL3",

                "encodingType": "STRING",

                "accessType": "RW",

                "facetType": "ELECTRICAL",

                "enumUrn": null,

                "unit": {

                  "id": 7,

                  "isSi": true,

                  "symbol": "",

                  "urn": "urn:edm-se:em:core:ut:dimensionless",

                  "quantityName": "NONE",

                  "__typename": "EMCP_Unit"

                },

                "__typename": "EMCP_Property"

              },

              "__typename": "EMCP_AlarmOccurrencePValue"

            }

          ],

          "alarmInstance": {

            "id": 163805,

            "alarmControl": "ACK",

            "alarmFamily": null,

            "alarmModel": "ALM_WITH_ACK",

            "alarmState": "RTNUN",

            "alarmConceptId": 493,

            "thingId": 1914464,

            "tsMath": "INPUT_BASED",

            "alarmConcept": {

              "id": 493,

              "urn": "urn:edm-se:em:core:al:calh1_gasoverconsalm",

              "name": "Gas overconsumption alarm",

              "label": "Gas overconsumption alarm",

              "description": "Alarm raised when the cumulated gas consumption is over the expected target.",

              "alarmEventConceptCategory": {

                "id": 3,

                "description": "Energy Management information",

                "name": "Energy Management",

                "packageId": 1,

                "label": "Energy Management",

                "__typename": "EMCP_AlarmEventConceptCategory"

              },

              "packageId": 1,

              "ui": "{\"icon\": \"notification_on\", \"color\": \"#71CBE0\"}",

              "__typename": "EMCP_AlarmConcept"

            },

            "thing": {

              "handle": "Site:1bc67bea-0d34-47bd-8427-74bfd158a330",

              "label": "MigrationSite1",

              "__typename": "EMCP_Thing"

            },

            "__typename": "EMCP_AlarmInstance"

          },

          "acknowledgementAlarmStateTransition": null,

          "__typename": "EMCP_AlarmOccurrence"

        }

      ],

      "__typename": "EMCP_AlarmOccurrenceCollectionSegment"

    }

  }

}

Queries

Dictionary

All queries related to the EDM dictionary entities. Those queries that directly expose the data to any authenticated user. There currently is no scope, so all the dictionary data is shared to every user. The data is Read-Only.

The queries follow the same format :

  • queryName : the name of the entity (eg: concepts)
  • where clause allowing filtering
  • projection possible across dictionary entities only

The following is a complete list of all exposed entities, with the 'where' clause type and 'return' type :

Query where clause Result
alarmConcepts EMCP_AlarmConceptFilterInput EMCP_AlarmConcept
alarmMappings EMCP_AlarmMappingFilterInput EMCP_AlarmMapping
alarmPropertyLinks EMCP_AlarmPropertyLinkFilterInput EMCP_AlarmPropertyLink
alarmEventConceptCategories EMCP_AlarmEventConceptCategoryFilterInput EMCP_AlarmEventConceptCategory
alarmEventConceptCategoryModuleMappings EMCP_AlarmEventConceptCategoryModuleMappingFilterInput EMCP_AlarmEventConceptCategoryModuleMapping
alarmEventConceptTypes EMCP_AlarmEventConceptTypeFilterInput EMCP_AlarmEventConceptType
concepts EMCP_ConceptFilterInput EMCP_Concept
properties EMCP_PropertyFilterInput EMCP_Property
enumDescriptions EMCP_EnumDescriptionFilterInput EMCP_EnumDescription
toponodes EMCP_TopoNodeFilterInput EMCP_TopoNode
topologies EMCP_TopologyFilterInput EMCP_Topology
packages EMCP_PackageFilterInput EMCP_Package
tags EMCP_TagFilterInput EMCP_Tag
standards EMCP_StandardFilterInput EMCP_Standard
standardDescriptions EMCP_StandardDescriptionFilterInput EMCP_StandardDescription
propertyLinks EMCP_PropertyLinkFilterInput EMCP_PropertyLink
nodeInfos EMCP_NodeInfoFilterInput EMCP_NodeInfo
nodeInfoLayouts EMCP_NodeInfoLayoutFilterInput EMCP_NodeInfoLayout
conceptMappings EMCP_ConceptMappingFilterInput EMCP_ConceptMapping
conceptTypeMappings EMCP_ConceptTypeMappingFilterInput EMCP_ConceptTypeMapping
eventConcepts EMCP_EventConceptFilterInput EMCP_EventConcept
eventMappings EMCP_EventMappingFilterInput EMCP_EventMapping
eventPropertyLinks EMCP_EventPropertyLinkFilterInput EMCP_EventPropertyLink
measures EMCP_MeasureFilterInput EMCP_Measure
measureMappings EMCP_MeasureMappingFilterInput EMCP_MeasureMapping
mValueMappings EMCP_MValueMappingFilterInput EMCP_MValueMapping
businessQuantities EMCP_BusinessQuantityFilterInput EMCP_BusinessQuantity
businessQuantityPriorities EMCP_BusinessQuantityPriorityFilterInput EMCP_BusinessQuantityPriority
phaseDescriptions EMCP_PhaseDescriptionFilterInput EMCP_PhaseDescription
units EMCP_UnitFilterInput EMCP_Unit
tableGadgets EMCP_TableGadgetFilterInput EMCP_TableGadget
tableGadgetItems EMCP_TableGadgetItemFilterInput EMCP_TableGadgetItem
tableGadgetMappings EMCP_TableGadgetMappingFilterInput EMCP_TableGadgetMapping

Examples

GetConceptFromUrn

query MyQuery {

  concepts(where:{urn:{eq:"urn:edm-se:em:core:pc:load"}}) {

    id

    conceptKind

    urn

    label

  }

}

{

  "data": {

    "concepts": [

      {

        "id": 3836,

        "conceptKind": "LOAD",

        "urn": "urn:edm-se:em:core:pc:load",

        "label": "Load"

      }

    ]

  }

}

GetPropertyFromConceptUrn

query MyQuery {

  propertyLinks(where: {concept: {urn: {eq: "urn:edm-se:em:core:pc:load"}}}) {

    conceptId

    property {

      id

      label

      urn

    }

  }

}

{

  "data": {

    "propertyLinks": [

      {

        "conceptId": 3836,

        "property": {

          "id": 7,

          "label": "brand",

          "urn": "urn:edm-se:em:core:pr:brand"

        }

      },

      ...

      {

        "conceptId": 3836,

        "property": {

          "id": 945,

          "label": "Zoom Level",

          "urn": "urn:edm-se:em:core:pr:zoom_level"

        }

      }

    ]

  }

}

appContext

This query retrieves the full appContext (ToponodeContext) for a thing

Arguments

  • thingId : the ID of the thing for the appContext
  • includeCurrentThing : an optional boolean indicating whether the thing itself should be returned, or just the nodes above it. If not specified, the value is false.

Behavior

Return the appContext for a thing. Examples of appContext :

  • For a tenant: the appContext is empty
  • For a region: the appContext contains the tenant
  • For a site: the appContext contains the tenant, and a region if there is one
  • For a toponode thing: the parents of a thing, including the tenant and all the toponodes
  • For a device: the parents of a thing, including the tenant and all the toponodes

Deprecation notice

The following fields are deprecated and should not be used anymore. The default value is null:

  • Name
  • Label
  • Value

They will be removed in a future release

Examples

appContext for a site below a region

query getAppContext {

  __typename

  appContext(thingId: 87301) {

    id

    type

    urn

  }

}

{

  "data": {

    "__typename": "Query",

    "appContext": [

      {

        "id": 87293,

        "type": "TENANT",

        "urn": "urn:edm-se:em:core:pr:tenant"

      },

      {

        "id": 87295,

        "type": "ID",

        "urn": "urn:edm-se:em:core:pr:region"

      }

    ]

  }

}

slot

The slot query is designed to return a paginated view of the slots

Arguments

  • skip & take : integers to paginate the results; take is the number of results to return, skip is the number of results to skip - optional
  • where : type EMCP_SlotFilterInput : this allows advanced filtering capabilities - optional
  • order : type [EMCP_SlotSortInput!] : this allows sorting capabilities - optional

Behavior

Returns the slots (and allows projection to other entities) accessible by any current user

Examples

Gets all the slots from one thing

query slots($where: EMCP_SlotFilterInput) {

  slots(where: $where) {

    items {

      uuid

      handle

      thingId

    }

  }

}

{

  "where": {

    "thingId": {

      "eq": 263156

    }

  }

}

{

  "data": {

    "slots": {

      "items": [

        {

          "uuid": "9c26689c3a3a4712b2fc15b16d641fa3",

          "handle": "ION:0c22f8a1-3427-4629-8edf-efef906927fe",

          "thingId": 263156

        },

        {

          "uuid": "a15177bd452b40b2908b97a413569490",

          "handle": "ION:6b8e817b-c010-41c7-8426-5ffd4d0ca003",

          "thingId": 263156

        },

        {

          "uuid": "aeebf20851a04122b0fad4d9542364ad",

          "handle": "ION:e49dcddd-ef10-4178-a643-0c08d27eeed4",

          "thingId": 263156

        }

      ]

    }

  }

}

thing

The thing query is designed to return a paginated view of things

Arguments

  • appContext : an Array of EMCP_TopoNodeContextInput to filter the results by using the topology - optional
  • skip & take : integers to paginate the results; take is the number of results to return, skip is the number of results to skip - optional
  • includeAllParents : Boolean (defaults to false) adds the parent of the thing (from the appContext) if the appContext is used - optional
  • includeLeafDevice : Boolean (defaults to false) adds the leaf device to the results - optional
  • where : type EMCP_ThingFilterInput : allows the advanced filtering capabilities - optional
  • order : type [EMCP_ThingSortInput!] : allows the sorting capability - optional

Behavior

Return things (and allows projection to other entities) accessible by any current user

Examples

Retrieves all things of a single type

query getThingByConcept($appContext: [EMCP_TopoNodeContextInput], $conceptUrn:String) {

  things(appContext: $appContext, where: {concept: {urn: {eq: $conceptUrn}}}) {

    items {

      id

      name

      label

      pvalues(where: {or: [{pfval: {neq: null}}, {psval: {neq: null}}, {pival: {neq: null}}]}) {

        property {

          label

        }

        pfval

        pival

        psval

      }

    }

  }

}

{

  "appContext":[

    {"id":<TENANTID>,"type":"TENANT","urn":"urn:edm-se:em:core:pr:tenant"}

  ],

  "conceptUrn": "<conceptURN>"

}

{

  "data": {

    "things": {

      "items": [

        {

          "id": 87295,

          "name": "Canada",

          "label": "Canada",

          "pvalues": [

            {

              "property": {

                "label": "Criticality"

              },

              "pfval": null,

              "pival": 1099,

              "psval": null

            },

            {

              "property": {

                "label": "description"

              },

              "pfval": null,

              "pival": null,

              "psval": ""

            }

          ]

        },

        {

          "id": 88040,

          "name": "Switzerland",

          "label": "Switzerland",

          "pvalues": [

            {

              "property": {

                "label": "Criticality"

              },

              "pfval": null,

              "pival": 1098,

              "psval": null

            }

          ]

        }

      ]

    }

  }

}

Retrieves things associated to a particular gateway

query getThingByParent($parentId: Int) {

  things(where: {pvalues: {some: {pival: {eq: $parentId}}}}) {

    items {

      id

      name

      label

      pvalues(where: {or: [{pfval: {neq: null}}, {psval: {neq: null}}, {pival: {neq: null}}]}) {

        property {

          label

        }

        pfval

        pival

        psval

      }

    }

  }

}

{

  "parentId": 87351

}

{

  "data": {

    "things": {

      "items": [

        {

          "id": 87352,

          "name": "c5e7c94d-598a-464e-9df2-b838b0d9a439",

          "label": "Keating.Elevator",

          "pvalues": [

            {

              "property": {

                "label": "Zoom Level"

              },

              "pfval": null,

              "pival": 10,

              "psval": null

            },

            {

              "property": {

                "label": "Latitude"

              },

              "pfval": 45.498681,

              "pival": null,

              "psval": null

            },

            {

              "property": {

                "label": "Gateway"

              },

              "pfval": null,

              "pival": 87351,

              "psval": null

            },

            {

              "property": {

                "label": "is enabled"

              },

              "pfval": null,

              "pival": 1,

              "psval": null

            },

            {

              "property": {

                "label": "Site"

              },

              "pfval": null,

              "pival": 87297,

              "psval": null

            },

            {

              "property": {

                "label": "Criticality"

              },

              "pfval": null,

              "pival": 1098,

              "psval": null

            },

            {

              "property": {

                "label": "family"

              },

              "pfval": null,

              "pival": null,

              "psval": "Elevator"

            },

            {

              "property": {

                "label": "serial number"

              },

              "pfval": null,

              "pival": null,

              "psval": "PC-0708B329-11"

            },

            {

              "property": {

                "label": "model"

              },

              "pfval": null,

              "pival": null,

              "psval": "ComPact NSX"

            },

            {

              "property": {

                "label": "Longitude"

              },

              "pfval": -73.6459,

              "pival": null,

              "psval": null

            },

            {

              "property": {

                "label": "Region"

              },

              "pfval": null,

              "pival": 87295,

              "psval": null

            }

          ]

        },

    ...

    }

  }

tenants

Shortcut on the thing query to get only the list of accessible tenants

Arguments

None

Examples

query getTenants{

  tenants {

    id

    label

  }

}

{

  "data": {

    "tenants": [

      {

        "id": 87275,

        "label": "ACME Inc"

      },

      {

        "id": 87293,

        "label": "Mindt Chocolates"

      },

      {

        "id": 167623,

        "label": "Test Tenant QA"

      }

    ]

  }

}

hierarchy

The hierarchy query is designed to return the Thing data showing the parent-child relationship between them.

Arguments

  • mode: enum (ENERGY, PHYSICAL, COMMUNICATION, BILLING, EQUIPMENT) to specify which type of hierarchy is wanted
  • appContext: an Array of ÈMCP_TopoNodeContextInput to filter the results by topology
  • includeAllParents: Boolean (default set to false) add the parent of the thing (from appContext) if appContext is used - optional
  • where: type EMCP_HierarchyFilterInput: allows advanced filtering capabilities - optional

Behavior

Return things (and allows projection to other entities) accessible by the current user, with 2 or more fields:

  • level:
    • the level from toponode: 0 is for Region, 1 is for Site, empty if it is a product
    • especially for EQUIPMENT mode, the level starting from 0 for the root returned item and is increased for children.
  • parent: the parent thing ID

If the nodelink is set to CONTAINS or EXTENDS it will be considered a Parent/Child relationship for the PHYSICAL|EQUIPMENT hierarchy ie : it will modify the parent extract from toponode and get the one from the nodelink

Hierarchy mode

Physical

  • Kinds of thing returned:
    • Thing with ConceptKind: PRODUCT
      • Exceptions:
        • Gateway
        • LeafNode
    • Thing with ConceptKind: EQUIPEMENT
    • Toponodes (Region, Site, Building, Floor, Area, Space, Production Line, Zone, PanelBoard)
  • How Parent/Child relationship is computed:
    • The Parent will be the lowest level of all the toponodes defined in the thing properties

Energy

  • Kinds of thing returned:
    • Thing with a LOAD linked to them with a NodelinkKind Performs or Measure
    • Toponodes (Region, Site, Building, Floor, Area, Space, Production Line, Zone, PanelBoard)
  • How Parent/Child relationship is computed :
    • For toponodes: The Parent will be the lowest level of all the toponodes, defined in the thing properties
    • For other things: Parent will be the parent of the linked LOAD thing

Communication

  • Kind of thing returned:
    • Thing with ConceptKind: PRODUCT and has the gateway ID property
    • Gateway
    • Toponodes (Region, Site, Building, Floor, Area, Space, Production Line, Zone, PanelBoard)
  • How Parent/Child relationship is computed:
    • For toponodes: The Parent will be the lowest level of all the toponodes defined in the thing properties
    • For gateway: The Parent will be the lowest level of all the toponodes defined in the thing properties
    • For other PRODUCT: The Parent will be the gateway targeted by the gateway ID property

Billing

  • Kind of thing returned:
    • Toponodes (Region, Site, Building, Floor, Area, Space, Production Line, Zone, PanelBoard)
    • Products with a "bill_run" concept
  • How Parent/Child relationship is computed:
    • The Parent will be the lowest level of all the toponodes defined in the thing properties

Equipment

  • Kinds of thing returned:
    • Toponodes (Region, Site, Building, Floor, Area, Space, Production Line, Zone, PanelBoard)
    • Thing with ConceptKind: PRODUCT
      • Exceptions:
        • Gateway
        • LeafNode
    • Thing with ConceptKind: EQUIPEMENT
    • Thing with Concept equals to equipment indicator (urn:edm-se:em:core:oc:indicator)
  • How Parent/Child relationship is computed:
    • For toponodes, use the thing properties to compute the hierarchy,
    • For products and equipment, use the nodelinks of kind: CONTAINS, EXTENDS,
    • For indicators, use the nodelinks of kind: PERFORMS.

Examples

Get physical hierarchy

query getPhysicalHierarchy($appContext: [EMCP_TopoNodeContextInput]) {

  hierarchy(appContext: $appContext, mode: PHYSICAL) {

    level

    parentId

    thing {

      id

      name

      label

    }

  }

}

 {

  "appContext":[

    {"id":87293,"type":"TENANT","urn":"urn:edm-se:em:core:pr:tenant"}

  ]

}

{

  "data": {

    "hierarchy": [

      {

        "level": 0,

        "parentId": null,

        "thing": {

          "id": 87293,

          "name": "243f127d-9b73-4cc0-a656-ceee67c79d0d",

          "label": "Mindt Chocolates"

        }

      },

      {

        "level": 1,

        "parentId": 87293,

        "thing": {

          "id": 87295,

          "name": "Canada",

          "label": "Canada"

        }

      },

      {

        "level": 2,

        "parentId": 87295,

        "thing": {

          "id": 87297,

          "name": "73f2b653-5e40-401e-8399-34e10149ad59",

          "label": "Montréal Factory"

        }

      },

      {

        "level": 2,

        "parentId": 87295,

        "thing": {

          "id": 87299,

          "name": "Québec City Factory",

          "label": "Québec City Factory"

        }

      },

      ...

    ]

  }

}  

Get physical hierarchy with equipment

Consider the following topology:

  • Building: Test Building 4
    • Device: Test Gateway 2
      • Panel: Test Panel 3
      • Device: ElectricDevice 1
      • Device: Test Temp Sensor1
      • Device: Test Temp Sensor2
    • Equipment Column 1
      • nodelink CONTAINS Equipment CircuitBreaker
    • Equipment CircuitBreaker 1
      • nodelink CONTAINS ElectricDevice 1
      • nodelink EXTENDS Equipment Extension
      • nodelink PERFORMS Indicator Temperature 1
    • Equipment ExtensionThermalMonitoring 1
      • nodelink PERFORMS Test Temp Sensor1
    • Indicator Temperature 1
      • nodelink PERFORMS Test Temp Sensor2

When the “EQUIPMENT” filter is used Then, the following hiearchy will be returned:

  • Building: Test Building 4
    • Indicator Temperature 1
    • Equipment Column 1
      • Equipment CircuitBreaker 1
        • ElectricDevice 1
        • Equipment ExtensionThermalMonitoring 1
    • Test Panel 3
      • TempSensor 1
      • TempSensor 2
query getPhysicalHierarchy($appContext: [EMCP_TopoNodeContextInput]) {

  hierarchy(appContext: $appContext, mode: PHYSICAL) {

    level

    parentId

    thing {

      id

      name

      label

    }

  }

}

 {

  "appContext":[

    {"id":21,"type":"TENANT","urn":"urn:edm-se:em:core:pr:tenant"},

    {"id":182,"type":"ID","urn":"urn:edm-se:em:core:pr:region"},

    {"id":184,"type":"ID","urn":"urn:edm-se:em:core:pr:site"}

  ]

}

[

  {

    "Level": 0,

    "Thing": {

      "ConceptId": 0,

      "CreateDate": "0001-01-01T00:00:00+00:00",

      "Id": 21,

      "Label": "Mindt Chocolates",

      "UpdateDate": "0001-01-01T00:00:00+00:00"

    }

  },

  {

    "Level": 1,

    "ParentId": 21,

    "Thing": {

      "ConceptId": 0,

      "CreateDate": "0001-01-01T00:00:00+00:00",

      "Id": 182,

      "Label": "Test Region",

      "UpdateDate": "0001-01-01T00:00:00+00:00"

    }

  },

  {

    "Level": 2,

    "ParentId": 182,

    "Thing": {

      "ConceptId": 0,

      "CreateDate": "0001-01-01T00:00:00+00:00",

      "Id": 184,

      "Label": "Test Site",

      "UpdateDate": "0001-01-01T00:00:00+00:00"

    }

  },

  {

    "Level": 3,

    "ParentId": 184,

    "Thing": {

      "ConceptId": 0,

      "CreateDate": "0001-01-01T00:00:00+00:00",

      "Id": 186,

      "Label": "Test Building 1",

      "UpdateDate": "0001-01-01T00:00:00+00:00"

    }

  },

  {

    "Level": 3,

    "ParentId": 184,

    "Thing": {

      "ConceptId": 0,

      "CreateDate": "0001-01-01T00:00:00+00:00",

      "Id": 188,

      "Label": "Test Building 2",

      "UpdateDate": "0001-01-01T00:00:00+00:00"

    }

  }

] 

assetInfo

The asset info query is used when a client is looking for an asset or gateway before adding it to EMCP.

Arguments

  • appContext: an array of EMCP_TopoNodeContextInput to filter the result by topology - required
  • type: enum (ASSET, B_PAS, SITE_SERVER) to specify the kind of assets the client is expecting, it's the only way to determine the correct kind of gateway - required
  • commercialReference: string to specify the commercial reference - optional
  • serialNumber: string to specify the serial number - required

Behavior

The assetInfo query looks up and returns the list of assets based on the their commissioned status.

Commissioned assets

When the asset(s) are already commissioned on EMCP, the query will return only the accessible asset(s) via the commissionedAssets field.

Uncommissioned assets

When the asset is not commissioned yet, an internal lookup logic is applied, which is dependant on the type of the asset.

Types of ASSETs

When the serialNumber or the serialNumber + commercialReference are valid references, the query returns:

  • the asset is part of uncommissionedAssets with the basic information.

  • the topology from Cloud Commissioning (if one exists) in the hierarchy is part of uncommissionedAssets.

:::note The query returns an empty array when the device is not found or is inaccessible. :::

Type B_PAS

When a device with the given serial number is available in ETP, the query returns:

  • the asset is part of uncommissionedAssets with basic information retrieved from ETP, and from the commercial reference

  • the topology from Cloud Commissioning (if one exists) in the hierarchy part of uncommissionedAssets

:::note The query returns NOT_FOUND when a device is not found. The query returns NOT_ACCESSIBLE when a device has already been associated. :::

Type SITE_SERVER

When a site server with the given serial number is available on Power Solution APIs, the query returns:

  • the asset is part of uncommissionedAssets with the basic information retrieved from the topology
  • the topology in the hierarchy is part of uncommissionedAssets

:::note The query returns NOT_FOUND when a device is not found. :::

:::caution The fields asset and basicAsset are now deprecated, please use the new fields called commissionedAssets and uncommissionedAssets. :::

Examples

Asset info query

query GetAssetInfo(

  $appContext: [EMCP_TopoNodeContextInput]!

  $serialNumber: String!

  $commercialReference: String

  $type: EMCP_AssetType!

) {

  assetInfo(

    appContext: $appContext

    type: $type

    serialNumber: $serialNumber

    commercialReference: $commercialReference

  ) {

    commissionedAssets {

      id

      handle

      tenantId

      conceptId

      label

      name

      concept {

        id

        name

        label

      }

    }

    uncommissionedAssets {

      asset {

        label

        id

        handle

        conceptUrn

        properties {

          encoding

          floatValue

          integerValue

          stringValue

          urn

        }

      }

      hierarchy {

        type

        id

        label

        panelId

        gatewayId

      }

    }

  }

}

{

  "appContext": [{"id": <TENANTID>, "type": "TENANT", "urn": "urn:edm-se:em:core:pr:tenant"}],

  "serialNumber": "SN1023456",

  "type": "ASSET"

}

Asset found in DB

{

  "data": {

    "assetInfo": {

      "commissionedAssets": [{

        "id": 156996,

        "handle": "f2f7b215-1e13-4cee-b9eb-b854093849bf",

        "tenantId": 87275,

        "conceptId": 3530,

        "label": "My PowerHeatTag",

        "name": "8c4418e6-5c61-40f2-a9dc-023f88aa9add",

        "concept": {

          "id": 3530,

          "name": "sensor",

          "label": "sensor"

        }

      }],

      "uncommissionedAssets": []

    }

  }

}

Asset not found in DB

{

  "data": {

    "assetInfo": {

      "commissionedAssets": [],

      "uncommissionedAssets":  [{

        "asset": {

          "label": null,

          "id": 0,

          "handle": null,

          "conceptUrn": "urn:edm-se:em:core:pc:sensor",

          "properties": [

            {

              "encoding": "STRING",

              "floatValue": null,

              "integerValue": null,

              "stringValue": "Htag20203441C0010AAA",

              "urn": "urn:edm-se:em:core:pr:serial_number"

            },

            ...

          ]

        },

        "hierarchy": null

      }]

    }

  }

}

Gateway with hierarchy

{

  "data": {

    "assetInfo": {

      "commissionedAssets": [],

      "uncommissionedAssets":  [{

        "asset": {

          "label": "urn:dev:ops:112143510002",

          "id": 2,

          "handle": "CC:FKCC44d65307-ad6a-4d05-af86-dd78f7e8949c:FKCC44d65307-ad6a-4d05-af86-dd78f7e89400",

          "conceptUrn": "urn:edm-se:em:core:pc:gateway",

          "properties": [

            {

              "encoding": "STRING",

              "floatValue": null,

              "integerValue": null,

              "stringValue": "112143510002",

              "urn": "urn:edm-se:em:core:pr:serial_number"

            },

            {

              "encoding": "STRING",

              "floatValue": null,

              "integerValue": null,

              "stringValue": "PAS600T",

              "urn": "urn:edm-se:em:core:pr:commercial_reference"

            },

            {

              "encoding": "STRING",

              "floatValue": null,

              "integerValue": null,

              "stringValue": "B-PAS",

              "urn": "urn:edm-se:em:core:pr:range"

            }

          ]

        },

        "hierarchy": [

          {

            "type": "PANEL",

            "id": 1,

            "label": "Panel Demo",

            "panelId": null,

            "gatewayId": null

          },

          {

            "type": "GATEWAY",

            "id": 2,

            "label": "B-PAS Panel Demo",

            "panelId": 1,

            "gatewayId": null

          },

          {

            "type": "DEVICE",

            "id": 3,

            "label": "PowerTag PT00017",

            "panelId": 1,

            "gatewayId": 2

          },

          {

            "type": "DEVICE",

            "id": 4,

            "label": "PowerTag PT00029",

            "panelId": 1,

            "gatewayId": 2

          },

          {

            "type": "DEVICE",

            "id": 5,

            "label": "SM6 3",

            "panelId": 1,

            "gatewayId": 2

          },

          {

            "type": "DEVICE",

            "id": 6,

            "label": "ASCO 7000 4",

            "panelId": 1,

            "gatewayId": 2

          },

          {

            "type": "DEVICE",

            "id": 7,

            "label": "Powertag PT00026",

            "panelId": 1,

            "gatewayId": 2

          }

        ]

      }]

    }

  }

}

alarmInstances

Returns alarm instances by the input parameters, user's assignments, subscriptions, and notification preferences.

Arguments

  • appContext!: the execution context.
  • skip / take: Ints specifying pagination of the data.
  • hierarchyMode: optional hierarchy mode to filter the returned data. Default value PHYSICAL.
  • enableNotificationPreferences: an optional Boolean indicating whether to apply the user's notification preferences filter to the returned data. Default value false.

Behavior

  • If a user has no required permissions to view alarms, the response is an empty array.

  • If a user has no required privileges to access the requested organization topology, the response is an empty array.

  • If there are no alarm instances available to the user via alarm categories, the response is an empty array. This is the basic alarm category available for all registered users. More alarm categories are provided via module subscriptions.

  • If the input parameter enableNotificationPreferences is set to true, the result is filtered by the user's notification preferences. Otherwise, a user's notification preferences are ignored, and the request processing continues to the next stage.

  • If the input parameter appContext is set to null or an empty array and enableNotificationPreferences is set to true, the response will be a BAD_INPUT error.

AlarmPriority Enum consideration and backward compatibility

The AlarmPriority field has been moved from alarmInstance to alarmOccurence, and will be removed later (see Deprecation Section). The same is true for the value GREEN, YELLOW, RED. The behaviour is :

  • AlarmInstance.AlarmPriority
    • NONE, LOW, and GREEN are considered the same
    • YELLOW and MEDIUM are considered the same
    • RED and HIGH are considered the same
  • AlarmOccurence.AlarmPriority
    • NONE
    • LOW and GREEN are considered the same
    • YELLOW and MEDIUM are considered the same
    • RED and HIGH are considered the same

The enum values will differ depending on whether you are on the alarmInstance or alarmOccurence object :

  • alarmInstance : enum value will always be GREEN, YELLOW or RED
  • alarmOccurence : enum value will always be NONE, LOW, MEDIUM or HIGH

Example

The following GraphQL query returns alarm instances for the organization's communication hierarchy.

  • scoped by the user's assignments, subscriptions, and notification preferences.
  • projects alarm instance fields, concept and their occurrences.
  • filters to a one-day time-range.
  • sorts in the descending order.

Query

query alarmInstances(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $hierarchyMode: EMCP_HierarchyMode

  $enableNotificationPreferences: Boolean

  $startTime: DateTime!

  $endTime: DateTime!

) {

  alarmInstances(

    appContext: $appContext

    hierarchyMode: $hierarchyMode

    enableNotificationPreferences: $enableNotificationPreferences

    where: {

      and: [

        { alarmOccurrences: { some: { startTime: { gte: $startTime } } } }

        { alarmOccurrences: { some: { endTime: { lte: $endTime } } } }

      ]

    }

    order: { lastUpdated: DESC }

  ) {

    totalCount

    items {

      id

      lastUpdated

      tsMath

      thingId

      alarmModel

      alarmState

      alarmPriority

      alarmFamily

      alarmControl

      alarmConcept {

        alarmEventConceptCategory {

          name

        }

      }

      alarmOccurrences(

        where: {

          and: [

            { startTime: { gte: $startTime } }

            { endTime: { lte: $endTime } }

          ]

        }

      ) {

        id

        startTime

        endTime

      }

    }

  }

}

Variables

{

  "appContext": [

    {

      "id": 87293,

      "label": "Mindt Chocolates",

      "urn": "urn:edm-se:em:core:pr:tenant",

      "type": "TENANT"

    }

  ],

  "hierarchyMode": "COMMUNICATION",

  "enableNotificationPreferences": true,

  "startTime": "2022-01-01T00:00:00.000Z",

  "endTime": "2022-01-02T00:00:00.000Z"

}

Result

{

  "data": {

    "alarmInstances": {

      "totalCount": 75,

      "items": [

        {

          "id": 14426,

          "lastUpdated": "2022-02-21T22:01:54.966Z",

          "tsMath": "INPUT_BASED",

          "thingId": 87354,

          "alarmModel": "ALM_WITH_ACK",

          "alarmState": "UNACK",

          "alarmPriority": "YELLOW",

          "alarmFamily": null,

          "alarmControl": "NA",

          "alarmConcept": {

            "alarmEventConceptCategory": {

              "name": "Diagnostics"

            }

          },

          "alarmOccurrences": [

            {

              "id": 91923,

              "startTime": "2022-01-01T07:23:23.617Z",

              "endTime": "2022-01-01T07:34:30.213Z"

            },

            {

              "id": 91954,

              "startTime": "2022-01-01T17:34:33.724Z",

              "endTime": "2022-01-01T17:39:52.403Z"

            }

          ]

        },

        ...

      ]

  }

}

alarmOccurrences

Returns alarm occurrences by the input parameters, user's assignments, subscriptions and notification preferences.

Arguments

  • appContext!: the execution context.
  • skip / take : Ints specifying pagination of the data.
  • hierarchyMode: optional hierarchy mode to filter the returned data. Default value PHYSICAL.
  • enableNotificationPreferences : an optional Boolean indicating whether to apply the user's notification preferences filter to the returned data. Default value false.

Behavior

  • If user has no required permissions to view alarms, the response is an empty array.

  • If the user has no required privileges to access the requested organization topology, the response is an empty array.

  • If input parameter enableNotificationPreferences set to true, the result is filtered by the user's notification preferences. Otherwise, user's notification preferences are ignored.

  • If input parameter appContext is null or an empty array and enableNotificationPreferences set to true, the response is BAD_INPUT error.

AlarmPriority Enum consideration and backward compatibility

AlarmPriority field has moved from alarmInstance to alarmOccurence, and will be removed later (see Deprecation Section), same for value GREEN, YELLOW, RED. The behaviour is :

  • AlarmInstance.AlarmPriority
    • NONE, LOW, GREEN are considered the same
    • YELLOW and MEDIUM are considered the same
    • RED and HIGH are considered the same
  • AlarmOccurence.AlarmPriority
    • NONE
    • LOW, GREEN are considered the same
    • YELLOW and MEDIUM are considered the same
    • RED and HIGH are considered the same

The enum values will differ depending on whether you are on the alarmInstance or alarmOccurence object :

  • alarmInstance : enum value will always be GREEN, YELLOW, RED
  • alarmOccurence : enum value will always be NONE, LOW, MEDIUM, HIGH

Example

The following GraphQL query returns alarm occurrences for the organization's communication hierarchy.

  • scoped by user's assignments, subscriptions and notification preferences.
  • projects alarm occurrence properties and their instances.
  • filters to a one-day time-range.
  • sorts in the descending order.

Query

query alarmOccurrences(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $hierarchyMode: EMCP_HierarchyMode

  $enableNotificationPreferences: Boolean

  $startTime: DateTime!

  $endTime: DateTime!

) {

  alarmOccurrences(

    appContext: $appContext

    hierarchyMode: $hierarchyMode

    enableNotificationPreferences: $enableNotificationPreferences

    where: {

      and: [

        { startTime: { gte: $startTime } }, 

        { endTime: { lte: $endTime } }

      ]

    }

    order: { lastUpdated: DESC }

  ) {

    totalCount

    items {

      id

      alarmState

      lastUpdated

      startTime

      endTime

      measures

      alarmPriority

      alarmOccurrencePValues {

        pfval

        psval

        pival

        pTsVal

        property {

          name

          urn

          encodingType

        }

      }

      alarmInstance {

        id

        lastUpdated

        tsMath

        thingId

        alarmModel

        alarmState

        alarmPriority

        alarmFamily

        alarmControl

      }

    }

  }

}

Variables

{

  "appContext": [

    {

      "id": 87293,

      "label": "Mindt Chocolates",

      "urn": "urn:edm-se:em:core:pr:tenant",

      "type": "TENANT"

    }

  ],

  "hierarchyMode": "COMMUNICATION",

  "enableNotificationPreferences": true,

  "startTime": "2022-01-01T00:00:00.000Z",

  "endTime": "2022-01-02T00:00:00.000Z"

}

Result

{

  "data": {

    "alarmOccurrences": {

      "totalCount": 59,

      "items": [

        {

          "id": 91896,

          "alarmState": "RTNUN",

          "lastUpdated": "2022-01-01T00:31:46.016Z",

          "startTime": "2022-01-01T00:31:05.264Z",

          "endTime": "2022-01-01T00:31:46.016Z",

          "measures": null,

          "alarmOccurrencePValues": [

            {

              "pfval": null,

              "psval": "61.5% Nominal Voltage",

              "pival": null,

              "pTsVal": null,

              "property": {

                "name": "detail text",

                "urn": "urn:edm-se:em:core:pr:detail_text",

                "encodingType": "STRING"

              }

            },

            {

              "pfval": null,

              "psval": null,

              "pival": null,

              "pTsVal": "2020-07-08T19:00:45.000Z",

              "property": {

                "name": "PQ end time",

                "urn": "urn:edm-se:em:core:pr:pq_end_time",

                "encodingType": "TIMESTAMP"

              }

            },

            {

              "pfval": null,

              "psval": null,

              "pival": 1,

              "pTsVal": null,

              "property": {

                "name": "disturbance direction",

                "urn": "urn:edm-se:em:core:pr:disturbance_direction",

                "encodingType": "INTEGER"

              }

            },

            {

              "pfval": 1,

              "psval": null,

              "pival": null,

              "pTsVal": null,

              "property": {

                "name": "Disturbance Confidence",

                "urn": "urn:edm-se:em:core:pr:disturbance_confidence",

                "encodingType": "FLOAT"

              }

            }

          ],

          "alarmInstance": {

            "id": 14544,

            "lastUpdated": "2022-02-21T12:47:00.784Z",

            "tsMath": "INPUT_BASED",

            "thingId": 87386,

            "alarmModel": "ALM_WITH_ACK",

            "alarmState": "RTNUN",

            "alarmPriority": "GREEN",

            "alarmFamily": null,

            "alarmControl": "NA"

          }

        },

        ...

      ]

    }

  }

}

alarmOccurrencesSummary

Returns alarm occurrence counts, binned by time range and interval, and by active/inactive and acknowledged/unacknowledged flags.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • hierarchyMode : The kind of hierarchy to aggregate up EMCP_HierarchyMode.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • timeZone! : a String to indicate the IANA time zone the data should be aggregated in.
  • interval! : an EMCP_AggregationInterval indicating the temporal grouping.
  • alarmPriorityFilter : an Array of EMCP_AlarmPriorityType to return data for. If null, no filter is applied.
  • alarmStateFilter : an Array of EMCP_AlarmStateType to return data for. If null, no filter is applied.
  • enableNotificationPreferences : a Boolean indicating whether to apply the user's notification filters to the returned data.

Example

Query

query(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $enableNotificationPreferences: Boolean = false

  $interval: EMCP_AggregationInterval!

) {

  alarmOccurrencesSummary(

    appContext: $appContext

    enableNotificationPreferences: $enableNotificationPreferences

    startTime: $startTime

    endTime: $endTime

    timeZone: $timeZone

    interval: $interval

  ) {

    totalCount

    alarmPrioritySummary {

      details {

        acknowledgedCount

        activeCount

        inactiveCount

        unacknowledgedCount

      }

    }

  }

}

Variables

{

  "appContext": [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "ID", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "ID", "id": 87297, "urn": "urn:edm-se:em:core:pr:site" }

  ],

  "enableNotificationPreferences": false,

  "interval": "MONTH",

  "startTime": "2021-08-06T00:00:00-04:00",

  "endTime": "2021-12-08T12:00:00-05:00",

  "timeZone": "America/Vancouver"

}

Result

{

  "data": {

    "alarmOccurrencesSummary": {

      "totalCount": 5060,

      "alarmPrioritySummary": [

        {

          "details": {

            "acknowledgedCount": 1175,

            "activeCount": 5,

            "inactiveCount": 2125,

            "unacknowledgedCount": 955

          }

        },

        {

          "details": {

            "acknowledgedCount": 620,

            "activeCount": 0,

            "inactiveCount": 1332,

            "unacknowledgedCount": 712

          }

        },

        {

          "details": {

            "acknowledgedCount": 764,

            "activeCount": 0,

            "inactiveCount": 1598,

            "unacknowledgedCount": 834

          }

        }

      ]

    }

  }

}

binnedAlarmOccurrences

Returns alarm occurrence priority counts binned by time range and interval.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • hierarchyMode : The kind of hierarchy to aggregate up EMCP_HierarchyMode.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • timeZone! : a String to indicate the IANA time zone the data should be aggregated in.
  • interval! : an EMCP_AggregationInterval indicating the temporal grouping.
  • alarmPriorityFilter : an Array of EMCP_AlarmPriorityType to return data for. If null, no filter is applied.
  • alarmStateFilter : an Array of EMCP_AlarmStateType to return data for. If null, no filter is applied.
  • enableNotificationPreferences : a Boolean indicating whether to apply the user's notification filters to the returned data.

Example

Query

query (

  $appContext: [EMCP_TopoNodeContextInput!]!

  $interval: EMCP_AggregationInterval!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String

  $enableNotificationPreferences: Boolean = false

) {

  binnedAlarmOccurrences(

    appContext: $appContext

    enableNotificationPreferences: $enableNotificationPreferences

    interval: $interval

    startTime: $startTime

    endTime: $endTime

    timeZone: $timeZone

  ) {

    totalCount

    items {

      startTime

      endTime

      timeZone

      priorityCounts {

        priority

        count

      }

    }

  }

}

Variables

{

  "appContext": [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "ID", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "ID", "id": 87297, "urn": "urn:edm-se:em:core:pr:site" }

  ],

  "enableNotificationPreferences": false,

  "interval": "MONTH",

  "startTime": "2021-08-06T00:00:00-04:00",

  "endTime": "2021-12-08T12:00:00-05:00",

  "timeZone": null

}

Result

{

  "data": {

    "binnedAlarmOccurrences": {

      "totalCount": 5,

      "items": [

        {

          "startTime": "2021-08-01T00:00:00.000-04:00",

          "endTime": "2021-09-01T00:00:00.000-04:00",

          "timeZone": "America/Toronto",

          "priorityCounts": [

            { "priority": "GREEN", "count": 357 },

            { "priority": "YELLOW", "count": 231 },

            { "priority": "RED", "count": 243 }

          ]

        },

        {

          "startTime": "2021-09-01T00:00:00.000-04:00",

          "endTime": "2021-10-01T00:00:00.000-04:00",

          "timeZone": "America/Toronto",

          "priorityCounts": [

            { "priority": "GREEN", "count": 563 },

            { "priority": "YELLOW", "count": 339},

            { "priority": "RED", "count": 399 }

          ]

        },

        {

          "startTime": "2021-10-01T00:00:00.000-04:00",

          "endTime": "2021-11-01T00:00:00.000-04:00",

          "timeZone": "America/Toronto",

          "priorityCounts": [

            { "priority": "GREEN", "count": 554 },

            { "priority": "YELLOW", "count": 359 },

            { "priority": "RED", "count": 407 }

          ]

        },

        {

          "startTime": "2021-11-01T00:00:00.000-04:00",

          "endTime": "2021-12-01T00:00:00.000-05:00",

          "timeZone": "America/Toronto",

          "priorityCounts": [

            { "priority": "GREEN", "count": 625 },

            { "priority": "YELLOW", "count": 315 },

            { "priority": "RED", "count": 370 }

          ]

        },

        {

          "startTime": "2021-12-01T00:00:00.000-05:00",

          "endTime": "2022-01-01T00:00:00.000-05:00",

          "timeZone": "America/Toronto",

          "priorityCounts": [

            { "priority": "GREEN", "count": 536 },

            { "priority": "YELLOW", "count": 319 },

            { "priority": "RED", "count": 393 }

          ]

        }

      ]

    }

  }

}

rankedAlarmOccurrences

Returns a list of alarm counts, ranked from highest count to lowest count. In the case of a tie, the ranking is shared by those items.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • hierarchyMode : The kind of hierarchy to aggregate up EMCP_HierarchyMode.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • alarmPriorityFilter : an Array of EMCP_AlarmPriorityType to return data for. If null, no filter is applied.
  • alarmStateFilter : an Array of EMCP_AlarmStateType to return data for. If null, no filter is applied.
  • enableNotificationPreferences : a Boolean indicating whether to apply the user's notification filters to the returned data.

Example

Query

query (

  $appContext: [EMCP_TopoNodeContextInput!]!

  $startTime: DateTime!

  $endTime: DateTime!

  $enableNotificationPreferences: Boolean = false

  $pageSize: Int = 10

  $offset: Int = 0

) {

  rankedAlarmOccurrences(

    appContext: $appContext

    enableNotificationPreferences: $enableNotificationPreferences

    startTime: $startTime

    endTime: $endTime

    take: $pageSize

    skip: $offset

  ) {

    totalCount

    items {

      ranking

      count

      thingId

      thingLabel

    }

  }

}

Variables

{

  "appContext": [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "ID", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "ID", "id": 87297, "urn": "urn:edm-se:em:core:pr:site" }

  ],

  "enableNotificationPreferences": false,

  "interval": "MONTH",

  "startTime": "2021-08-06T00:00:00-04:00",

  "endTime": "2021-12-08T12:00:00-05:00",

  "timeZone": null

}

Result

{

  "data": {

    "rankedAlarmOccurrences": {

      "totalCount": 2,

      "items": [

        {

          "ranking": 1,

          "count": 4610,

          "thingId": 87303,

          "thingLabel": "Building A"

        },

        {

          "ranking": 2,

          "count": 450,

          "thingId": 87305,

          "thingLabel": "Building B"

        }

      ]

    }

  }

}

events

The event query is designed to return a paginated view of events

Arguments

  • skip & take : Int to navigate into the pagination - optional (default page size : 10, max page size : 50)
  • where : type EMCP_EventFilterInput : allow advanced filtering capabilities - optional
  • order : type array of EMCP_EventSortInput! : allow sorting capabilities - optional

Behaviour

Return events (and capacity to project to others entity) accessible by the current user

Examples

Get all event

query getAllEvent {

  events {

    items {

      id

      eventFamily

      eventType

      handle

      measures

      eventConcept {

        urn

      }

      thing {

        label

      }

    }

  }

}

{}

{

  "data": {

    "events": {

      "items": [

        {

          "id": 120277,

          "eventFamily": "ELECTRICAL",

          "eventType": "UNARY",

          "handle": "ION:904384fe-f75f-4b1d-bcbb-096c6db55264:event:383475",

          "measures": null,

          "eventConcept": {

            "urn": "urn:edm-se:em:core:ev:generic_event"

          },

          "thing": {

            "label": "Keating.Elevator"

          }

        },

        ...

        {

          "id": 120285,

          "eventFamily": "ELECTRICAL",

          "eventType": "UNARY",

          "handle": "ION:904384fe-f75f-4b1d-bcbb-096c6db55264:event:762285",

          "measures": null,

          "eventConcept": {

            "urn": "urn:edm-se:em:core:ev:generic_event"

          },

          "thing": {

            "label": "Keating.Main_7650"

          }

        }

      ]

    }

  }

}

Get thing associated to a gateway

query GetEventByThingId($where: EMCP_EventFilterInput) {

  events(where: $where) {

    items {

      id

      eventFamily

      eventType

      handle

      measures

      eventConcept {

        urn

      }

      thing {

        label

      }

    }

  }

}

{

  "where": {

    "thingId": {

      "eq": 87352

    }

  }

}

{

  "data": {

    "events": {

      "items": [

        {

          "id": 120277,

          "eventFamily": "ELECTRICAL",

          "eventType": "UNARY",

          "handle": "ION:904384fe-f75f-4b1d-bcbb-096c6db55264:event:383475",

          "measures": null,

          "eventConcept": {

            "urn": "urn:edm-se:em:core:ev:generic_event"

          },

          "thing": {

            "label": "Keating.Elevator"

          }

        },

        ...

        {

          "id": 120583,

          "eventFamily": "ELECTRICAL",

          "eventType": "UNARY",

          "handle": "ION:904384fe-f75f-4b1d-bcbb-096c6db55264:event:642988",

          "measures": null,

          "eventConcept": {

            "urn": "urn:edm-se:em:core:ev:generic_event"

          },

          "thing": {

            "label": "Keating.Elevator"

          }

        }

      ]

    }

  }

}

Time Series Queries

AggregatedTimeSeries query

Returns a paginated view of AggregatedTimeSeries data, based on the parameters. The data is aggregated into time "bins" based on the parameters.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • slotUuids! : an Array of Uuid to filter the result.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • timeZone! : a String to indicate the IANA time zone the data should be aggregated into.
  • aggregationInterval! : a EMCP_AggregationInterval indicating the temporal bin size that the data is aggregated into.
  • aggregationDayLightSavingTimeBehavior! : an Aggregationdaylightsavingtimebehaviortype that indicates how the DST transition data is handled, specifically for aggregation values of an HOUR or less.
    • a value of AGGREGATE indicates that when the time "is set back", all data in that time bucket is aggregated together. E.g., if the amount is two hours, say from 1am-2am, there is only one bucket returned.
    • a value of SEPARATE indicates that when the time "is set back", the duplicate local timestamps will be bucketed separately. E.g., if the amount is two hours, say from 1am-2am, there is only one bucket returned.
  • aggregationQualityBehavior : an Aggregationqualitybehaviortype that indicates how to change data quality.
  • Currently this only has one value: INCLUDE
  • normalizationFactor : a NormalizationFactor? indicates that retrieved time-series has to be normalized according to weather data.
    • a value of None, null, or the omission of the parameter will not apply any normalization
    • a value of CDD, will normalize the results by the Cooling Degree Days time-series linked to the sites of the slotUids fetched.
    • a value of HDD, will normalize the results by the Heating Degree Days time-series linked to the sites of the slotUids fetched.
    • a value of CDDHDD, will normalize the results by both Heating and Cooling Degree Days time-series linked to the sites of the slotUids fetched.
  • specialFilter : a SpecialFilter? for fitlering out some specific data.
    • a value of None, null, or the omission of the parameter will not apply any filtering.
    • a value of OPENED_HOURS, will only fetch data when the building or site linked to the slotUuid has a schedule indicating the site is open.
    • a value of CLOSED_HOURS, will only fetch data when the building or site linked to the slotUuid has a schedule indicating the site is closed.

Results

  • The results are returned as interval-starting timestamps. That is, the localTs timestamp is the start of the interval.
  • The results are very raw, and it is up to the caller to know which aggregation value (min, max, avg, count, delta, etc.) to use.

Example - Get Daily-aggregated values for the given slot UUIDs and specified time range in the specified time zone

Query

query exampleQuery (

  $appContext: [EMCP_TopoNodeContextInput!]!

  $slotUuids: [Uuid!]!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $aggregationInterval: EMCP_AggregationInterval!

  $aggregationDayLightSavingTimeBehavior: EMCP_AggregationDayLightSavingTimeBehaviorType!

  ) {

  aggregatedTimeSeries(

    appContext: $appContext

    slotUuids: $slotUuids

    startTime: $startTime

    endTime: $endTime

    timeZone: $timeZone

    aggregationInterval: $aggregationInterval

    aggregationDayLightSavingTimeBehavior: $aggregationDayLightSavingTimeBehavior    

    ) {

    items {

      slotUuid

      localTs

      minValueOnInterval

      maxValueOnInterval

      avgValueOnInterval

      countValueOnInterval      

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" }

  ],

  "slotUuids": ["efa710c4-b0f5-442e-9589-607bfcbacfb1","8f890740-4c00-482f-a4af-cc89f80386b8"],

  "startTime": "2021-11-25Z",

  "endTime": "2021-11-30Z",

  "timeZone": "America/Vancouver",

  "aggregationInterval": "DAY",

  "aggregationDayLightSavingTimeBehavior": "SEPARATE"

}

Results

{

  "data": {

    "aggregatedTimeSeries": {

      "items": [

        {

          "slotUuid": "8f8907404c00482fa4afcc89f80386b8",

          "localTs": "2021-11-24T08:00:00.000Z",

          "minValueOnInterval": 657711002181,

          "maxValueOnInterval": 659541300883,

          "avgValueOnInterval": 658665838549.6562,

          "countValueOnInterval": 32

        },

        [...truncated...]

        {

          "slotUuid": "efa710c4b0f5442e9589607bfcbacfb1",

          "localTs": "2021-11-27T08:00:00.000Z",

          "minValueOnInterval": 97.924193968389,

          "maxValueOnInterval": 145.90156926085,

          "avgValueOnInterval": 122.90787830510253,

          "countValueOnInterval": 96

        }

      ]

    }

  }

}

RawTrendData query

Returns a paginated view of EMCP_BusinessQuantityTimeSeries data, based on the parameters. The data returned as the raw interval data, except it will be aggregated into 1-minute bins if the data is sub-1-minute interval.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • timeZone! : a String to indicate the IANA time zone the data should be aggregated into.
  • businessQuantityNames! : an Array of String indicating the business quantities to get values for.

Results

  • The timeSeriesValues results are returned as interval-ending timestamps. That is, the localTs timestamp is the end of the interval.
  • The value returned is always interval-based -- the value for that time interval -- it is never cumulative.

Example - Get raw values for the given appContext and specified time range

Query

query exampleQuery (

  $appContext: [EMCP_TopoNodeContextInput!]!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $businessQuantityNames: [String!]!

  ) {

  rawTrendData(

    appContext: $appContext

    businessQuantityNames: $businessQuantityNames

    startTime: $startTime

    endTime: $endTime

    timeZone: $timeZone

    ) {

    items {

      businessQuantity { name }

      measure { label unit { symbol } }

      thingContext { type urn id }

      timeSeriesValues { timestamp value }

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "TENANT", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "TENANT", "id": 87297, "urn": "urn:edm-se:em:core:pr:site" },

    { "type": "TENANT", "id": 87354, "urn": "urn:edm-se:em:core:pc:circuit_breaker" }

  ],

  "startTime": "2021-11-25Z",

  "endTime": "2021-11-30Z",

  "timeZone": "America/Vancouver",

  "businessQuantityNames": ["CURRENT_A", "APPARENT_ENERGY"]

}

Results

{

  "data": {

    "rawTrendData": {

      "items": [

        {

          "businessQuantity": {

            "name": "APPARENT_ENERGY"

          },

          "measure": {

            "label": "Apparent energy delivered+received",

            "unit": {

              "symbol": "VAh"

            }

          },

          "thingContext": [

            { "type": "TENANT", "urn": "urn:edm-se:em:core:pr:tenant", "id": 87293 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pr:region", "id": 87295 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pr:site", "id": 87297 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pc:circuit_breaker", "id": 87354 }

          ],

          "timeSeriesValues": [

            { "timestamp": "2021-11-25T00:15:00.000Z", "value": 45770885 },

            { "timestamp": "2021-11-25T00:30:00.000Z", "value": 58992410 },

            [ ... truncated ... ]

            { "timestamp": "2021-11-30T00:00:00.000Z", "value": 133.120089858674 }

          ]

        }

      ]

    }

  }

}

BinnedTrendData query

Returns a paginated view of EMCP_BusinessQuantityBinnedTimeSeries data, based on the parameters.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • timeZone! : a String to indicate the IANA time zone the data should be aggregated into.
  • businessQuantityName! : a String indicating the business quantity to get values for.
  • aggregationInterval! : an EMCP_AggregationInterval indicating the temporal bin size that the data is aggregated into.
  • normalizationFactor : a NormalizationFactor? indicates that retrieved time-series has to be normalized according to weather data.
    • a value of None, null, or the omission of the parameter will not apply any normalization
    • a value of CDD, will normalize the results by the Cooling Degree Days time-series linked to the sites of the slotUids fetched.
    • a value of HDD, will normalize the results by the Heating Degree Days time-series linked to the sites of the slotUids fetched.
    • a value of CDDHDD, will normalize the results by both Heating and Cooling Degree Days time-series linked to the sites of the slotUids fetched.
  • specialFilter : a SpecialFilter? for fitlering out some specific data.
    • a value of None, null, or the omission of the parameter will not apply any filtering.
    • a value of OPENED_HOURS, will only fetch data when the building or site linked to the slotUuid has a schedule indicating the site is open.
    • a value of CLOSED_HOURS, will only fetch data when the building or site linked to the slotUuid has a schedule indicating the site is closed.

Results

  • The timeSeriesValues results' time range are returned with an inclusive startTime and exclusive endTime.
  • The value returned is always interval-based -- the value for that time interval -- it is never cumulative.

Example - Get Monthly-aggregated values for the appContext and specified time range, in the specified time zone, for the given business quantity.

Query

query exampleQuery (

  $appContext: [EMCP_TopoNodeContextInput!]!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $businessQuantityName: String!

  $aggregationInterval: EMCP_AggregationInterval!

  ) {

  binnedTrendData(

    appContext: $appContext

    businessQuantityName: $businessQuantityName

    startTime: $startTime

    endTime: $endTime

    timeZone: $timeZone

    aggregationInterval: $aggregationInterval

    ) {

    items {

      businessQuantity { name }

      measure { label unit { symbol } }

      thingContext { type urn id }

      timeSeriesValues { startTime endTime value }

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "TENANT", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "TENANT", "id": 87297, "urn": "urn:edm-se:em:core:pr:site" },

    { "type": "TENANT", "id": 87354, "urn": "urn:edm-se:em:core:pc:circuit_breaker" }

  ],

  "startTime": "2021-11-25Z",

  "endTime": "2021-11-30Z",

  "timeZone": "America/Vancouver",

  "businessQuantityName": "APPARENT_ENERGY",

  "aggregationInterval": "MONTH"

}

Results

{

  "data": {

    "binnedTrendData": {

      "items": [

        {

          "businessQuantity": {

            "name": "APPARENT_ENERGY"

          },

          "measure": {

            "label": "Apparent energy delivered+received",

            "unit": {

              "symbol": "VAh"

            }

          },

          "thingContext": [

            { "type": "TENANT", "urn": "urn:edm-se:em:core:pr:tenant", "id": 87293 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pr:region", "id": 87295 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pr:site", "id": 87297 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pc:circuit_breaker", "id": 87354 }

          ],

          "timeSeriesValues": [

            {

              "startTime": "2021-11-01T00:00:00.000-07:00",

              "endTime": "2021-12-01T00:00:00.000-08:00",

              "value": 161833741052

            }

          ]

        }

      ]

    }

  }

}

BinnedUsageTrendData query

Returns a paginated view of EMCP_BusinessQuantityBinnedUsageTimeSeries data, based on the parameters. There is no way to filter the usages -- it will always return all usages, including Total Usage.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • timeZone! : a String to indicate the IANA time zone the data should be aggregated into.
  • businessQuantityName! : a String indicating the business quantity to get values for.
  • aggregationInterval! : a EMCP_AggregationInterval indicating the temporal bin size that the data is aggregated into.
  • normalizationFactor : a NormalizationFactor? indicates that retrieved time-series has to be normalized according to weather data.
    • a value of None, null, or the omission of the parameter will not apply any normalization
    • a value of CDD, will normalize the results by the Cooling Degree Days time-series linked to the sites of the slotUids fetched.
    • a value of HDD, will normalize the results by the Heating Degree Days time-series linked to the sites of the slotUids fetched.
    • a value of CDDHDD, will normalize the results by both Heating and Cooling Degree Days time-series linked to the sites of the slotUids fetched.
  • specialFilter : a SpecialFilter? for fitlering out some specific data.
    • a value of None, null, or the omission of the parameter will not apply any filtering.
    • a value of OPENED_HOURS, will only fetch data when the building or site linked to the slotUuid has a schedule indicating the site is open.
    • a value of CLOSED_HOURS, will only fetch data when the building or site linked to the slotUuid has a schedule indicating the site is closed.

Results

  • The timeSeriesValues results' time range are returned with an inclusive startTime and exclusive endTime.
  • The value returned is always interval-based -- the value for that time interval -- it is never cumulative.
  • The results are based on the configuration of the Energy hierarchy.
  • Calculation methodology can be found on this page on the Team 2 Wiki.

Example - Get Monthly-aggregated values for the appContext and specified time range in the specified time zone

Query

query exampleQuery (

  $appContext: [EMCP_TopoNodeContextInput!]!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $businessQuantityName: String!

  $aggregationInterval: EMCP_AggregationInterval!

  ) {

  binnedUsageTrendData(

    appContext: $appContext

    businessQuantityName: $businessQuantityName

    startTime: $startTime

    endTime: $endTime

    timeZone: $timeZone

    aggregationInterval: $aggregationInterval

    ) {

    items {

      usageId

      businessQuantity { name }

      measure { label unit { symbol } }

      thingContext { type urn id }

      timeSeriesValues { startTime endTime value }

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "TENANT", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "TENANT", "id": 87297, "urn": "urn:edm-se:em:core:pr:site" },

    { "type": "TENANT", "id": 87354, "urn": "urn:edm-se:em:core:pc:circuit_breaker" }

  ],

  "startTime": "2021-11-25Z",

  "endTime": "2021-11-30Z",

  "timeZone": "America/Vancouver",

  "businessQuantityName": "APPARENT_ENERGY",

  "aggregationInterval": "MONTH"

}

Results

{

  "data": {

    "binnedTrendData": {

      "items": [

        {

          "usageId": 255,

          "businessQuantity": {

            "name": "APPARENT_ENERGY"

          },

          "measure": {

            "label": "Apparent energy delivered+received",

            "unit": {

              "symbol": "VAh"

            }

          },

          "thingContext": [

            { "type": "TENANT", "urn": "urn:edm-se:em:core:pr:tenant", "id": 87293 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pr:region", "id": 87295 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pr:site", "id": 87297 },

            { "type": "ID", "urn": "urn:edm-se:em:core:pc:circuit_breaker", "id": 87354 }

          ],

          "timeSeriesValues": [

            {

              "startTime": "2021-11-01T00:00:00.000-07:00",

              "endTime": "2021-12-01T00:00:00.000-08:00",

              "value": 161833741052

            }

          ]

        }

      ]

    }

  }

}

BinnedUsageCostData query

Returns a paginated view of EMCP_BusinessQuantityBinnedUsageTimeSeriesWithCostsCollectionSegment data, based on the parameters. There is no way to filter the usages -- it will always return all usages, including Total Usage.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • input : a collection of the following values, type = EMCP_BinnedUsageCostDataInput!
    • startTime! : a DateTime to indicate the inclusive start of the interval.
    • endTime! : a DateTime to indicate the exclusive end of the interval.
    • timeZone! : a String to indicate the IANA time zone the data should be aggregated into.
    • businessQuantityName! : a String indicating the business quantity to get values for.
    • aggregationInterval! : a EMCP_AggregationInterval indicating the temporal bin size that the data is aggregated into.

Results

  • The timeSeriesValues results' time range are returned with an inclusive startTime and exclusive endTime.
  • The value returned is always interval-based -- the value for that time interval -- it is never cumulative.
  • The results are based on the configuration of the Energy hierarchy.
  • Calculation methodology can be found on this page on the Team 2 Wiki.

Example - Get Yearly-aggregated cost values for the appContext and specified time range in the specified time zone

Query

query binnedUsageCostData(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $businessQuantityName: String!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $aggregationInterval: EMCP_AggregationInterval!

) {

  binnedUsageCostData(

    appContext: $appContext

    input: {

      startTime: $startTime

      endTime: $endTime

      timeZone: $timeZone

      businessQuantityName: $businessQuantityName

      aggregationInterval: $aggregationInterval

    }

  ) {

    items {

      usageId

      businessQuantity { name }

      measure {

        name

        unit { symbol }

      }

      thingId

      thingLabel

      timeSeriesValuesAndCosts { startTime endTime value cost }

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87901, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "TENANT", "id": 132441, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "TENANT", "id": 87903, "urn": "urn:edm-se:em:core:pr:site" },

  ],

  "businessQuantityName": "ACTIVE_ENERGY",

  "startTime": "2020-01-01T00:00:00-08:00",

  "endTime": "2023-01-01T00:00:00-08:00",

  "timeZone": "America/Vancouver",

  "aggregationInterval": "YEAR"

}

Results

{

  "data": {

    "binnedUsageCostData": {

      "items": [

        {

          "usageId": 276,

          "businessQuantity": {

            "name": "ACTIVE_ENERGY"

          },

          "measure": {

            "name": "Wp del+rec",

            "unit": {

              "symbol": "Wh"

            }

          },

          "thingId": 87903,

          "thingLabel": "Team 2 Site",

          "timeSeriesValuesAndCosts": [

            {

              "startTime": "2020-01-01T00:00:00.000-08:00",

              "endTime": "2021-01-01T00:00:00.000-08:00",

              "value": 0,

              "cost": 0

            },

            {

              "startTime": "2021-01-01T00:00:00.000-08:00",

              "endTime": "2022-01-01T00:00:00.000-08:00",

              "value": -14966477,

              "cost": -17959.7724

            },

            {

              "startTime": "2022-01-01T00:00:00.000-08:00",

              "endTime": "2023-01-01T00:00:00.000-08:00",

              "value": 1278100,

              "cost": 1533.72

            }

          ]

        },

        [ ... truncated ... ]

        {

          "usageId": 9550,

          "businessQuantity": {

            "name": "ACTIVE_ENERGY"

          },

          "measure": {

            "name": "Wp del+rec",

            "unit": {

              "symbol": "Wh"

            }

          },

          "thingId": 87903,

          "thingLabel": "Team 2 Site",

          "timeSeriesValuesAndCosts": [

            {

              "startTime": "2020-01-01T00:00:00.000-08:00",

              "endTime": "2021-01-01T00:00:00.000-08:00",

              "value": null,

              "cost": null

            },

            {

              "startTime": "2021-01-01T00:00:00.000-08:00",

              "endTime": "2022-01-01T00:00:00.000-08:00",

              "value": 3235563,

              "cost": 3882.6756

            },

            {

              "startTime": "2022-01-01T00:00:00.000-08:00",

              "endTime": "2023-01-01T00:00:00.000-08:00",

              "value": 3448733,

              "cost": 4138.4796

            }

          ]

        }

      ]

    }

  }

}

RankedMeasures query

Returns a paginated view of EMCP_RankedMeasureValue data, based on the parameters.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • businessQuantityName! : a String indicating the business quantity to get values for.
  • topoConceptUrn : a String indicating (by urn) of the level of items that will be ranked, such as ranking all buildings below the current appContext node. If null, the direct child toponodes are ranked.

Results

  • The results are the ranked energy usage -- highest usage to lowest usage -- based on the appContext (parent node).
    • If there is no data for a child, NULL is returned.
    • In the case of a tie, all children with the same value will have the same rank
  • If topoConceptUrn is null, the items to be ranked are the direct children of the node specified in the appContext.
  • If topoConceptUrn is not null, the items to be ranked are the descendants of the node specified in the appContext that are of the specified concept.
    • For example, if the appContext specified the orgniazation, and the topoConceptUrn is "building", then all buildings under the organization will be ranked against each other.

Example - Get ranked values for the children of the specified appContext and specified time range for the given business quantity

Query

query exampleQuery (

  $appContext: [EMCP_TopoNodeContextInput!]!

  $startTime: DateTime!

  $endTime: DateTime!

  $businessQuantityName: String!

  ) {

  rankedMeasures(

    appContext: $appContext

    businessQuantityName: $businessQuantityName

    startTime: $startTime

    endTime: $endTime

    ) {

    items {

      ranking

      value

      thingId

      thingLabel      

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "TENANT", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" }

  ],

  "startTime": "2021-11-25Z",

  "endTime": "2021-11-30Z",

  "businessQuantityName": "APPARENT_ENERGY"

}

Results

{

  "data": {

    "rankedMeasures": {

      "items": [

        {

          "ranking": 1,

          "value": 26957916065,

          "thingId": 87297,

          "thingLabel": "Montréal Factory"

        },

        {

          "ranking": 2,

          "value": null,

          "thingId": 87299,

          "thingLabel": "Québec City Factory"

        },

        {

          "ranking": 2,

          "value": null,

          "thingId": 87301,

          "thingLabel": "Halifax Factory"

        }

      ]

    }

  }

}

RankedUsageIntensity query

Returns a paginated view of EMCP_RankedUsageIntensityValue data, based on the parameters.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • businessQuantityName! : a String indicating the business quantity to get values for.
  • topoConceptUrn : a String indicating (by urn) of the level of items that will be ranked, such as ranking all buildings below the current appContext node.
    • If value is null, the direct child toponodes are ranked.
    • If value is 'urn:PRODUCT' then it will rank all products (aka, devices) under the given appContext.

Results

  • The results are the ranked energy usage intensities -- highest usage to lowest usage -- based on the appContext (parent node).
    • If there is no data for a child, NULL is returned.
    • In the case of a tie, all children with the same value will have the same rank
  • If topoConceptUrn is null, the items to be ranked are the direct children of the node specified in the appContext.
  • If topoConceptUrn is not null, the items to be ranked are the descendants of the node specified in the appContext that are of the specified concept.
    • For example, if the appContext specified the orgniazation, and the topoConceptUrn is "building", then all buildings under the organization will be ranked against each other.
    • And for the special topoConceptUrn value of 'urn:PRODUCT', all descendant products (aka, devices) will be returned

Example - Get ranked values for the children of the specified appContext and specified time range for the given business quantity

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

      usageIntensity

      thingId

      thingLabel

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "TENANT", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" }

  ],

  "startTime": "2021-11-25Z",

  "endTime": "2021-11-30Z",

  "businessQuantityName": "APPARENT_ENERGY",

  "topoContextUrn": "urn:PRODUCT"

}

Results

{

  "data": {

    "rankedUsageIntensity": {

      "items": [

        {

          "ranking": 1,

          "usageIntensity": 26957916065,

          "thingId": 87297,

          "thingLabel": "Montréal Factory"

        },

        {

          "ranking": 2,

          "usageIntensity": null,

          "thingId": 87299,

          "thingLabel": "Québec City Factory"

        },

        {

          "ranking": 2,

          "usageIntensity": null,

          "thingId": 87301,

          "thingLabel": "Halifax Factory"

        }

      ]

    }

  }

}

UsageData query

Returns a paginated view of EMCP_BusinessQuantityUsageData data, based on the parameters.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter to result by topology.
  • skip / take : Ints specifying pagination of the data.
  • startTime! : a DateTime to indicate the inclusive start of the interval.
  • endTime! : a DateTime to indicate the exclusive end of the interval.
  • timeZone! : a String to indicate the IANA time zone the data should be aggregated into.
  • businessQuantityName! : a String indicating the business quantitiy to get values for.
  • splitByChildNodes! : to indicate whether to return usage information for the toponode specified in the appContext (false), or for the child toponodes (true).
  • normalizationFactor : a NormalizationFactor? indicates that retrieved time-series has to be normalized according to weather data.
    • a value of None, null, or the omission of the parameter will not apply any normalization
    • a value of CDD, will normalize the results by the Cooling Degree Days time-series linked to the sites of the slotUids fetched.
    • a value of HDD, will normalize the results by the Heating Degree Days time-series linked to the sites of the slotUids fetched.
    • a value of CDDHDD, will normalize the results by both Heating and Cooling Degree Days time-series linked to the sites of the slotUids fetched.
  • specialFilter : a SpecialFilter? for fitlering out some specific data.
    • a value of None, null, or the omission of the parameter will not apply any filtering.
    • a value of OPENED_HOURS, will only fetch data when the building or site linked to the slotUuid has a schedule indicating the site is open.
    • a value of CLOSED_HOURS, will only fetch data when the building or site linked to the slotUuid has a schedule indicating the site is closed.

Results

  • The value for each configured usage for the appContext (or the immediate children of the appContext) is returned.

Example - Get usage values for the children of the specified appContext and specified time range for the given business quantity

Query

query usageData(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $businessQuantityName: String!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $take: Int = 250

  $skip: Int = 0

  $splitByChildNodes: Boolean

) {

  usageData(

    skip: $skip

    take: $take

    appContext: $appContext

    input: {

      startTime: $startTime

      endTime: $endTime

      timeZone: $timeZone

      businessQuantityName: $businessQuantityName

      splitByChildNodes: $splitByChildNodes

    }

  ) {

    items {

      thingId

      thingLabel

      startTime

      endTime

      timeZone

      usageId

      businessQuantityName

      unit { urn name symbol }

      value

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "TENANT", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "ID", "id": 87903, "urn": "urn:edm-se:em:core:pr:site" },

    { "type": "ID", "id": 87905, "urn": "urn:edm-se:em:core:pr:building" }

  ],

  "startTime": "2021-11-25Z",

  "endTime": "2021-11-30Z",

  "businessQuantityName": "APPARENT_ENERGY",

  "timeZone": "America/Vancouver",

  "splitByChildNodes": true

}

Results

{

  "data": {

    "usageData": {

      "items": [

        {

          "thingId": 87909,

          "thingLabel": "Floor 2",

          "startTime": "2022-02-13T08:00:00.000Z",

          "endTime": "2022-02-17T08:00:00.000Z",

          "timeZone": "America/Vancouver",

          "usageId": 277,

          "businessQuantityName": "ACTIVE_ENERGY",

          "unit": { "urn": "urn:edm-se:em:core:ut:watt_hour", "name": "watt hour", "symbol": "Wh" },

          "value": 555589

        },

        {

          "thingId": 87909,

          "thingLabel": "Floor 2",

          "startTime": "2022-02-13T08:00:00.000Z",

          "endTime": "2022-02-17T08:00:00.000Z",

          "timeZone": "America/Vancouver",

          "usageId": 9546,

          "businessQuantityName": "ACTIVE_ENERGY",

          "unit": { "urn": "urn:edm-se:em:core:ut:watt_hour", "name": "watt hour", "symbol": "Wh" },

          "value": 499651

        },

        {

          "thingId": 87909,

          "thingLabel": "Floor 2",

          "startTime": "2022-02-13T08:00:00.000Z",

          "endTime": "2022-02-17T08:00:00.000Z",

          "timeZone": "America/Vancouver",

          "usageId": 9550,

          "businessQuantityName": "ACTIVE_ENERGY",

          "unit": { "urn": "urn:edm-se:em:core:ut:watt_hour", "name": "watt hour", "symbol": "Wh" },

          "value": 55938

        }

      ]

    }

  }

}

BinnedUsage query

This function returns multiple streams of data, based on the input parameters.

It can return two main types of energy data, returned as mode in the dataset.

  • CONSUMPTION: energy that is consumed (such as lighting and heating)
  • PRODUCTION: energy that is produced (such as solar power and generators)

And each of these two main types can be further broken down into the energySource: ALL, GRID, and LOCAL.

  • Consumption
    • GRID
      • all consumption that came from the utility/grid.
      • the cost is the "grid" consumption value multiplied by the electricity rate for the site.
    • LOCAL
      • all consumption that was produced locally.
      • the cost is the "local" consumption value multiplied by the electricity rate for the site.
    • ALL
      • all consumption, independent of how/where the energy was produced.
      • the cost is the "all" consumption value multiplied by the electricity rate for the site.
  • Production
    • GRID
      • all production that is sent to the grid (or more specifically, sent to a higher level in the hierarchy than is being queried).
      • the cost is the "grid" production multiplied by the electricity sell-back rate for the site.
    • LOCAL
      • all production that is consumed locally.
      • the cost is the "local" production multiplied by the electricity rate for the site.
    • ALL
      • all production, independent of how/where it is consumed.
      • the cost is the sum of "grid" production cost and "local" production cost.

Although this takes a business quantity, that business quantity is not used verbatim for electrical commodities. This is because for the electrical commodity, when asking for ACTIVE_ENERGY, consumption data generally comes from ACTIVE_ENERGY_DELIVERED and production generally comes from ACTIVE_ENERGY_RECEIVED.

Note: To know what was sent back to the grid, a TotalUsage device must be configured at the site level.

Note: Future versions of this API will support APPARENT_ENERGY and REACTIVE_ENERGY, but currently those are not supported and will simply use ACTIVE_ENERGY instead.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter the result by topology.
  • skip / take : Ints specifying pagination of the data.
  • input : a collection of the following values, type = EMCP_BinnedUsageCostDataInput!
    • startTime! : a DateTime to indicate the inclusive start of the interval.
    • endTime! : a DateTime to indicate the exclusive end of the interval.
    • timeZone! : a String to indicate the IANA time zone the data should be aggregated into.
    • aggregationInterval! : an EMCP_AggregationInterval indicating the temporal bin size that the data is aggregated into.
    • businessQuantityName! : a String to indicate what measures should be returned. This does not DIRECTLY relate to a specific business quantity, but is more general. I.e., when asking for ACTIVE_ENERGY, multiple business quantities maybe be needed (ACTIVE_ENERGY_DELIVERED and ACTIVE_ENERGY_RECEIVED).
    • includeConsumptionTimeseries : a Boolean indicating whether consumption data streams should be returned.
    • IncludeConsumptionEnergySourceBreakdown : a Boolean indicating whether to return the breakdown of consumption energy.
    • includeProductionTimeseries : a Boolean indicating whether production data streams should be returned.
    • IncludeProductionEnergySourceBreakdown : a Boolean indicating whether to return the breakdown of production energy.

Results

  • The timeSeriesValues results' time range are returned with an inclusive startTime and exclusive endTime.
    • E.g., if the aggregation period is an HOUR, then a value with a timestamp of 02:00:00 refers to the time period 02:00:00 (inclusive) to 03:00:00 (exclusive).
  • The value returned is the energy consumed or produced in that interval; it is never cumulative.
  • The results are based on the configuration of the Energy hierarchy.

Example - Get Monthly-aggregated values for the appContext and specified time range in the specified time zone

Query

query binnedUsage(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $businessQuantityName: String!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $aggregationInterval: EMCP_AggregationInterval!

  $includeConsumptionTimeseries: Boolean!

  $includeConsumptionEnergySourceBreakdown: Boolean!

  $includeProductionTimeseries: Boolean!

  $includeProductionEnergySourceBreakdown: Boolean!

  $take: Int = 250

  $skip: Int = 0

) {

  binnedUsage(

    input: {

      startTime: $startTime

      endTime: $endTime

      timeZone: $timeZone

      businessQuantityName: $businessQuantityName

      aggregationInterval: $aggregationInterval

      includeConsumptionTimeseries: $includeConsumptionTimeseries

      includeConsumptionEnergySourceBreakdown: $includeConsumptionEnergySourceBreakdown

      includeProductionTimeseries: $includeProductionTimeseries

      includeProductionEnergySourceBreakdown: $includeProductionEnergySourceBreakdown

    }

    appContext: $appContext

  ) {

    items {

      mode

      energySource

      usageId

      thingId

      thingLabel

      thingContext { type id urn }

      measureId

      measure { urn name label unit { symbol } }

      timeSeriesValues { startTime endTime value }

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 87293, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "TENANT", "id": 87295, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "TENANT", "id": 87297, "urn": "urn:edm-se:em:core:pr:site" }

  ],

  "startTime": "2023-01-01T08:00:00.000Z",  

  "endTime": "2023-07-01T07:00:00.000Z",

  "businessQuantityName": "ACTIVE_ENERGY",

  "timeZone": "America/Vancouver",

  "aggregationInterval": "MONTH",  

  "includeConsumptionTimeseries": true,

  "includeConsumptionEnergySourceBreakdown": true,

  "includeProductionTimeseries": true,

  "includeProductionEnergySourceBreakdown": false

}

Results

{

  "data": {

    "binnedUsage": {

      "items": [

        {

          "mode": "CONSUMPTION",

          "energySource": "ALL",

          "usageId": 276,

          "thingId": 1326454,

          "thingLabel": "Floor z",

          "thingContext": [...],

          "measureId": 5790,

          "measure": {

            "urn": "urn:edm-se:em:core:me:whrin",

            "name": "Wp del",

            "label": "Active energy delivered",

            "unit": {

              "symbol": "Wh"

            }

          },

          "timeSeriesValues": [

            {

              "startTime": "2023-01-01T00:00:00.000-08:00",

              "endTime": "2023-02-01T00:00:00.000-08:00",

              "value": 0

            },

            ...

            {

              "startTime": "2023-06-01T00:00:00.000-07:00",

              "endTime": "2023-07-01T00:00:00.000-07:00",

              "value": 0

            }

          ]

        },

        {

          "mode": "CONSUMPTION",

          "energySource": "ALL",

          "usageId": 277,

          "thingId": 1326454,

          "thingLabel": "Floor z",

          "thingContext": [...],

          "measureId": 5790,

          "measure": {

            "urn": "urn:edm-se:em:core:me:whrin",

            "name": "Wp del",

            "label": "Active energy delivered",

            "unit": {

              "symbol": "Wh"

            }

          },

          "timeSeriesValues": [

            {

              "startTime": "2023-01-01T00:00:00.000-08:00",

              "endTime": "2023-02-01T00:00:00.000-08:00",

              "value": "128831582"

            },

            ...

            {

              "startTime": "2023-06-01T00:00:00.000-07:00",

              "endTime": "2023-07-01T00:00:00.000-07:00",

              "value": "44026406.3"

            }

          ]

        },

        {

          "mode": "CONSUMPTION",

          "energySource": "ALL",

          "usageId": 278,

          "thingId": 1326454,

          "thingLabel": "Floor z",

          "thingContext": [...],

          "measureId": 5790,

          "measure": {

            "urn": "urn:edm-se:em:core:me:whrin",

            "name": "Wp del",

            "label": "Active energy delivered",

            "unit": {

              "symbol": "Wh"

            }

          },

          "timeSeriesValues": [

            {

              "startTime": "2023-01-01T00:00:00.000-08:00",

              "endTime": "2023-02-01T00:00:00.000-08:00",

              "value": 343687.5

            },

            ...

            {

              "startTime": "2023-06-01T00:00:00.000-07:00",

              "endTime": "2023-07-01T00:00:00.000-07:00",

              "value": 342718.8

            }

          ]

        },

        ...

        {

          "mode": "CONSUMPTION",

          "energySource": "GRID",

          "usageId": 276,

          "thingId": 1326454,

          "thingLabel": "Floor z",

          "thingContext": [...],

          "measureId": 5790,

          "measure": {

            "urn": "urn:edm-se:em:core:me:whrin",

            "name": "Wp del",

            "label": "Active energy delivered",

            "unit": {

              "symbol": "Wh"

            }

          },

          "timeSeriesValues": [

            {

              "startTime": "2023-01-01T00:00:00.000-08:00",

              "endTime": "2023-02-01T00:00:00.000-08:00",

              "value": 0

            },

            ...

            {

              "startTime": "2023-06-01T00:00:00.000-07:00",

              "endTime": "2023-07-01T00:00:00.000-07:00",

              "value": 0

            }

          ]

        },

        ...

        {

          "mode": "CONSUMPTION",

          "energySource": "LOCAL",

          "usageId": 276,

          "thingId": 1326454,

          "thingLabel": "Floor z",

          "thingContext": [...],

          "measureId": null,

          "measure": null,

          "timeSeriesValues": [

            {

              "startTime": "2023-01-01T00:00:00.000-08:00",

              "endTime": "2023-02-01T00:00:00.000-08:00",

              "value": null

            },           

            {

              "startTime": "2023-06-01T00:00:00.000-07:00",

              "endTime": "2023-07-01T00:00:00.000-07:00",

              "value": null

            }

          ]

        },

        ...

        {

          "mode": "PRODUCTION",

          "energySource": "ALL",

          "usageId": 277,

          "thingId": 1326454,

          "thingLabel": "Floor z",

          "thingContext": [...],

          "measureId": 5791,

          "measure": {

            "urn": "urn:edm-se:em:core:me:whrout",

            "name": "Wp rec",

            "label": "Active energy received",

            "unit": {

              "symbol": "Wh"

            }

          },

          "timeSeriesValues": [...],

        },

        {

          "mode": "PRODUCTION",

          "energySource": "ALL",

          "usageId": 9597,

          "thingId": 1326454,

          "thingLabel": "Floor z",

          "thingContext": [...],

          "measureId": 5791,

          "measure": {

            "urn": "urn:edm-se:em:core:me:whrout",

            "name": "Wp rec",

            "label": "Active energy received",

            "unit": {

              "symbol": "Wh"

            }

          },

          "timeSeriesValues": [

            {

              "startTime": "2023-01-01T00:00:00.000-08:00",

              "endTime": "2023-02-01T00:00:00.000-08:00",

              "value": 0

            },

            ...

            {

              "startTime": "2023-06-01T00:00:00.000-07:00",

              "endTime": "2023-07-01T00:00:00.000-07:00",

              "value": 1122709.1

            }

          ]

        }

      ]

    }

  }

}

BinnedUsageCO2Data query

Returns a paginated view of EMCP_BusinessQuantityBinnedUsageTimeSeriesWithCO2CollectionSegment data, based on the parameters. There is no way to filter the usages -- it will always return all usages, including Total Usage.

Arguments

  • appContext! : an Array of EMCP_TopoNodeContextInput to filter the results by topology.
  • skip / take : Ints specifying pagination of the data.
  • input : a collection of the following values, type = EMCP_BinnedUsageCO2DataInput!
    • startTime! : a DateTime to indicate the inclusive start of the interval.
    • endTime! : a DateTime to indicate the exclusive end of the interval.
    • timeZone! : a String indicates the IANA time zone the data should be aggregated into.
    • businessQuantityName! : a String indicating the business quantity to get values for.
    • aggregationInterval! : an EMCP_AggregationInterval indicating the temporal bin size that the data is aggregated into.

Results

  • The timeSeriesValues results' time range are returned with an inclusive startTime and exclusive endTime.
  • The value returned is always interval-based -- the value for that time interval -- it is never cumulative.
  • The results are based on the configuration of the Energy hierarchy.
  • isEmissionFactorAvailable returns true only if all the sites (the countries they belong to) have emission factors configured.
  • cO2 value is null for a tenant/region if any site under it doesn't have emission factor configured.
  • Calculation methodology can be found on this page on the Team 2 Wiki.

Example - Get Yearly-aggregated CO2 values for the appContext and specified time range in the specified time zone for the tenant

Query

query binnedUsageCO2Data(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $businessQuantityName: String!

  $startTime: DateTime!

  $endTime: DateTime!

  $timeZone: String!

  $aggregationInterval: EMCP_AggregationInterval!

) {

  binnedUsageCO2Data(

    appContext: $appContext

    input: {

      startTime: $startTime

      endTime: $endTime

      timeZone: $timeZone

      businessQuantityName: $businessQuantityName

      aggregationInterval: $aggregationInterval

    }

  ) {

    items {

      usageId

      businessQuantity { name }

      isEmissionFactorAvailable

      measure {

        name

        unit { symbol }

      }

      thingId

      thingLabel

      timeSeriesValuesAndCO2 { startTime endTime value cO2 }

      unit { symbol }

    }

  }

}

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 1524425, "urn": "urn:edm-se:em:core:pr:tenant" }

  ],

  "businessQuantityName": "ACTIVE_ENERGY",

  "startTime": "2021-12-31T18:30:00.000Z",

  "endTime": "2023-08-29T18:30:00.000Z",

  "timeZone": "Asia/Calcutta",

  "aggregationInterval": "YEAR"

}

Results

{

  "data": {

    "binnedUsageCO2Data": {

      "items": [

        {

          "usageId": 276,

          "businessQuantity": {

            "name": "ACTIVE_ENERGY"

          },

          "isEmissionFactorAvailable": true,

          "measure": {

            "name": "Wp del pos no reset",

            "unit": {

              "symbol": "Wh"

            }

          },

          "thingId": 1524425,

          "thingLabel": "Emission Trials",

          "timeSeriesValuesAndCO2": [

            {

              "startTime": "2022-01-01T00:00:00.000+05:30",

              "endTime": "2023-01-01T00:00:00.000+05:30",

              "value": 815311,

              "cO2": -5.202861

            },

            {

              "startTime": "2023-01-01T00:00:00.000+05:30",

              "endTime": "2024-01-01T00:00:00.000+05:30",

              "value": -606328,

              "cO2": 165.530278

            }

          ],

          "unit": {

            "symbol": "kg"

          }

        },

        [ ... truncated ... ]

        {

          "usageId": 278,

          "businessQuantity": {

            "name": "ACTIVE_ENERGY"

          },

          "isEmissionFactorAvailable": true,

          "measure": {

            "name": "Wp del pos no reset",

            "unit": {

              "symbol": "Wh"

            }

          },

          "thingId": 1524425,

          "thingLabel": "Emission Trials",

          "timeSeriesValuesAndCO2": [

            {

              "startTime": "2022-01-01T00:00:00.000+05:30",

              "endTime": "2023-01-01T00:00:00.000+05:30",

              "value": 560193,

              "cO2": 27.606372

            },

            {

              "startTime": "2023-01-01T00:00:00.000+05:30",

              "endTime": "2024-01-01T00:00:00.000+05:30",

              "value": -663077,

              "cO2": -88.007621

            }

          ],

          "unit": {

            "symbol": "kg"

          }

        }

      ]

    }

  }

}

Example - Get Yearly-aggregated CO2 values for the appContext and specified time range in the specified time zone for the site

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 1524425, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "ID", "id": 1524605, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "ID", "id": 1524597, "urn": "urn:edm-se:em:core:pr:site" }

  ],

  "businessQuantityName": "ACTIVE_ENERGY",

  "startTime": "2021-12-31T18:30:00.000Z",

  "endTime": "2023-08-29T18:30:00.000Z",

  "timeZone": "Asia/Calcutta",

  "aggregationInterval": "YEAR"

}

Results

{

  "data": {

    "binnedUsageCO2Data": {

      "items": [

        [ ... truncated ... ]

        {

          "usageId": 277,

          "businessQuantity": {

            "name": "ACTIVE_ENERGY"

          },

          "isEmissionFactorAvailable": true,

          "measure": {

            "name": "Wp del pos no reset",

            "unit": {

              "symbol": "Wh"

            }

          },

          "thingId": 1524597,

          "thingLabel": "Bengaluru",

          "timeSeriesValuesAndCO2": [

            {

              "startTime": "2022-01-01T00:00:00.000+05:30",

              "endTime": "2023-01-01T00:00:00.000+05:30",

              "value": 9105,

              "cO2": 9.50562

            },

            {

              "startTime": "2023-01-01T00:00:00.000+05:30",

              "endTime": "2024-01-01T00:00:00.000+05:30",

              "value": -11318,

              "cO2": -11.815992

            }

          ],

          "unit": {

            "symbol": "kg"

          }

        },

        [ ... truncated ... ]

      ]

    }

  }

}

Example - Get Yearly-aggregated CO2 values for the appContext and specified time range in the specified time zone for the asset

Variables

{

  "appContext":  [

    { "type": "TENANT", "id": 1524425, "urn": "urn:edm-se:em:core:pr:tenant" },

    { "type": "ID", "id": 1524605, "urn": "urn:edm-se:em:core:pr:region" },

    { "type": "ID", "id": 1524597, "urn": "urn:edm-se:em:core:pr:site" },

    { "type": "ID", "id": 1615425, "urn": "urn:edm-se:em:core:pc:accessory" }

  ],

  "businessQuantityName": "ACTIVE_ENERGY",

  "startTime": "2021-12-31T18:30:00.000Z",

  "endTime": "2023-08-29T18:30:00.000Z",

  "timeZone": "Asia/Calcutta",

  "aggregationInterval": "YEAR"

}

Results

{

  "data": {

    "binnedUsageCO2Data": {

      "items": [

        [ ... truncated ... ]

{

          "usageId": 277,

          "businessQuantity": {

            "name": "ACTIVE_ENERGY"

          },

          "isEmissionFactorAvailable": true,

          "measure": {

            "name": "Wp del pos no reset",

            "unit": {

              "symbol": "Wh"

            }

          },

          "thingId": 1615425,

          "thingLabel": "MasterpactMTZ-CO2",

          "timeSeriesValuesAndCO2": [

            {

              "startTime": "2022-01-01T00:00:00.000+05:30",

              "endTime": "2023-01-01T00:00:00.000+05:30",

              "value": 9105,

              "cO2": 9.50562

            },

            {

              "startTime": "2023-01-01T00:00:00.000+05:30",

              "endTime": "2024-01-01T00:00:00.000+05:30",

              "value": -11318,

              "cO2": -11.815992

            }

          ],

          "unit": {

            "symbol": "kg"

          }

        },

        [ ... truncated ... ]

      ]

    }

  }

}

subject

The subject query is designed to return only one subject.

Arguments

  • federatedId: The user federatedId from IDMS - optional
  • email: The user email - optional
  • subjectId: The subject identifier - optional

Behavior

If there is no argument passed to the subject query, the query will return the current user information based on the idms token.

:::note This query enable filtering on the subjectPropertyValues. :::

Examples

Get the current user information

To get information about the currently logged user you can call the subject query without arguments.

:::caution The field assignments is resolved by the graphql gateway and doesn't appears on the original subject graphql api. :::

query subjectInfo($where: EMCP_SubjectPropertyValueFilterInput){

  subject {

    id

    ...Assignments

    ...Properties

  }

}



fragment Assignments on EMCP_Subject {

  assignments {

    items {

      status

      roleId

      ...Access

    }

  }

}



fragment Access on EMCP_AccessAssignment {

  access {

    tenant {

      label

    }

  }

}



fragment Properties on EMCP_Subject{

  subjectPropertyValues(where:$where){

    psval

    property{

      urn

      label

    }

  }

}

{

  "where": {

    "property": {

      "urn": {

        "in":[

        "urn:edm-se:em:core:pr:federated_id",

        "urn:edm-se:em:core:pr:email",

        "urn:edm-se:em:core:pr:name",

        "urn:edm-se:em:core:pr:first_name",

        "urn:edm-se:em:core:pr:last_name",

        "urn:edm-se:em:core:pr:company",

        "urn:edm-se:em:core:pr:locale",

        "urn:edm-se:em:core:pr:favorite_organization_id"

          ]

      }

    }

  }

}

{

  "data": {

    "subject": {

      "id": 165,

      "assignments": {

        "items": [

          {

            "status": "ACTIVE",

            "roleId": 4,

            "access": {

              "tenant": {

                "label": "ACME Inc"

              }

            }

          },

          {

            "status": "ACTIVE",

            "roleId": 4,

            "access": {

              "tenant": {

                "label": "Mindt Chocolates"

              }

            }

          }

        ]

      },

      "subjectPropertyValues": [

        {

          "psval": "gb009fbd-698a-e81d-a3df-367daf1e9949",

          "property": {

            "urn": "urn:edm-se:em:core:pr:federated_id",

            "label": "federated id"

          }

        },

        {

          "psval": "econrjop+johnnorman@gmail.com",

          "property": {

            "urn": "urn:edm-se:em:core:pr:email",

            "label": "email"

          }

        },

        {

          "psval": "John",

          "property": {

            "urn": "urn:edm-se:em:core:pr:first_name",

            "label": "first name"

          }

        },

        {

          "psval": "Norman",

          "property": {

            "urn": "urn:edm-se:em:core:pr:last_name",

            "label": "last name"

          }

        },

        {

          "psval": "John Norman",

          "property": {

            "urn": "urn:edm-se:em:core:pr:name",

            "label": "name"

          }

        },

        {

          "psval": "Momentum",

          "property": {

            "urn": "urn:edm-se:em:core:pr:company",

            "label": "Company"

          }

        },

        {

          "psval": "en-US",

          "property": {

            "urn": "urn:edm-se:em:core:pr:locale",

            "label": "locale"

          }

        },

        {

          "psval": null,

          "property": {

            "urn": "urn:edm-se:em:core:pr:favorite_organization_id",

            "label": "favorite organization id"

          }

        }

      ]

    }

  }

}

:::caution The subject will be null if the user is not yet registered on the db.

{

  "data": {

    "subject": null

  }

} 

:::

Find a user by using the user federatedId

You can use the argument federatedId to find a specific user.

query subjectQuery(

  $federatedId: String

  $where: EMCP_SubjectPropertyValueFilterInput

) {

  subject(federatedId: $federatedId) {

    subjectPropertyValues(where: $where) {

      psval

      property {

        label

        urn

      }

    }

  }

}

{

  "federatedId": "gb007fed-4719-af59-d5b4-909c372120b8"

}

:::tip You can use a filter on the subjectPropertyValues to get a specific property.

{

"where": {

  "property": {

    "urn": {

      "eq": "urn:edm-se:em:core:pr:email"

    }

  }

}

}

:::

{

  "data": {

    "subject": {

      "subjectPropertyValues": [

        {

          "psval": "econrjop+christinehoffman@gmail.com",

          "property": {

            "label": "email",

            "urn": "urn:edm-se:em:core:pr:email"

          }

        }

      ]

    }

  }

}

:::caution The subject will be null if the logged user doesn't share at least one same organization with the requested user.

{

  "data": {

    "subject": null

  }

} 

:::

Find a user by using the user email

You can use the argument email to find a specific user.

query subjectQuery(

  $email: String

  $where: EMCP_SubjectPropertyValueFilterInput

) {

  subject(email: $email) {

    subjectPropertyValues(where: $where) {

      psval

      property {

        label

        urn

      }

    }

  }

}

{

  "email": "econrjop+peterdoe@gmail.com"

}

:::tip You can use a filter on the subjectPropertyValues to get only certain property.

{

"where": {

  "property": {

    "urn": {

      "eq": "urn:edm-se:em:core:pr:name"

    }

  }

}

}

:::

{

  "data": {

    "subject": {

      "subjectPropertyValues": [

        {

          "psval": "Peter Doe",

          "property": {

            "label": "name",

            "urn": "urn:edm-se:em:core:pr:name"

          }

        }

      ]

    }

  }

}

:::caution The subject will be null if the logged user doesn't share at least one same organization with the requested user.

{

  "data": {

    "subject": null

  }

} 

:::

Find a user by using the subjectId of the user

You can use the argument subjectId to find a specific user.

query subjectQuery(

  $subjectId: Int

  $where: EMCP_SubjectPropertyValueFilterInput

) {

  subject(subjectId: $subjectId) {

    subjectPropertyValues(where: $where) {

      psval

      property {

        label

        urn

      }

    }

  }

}

{

  "subjectId": 1611

}

:::tip You can use a filter on the subjectPropertyValues to get a specific property.

{

"where": {

  "property": {

    "urn": {

      "eq": "urn:edm-se:em:core:pr:name"

    }

  }

}

}

:::

{

  "data": {

    "subject": {

      "subjectPropertyValues": [

        {

          "psval": "Jesper Nielsen",

          "property": {

            "label": "name",

            "urn": "urn:edm-se:em:core:pr:name"

          }

        }

      ]

    }

  }

}

:::caution The subject will be null if the logged user doesn't share at least one same organization with the requested user.

{

  "data": {

    "subject": null

  }

} 

:::

subjects

The subjects query is designed to return a list of subjects.

Arguments

  • appContext: The execution context - optional
  • kind [User, Service, Group] : Argument used to specify the type of expected subject - mandatory

Behavior

If the appContext argument is not passed to the subjects query, the query will return all subjects based on the specified kind and will use the EEO Token to scope the result.

If an appContext argument is provied the list of subjects will be scoped to it.

:::note This query enable filtering on subjet and subjectPropertyValues.

The offset paging is enabled for this query. :::

Examples

Get a list of users scoped to an organization

To get the list of users scoped to an organization you can use the subjects query with the appContext set to the targeted organization.

query subjectsQuery(

  $appContext: [EMCP_TopoNodeContextInput!]

  $kind: EMCP_SubjectKind!

  $where: EMCP_SubjectPropertyValueFilterInput

) {

  subjects(kind: $kind, appContext: $appContext, take: 100) {

    totalCount

    items {

      id

      subjectPropertyValues(where: $where) {

        psval

        pival

        property {

          urn

          label

        }

      }

    }

  }

}

{

  "appContext": [

    {

      "id": 21,

      "type": "TENANT",

      "urn": "urn:edm-se:em:core:pr:tenant"

    }

  ],

  "where": {

    "property": {

      "urn": {

        "in": [

          "urn:edm-se:em:core:pr:name",

          "urn:edm-se:em:core:pr:email"

        ]

      }

    }

  },

  "kind": "USER"

}

:::tip As you can see you can set a filter on the subjectPropertyValues to get some specific properties. :::

{

  "data": {

    "subjects": {

      "totalCount": 5,

      "items": [

        {

          "id": 1622,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+johnnorman@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "John Norman",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1623,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+janecooper@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Jane Cooper",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1624,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+tomomaeda@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Tomo Maeda",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1625,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+jespernielsen@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Jesper Nielsen",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1629,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+christinehoffman@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Christine Hoffman",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        }

      ]

    }

  }

}

:::caution The subjects list will be empty if the caller can't access to the targeted organization.

{

  "data": {

    "subjects": {

      "totalCount": 0,

      "items": []

    }

  }

}

:::

Get a list of all accessible users

To get the list of all users that the caller can access you can use the subjects query without the appContext argument.

query subjectsQuery(

  $kind: EMCP_SubjectKind!

  $where: EMCP_SubjectPropertyValueFilterInput

) {

  subjects(kind: $kind, take: 100) {

    totalCount

    items {

      id

      subjectPropertyValues(where: $where) {

        psval

        pival

        property {

          urn

          label

        }

      }

    }

  }

}

{

  "where": {

    "property": {

      "urn": {

        "in": [

          "urn:edm-se:em:core:pr:name",

          "urn:edm-se:em:core:pr:email"

        ]

      }

    }

  },

  "kind": "USER"

}

:::tip As you can see you can set a filter on the subjectPropertyValues to get some specific properties. :::

{

  "data": {

    "subjects": {

      "totalCount": 6,

      "items": [

        {

          "id": 1622,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+johnnorman@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "John Norman",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1623,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+janecooper@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Jane Cooper",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1624,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+tomomaeda@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Tomo Maeda",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1625,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+jespernielsen@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Jesper Nielsen",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1628,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+peterdoe@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Peter Doe",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        },

        {

          "id": 1629,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+christinehoffman@gmail.com",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:email",

                "label": "email"

              }

            },

            {

              "psval": "Christine Hoffman",

              "pival": null,

              "property": {

                "urn": "urn:edm-se:em:core:pr:name",

                "label": "name"

              }

            }

          ]

        }

      ]

    }

  }

}

Get a list of all users

A service plaftorm with global scope can use subjects query to get all users and can also apply differents filters to it.

:::note The EEO token is used to determined if the caller is a service plaform or not. :::

Here on this example we use the subjects query to get the email of each user thanks to the user federatedId.

query subjectsQuery(

  $kind: EMCP_SubjectKind!

  $where1: EMCP_SubjectFilterInput  

  $where2: EMCP_SubjectPropertyValueFilterInput

) {

  subjects(kind: $kind,take: 100,where:$where1) {

    totalCount

    items {

      id

      subjectPropertyValues(where: $where2) {

        psval

      }

    }

  }

}

{

  "where1": {

    "subjectPropertyValues": {

      "some": {

        "and": [

          {

            "psval": {

              "in": [

                "gb006a9b-8ba9-855c-b8d9-e7b7bbca2c5d",

                "gb0043b9-1ff8-f375-af24-b7d5014e1700"

              ]

            }

          },

          {

            "property": {

              "urn": {

                "eq": "urn:edm-se:em:core:pr:federated_id"

              }

            }

          }

        ]

      }

    }

  },

  "where2": {

    "property": {

      "urn": {

        "in": [

          "urn:edm-se:em:core:pr:email"

        ]

      }

    }

  },

  "kind": "USER"

}

:::tip As you can see a filter can be set on subjectPropertyValues to get some specific properties.

And another filter can also be set on subject to filter the list of users. :::

{

  "data": {

    "subjects": {

      "totalCount": 2,

      "items": [

        {

          "id": 1623,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+janecooper@gmail.com"

            }

          ]

        },

        {

          "id": 1624,

          "subjectPropertyValues": [

            {

              "psval": "econrjop+tomomaeda@gmail.com"

            }

          ]

        }

      ]

    }

  }

}

Mutations

acknowledgeAlarmInstance

Acknowledges alarm instance and all its previously unacknowledged occurrences up to the moment.

Arguments

  • appContext: the execution context.
  • input: required parameter EMCP_AcknowledgeAlarmInstanceInput with the required fields alarmInstanceId and comment.

Behavior

  • If the user has no required permissions to update alarms, the response is ALARM_INSTANCE_NOT_FOUND error.

  • If the alarm instance is not available to the user via alarm categories, the response is ALARM_INSTANCE_NOT_FOUND error. Basic alarm categories available for all registered users. More alarm categories are provided via module subscriptions.

  • If the user has no required privileges to access the requested organization topology, the response is ALARM_INSTANCE_NOT_FOUND error.

  • If current state of the alarm instance is not acknowledgeable, the response is ALARM_INSTANCE_NOT_ACKNOWLEDGEABLE error.

  • If composite state cannot be calculated, the alarm instance is in corrupt state and response is ALARM_INSTANCE_COMPOSITE_STATE_NOT_DEFINED error. The composite state of the alarm instance calculated by alarmModel and alarmState properties of the alarm instance.

  • If all conditions described above verified, following changes are applied in a single database transaction:

    • create a new alarm state transition in the database with a UTC timestamp to represent the acknowledgement event.
    • assign the new state transition to all previously unacknowledged occurrences of the alarm instance.
    • set alarm state of the instance to acknowledged, in accordance with the latest alarm state transition.
  • If any part of the database transaction fails, the entire transaction is rolled back, and the response is ALARM_INSTANCE_ACKNOWLEDGEMENT_FAILED error.

Example

The following GraphQL mutation acknowledges alarm instance with a comment.

Mutation

mutation acknowledgeAlarmInstance(

  $appContext: [EMCP_TopoNodeContextInput!]!

  $input: EMCP_AcknowledgeAlarmInstanceInput!

) {

  acknowledgeAlarmInstance(appContext: $appContext, input: $input) {

    id

    alarmState

    alarmStateTransitions {

      id

      alarmInstanceId

      alarmState

      transitionTime

      idmsFederatedId

      comment

    }

    alarmOccurrences {

      id

      endTime

      acknowledgementAlarmStateTransitionId

    }

  }

}

Variables

{

  "appContext": [

    {

      "id": 87293,

      "label": "Mindt Chocolates",

      "urn": "urn:edm-se:em:core:pr:tenant",

      "type": "TENANT"

    }

  ],

  "input": {

    "alarmInstanceId": 14477,

    "comment": "Alarm was reviewed and acknowledged."

  }

}

Result

{

  "data": {

    "acknowledgeAlarmInstance": {

      "id": 14477,

      "alarmState": "NORM",

      "alarmStateTransitions": [

        {

          "id": 39592,

          "alarmInstanceId": 14477,

          "alarmState": "NORM",

          "transitionTime": "2022-02-21T19:49:36.505Z",

          "idmsFederatedId": "gb009fbd-698a-e81d-a3df-367daf1e9949",

          "comment": "Alarm was reviewed and acknowledged."

        }

      ],

      "alarmOccurrences": [

        {

          "id": 105779,

          "endTime": "2022-02-05T01:00:15.109Z",

          "acknowledgementAlarmStateTransitionId": 39592

        },

        ...

      ]

    }

  }

}

upsertAlarmInstancesAndOccurrences

Add and/or update alarm instance and occurrence information. This mutation performs several things:

  • Create or update the AlarmInstance.
  • Create or update the AlarmOccurrence.
  • Add a new AlarmStateTransition if a new instance or the state has changed.
  • Sends out AlarmOccurrence Message

Arguments

  • alarmInstance! : EMCP_UpsertAlarmMutationInput
    • startTime!: The start of the alarm. Be sure to indicate the offset. DateTime
    • endTime: The end of the alarm. Be sure to indicate the offset. If null, then the alarm is still active. DateTime
    • properties!: A JSON array of alarm property+value pairs. String
    • measures : A JSON array of measure information. String
    • possibleProblem: Describes a problem that can be presented if an alarm occurs. String
    • possibleCause: A list of possible causes for an alarm. String
    • possibleRisk: A list of possible risks and impacts. String
    • possibleRecommendation: Possible recommendations based on a particular alarm. String
    • instanceHandle: The unique identifier of an alarm instance in the external system. Used when updating this instance in a later mutation. String
    • occurrenceHandle!: The unique identifier of an alarm occurrence in the external system. Used when updating this occurrence in a later mutation. String
    • conceptUrn!: The URN of the concept for an alarm. String
    • priority!: The proposed priority of an alarm. EMCP_AlarmPriorityType
    • state!: The current state of an alarm. EMCP_AlarmState
    • condition!: The current condition of an alarm. EMCP_AlarmCondition
    • confirmed: The confirmation state of an alarm. EMCP_AlarmConfirmed
    • thingHandle: The handle of the thing that a particular alarm is associated with. String
    • thingId: The ID of the thing that an alarm is associated with. String
    • controlValue!: The alarm's control value. EMCP_AlarmControlValueType
    • tsMath!: How the alarm timestamp is determined. EMCP_TsMathType
    • onditmms!: On delay for activation of the alarm. Int

Argument verification

  • Either thingId or thingHandle has to be set, but not both

Behavior

  • If an instance exists with the instanceHandle, then it will update the instance otherwise it will create it
  • If an occurrence exists with the occurrenceHandle, then it will update the occurrence otherwise it will create it
  • If the condition is NORMAL and the instance already exist, all linked occurences will be modified to reflect that this is a normal condition

Results

  • The new or updated EMCP_AlarmOccurrence is returned.

Example

Add a new alarm occurrence.

Mutation

mutation {

  upsertAlarmInstancesAndOccurrences(inputs: [ {

       conceptUrn: "urn:edm-se:em:core:al:calh1_unbalialm",

       condition: NORMAL,

       confirmed: NOT_APPLICABLE,

       controlValue: NA,

       priority: YELLOW,

       state: NORMAL,

       endTime: "2022-02-07T17:34:34Z",

       startTime: "2022-02-07T17:32:47Z",

       occurrenceHandle: "ION:c14fc11e-283d-4ca7-a6f8-6b40b6fda69a:alarm:34051",

       onditmms: 0,

       properties: "{\"urn:edm-se:em:core:pr:detail_text\":\"Current Unbalance – Extreme: 200.0\",\"urn:edm-se:em:core:pr:summary_text\":\"Over I unbal\",\"urn:edm-se:em:core:pr:user_priority\":128}",

       thingHandle: "ION:c14fc11e-283d-4ca7-a6f8-6b40b6fda69a:Keating.RTU_5",

       tsMath: INPUT_BASED } ]) {

    id

    alarmInstanceId

  }

}

event

Allow to create or update an event

Arguments

  • id : optional : the event ID : if set this is an update, otherwise it's a create
  • thingId : mandatory for creation, the thingId
  • handle : mandatory for creation, should be unique accross all handle
  • eventConceptId & eventConceptUrn : mandatory for creation, but only one should be set, the URN has the precedence over the Id : the concept of the event
  • eventType : the event type, possible value : TOPO, UNARY, PICK, DROPOUT
  • eventFamily : mandatory for creation, the event family, possible value : ELECTRICAL, HVAC
  • measures : optional, an json array of measures
  • message : optional, the event message
  • pvUrns : The list of property value with the corresponding urn

Examples

Create a event

mutation EventMutation($inputParams: EMCP_EventMutationInput) {

  event(input: $inputParams) {

    id

    handle

    eventType

    eventFamily

    eventConceptId

    message

    measures

    thingId

    thing {

      id

    }

    eventPValues {

      createDate

      eventId

      handle

      id

      pFVal

      pIVal

      pSVal

      pTsVal

      property {

        urn

      }

    }

  }

}

{

  "inputParams": {

    "thingId": 150,

    "handle": "TEST_EVENT_HANDLE_2",

    "eventConceptUrn": "urn:edm-se:em:core:ev:calh1_batalm",

    "measures": "{\"foo\":\"bar\"}",

    "message": "Test Message",

    "pvUrns": [

      {"urn": "urn:edm-se:em:core:pr:cause", "sval": "testCause"},

      {"urn": "urn:edm-se:em:core:pr:user_priority", "ival": 1},

      {"urn": "urn:edm-se:em:core:pr:enum_statusid", "ival": 1}

    ]

  }

}

deleteEvents

Allow to delete a set of events

Arguments

  • ids : mandatory : the event IDs (Int) array to delete

Examples

Delete Slot(s)

mutation deleteEvents($ids: [Int!]) {

  __typename

  deleteEvents(ids: $ids) {

    id

  }

}

{

  "ids": [

    10

  ]

}