1.             General Rules

Every API need the Application key, submitted with the request header “Ocp-Apim-Subscription-Key” as string.

For all requests which will return a list (e.g. list of plants) is a paging implemented which can be defined over Query Parameters. In case that they are missing, only the first n entities will be delivered.

 

All responses and POST parameter will only support application/json output format.

 

After the authentication via OAuth 2 (“Authentication”) is done, all requests have to contain the OAuth2 token as string request header “Authorization”.

1.1          Addressing and View Nodes

It is important to know, that the query over the structure has to use the ViewNodes resource.

Each resource has a system wide unique identifier. The ID is NOT representing any logical structure or navigation guide. To identify the location of the resource the ViewNodes resource has to be used. A view node is a graph of objects to navigate through. There will be no back links available, only forward references.

Currently are only fixed structure supported (TenantàPlantàPages (future real view nodes)àDataPoints), but this will change in the future, therefore it is important to use from the beginning the view nodes instead of assuming a fixed structure.

In case that a resource will be placed under another resource the corresponding id has to be used.

 

 

Every view node is a composition of items and other view nodes. Currently are the following types of view nodes supported:

 

Type

Description

Tenant

The representation of the organizational structure tenant, which represents a tenant (main tenant and sub tenant).

Site

The representation of the organizational structure site, which represents a site.

For future implementation.

Plant

The representation of the organizational structure Plant, which represents a plant.

ViewNode

The ViewNode itself, currently only created from the plant (device)

 

With the view node Type, the client can decide over the best representation and also use this to access the corresponding Resource for additional information (e.g. Type: Tenant à /Tenants).

1.2          Request Header and Query Parameter

Standard Request Header

Request

Header

Data Type

 

Description

Ocp-Apim-Subscription-Key

String

Required

Amount of entries for this property

Authorization

String

Required
(except Authentication API)

OAuth 2.0 access token obtained from API “Authentication”.

 

Standard Query Parameter:

Request

Header

Data Type

Feature

Description

skip

Integer

P

The amount of entities to skip.

take

Integer

P

The amount of entities to return. Depending on the request the max value can be different.

Mean for some request the amount can be bigger than for other requests. This is needed to avoid to huge calls.

sortBy

JSON Array of Objects

P

The sort key and the sort direction, depends on the request if sorting is supported or not.

The result will be sorted according the order inside the array. To support a stable sort order, the default would be the primary key (id).

e.g. &sortBy=[{“ParentName”:”asc”},{“Name”,”desc”}] delivers all Tenants sorted by their father name (Main Tenant name) and then sorted (descending) by the tenant name (Sub Tenant name).

The stable sort is guaranteed, because TenantId is unique and the primary key.

parentId

JSON parent object

 

Some requests need a parent ID (like tenant ID), to assign the resource to a concrete view node.

To identify the resource, the resource type and the unique ID is needed, Currently is only one parent possible, in the future maybe also more than one parent, therefore a array is used:

 

Assign one plant to a tenant:

&parentId=[{“Tenant”:”{id}”}]

 

filterId

JSON objects

F

Contains the IDs (view node or data points ids) which are requested if filtering is needed. The IDs will be entered as JSON array:

In the following example will be two data points from different plants requested:

&filterId=[{“DataPoints“:”07cf5899-e5f2-4b6d-a669-3e0a51578793/1!6WHH6I0EOMMGMC”}, {“DataPoints“:”13a3d393-cf1d-43fe-8e80-8cc1e06bebd3/1!6WHH6I0EOMMGMC”}]

tenantId

String

 

Some Resources needs the tenant ID for administrative users (e.g. Tenant Administrators). This parameter is only need for such users, which like to access plants without be assigned as a plant user. The Administrative user can then access the plants for the given tenant ID and all sub tenants of this ID.

2.             Error Handling

In case that an API call fails, a meaning full result will be delivered back (body). In case that an unhandled exception occurred, the error code contains a GUID.

This unhandled exception will be written to a diagnostic table.

 

Entity columns

Data Type

Description

PartitionKey

Edm.String

