Nodes

Nodes are the container objects that store all data and configuration for your projects. There are various types of nodes including: Workspaces, Groups, Locations, Dashboards, Attachments, Sources and Parameters.


Node References

A Node can be referenced programmatically using either a Node Id (globally unique) or a user-defined Custom Id (unique to your account). These identifiers can be found (and Custom Id configured) at the bottom of the Properties for each Node.

../../_images/api_resources_node_id.jpg

Node Id

A Node Id is a 24-character alphanumeric string that uniquely identifies a Node in eagle.io. It is generated by the system and cannot be changed.

Custom Id

A Custom Id is a 255-character user-defined string that uniquely identifies a Node in your account. A Custom Id is prefixed with the @ symbol and must not contain the following special characters: dot ., underscore _ and hyphen -. In the example above, the Custom Id has been set to sensor_254.

Node Attributes

Consumers of Nodes should tolerate the addition of new attributes and variance in ordering of attributes with ease. Not all attributes appear in all contexts. It is generally safe to consider a nulled attribute, an empty set, and the absence of an attribute as the same thing.

Standard attributes Type Update Description
_class String   Identifies resource type: io.eagle.models.node.*
_id ObjectId   Unique identifier for this node
alarms Object Yes Alarm configuration and status
createdTime Time   ISO8601 timestamp the node was created
customId String Yes Optional user-assigned identifier for this node. Unique to owner (account)
isActive Boolean   Flag to indicate if node is active
isPublic Boolean Yes Flag to indicate if Public access is enabled
metadata Array Yes Array of metadata fields and values for a location
name String Yes Name of node. Restrictions apply.
ownerId ObjectId   Unique owner _id
parentId ObjectId   Parent node _id (not included in Workspace)
publicId String   Unique identifier used in public URL when isPublic is enabled. eg. https://public.eagle.io/public/dash/w31s3dndr408wcq
workspaceId ObjectId   Associated Workspace _id (not set on Workspace node)
Attachment attributes Type Update Description
description String Yes Description of attachment as set by user.
fileSize Int64   Size of attachment in bytes
fileUrl [3] String   Attachment URL. Requires ATTACHMENT_READ permission. Optionally specify an expiry period for the URL.
filePreviewUrl [3] String   Preview URL. Only included if the attachment is a valid media file. Requires ATTACHMENT_READ permission. Optionally specify an expiry period for the URL. Note: image dimensions may change without notice.
mimeType String   Mime-type of the attachment
Parameter & Location attributes Type Update Description
coordinateSourceId ObjectId   Data Source _id used to set location coordinates. Applies to Locations only.
chart Object Yes Parameter chart configuration
controlValue Variable Yes Pending control value. Type inherited from _class.
controlValueMaximum Double Yes Maximum control value when controlValueRestriction set to RANGE
controlValueMinimum Double Yes Minimum control value when controlValueRestriction set to RANGE
controlValueRestriction String Yes Control value is restricted to: [NONE, RANGE, STATES]
currentQuality Int32   Quality code associated with current value
currentStateId ObjectId   State _id associated with current value
currentTime Time   ISO8601 timestamp of the current value
currentValue Variable   Latest value with multiplier and offset applied. Type inherited from _class
displayType String Yes Default display type of parameter: [VALUE, STATE]
format String Yes Formatting to apply to displayed value
imageSourceId ObjectId   Attachment Source _id used to set location image. Applies to Locations only.
multiplier Double Yes Value to multiply rawValue and historic data on extraction. Applies to number parameters only
offset Double Yes Value to add to rawValue and historic data on extraction. Applies to number parameters only
oldestQuality Int32   Quality code associated with oldest value
oldestStateId ObjectId   State _id associated with oldest value
oldestTime Time   ISO8601 timestamp of the oldest value
oldestValue Variable   Oldest value. Type inherited from _class
previousQuality Int32   Quality code associated with oldest value
previousStateId ObjectId   State _id associated with previous value
previousTime Time   ISO8601 timestamp of the previous value
previousValue Variable   Previous value. Type inherited from _class
rating Object Yes Rating parameter configuration
rawValue Double   Latest raw value. Applies to number parameters only
states Array Yes Array of state configuration objects
statesType String Yes States evaluation mode: [RANGE, DISCRETE]
units String Yes Units to display with value
updatedTime Time   ISO8601 timestamp the historic data was last updated.
Source attributes Type Update Description
currentAttachmentId ObjectId   Current attachment _id associated with Attachment Source
currentStatus String   Current status: [DISABLED, FAILED, IDLE, SCHEDULED, QUEUED, CONNECTING, DOWNLOADING, PROCESSING, RETRYING, CONFIGURING, CONTROLLING, REMOTE]
clockSync Boolean   Flag to indicate if data logger clock is being syncronized with server
firmwareVersion String   Firmware version in-use by data logger
isEnabled Boolean Yes Flag to enable or disable the Source
lastAcquireRecordCount Int32   Number of records acquired on last acquisition
lastCommsAttempt Time   ISO8601 timestamp of the last communications attempt
lastCommsSuccess Time   ISO8601 timestamp of the last successful communication with Source
model String   Model of data logger in-use
pakBusAddress Int32 Yes PakBus address of Campbell data logger
pakBusGatewayAddress Int32 Yes PakBus gateway address of Campbell data logger
progName String   Name of program currently loaded in Campbell data logger
quietMaxSeconds Int32 Yes Maximum period in seconds between communication updates before triggering an Outdated alarm (non-scheduled collection only). 120 - 31536000 seconds
scheduleType String   Type of Schedule for automatic collection: [SERVER, REMOTE, NONE]
timezone String Yes Timezone of Source data.
timezoneAdjustForDst Boolean Yes Flag to indicate if acquired data is adjusted for DST in selected timezone
totalCommsAttempt Int32   Total count of communications attempts
totalCommsSuccess Int32   Total count of successful communications
[3](1, 2) Certain attributes can not be used in filter criteria.

Retrieve all nodes

Retrieve a list of all nodes available to the authenticated API key. Optionally filter by attribute values.

Arguments