The UTC time with date, but without time, Mean with one request we get all errors for one day.

RowKey

Edm.String

The generated Guid of the exception as string. This Guid is delivered to the API caller. The support can then search for the Guid (PartionKey can be empty).

APIcall

Edm.String

The API call with all parameters

TImeStamp

Edm.DateTime

The exact data and time

Exception

Edm.String

The exception string

AdditionalInfo

Edm.String

Optional additional information if available

 

3.             URI

All resources can be accessed via the API, where the Resource name is the first part of the URI. Inside a resource every entity has an own unique ID. The format of the {id} depends on the resource itself and can be changed in the future.

The {id} is a string and can contain any character like a GUID (e.g.: “0a6fe8c0-9c97-4040-83d0-a4fe75b29af8”) or a combination of GUID and names
(e.g.: “0a6fe8c0-9c97-4040-83d0-a4fe75b29af8 /1!6WHH6I0EOMMGMC”).

 

Query schema:

 

URI

 

/<Resource>

Delivers the list the addressed resource.

/<Resource>/{id}

Address a single resource element.

/<Resource>/{id}/<SubResource>

Delivers the list of subordinated resources (e.g. History values).

 

Possible requests:

 

URI

Intention

Implementation

Status

/Tenants

All accessible tenants will be addressed.

available

/Tenants/{id}

The Tenant detail Info

available

/Plants

All accessible plants will be delivered

available

/Plants/{id}

Info over dedicated plant

available

/Plants /{id}/ActiveAlarms

The active alarm list of the Plant/Device.

available

/Plants /{id}/HistoryAlarms

The alarm history of the Plant/Device.

available

/Plants/{id}/Notifications

Creates a new plant notification

available

/Plants/{id}/Upgrade/Status

Report the current status of the device

new

/Plants/{id}/Upgrade/Commands

Controls the manual upgrade commands of the device

new

/Plants/{id}/Upgrade/Automated

Controls the automated upgrade of the device

new

/ViewNodes

Delivers the list of accessible view nodes. Returned will be a list of root view node Ids, with the view node type.

available

/ViewNodes/{id}

All Sub view nodes of the addressed view node. The response can also contain data points.

available

/ViewNodes/{id}/Values

Delivers only the current values of the data points of a view node.

available

/DataPoints/

Address all accessible Data Points.

available

/DataPoints/Values

Delivers only the current values of the data points.

available

/DataPoints/{id}

Address a dedicated Data Point

available

/DataPoints/{id}/History

The historical values of a dedicated data point

available

/UserRoles

All accessible user roles will be addressed

available

/UserRoles/{id}

Address a dedicated user role.

available

/Users

All accessible users will be addressed

available

/Users/{id}

Address a dedicated user.

available

/Account/SignUp

User registration (self sign on)

available

/Account/RequestPasswordReset

Request a password reset

available

/Account/ResetPassword

Perform a password change

available

/ApplicationSets

All accessible application sets will be addressed

available

/ApplicationSets/{id}

Address a dedicated application set

available

/Files

All accessible files will be addressed

available

/Files/{id}

Address a dedicated file

available

/Files/{id}/Content

Address the file content

available

/KPIs

All accessible key performance indicators will be addressed

Later planned

/KPIs/{id}

Address a dedicated key performance indicator

Later planned

/AlarmNotifications

All accessible alarm notifications will be addressed

Later planned

/AlarmNotifications/{id}

Address a dedicated Alarm notification

Later planned

/Devices

Manage all accessible virtual devices

available

/Devices/{id}/Alarms

Mange the alarms for a virtual device

available

4.             Operations

The following request operations are supported, but not every resource will support all requests, in case that a not supported operation is performed, an error is returned.

 

Example:

 

Resource

POST

GET

PUT

DELETE

/Plants

Create a new plant view node

Code = 201

All accessible plants will be delivered

Code = 200

Error 501

Error 501

/Plants/{id}

Error
Code = 501

Details over the Plant (Code = 200) or Error if not exists (Code =

 

Update the plant settings (e.g. address)

Delete the plant and set the assigned device in unassigned state

 

 

4.1          GET

GET to retrieve a copy of the resource at the specified URI. The body of the response message contains the details of the requested resource.

 

If the request is successful, the web server should respond with a message code with HTTP status code 200 and the response body contains the data.

4.2          POST

POST to create a new resource at the specified URI. The body of the request message provides the details of the new resource. Note that POST can also be used to trigger operations that don't actually create resources.

 

If the request is successful, the web server should respond with a message code with HTTP status code 201 (Created). The Location header should contain the URI of the newly created resource, and the body of the response should contain a copy of the new resource; the Content-Type header specifies the format of this data:

 

HTTP/1.1 201 Created

...

Content-Type: application/json; charset=utf-8

Location: /Plants/b67eae1a-8481-4844-8292-4f7031baf219

...

Date: Fri, 10 Mar 2017 07:48:38 GMT

Content-Length: ...

{

    "Id": "a4e11b3c-55a4-44c6-9480-01c14e5a4976",

    "ActivationKey": "UBB2CA-OJY7Y-UJGLK-BH3PK-45VWM",

    "Address": "Berliner Ring 23",

    "AlarmStatus": 0,

    "ApplicationSetDescription": null,

    "ApplicationSetName": null,

    "Asn": "POL687",

    "Assigned": true,

    "City": "Rastatt",

    "Country": "DE",

    "Description": "1406-POL687",

    "EnergyIndicator": 0,

    "IsOnline": true,

    "Name": "DEV12",

    "Phone": "",

    "SerialNumber": "1406",

    "State": "Baden-Württemberg",

    "TaskStatus": 0,

    "Tenant": "Siemens Rastatt",

    "Timezone": "W. Europe Standard Time",

    "ZipCode": "76437"

  }

4.3          PUT

PUT to replace or update the resource at the specified URI. The body of the request message specifies the resource to be modified and the values to be applied. If the resource did not exist, an error is returned. Partially updates are in a first step also supported (for example only the street of a plant setting can be updated and all other fields are not touched).

 

If the modification is successful, it should ideally respond with an HTTP 204 status code, indicating that the process has been successfully handled, but that the response body contains no further information. The Location header in the response contains the URI of the newly updated resource:

 

HTTP/1.1 204 No Content

...

Location: /Plants/ b67eae1a-8481-4844-8292-4f7031baf219

...

Date: Fri, 10 Mar 2017 07:48:38 GMT

4.4          DELETE

DELETE to remove the resource at the specified URI.

To remove a resource, an HTTP DELETE request simply provides the URI of the resource to be deleted.

 

If the delete operation is successful, the web server should respond with HTTP status code 204, indicating that the process has been successfully handled, but that the response body contains no further information (this is the same response returned by a successful PUT operation, but without a Location header as the resource no longer exists.) It is also possible for a DELETE request to return HTTP status code 200 (OK) or 202 (Accepted) if the deletion is performed asynchronously.

 

HTTP/1.1 204 No Content

...

Date: Fri, 10 Mar 2017 07:48:38 GMT

5.             API  usage

CORS is supported from the Climatix API, any domain will be accepted (*).

Hint for correct API usage:

  • Add to your APP the subscription key via the header Ocp-Apim-Subscription-Key,
  • Call the /Token API to get the corresponding Bearer token, add this token to the header Authorization: Bearer <token>
  • Use for all following calls the header Ocp-Apim-Subscription-Key and Authorization must be used.

6.             API -List

The chapter of the API named the API, and inside the chapter are the operations defined. The details of parameter, behavior and functionality can be found direct via the API management portal.

The feature defines the request possibilities:

+ à Supported

à Not supported (Error code 501)

P à Paginating

F à Filtering

Pr à Parameter parentId required

Po à Parameter perentId optional, for easier query.

6.1          Token

This interface is important to get the OAuth2 token, which is needed for all requests to the Climatix IC API.

 

Request: /Token

Request

Features

Result

GET

-

 

POST

+

Create a new OAuth2 token, which must be submitted for all future calls over the Authorization request header.

This token will be active for a given time period.

PUT

-

 

DELETE

-

 

 

6.2          Tenants

Request: /Tenants

Request

Features

Remark

GET

+,P,F,Po

All accessible tenants with the provided user credentials will be returned. All available information over this tenant will be delivered.

Parameter parentId can contain:

-     the parent tenants Id.

POST

+,Pr

Create a new tenant bellow the addressed tenant. Main Tenants cannot be created, only Subtenants.
Currently is only one hierarchy level supported.

Parameter parentId must contain:

-     the parent tenants Id

PUT

-

 

DELETE

-

 

 

Request: /Tenants/{id}

Request

Features

Result

GET

+

The detailed information of a tenant will be returned, includes all known properties

POST

-

 

PUT

+

Update only the delivered properties of the addressed tenant.

DELETE

+

The tenant will be deleted.

 

6.3          Plants

Request: /Plants

Request

Features

Result

GET

+,P,F,Po

All accessible plants with the provided user credentials will be returned. All available information over this plant will be delivered.

Parameter parentId can contain:

-     the parent tenants Id.

POST

+,Pr

Create a new plant.

Parameter parentId must contain:

-     the parent tenants Id

PUT

-

 

DELETE

-

 

 

Request: /Plants/{id}

Request

Features

Result

GET

+

The detailed information of a plant will be returned, includes all known properties

POST

-

 

PUT

+

Update only the delivered properties of the addressed plant.

DELETE

+

The plant will be deleted including all sub view nodes and data points.

 

Request: Plants/{id}/ActiveAlarms

Request

Features

Result

GET

+,P,F

All active alarms will be returned.

POST

-

 

PUT

-

 

DELETE

-

 

 

Request: Plants/{id}/HistoryAlarms

Request

Features

Result

GET

+,P,F

The alarm history of the plant will be returned.

POST

-

 

PUT

-

 

DELETE

-

 

 

Request: Plants/{id}/Notifications

Request

Features

Result

GET

-

 

POST

-

 

PUT

+

This request creates a new plant notification. The following Parameters are needed from the Alarm Object (9.2.1.1):

  • UTCTime (required): Plant UTC time when event occured
  • Class (required): The notification class
  • String (required): The original alarm string from the controller depends on the alarm configuration.
  • Value (optional): Deliver the additional value of the alarm. Value is reported in metric system.
  • TriggerPoint (optional): If the source of the notification is mapped to the cloud it contains the point name which has generated the event.
  • ValuePoint (optional): If the additional value of the alarm is mapped to the cloud it contains the point name.

DELETE

-

 

 

Request: Plants/{id}/Upgrade/Status

Request

Features

Result

GET

+

Delivers the current upgrade status of the plant with the information which are available in the Upgrade view:

POST

-

 

PUT

-

 

DELETE

-

 

 

Request: Plants/{id}/Upgrade/Commands

Request

Features

Result

GET

+,P

Gets a list of Upgrade commands.

POST

+

Create a new Upgrade command. The request delivers back a unique id to query afterwards for the status of this command.  This request will come back immeadatly and trigger only the command inside the cloud.

PUT

-

 

DELETE

-

 

 

Request: Plants/{id}/Upgrade/Commands/{id}

Request

Features

Result

GET

+

Gets the Upgrade command result

1 = active

2 = successful

3 = failed

Additional two strings are delivered with additional information, regarding the request and the result.

POST

+

Create a new Upgrade command. The request delivers back a unique id to query afterwards for the status of this command.  This request will come back immeadatly and trigger only the command inside the cloud.

The following commands are possible:

 

Cmd

invalid

QueryParameter

Description

0x0001

Reset device

-

-

0x0002

Stop application

-

-

0x0003

Start application

-

-

0x0004

Start upgrade process

-

-

0x0005

Create device trace file

fileId={id}

fileId has to contain a valid file id of the /Files resource. For a new file a file object must be created (POST /Files)

0x0006

Create device parameter file

fileId={id}

fileId has to contain a valid file id of the /Files resource. For a new file a file object must be created (POST /Files)

0x0007

Send file to device

fileId={id}
destName={name}

fileId has to contain a valid file id of the /Files resource.

destName is the file name which defines the device local storage location

0x0008

Restore device parameter file

fileId={id}
destName={name}

fileId has to contain a valid file id of the /Files resource.

destName is the file name which defines the device local storage location. The parameter file must be send before over the command 0x0007 to the device

PUT

+

Terminates a running command no parameters are needed. The response delivers in case of failure the error code back.

DELETE

-

 

 

Request: Plants/{id}/Upgrade/Automated

Request

Features

Result

GET

+,P

Gets a list of automated upgrade requests

POST

+

Create a new automated upgrade request. The request delivers back a unique id to query afterwards for the status of this automated upgrade process.  This request will come back immeadatly and trigger only the upgrade process inside the cloud.

 

The body has to contain the following values:

Parameter

Mandatory

Description

schedule

yes

UTC time when the upgrade process will start.

donwloadTimeout

yes

The timeout im minutes until a file must be downloaded from the cloud to the device.

retries

no

The amount of upgrade retries for Climatix devices.

applicationTimeout

no

The application shutdown time for Climatix devices.

notifyReciepient

No

An array of email address which will be informed via email over the upgrade status.

parameterFileId

Yes

The fileId of the parameter file which will be used for restoring the parameters. If null the automatically created parameter file will be used.

bacnetFileId

No

The fileId of the BACnet client file which will be used for restoring the parameters.

comment

No

An optional comment for the upgrade command

 

 

PUT

-

 

DELETE

-

 

 

Request: Plants/{id}/Upgrade/Automated/{id}

Request

Features

Result

GET

+

Gets the upgrade information back:

 

Parameter

Mandatory

Description

schedule

yes

UTC time when the upgrade process will start.

donwloadTimeout

yes

The timeout im minutes until a file must be downloaded from the cloud to the device.

retries

no

The amount of upgrade retries for Climatix devices.

applicationTimeout

no

The application shutdown time for Climatix devices.

notifyReciepient

No

An array of email address which will be informed via email over the upgrade status.

parameterFileId

Yes

The fileId of the parameter file which will be used for restoring the parameters. If null the automatically created parameter file will be used.

bacnetFileId

No

The fileId of the BACnet client file which will be used for restoring the parameters.

comment

No

An optional comment for the upgrade command

currentStatus

Yes

1 = active

2 = successful

3 = failed

4 = timedout

5 = aborted

currenStatusInfo

No

Optional the

startTime

Yes

UTC time when the automated ugrade was planned for,

endTime

No

UTC time when the automatated upgrade has finished

POST

-

 

PUT

+

Abort the automated upgrade process.

DELETE

-

 

 

 

6.4          ViewNodes

Request: /ViewNodes

Request

Features

Result

GET

+,P,F,Po

Delivers the list of accessible view nodes. Returned will be a list of root view node Ids, with their view node type.

Currently will this be the Tenants view nodes.

Parameter parentId can contain:

-     Parent plant Id

-     Parent tenant Id (future).

-     Parent view node Id (future)

POST

-

+,Pr (future)

Create a new view node, under the addressed view node.

Parameter parentId must contain:

-     Parent tenants id

-     Parent plants id

PUT

-

 

DELETE

-

 

 

Request: /ViewNodes/{id}

Request

Features

Result

GET

+

The detailed information of a view node will be returned, includes all known properties

POST

-

 

PUT

-

+ (future)

Update only the delivered properties of the addressed view node.

DELETE

-

+ (future)

The view node will be deleted including all sub view nodes and data points.

 

Request: /ViewNodes /{id}/Values

Request

Features

Result

GET

+

Delivers only the actual values of the referenced view node.

POST

-

 

PUT

-

 

DELETE

-

 

6.5          DataPoints

Request: /DataPoints

Request

Features

Result

GET

+,P,F,Po

Delivers the list of accessible data points. This request delivers the verbose information. If only the current values are needed then the request /DataPoints/Values must be called.

To restrict the amount of delivered points, the parentId or filterId must be used.

Parameter parentId can contain:

-     Parent plant Id

POST

-

+,Pr (future)

Create a new data point.

Parameter parentId must contain:

-     Parent plant id

PUT

-

 

DELETE

-

 

 

Request: /DataPoints/Value

Request

Features

Result

GET

+,P,F,Po

Delivers the list of accessible data points. This request delivers only the current values. For verbose information the request /DataPoints must be called.

To restrict the amount of delivered points, the parentId or filterId must be used.

Parameter parentId can contain:

-     Parent plant Id

POST

-

 

PUT

-

 

DELETE

-

 

 

 

Request: /DataPoints/{id}

Request

Features

Result

GET

+

The detailed information of a data point will be returned, includes all known properties

POST

-

 

PUT

+

Write the new value to the data point. In the future also other properties can be updated.

DELETE

-

+ (future)

The data point will be deleted including historical values.

 

Request: /DataPoints/{id}/History

Request

Features

Result

GET

+,P,F

The historical values of the data point are returned.

POST

-

 

PUT

-

 

DELETE

-

 

6.6          UserRoles

Request: /UserRoles

Request

Features

Result

GET

+,P,F,Po

Delivers the list of accessible user roles with all details.

Parameter parentId can contain:

-     Parent tenant Id

POST

+,Pr

Create a new user role.

Parameter parentId must contain:

-     Parent tenant id

PUT

-

 

DELETE

-

 

 

Request: /UserRoles/{id}

Request

Features

Result

GET

+

The detailed information of a data point will be returned, includes all known properties

POST

-

 

PUT

+

Update the user role

DELETE

+

The user role will be deleted and all reference from users to this role will be also deleted.

6.7          Users

In the current implementation, can only users accessed which are plant related, the administrative users can not be accessed.

 

Request: /Users

Request

Features

Result

GET

+,P,F,Po

Delivers the list of accessible users with all details.

Parameter parentId can contain:

-     Parent tenant Id

-     Parent plant Id

POST

+,Pr

Create a new user.

Parameter parentId must contain:

-     Parent plant Id

PUT

-

 

DELETE

-

 

 

Request: /Users/{id}

Request

Features

Result

GET

+

The detailed information of a user will be returned, includes all known properties

POST

-

 

PUT

+

Update the user

DELETE

+

The user role will be deleted and all reference from users will be also deleted.

 

6.8          Application sets

 

Request: /ApplicationSets

Request

Features

Result

GET

+,P,F,Pr

Delivers the list of accessible application sets with all details.

Parameter parentId must contain:

-     Parent tenant Id

POST

-

+,Pr (future)

Create a new application set.

Parameter parentId must contain:

-     Parent tenant Id

PUT

-

 

DELETE

-

 

 

Request: /ApplicationSets /{id}

Request

Features

Result

GET

+

The detailed information of an application set will be returned, includes all known properties including the files id.

POST

-

 

PUT

-

+ (future)

Update the application set properties, the files cannot be modified, therefore /Files has to be used.

DELETE

-

+ (future)

The application set will be deleted, and all references to the assigned plants, including all files.

 

6.9          Files

Request to Files address only the file metadata, to access the content /Files/{id}/Content has to be used.

 

Request: /Files

Request

Features

Result

GET

+,P,F,Pr

Delivers the list of accessible files with all details.

Parameter parentId must contain:

-     Parent application set Id

-     Parent plants id

POST

+,Pr

Create a new file.

Parameter parentId must contain:

-     Parent application set Id

-     Parent plant id

PUT

-

 

DELETE

-

 

 

Request: /Files /{id}

Request

Features

Result

GET

+

The detailed information of a file will be returned, includes all known properties.

POST

-

 

PUT

-

+ (future)

Update the file properties.

DELETE

-

+ (future)

The file will be deleted, and all references to the assigned application sets.

 

Request: /Files /{id}/Content

Request

Features

Result

GET

+

The http download will start.

POST

-

 

PUT

+

Http upload of the file content.

DELETE

+

Delete the file content.

6.10       KPIs

Request: /KPIs

Request

Features

Result

GET

+,P,F,Po

Delivers the list of key performance indicators with all details.

Parameter parentId can contain:

-     Parent tenant Id

POST

+,Pr

Create a new key performance indicator.

Parameter parentId must contain:

-     Parent tenant Id

PUT

-

 

DELETE

-

 

 

Request: /KPIs /{id}

Request

Features

Result

GET

+

The detailed information of the key performance indicator will be returned, includes all known properties.

POST

-

 

PUT

+

Modify the key performance indicator.

DELETE

+

Delete the key performance indicator.

6.11       AlarmNotifications

 

Request: /AlarmNotifications

Request

Features

Result

GET

+,P,F,Po

All accessible alarm notifications will be returned.

Parameter parentId can contain:

-     Parent plant Id

POST

-

 

PUT

-

 

DELETE

-

 

 

Request: /AlarmNotifications /{id}

Request

Features

Result

GET

+

The detailed information of the alarm notification will be returned, includes all known properties.

POST

-

 

PUT

+

Modify the alarm notification.

DELETE

+

Delete the alarm notification.

6.12       Devices

Request: /Devices

Request

Features

Result

GET

-

 

POST

+,Pr

Create a virtual device and the corresponding plant.

Parameter parentId must contain:

-     Parent tenant Id

The body has to contain the same information like for a plant creation.

The response has to contain the virtual device user. This user has a virtual email address and a fixed automatically created password. This user credentials are then needed to access the APIs. This user is a normal plant user, and if the password is known also the Web UI will work.

The plant will get a new entry in assignedResources to identify the {id} for Devices like:

“VirtualDevices”:["52249740-258D-48BA-81FC-966B341D8DAB"].

PUT

-

 

DELETE

-

 

 

Request: /Devices/{id}

Request

Features

Result

GET

-

 

POST

-

 

PUT

+

Allow only the modification of the Online Property. This must be called from the gateway to confirm that the gateway has received the user from type VirtualDevicePlantRole.

Also the gateway has to use this call to tell the cloud that the Gateway is online.

DELETE

-

 

 

Request: /Devices/{id}/Alarms

Request

Features

Result

GET

-

 

POST

-

 

PUT

+

This request creates a new plant alarm via the virtual device. The following JSON object must be proviced which is similar to the Alarm Report (9.2.1.1):

{
  "actState":1,

  "alarms":[
    {
      "id":74272346

      "string":"Value Fault: noSensor",
      "utcTime":23123121,

      "eventState":3,
      "class":2,
      "value":43.3,
      "device":"Local",
      "triggerPoint":"EAABAAAAAGACAA",
      "valuePoint":"FQAN7UJJAQABAA"
    },
    {
      "id":74272346

      "string":"Value Fault: OK",
      "utcTime":231231221,

      "eventState":0,
      "class":3
    }
  ]
}

 

actState (required):

The actual site Alarm status. Enumeration:

-     0: no active alarm (no alarm bell in site overview)

-     1: new alarm (alarm bell shaking in site overview)

-     2: confirmed alarm (alarm bell static in site overview)

 

The alarms array contains the following values:

  • id (required): A unique Alarm Id. Must be identical for the same alarm source, independent from the alarm state. Will be used for the Climatix IC Device API to update the actual alarm list.
  • utcTime (required): Plant UTC time when event occured
  • class (required): The notification class
  • string (required): The original alarm string from the controller depends on the alarm configuration.
  • eventState (required): Indicates if the alarm state changes to active or inactive for Boolean values. If reported as number the following coding is used:

ENUMERATED {
normal (0),
fault (1),
offnormal (2),
high-limit (3),
low-limit (4),
life-safety-alarm (5),
}

  • value (optional): Deliver the additional value of the alarm. Value is reported in metric system.
  • triggerPoint (optional): If the source of the notification is mapped to the cloud it contains the point name which has generated the event.
  • valuePoint (optional): If the additional value of the alarm is mapped to the cloud it contains the point name.

DELETE

-