Argument Example Description
attr _id,slug Optional. Comma delimited list of attributes to include in response
type TREE Optional - Default is LIST [4] | LIST returns a flat list of nodes | TREE returns hierarchical list of nodes (only available for requests that return less than 5000 nodes)
filter isActive($eq:true) Optional. Filter the records based on attribute value(s)
limit 100 Optional - Default is 50000 Maximum number of records to be returned. 0-50000
skip 50 Optional. Skip the first n records returned. Can be used with limit to paginate results
sort createdTime(DESC) Optional. Comma delimited list of attributes to sort by. Optionally include sort direction in parentheses or default to ASC: [ASC, DESC]
expiry 60 Optional. Expiry period in minutes for any included resource links. ie. fileUrl for Attachments. Default is 0 (no expiry). Expired resource links will return 403 Forbidden.
[4](1, 2) When TREE type is specified the filter, limit, skip and sort arguments are not allowed. A 413 ‘request too large` response will be returned if there are more than 5000 nodes when using type TREE.

Request

GET /api/v1/nodes

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
    {
        "_class": "io.eagle.models.node.Workspace",
        "_id": "536884ecb5a76fd5d3000014",
        "createdTime": "2014-05-06T06:45:00.061Z",
        "isActive": true,
        "name": "My Workspace",
        "ownerId": "52969365593a1a3a3200000f"
    },
    {
        "_class": "io.eagle.models.node.Group",
        "_id": "53eada0ada91110000000046",
        "createdTime": "2014-08-13T03:22:50.489Z",
        "isActive": true,
        "name": "Australia",
        "ownerId": "52969365593a1a3a3200000f",
        "parentId": "536884ecb5a76fd5d3000014",
        "workspaceId": "536884ecb5a76fd5d3000014"
    },
    {
        "_class": "io.eagle.models.node.location.Location",
        "_id": "542cbd18815043850e995f84",
        "alarms": {
            "stateAlarm": {
                "status": {
                    "acknowledgeComment": null,
                    "acknowledgeTime": null,
                    "acknowledgeUsername": null,
                    "categoryId": null,
                    "message": null,
                    "alarmState": "CLEARED"
                },
                "_class": "io.eagle.models.node.alarm.StateAlarm"
            }
        },
        "createdTime": "2014-10-02T02:48:56.186Z",
        "displayType": "VALUE",
        "isActive": true,
        "metadata": [],
        "name": "New Location",
        "ownerId": "52969365593a1a3a3200000f",
        "parentId": "53eada0ada91110000000046",
        "states": [
            {
                "name": "NORMAL",
                "index": 0,
                "categoryId": null,
                "_id": "542cbc4f815043850e995ebb",
                "threshold": {
                    "_class": "io.eagle.util.geo.GeoPoint"
                },
                "notify": "NEVER",
                "description": null,
                "isAlarm": null,
                "_class": "io.eagle.models.node.point.PointState"
            }
        ],
        "statesType": "RANGE",
        "workspaceId": "536884ecb5a76fd5d3000014"
    }
]

Example response when type argument is TREE. Descendants are wrapped in a children array:

[
    {
        "_class": "io.eagle.models.node.Workspace",
        "_id": "536884ecb5a76fd5d3000014",
        "createdTime": "2014-05-06T06:45:00.061Z",
        "isActive": true,
        "name": "My Workspace",
        "ownerId": "52969365593a1a3a3200000f",
        "children": [
            {
                "_class": "io.eagle.models.node.Group",
                "_id": "53eada0ada91110000000046",
                "createdTime": "2014-08-13T03:22:50.489Z",
                "isActive": true,
                "name": "Australia",
                "ownerId": "52969365593a1a3a3200000f",
                "parentId": "536884ecb5a76fd5d3000014",
                "workspaceId": "536884ecb5a76fd5d3000014",
                "children": [
                    {
                        "_class": "io.eagle.models.node.location.Location",
                        "_id": "542cbd18815043850e995f84",
                        "alarms": {
                            "stateAlarm": {
                                "status": {
                                    "acknowledgeComment": null,
                                    "acknowledgeTime": null,
                                    "acknowledgeUsername": null,
                                    "categoryId": null,
                                    "message": null,
                                    "alarmState": "CLEARED"
                                },
                                "_class": "io.eagle.models.node.alarm.StateAlarm"
                            }
                        },
                        "createdTime": "2014-10-02T02:48:56.186Z",
                        "displayType": "VALUE",
                        "isActive": true,
                        "metadata": [],
                        "name": "New Location",
                        "ownerId": "52969365593a1a3a3200000f",
                        "parentId": "53eada0ada91110000000046",
                        "states": [
                            {
                                "name": "NORMAL",
                                "index": 0,
                                "categoryId": null,
                                "_id": "542cbc4f815043850e995ebb",
                                "threshold": {
                                    "_class": "io.eagle.util.geo.GeoPoint"
                                },
                                "notify": "NEVER",
                                "description": null,
                                "isAlarm": null,
                                "_class": "io.eagle.models.node.point.PointState"
                            }
                        ],
                        "statesType": "RANGE",
                        "workspaceId": "536884ecb5a76fd5d3000014",
                        "children": []
                    }
                ]
            }
        ]
    }
]

Retrieve a node

Retrieve a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Arguments

Argument Example Description
attr _id,_class Optional. Comma delimited list of attributes to include in response
expiry 60 Optional. Expiry period in minutes for any included resource links. ie. fileUrl for Attachments. Default is 0 (no expiry). Expired resource links will return 403 Forbidden.

Request

GET /api/v1/nodes/:id

Example accessing a node by its automatically assigned _id

/api/v1/nodes/536884ecb5a76fd5d3000014

Example accessing a node by its customId

/api/v1/nodes/@workspace-01

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "_class": "io.eagle.models.node.Workspace",
    "_id": "536884ecb5a76fd5d3000014",
    "createdTime": "2014-05-06T06:45:00.061Z",
    "isActive": true,
    "name": "My Workspace",
    "ownerId": "52969365593a1a3a3200000f",
    "customId": "workspace-01"
}

Create a node

Create a node (currently limited to creation of Workspace and Group). You must specifiy both the _class and a unique name. Creating a Group also requires a valid parentId.

Note

Required API key permission: Modify

Request

POST /api/v1/nodes

Example creating a Workspace

{
    "_class": "io.eagle.models.node.Workspace",
    "name": "New Workspace"
}

Example creating a Folder

{
    "_class": "io.eagle.models.node.Group",
    "name": "New Folder",
    "parentId": "5a554eed0b64aabe5738da86"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
    "_class": "io.eagle.models.node.Workspace",
    "_id": "5ae7c3d03549e867c718ff97",
    "createdTime": "2018-05-01T01:33:04.830Z",
    "isActive": true,
    "metadata": [],
    "name": "New Workspace",
    "ownerId": "56d3a61a09c7aa9a82765540"
}

Update a node

Update a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. Updates are limited to the attributes listed with the Update flag. Multiple attributes can be updated in a single request.

The updated node will be returned in the response if the request is successful. You can optionally limit the returned attributes by specifying the attr argument.

Note

Required API key permission: Modify

Arguments

Argument Example Description
attr _id,_class Optional. Comma delimited list of attributes to include in successful response

Request

PUT /api/v1/nodes/:id
{
    "name": "My Renamed Workspace"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "_class": "io.eagle.models.node.Workspace",
    "_id": "536884ecb5a76fd5d3000014",
    "createdTime": "2014-05-06T06:45:00.061Z",
    "isActive": true,
    "name": "My Renamed Workspace",
    "ownerId": "52969365593a1a3a3200000f"
}

Complex attribute updates

Certain attributes such as alarms and states have specific update requirements:


Alarm configuration

Alarm configuration can be included in the update request for Location, Source and Parameter nodes. You must specify each alarm type as a nested attribute containing the config to be updated. Only changed attributes need to be specified.

Alarm config attributes Type Description
isEnabled Boolean Enable or disable the alarm. Overload alarm can not be disabled.
categoryId ObjectId Id of owner category to assign to this alarm. Required when notify option is not NEVER
notify String When notifications should be triggered: [NEVER, ALWAYS, AWAY_FROM_NORMAL, TOWARDS_NORMAL].
messageAway String Optional - Only valid for outdatedAlarm. Custom message to send when the alarm becomes active. Maximum of 255 characters. Leave empty for default message.
messageTowards String Optional - Only valid for outdatedAlarm. Custom message to send when the alarm becomes inactive. Maximum of 255 characters. Leave empty for default message.
qualityTypes Array Only valid for qualityAlarm. List of quality types that will trigger this alarm: [GOOD, BAD, UNCERTAIN].
excludeBeforeSeconds Int32 Optional - Default is null. Only valid for dataAlarm. Exclude data older than this duration and raise alarm if encountered. 120 - 315360000 seconds.
excludeAfterSeconds Int32 Optional - Default is null. Only valid for dataAlarm. Exclude data newer than this duration and raise alarm if encountered. 120 - 315360000 seconds.

Example:

{
    "alarms": {
        "communicationsAlarm": {
            "config": {
                "isEnabled": true,
                "notify": "ALWAYS",
                "categoryId": "52969367593a1a3a32000012"
            }
        },
        "qualityAlarm": {
            "config": {
                "isEnabled": true,
                "qualityTypes": ["BAD", "UNCERTAIN"]
            }
        },
        "configurationAlarm": { "config": { "isEnabled": false } }
    }
}

The alarm types available are specific to the type of node being updated:

Alarm types Supported nodes
communicationsAlarm Sources
configurationAlarm Sources
controlAlarm Control parameters
dataAlarm Sources
outdatedAlarm [1] Sources
overloadAlarm Sources
processAlarm Processor Sources, Process Parameters
qualityAlarm Locations, Parameters
stateAlarm [2] Locations, Parameters
[1]outdatedAlarm Maximum timeout is set via the node quietMaxSeconds attributes.
[2]stateAlarm has no direct configuration. Modify states to change state alarm behaviour.

States configuration

States configuration can be included in the update request for Number and Text Parameter nodes. Number parameters can use either DISCRETE or RANGE states. Text parameters are limited to DISCRETE states only.

States can be reset to parameter defaults by updating the states attribute with null.

Update existing states by providing the _id attribute for each state in the request. Any states without the _id attribute will be ignored. Only changed attributes need to be specified.

If no states in the request contain an _id attribute the update will Replace the existing states. RANGE states for number parameters must always be specified in ascending order based on threshold and there must be one state with the name attribute set to NORMAL.

Refer to Parameter states for further information.

Note

State type for number parameters can be changed with the statesType attribute. When changing statesType you should specify new states configuration or default states will be applied.

State attributes Type Description
name String Required. Unique name assigned to the state
threshold Variable Required. Unique threshold value for the state. Number parameters require a Double. Text parameters require a String.
occurrences Int32 Optional - Default is 1. Minimum number of repeat values equal or beyond threshold required to trigger state: 1-15.
isAlarm Boolean Optional - Default is FALSE. Flag to indicate if this state should raise an alarm. Not valid for NORMAL RANGE state.
notify String Optional - Default is NEVER. When notifications should be triggered: [NEVER, ALWAYS, AWAY_FROM_NORMAL, TOWARDS_NORMAL]. The NORMAL RANGE state is restricted to: [NEVER, ALWAYS]
categoryId ObjectId Id of owner category to assign to this state. Required when notify option is not NEVER
messageAway String Optional. Custom message to send when the state becomes active (away from normal). Maximum of 255 characters. Leave empty for default message.
messageTowards String Optional. Custom message to send when the state becomes inactive (towards normal). Maximum of 255 characters. Leave empty for default message.
qualityCode Int32 Optional - Default is null. Quality code to apply to acquired data that matches this state: 0-65535.

Example replacing DISCRETE states

{
    "statesType": "DISCRETE",
    "states": [
        {
            "name": "OFF",
            "threshold": 0
        },
        {
            "name": "ON",
            "threshold": 1,
            "occurrences": 1,
            "isAlarm": true,
            "notify": "ALWAYS",
            "categoryId": "52969367593a1a3a32000012",
            "messageAway": "PUMP IS RUNNING",
            "messageTowards": "PUMP IS OFF",
            "qualityCode": 192
        }
    ]
}

Example updating existing DISCRETE states

{
    "statesType": "DISCRETE",
    "states": [
        {
            "_id": "52969367593a1a3a32000091",
            "name": "SIREN OFF"
        },
        {
            "_id": "52969367593a1a3a32000092",
            "name": "SIREN ON",
            "notify": "NEVER"
        }
    ]
}

Example replacing RANGE states

{
    "statesType": "RANGE",
    "states": [
        {
            "name": "LOW",
            "threshold": 20
        },
        {
            "name": "NORMAL"
        },
        {
            "name": "HIGH",
            "threshold": 50
        },
        {
            "name": "CRITICAL",
            "threshold": 100,
            "occurrences": 2,
            "isAlarm": true,
            "notify": "ALWAYS",
            "categoryId": "52969367593a1a3a32000012",
            "qualityCode": 192
        }
    ]
}

Parameter chart configuration

Parameter chart configuration is used when displaying parameters as series on automatically generated charts. It can be included in the update request for Parameter nodes. Only changed attributes need to be specified.

Parameter chart config attributes Type Description
_class String Determines chart series type (Line or Column): [io.eagle.models.node.point.chart.LineChart, io.eagle.models.node.point.chart.ColumnChart]
stateThresholds String Threshold lines to display (when in y-axis range): [NONE, ALL, ALARM, NONALARM, USER_NOTIFICATION]
markerType String Marker type: [AUTOMATIC, CIRCLE, SQUARE, DIAMOND, TRIANGLE, TRIANGLE-DOWN]
markerSize Int32 Marker size (0 is Hidden): 0-6.
qualityStyle String Specify how quality colors are display on chart: [NONE, MARKER, MARKER_HOVER, MARKER_LINE, MARKER_FILL]
shadow Boolean Optional - default is false. Drop shadow effect
primaryColor String Optional - default is AUTOMATIC. Hex color code (eg. #ff3399) or AUTOMATIC used as primary color.
secondaryColor String Optional - default is AUTOMATIC. Hex color code (eg. #ffffff) or AUTOMATIC used as secondary color when fillStyle is a gradient.
fillStyle String Fill style: [NONE, SOLID, LINEAR_TOP, LINEAR_BOTTOM, LINEAR_LEFT, LINEAR_RIGHT, PIPE_VERTICAL, PIPE_HORIZONTAL, RADIAL_INSIDE, RADIAL_OUTSIDE]
fillOpacity Int32 Fill opacity (0 is Transparent): 0-100.
lineWidth Int32 Series line width (0 is Hidden): 0-6.
lineType String Line type (Line series only): [NORMAL, STEP_LEFT, STEP_CENTER, STEP_RIGHT, SPLINE]
lineStyle String Line style (Line series only): [SOLID, SHORTDASH, SHORTDOT, SHORTDASHDOT, SHORTDASHDOTDOT, DOT, DASH, LONGDASH, DASHDOT, LONGDASHDOT, LONGDASHDOTDOT]
pointPlacementType String Placement of datapoint on column (Column series only): [ON, BETWEEN]
groupType String Column layout (when multiple Column series used - Column series only): [NORMAL, GROUP, STACKED]
aggregation Object Historic data aggregation config attributes
mode
String Aggregation mode: [AUTOMATIC, RAW, CUSTOM]
type
String Historic aggregate to apply when mode is CUSTOM. Number parameters use the displayType attribute to determine if the aggregate is restricted to VALUE or STATE types. All other parameter types are restricted to STATE types. VALUE Types: [INTERPOLATED, AVERAGE, MEDIAN, TOTAL, MIN, MAX, RANGE, CHANGE, COUNT, START, END, DELTA]. STATE Types: [CHANGE, COUNT, START, END]
period
String Aggregation interval. AUTOMATIC determines interval based on zoom level. CUSTOM uses fixed interval attribute.
interval
String OPC Interval (eg. 1H) required when period is FIXED.
intervalInclude
String Optional - Default is PARTIAL. COMPLETE will include aggregated values for complete intervals only. PARTIAL will also include values for non-complete intervals: [PARTIAL, COMPLETE]
baseTime
String OPC Base Time (eg. D) required when period is FIXED.
baselineType
String Optional - Default is ABSOLUTE. Absolute will return data point values unmodified. Relative will subtract the first data point value from all subsequent data point values: [ABSOLUTE, RELATIVE]

Example Line series:

{
    "chart": {
        "_class": "io.eagle.models.node.point.chart.LineChart",
        "stateThresholds": "ALL",
        "markerType": "AUTOMATIC",
        "markerSize": 2,
        "qualityStyle": "MARKER_HOVER",
        "shadow": false,
        "primaryColor": "AUTOMATIC",
        "fillStyle": "NONE",
        "fillOpacity": 75,
        "lineWidth": 1,
        "lineType": "NORMAL",
        "lineStyle": "SOLID",
        "aggregation": {
            "mode": "AUTOMATIC"
        }
    }
}

Example updating to stepped Line series with custom gradient fill:

{
    "chart": {
        "_class": "io.eagle.models.node.point.chart.LineChart",
        "primaryColor": "#33ff00",
        "secondaryColor": "#ff0000",
        "fillStyle": "LINEAR_TOP",
        "fillOpacity": 100,
        "lineType": "STEP_LEFT"
    }
}

Example Column series with hourly totals:

{
    "chart": {
        "_class": "io.eagle.models.node.point.chart.ColumnChart",
        "markerSize": 0,
        "primaryColor": "AUTOMATIC",
        "fillStyle": "SOLID",
        "fillOpacity": 100,
        "pointPlacementType": "ON",
        "groupType": "NORMAL",
        "aggregation": {
            "mode": "CUSTOM",
            "type": "TOTAL",
            "period": "FIXED",
            "interval": "1H",
            "baseTime": "D"
        }
    }
}

Rating configuration

Rating configuration can be included in the update request for Rating Parameter nodes. An inputNodeId is required which specifies the Number Parameter to use as the input for the rating calculations. Multiple ratings can be added, with the startTime used to determine the data range each rating will apply.

Note

Rating configuration updates will replace any existing ratings and trigger historic data to be recalculated for this parameter.

Rating attributes Type Description
inputNodeId ObjectId Node _id to be used as the input for the rating calculations. Must be a Number parameter in the same Workspace as this Rating parameter.
ratings Array Rating table and rating equation objects (as documented below).
Rating table Type Description
startTime Time Required. ISO8601 timestamp of the start range this rating will be applied. End range is automatically set to the startTime of the next most recent rating or will continue to apply to new data if no other ratings are specified.
table Array Lookup table for rating calculations with each row specified as an array of input and result. Values that fall between each input lookup will be derived by linear interpolation.
[<input>, <result>]
Array Required. The numeric value of the input node to match and corresponding result.
Rating equation Type Description
startTime Time Required. ISO8601 timestamp of the start range this rating will be applied. End range is automatically set to the startTime of the next most recent rating or will continue to apply to new data if no other ratings are specified.
equationType String POLYNOMIAL is currently the only supported rating equation.
coefficients Object Map of coefficient key and corresponding value. The coefficient keys must be single letters, ordered alphabetically.

Example rating configuration:

{
    "rating": {
        "inputNodeId": "5ec206f9309acc31a896c3b9",
        "ratings": [
            {
                "startTime": "2020-01-01T00:00:00Z",
                "table": [
                    [0.1, 9.8],
                    [0.5, 40],
                    [1.2, 120]
                ]
            },
            {
                "startTime": "2020-10-24T11:00:00Z",
                "table": [
                    [0.1, 7.8],
                    [0.2, 18.3],
                    [0.6, 44.2],
                    [1.1, 130.4]
                ]
            },
            {
                "startTime": "2020-11-01T11:00:00Z",
                "equationType": "POLYNOMIAL",
                "coefficients": {
                    "a": 1.1,
                    "b": 2.5,
                    "c": 1.115,
                    "d": 4.01,
                    "e": 0.85
                }
            }
        ]
    }
}

In this example, Discharge is calculated using 2 rating lookup tables and 1 rating polynomial. The inputNodeId is set to the _id of the Water Level parameter. A water level value of 0.1 will result in an output value of 9.8 for data at the beginning of 2020. Water level 0.1 will result in an output value of 7.8 for data in the range starting 24th October. From 1st November onwards, a polynomial equation will be applied using the coefficients a, b, c, d, e.


Delete a node

Delete a node by its id including all child nodes. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Note

This will permanently delete the node including all historic data and events. Required API key permission: Modify

Request

DELETE /api/v1/nodes/:id

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 200,
        "message": "Success"
    }
}

Clone a node or create instance from template

Clone a node or create an instance from a template by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

When the node being cloned is not a Workspace you must specify a valid parentId as the destination for the clone/create operation. Optionally include name and metadata to be assigned to the newly created node.

Note

Not available for TRIAL accounts. Required API key permission: Modify. Cloning a workspace requires the API key to have ‘All workspaces’ access level.

Arguments

Argument Example Description
attr _id,slug Optional. Comma delimited list of attributes to include in response
type TREE Optional - Default is LIST [4] | LIST returns a flat list of nodes | TREE returns hierarchical list of nodes
expiry 60 Optional. Expiry period in minutes for any included resource links. ie. fileUrl for Attachments. Default is 0 (no expiry). Expired resource links will return 403 Forbidden.

Request

POST /api/v1/nodes/:id/clone
{
    "parentId": "5a554eed0b64aabe5738da86"
    "name": "Copy of Location 1",
    "metadata": [
        "name": "Site ID",
        "value": "abc123"
    ]
}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
[
    {
        "_id": "5ae809d73549e867c71900db",
        "_class": "io.eagle.models.node.location.Location",
        "parentId": "5a554eed0b64aabe5738da86",
        "name": "Copy of Location 1",
        "metadata": [
            "name": "Site ID",
            "value": "abc123"
        ],
        "ownerId": "56d3a61a09c7aa9a82765540",
        "createdTime": "2018-05-01T06:31:51.907Z",
        "workspaceId": "5a554eed0b64aabe5738da86"
    }
]

Acknowledge node alarms

Acknowledge active alarms for a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. Optionally provide a comment for the acknowledgement.

Note

Only available for Location, Source and Parameter nodes. Required API key permission: Modify

Arguments

Argument Example Description
alarmTypes stateAlarm,qualityAlarm Optional - Default is ALL. Comma delimited list of specific alarms to acknowledge: [communicationsAlarm, configurationAlarm, controlAlarm, outdatedAlarm, overloadAlarm, processAlarm, qualityAlarm, stateAlarm]

Request

POST /api/v1/nodes/:id/alarms/acknowledge
{
    "comment": "maintenance team investigating"
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Clear node alarms

Clear active and acknowledged alarms for a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Note

Only available for Location, Source and Parameter nodes. Required API key permission: Modify

Arguments

Argument Example Description
alarmTypes stateAlarm,controlAlarm Optional - Default is ALL. Comma delimited list of specific alarms to clear: [communicationsAlarm, configurationAlarm, controlAlarm, outdatedAlarm, overloadAlarm, processAlarm, qualityAlarm, stateAlarm]

Request

POST /api/v1/nodes/:id/alarms/clear

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Trigger an acquisition

Trigger an acquisition (Acquire Now) for a Source node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Note

Only available for Source nodes with Transports that allow for manual collection. Required API key permission: Modify

Request

POST /api/v1/nodes/:id/operate/acquire

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Retrieve user and group notification preferences

Retrieve a list of all users and groups subscribed to receive notifications for a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Arguments

Argument Example Description
subscribeType NODE Optional - Default is NODE. Users and Groups to return in the response: [NODE, BRANCH, ALL]. NODE includes users & groups subscribed to this node. BRANCH includes users & groups subscribed to this node and any nodes it contains. ALL includes all users & groups that have access to the node (and can be subscribed) regardless of current subscription state. This can used to retrieve user notification preferences for a workspace prior to subscribing to notifications.

Request

GET /api/v1/nodes/:id/notifications

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "users": [
        {
            "name": {
                "last": "Jones",
                "first": "Bob"
            },
            "contact": {
                "email": "bob@company.com"
            },
            "account": {
                "lastLoginTime": "2018-02-27T01:05:02.029Z"
            },
            "notificationCategories": [
                {
                    "category": "Maintenance",
                    "email": true,
                    "sms": false
                },
                {
                    "category": "Operations",
                    "email": true,
                    "sms": true
                },
                {
                    "category": "Critical",
                    "email": true,
                    "sms": false
                }
            ]
        }
    ],
    "groups": [
        {
            "group": "Engineers",
            "users": [
                {
                    "name": {
                        "last": "Smith",
                        "first": "Will"
                    },
                    "contact": {
                        "email": "will@company.com"
                    },
                    "account": {
                        "lastLoginTime": ""
                    },
                    "notificationCategories": [
                        {
                            "category": "Maintenance",
                            "email": true,
                            "sms": true
                        },
                        {
                            "category": "Operations",
                            "email": true,
                            "sms": true
                        },
                        {
                            "category": "Critical",
                            "email": true,
                            "sms": true
                        }
                    ]
                }
            ]
        }
    ]
}

Update user notification preferences

Update user notification preferences for a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

This allows for notificationCategories to have email and sms enabled or disabled per category. These preferences apply to all node notification subscriptions within the Workspace. Only categories with changed attributes need to be included in the update. If the category specified does not exist it will be ignored.

When subscribing groups to notifications you still need to update notification preferences for individual users of the group.

The response includes updated profiles for all requested users.

Note

The specified users (email addresses) must be valid workspace users. Required API key permission: Modify.

You must also subscribe users and groups to notifications for the specific nodes they want to receive notifications from.

Request

POST /api/v1/nodes/:id/notifications
{
    "users": [
        {
            "user": "bob@company.com",
            "notificationCategories": [
                {
                    "category": "Critical",
                    "email": true,
                    "sms": true
                }
            ]
        },
        {
            "user": "will@company.com",
            "notificationCategories": [
                {
                    "category": "Operations",
                    "sms": false
                },
                {
                    "category": "Critical",
                    "email": false,
                    "sms": false
                }
            ]
        }
    ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "users": [
        {
            "user": "bob@company.com",
            "notificationCategories": [
                {
                    "category": "Maintenance",
                    "email": false,
                    "sms": false
                },
                {
                    "category": "Operations",
                    "email": false,
                    "sms": false
                },
                {
                    "category": "Critical",
                    "email": true,
                    "sms": true
                }
            ]
        },
        {
            "user": "will@company.com",
            "notificationCategories": [
                {
                    "category": "Maintenance",
                    "email": true,
                    "sms": true,
                },
                {
                    "category": "Operations",
                    "email": true,
                    "sms": false
                },
                {
                    "category": "Critical",
                    "email": false,
                    "sms": false
                }
            ]
        }
    ]
}

Subscribe users and groups to notifications

Subscribe a list of users and groups to receive notifications for a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Note

Only available for Location, Source and Parameter nodes. The specified users (email addresses) must be valid workspace users. Required API key permission: Modify

Request

POST /api/v1/nodes/:id/notifications/subscribe
{
    "users": [
        {
            "user": "john@company.com"
        },
        {
            "user": "bob@company.com"
        }
    ],
    "groups": [
        {
            "group": "Engineers"
        }
    ]
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Unsubscribe users and groups from notifications

Unsubscribe a list of users and groups from receieving notifications for a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Note

Only available for Location, Source and Parameter nodes. Required API key permission: Modify

Request

POST /api/v1/nodes/:id/notifications/unsubscribe
{
    "users": [
        {
            "user": "john@company.com"
        },
        {
            "user": "bob@company.com"
        }
    ],
    "groups": [
        {
            "group": "Engineers"
        }
    ]
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Retrieve Workspace user and group permissions

Retrieve a list of all users and groups with access to a workspace (or node) by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. When a user is included in a group that has been provided access, the user entry may contain an effectivePermissions attribute which combines individual user and group(s) permissions (where different).

Request

GET /api/v1/nodes/:id/security

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "users": [
        {
            "name": {
                "last": "Smith",
                "first": "John"
            },
            "contact": {
                "email": "john@company.com"
            },
            "account": {
                "lastLoginTime": "2018-05-01T01:21:59.735Z"
            },
            "role": "OWNER",
            "permissions": [
                "VIEW",
                "ATTACHMENT_READ",
                "EXPORT_DATA",
                "SEND_MESSAGE",
                "SUBSCRIBE_NOTIFICATIONS",
                "MANAGE_NOTIFICATIONS",
                "ACKNOWLEDGE_ALARMS",
                "EDIT_ALARMS",
                "CONTROL",
                "CONFIGURE",
                "SECURITY",
                "OWNER"
            ]
        },
        {
            "name": {
                "last": "Jones",
                "first": "Bob"
            },
            "contact": {
                "email": "bob@company.com"
            },
            "account": {
                "lastLoginTime": "2018-02-27T01:05:02.029Z"
            },
            "role": "",
            "permissions": []
            "effectivePermissions": [
                "VIEW"
            ]
        }
    ],
    "groups": [
        {
            "group": "Engineers",
            "role": "View",
            "permissions": [
                "VIEW"
            ],
            "users": [
                {
                    "user": "bob@company.com"
                }
            ]
        }
    ]
}

Note

When retrieving permissions for a node it will return permissions that have been directly set on this node (or the Workspace) and not inherited node permissions.


Add or Update Workspace user and group permissions

Add a list of users and groups to a Workspace by its id and set or update user security roles. You can use the automatically assigned _id or your own customId prepended with ‘@’. You must specify a valid role name that has been preconfigured in account settings.

If the user (email address) does not already exist a new user profile will be created and a profileActivateUrl will be returned so the user profile can be finalized by navigating to the url in a web browser. When adding a new user (profile does not exist) you can optionally include attributes: name, phone, timezone, timezoneAdjustForDst, timeFormat and notificationCategories.

Note

Required API key permission: Modify

Arguments

Argument Example Description
notify TRUE Optional - Default is FALSE. Notify users they have been granted workspace access

Request

POST /api/v1/nodes/:id/security/subscribe
{
    "users": [
        {
            "user": "bob@company.com",
            "role": "View"
        },
        {
            "user": "jane@company.com",
            "role": "Operate",
            "expiryTime": "2019-11-05T05:24:32.000+0000"
            "name": {
                "first": "Jane",
                "last": "Smith"
            },
            "phone": "+61400000001",
            "timezone": "Australia/Sydney",
            "timezoneAdjustForDst": true,
            "timeFormat": "YYYY-MM-DD HH:mm:ss"
        }
    ],
    "groups": [
        {
            "group": "Engineers",
            "role": "View"
        }
    ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "added": [
        {
            "user": "jane@company.com",
            "role": "Operate",
            "permissions": [
                "VIEW",
                "ATTACHMENT_READ",
                "EXPORT_DATA",
                "SEND_MESSAGE",
                "ACKNOWLEDGE_ALARMS",
                "EDIT_ALARMS",
                "CONTROL",
                "SUBSCRIBE_NOTIFICATIONS"
            ],
            "expiryTime": "2019-11-05T05:24:32.000+0000",
            "profileActivateUrl": "https://app.eagle.io/auth/setupprofile/ca4d1da0-8231-46df-af69-df1b2f1a8b5d"
        },
        {
            "group": "Engineers",
            "role" : "View",
            "permissions": [
                "VIEW"
            ],
            "users": [
                {
                    "user": "will@company.com",
                    "profileActivateUrl": "https://app.eagle.io/auth/setupprofile/bb2d3fc9-7399-26dc-ca22-ee2b6f0b6a0c"
                }
            ]
        }
    ],
    "updated": [
        {
            "user": "bob@company.com",
            "role": "View",
            "permissions": [
                "VIEW"
            ]
        }
    ]
}

Remove users and groups from a Workspace

Remove a list of users and groups from a Workspace by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Note

Owner and Administrator users can not be removed from an individual workspace. Required API key permission: Modify

Arguments

Argument Example Description
notify TRUE Optional - Default is FALSE. Notify users they have had their workspace access revoked

Request

POST /api/v1/nodes/:id/security/unsubscribe
{
    "users": [
        {
            "user": "jane@company.com"
        }
    ],
    "groups": [
        {
            "group": "Engineers"
        }
    ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "removed": [
        {
            "user": "jane@company.com"
        },
        {
            "group": "Engineers"
        }
    ]
}

Retrieve node historic data

Retrieve historic data from a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. Data can be returned in JSON (JTS) or CSV format. Use the Historic resource for extracting historic data from multiple nodes in a single request.

Note

Only available for Location and Parameter nodes.

Arguments

Argument Example Description
format JSON Optional - Default is JSON. Data format to return: [JSON, CSV]
startTime 2014-08-16T02:00:00Z Required. [5] ISO8601 url encoded timestamp
endTime 2014-08-16T02:20:43Z Required. [5] ISO8601 url encoded timestamp
limit 100 Optional. Maximum number of historic records to be returned.
timezone Etc/UTC Optional - Default is Etc/UTC. Timezone applied to timestamps. Aggregate interval and baseTime calculations will also use this zone.
timezoneAdjustForDst FALSE Optional - Default is FALSE. Flag to indicate if timestamps should be adjusted for DST in selected timezone.
timeQuery RECORD Optional - Default is RECORD. Timestamp to query by. MODIFIED will query by modified timestamp (typically used to obtain records changed since a specific timestamp): [RECORD, MODIFIED]
timeFormat YYYY-MM-DD HH:mm:ss Optional. Time format to use when format is ‘CSV’.
header TRUE Optional - Default is TRUE. Flag to include header
delimiter , Optional - Default is ‘,’. Delimiter character to use (in CSV format).
textQualifier Optional - Default is ‘”’. Text qualifier character to use (in CSV format).
quality NONE Optional - Default is NONE. Specify how quality should be output (in CSV format): [NONE, DELIMITED_WITH_VALUE, SEPARATE_VALUE]
qualityDelimiter : Optional - Default is ‘:’. Delimiter to use when quality is ‘DELIMITED_WITH_VALUE’.
qualityExcluded BAD,UNCERTAIN Optional - Default uses account settings Exclude quality. Comma separated list of data point quality types to be excluded: [GOOD, BAD, UNCERTAIN or NONE]
annotation NONE Optional - Default is NONE. Specify how annotations should be output (in CSV format): [NONE, DELIMITED_WITH_VALUE, SEPARATE_VALUE]
annotationDelimiter ; Optional - Default is ‘;’. Delimiter to use when annotation is ‘DELIMITED_WITH_VALUE’.
renderType VALUE Optional - Default is node displayType. Rendering of value: [VALUE, STATE]
renderFormat 0.000 Optional - Default is node format. Format to apply when renderType is VALUE. ‘#’ must be URL Encoded as ‘%23’.
aggregate AVERAGE Optional - Default is NONE (raw). Historic aggregate to apply to extracted data.
baseTime D Optional. OPC Base Time required for aggregation.
interval 3H Optional. OPC Interval required for aggregation.
intervalInclude PARTIAL Optional - Default is PARTIAL. COMPLETE will include aggregated values for complete intervals only. PARTIAL will also include values for non-complete intervals: [PARTIAL, COMPLETE]
baselineType RELATIVE Optional - Default is ABSOLUTE. Absolute will return data point values unmodified. Relative will subtract the first data point value from all subsequent data point values: [ABSOLUTE, RELATIVE]
[5](1, 2) startTime or endTime can be omitted when limit is specified.

Request

GET /api/v1/nodes/:id/historic

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "docType": "jts",
    "version": "1.0",
    "header": {
        "startTime": "2014-08-16T02:00:00.000Z",
        "endTime": "2014-08-16T02:20:43.000Z",
        "recordCount": 5,
        "columns": {
            "0": {
                "id": "541a5a129bc9b4035f906d70",
                "name": "Temperature",
                "dataType": "NUMBER",
                "aggregate": "NONE"
            }
        }
    },
    "data": [
        {
            "ts": "2014-08-16T02:00:39.000Z",
            "f": { "0": {"v": 28.21 } }
        },
        {
            "ts": "2014-08-16T02:05:40.000Z",
            "f": { "0": {"v": 28.22 } }
        },
        {
            "ts": "2014-08-16T02:10:41.000Z",
            "f": { "0": {"v": 28.7 } }
        },
        {
            "ts": "2014-08-16T02:15:42.000Z",
            "f": { "0": {"v": 29.2 } }
        },
        {
            "ts": "2014-08-16T02:20:43.000Z",
            "f": { "0": {"v": 29.18 } }
        }
    ]
}

Retrieve node historic chart

Retrieve historic chart image from a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. Chart images can be returned in PNG, JPG, SVG and PDF format.

If a chart node is specified, you can optionally specify: format, width, height, title, subtitle, startTime, endTime, timezone, timezoneAdjustForDst.

If a parameter node is specified, the nodes’ pre-configured (or default) chart settings will be used but you can optionally specify any of the arguments below. Use the Historic resource chart endpoint for generating an adhoc chart using data from multiple parameters in a single request.

Note

Only available for Parameter and Custom Chart nodes.

Arguments

Argument Example Description
format PNG Optional - Default is PNG. Image format to return: [PNG, JPG, SVG, PDF]
width 1200 Optional - Default is 1200. Width of image (png, jpg) in pixels
height 800 Optional - Default is 800. Height of image (png, jpg) in pixels
scale 2 Optional - Default is 1. Multiplier to adjust image dimensions (png, jpg) for higher resolution output: 1-4.
title My Chart Optional. Title to display on chart
subtitle Generated by eagle.io Optional. Subtitle to display on chart
startTime 2014-08-16T02:00:00Z Required. ISO8601 url encoded timestamp
endTime 2014-08-16T02:20:43Z Required. ISO8601 url encoded timestamp
timezone Etc/UTC Optional - Default is Etc/UTC. Timezone applied to timestamps. Aggregate interval and baseTime calculations will also use this zone
timezoneAdjustForDst FALSE Optional - Default is FALSE. Flag to indicate if timestamps should be adjusted for DST in selected timezone
renderType [6] VALUE Optional - Default is node displayType. Rendering of value: [VALUE, STATE]
aggregate [6] AVERAGE Optional - Default is NONE (raw). Historic aggregate to apply to extracted data
baseTime [6] D Optional. OPC Base Time required for aggregation
interval [6] 3H Optional. OPC Interval required for aggregation
intervalInclude [6] PARTIAL Optional - Default is PARTIAL. COMPLETE will include aggregated values for complete intervals only. PARTIAL will also include values for non-complete intervals: [PARTIAL, COMPLETE]
baselineType [6] RELATIVE Optional - Default is ABSOLUTE. Absolute will return data point values unmodified. Relative will subtract the first data point value from all subsequent data point values: [ABSOLUTE, RELATIVE]
[6](1, 2, 3, 4, 5, 6) Only available when specifying a parameter node.

Request

GET /api/v1/nodes/:id/historic/chart

Response

HTTP/1.1 200 OK
Content-Type: image/png;
../../_images/api_resources_nodes_historic_chart.jpg


Retrieve node report

Generate and retrieve a PDF file from a report node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Note

The reporting feature is currently a pre-release version that is subject to change without notice and is only available to limited accounts.

Arguments

Argument Example Description
nowTime 2021-06-01T00:00:00Z Optional. Default is null (current time). ISO8601 url encoded timestamp to use for report generation. All current values and historic records are relative to this timestamp.
timezone Etc/UTC Optional - Default is report timezone. Timezone applied to timestamps. Only specify to override the default report timezone.
timezoneAdjustForDst FALSE Optional - Default is report timezone adjust for dst. Flag to indicate if timestamps should be adjusted for DST in selected timezone Only specify to override the default report timezone.

Request

GET /api/v1/nodes/:id/report

Response

HTTP/1.1 200 OK
Content-Type: application/pdf;
../../_images/api_resources_nodes_report.jpg


Update Parameter or Location historic data

Update historic data for a Parameter or Location node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. Data can be inserted in JSON (JTS) or CSV format. Use the Historic resource to update historic data for multiple nodes in a single request.

Note

Only available for Location and Parameter nodes. Required API key permission: Modify

Arguments

Argument Example Description
format JSON Optional - Default is JSON. Data format being inserted: [JSON].
writeMode MERGE_OVERWRITE_EXISTING Optional - Default is MERGE_OVERWRITE_EXISTING. See all available write mode options.
notifyOn LATEST_ONLY Optional - Default is LATEST_ONLY. When to generate events, raise alarms and send notifications: [ALL_NEWER, LATEST_ONLY, NONE]. ALL_NEWER: All events newer than parameter current value. LATEST_ONLY: Latest event newer than parameter current value.
columnIndex 0 Optional - Default is 0. Index of column in data to be associated with this parameter. Will use index specified in JTS Doc header if available or default to 0.

Request

PUT /api/v1/nodes/:id/historic
{
    "docType": "jts",
    "version": "1.0",
    "data": [
        {
            "ts": "2014-09-17T07:30:00Z",
            "f": { "0": {"v": 25.05 } }
        },
        {
            "ts": "2014-09-17T07:40:00Z",
            "f": { "0": {"v": 25.20 } }
        },
        {
            "ts": "2014-09-17T07:50:00Z",
            "f": { "0": {"v": 25.14 } }
        }
    ]
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Update Data Source historic data

Update historic data for multiple parameters via a Data Source node id. You can use the automatically assigned _id or your own customId prepended with ‘@’. Data can be inserted in JSON (JTS) format. New parameters will be automatically created.

The JTS Document must contain header columns. Each column must either specify a series or parameter id. If id is provided it will be used to match to the associated parameter under the current Data Source, otherwise the associated parameter will be matched using the series attribute.

If a column specified in the header can not be matched to an existing parameter (and series was provided), a new parameter will be created automatically. Optionally specify name, dataType (NUMBER, TEXT, TIME. Default is NUMBER) and units in the column header which will be used when creating new parameters.

Note

Only available for Datasource nodes. Required API key permission: Modify

Arguments

Argument Example Description
format JSON Optional - Default is JSON. Data format being inserted: [JSON].
writeMode MERGE_OVERWRITE_EXISTING Optional - Default is MERGE_OVERWRITE_EXISTING. See all available write mode options.
notifyOn LATEST_ONLY Optional - Default is LATEST_ONLY. When to generate events, raise alarms and send notifications: [ALL_NEWER, LATEST_ONLY, NONE]. ALL_NEWER: All events newer than parameter current value. LATEST_ONLY: Latest event newer than parameter current value.

Request

PUT /api/v1/nodes/:id/historic
{
    "docType": "jts",
    "version": "1.0",
    "header" : {
        "columns": {
            "0": {
                "series": "temp1",
                "name": "Temperature",
                "dataType": "NUMBER",
                "units": "°C"
            },
            "1": {
                "id": "541a5a129bc9b4035f906d71"
            }
        }
    },
    "data": [
        {
            "ts": "2014-09-17T07:30:00Z",
            "f": { "0": { "v": 25.05 } }
        },
        {
            "ts": "2014-09-17T07:40:00Z",
            "f": { "0": { "v": 25.20 } }
        },
        {
            "ts": "2014-09-17T07:50:00Z",
            "f": { "0": { "v": 25.14 }, "1": { "v": "text data here" } }
        }
    ]
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Update node historic data with a single value

Update historic data for a node with a single record. You can use the automatically assigned _id or your own customId prepended with ‘@’. You must specify at least one record attribute: value, quality, annotation. If timestamp is omitted the time the request was made will be used. Existing records with the same timestamp will be overwritten.

Note

Only available for Location and Parameter nodes. Required API key permission: Modify

Request

PUT /api/v1/nodes/:id/historic/now
{
    "value": 10,
    "quality": 156,
    "annotation": "maintenance performed at site",
    "timestamp": "2019-01-09T23:38:00Z"
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Delete node historic data

Delete all historic data from a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’.

Note

Only available for Location and Parameter nodes. Required API key permission: Modify

Request

DELETE /api/v1/nodes/:id/historic

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Retrieve node events

Retrieve events related to a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. Use the Events resource for retrieving events related to multiple nodes in a single request.

Arguments

Argument Example Description
startTime 2017-08-16T02:00:00Z Optional. ISO8601 url encoded timestamp
endTime 2017-08-16T02:20:43Z Optional. ISO8601 url encoded timestamp
attr eventTime,message Optional. Comma delimited list of attributes to include in response
filter level($eq:DEBUG) Optional. Filter the records based on attribute value(s). Note: eventTime can not be used as a filter
limit 100 Optional - Default is 1000 if both startTime & endTime are not specified. Maximum number of records to be returned.
skip 50 Optional. Skip the first n records returned. Can be used with limit to paginate results
sort eventTime(DESC) Optional - Default is eventTime(ASC). Comma delimited list of attributes to sort by. Optionally include sort direction in parentheses or default to ASC: [ASC, DESC]

Request

GET /api/v1/nodes/:id/events

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
    {
        "_class": "io.eagle.models.event.Event",
        "_id": "58d3508c8d6a80f2bd7eaf2e",
        "alarmState": "NONE",
        "message": "Processed 60 records from sensors.dat [4 parameters updated]",
        "eventType": "ACQUISITION",
        "eventTime": "2017-03-23T04:35:24.000Z",
        "nodeId": "57d799d86a559fb79215b5c1",
        "nodeType": "io.eagle.models.node.source.data.TextParser",
        "level": "DEBUG",
        "workspaceId": "57e0a4d8a19b65042ad079c2",
        "username": "System"
    },
    {
        "_class": "io.eagle.models.event.Event",
        "_id": "58d0b9df0bb36d2965e5b745",
        "alarmState": "NONE",
        "message": "Rename node 'Cond' to 'Conductivity'",
        "eventType": "CONFIGURATION",
        "eventTime": "2017-03-21T05:27:59.000Z",
        "nodeId": "58bf63d57426a2b19ea63f54",
        "nodeType": "io.eagle.models.node.point.NumberPoint",
        "level": "INFO",
        "workspaceId": "577b5a821f704bb5a3f1411b",
        "username": "user@company.com"
    }
]

Create node events

Create new event(s) for a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. Multiple events can be created for the node in a single request by providing an Array of Events in the request body. The event requires a message and optional eventTime. Events created via the API are assigned level: INFO, eventType: CONFIGURATION, alarmState: NONE.

Note

Required API key permission: Modify

Attributes

Attribute Type Description
message String Required. Event description. 1-500 characters.
eventTime Time Optional. ISO8601 timestamp associated with the event. If not specified the time the request was made will be used.

Request

POST /api/v1/nodes/:id/events
[
    {
        "message": "Configuration and Site Acceptance Test complete"
    },
    {
        "message": "New event created via API with optional timestamp",
        "eventTime": "2019-10-20T02:32:55.000Z"
    }
]

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

Delete node events

Delete all events related to a node by its id. You can use the automatically assigned _id or your own customId prepended with ‘@’. A new event “Cleared events” will be created to indicate this action occurred.

Note

Required API key permission: Modify

Request

DELETE /api/v1/nodes/:id/events

Response

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
    "status": {
        "code": 202,
        "message": "Operation accepted but not yet complete"
    }
}

PDF HTML Epub Powered by Read The Docs