Attention:

This developer portal is now deprecated. You can continue to use it, as per usual, until its retirement in September 2023, when it will not any more accessible.
Please check the climatixic.com release notes for the portal migration.

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.1.1 Relationship Climatix Watch pages to View nodes

View nodes are the cloud representation of a hierarchical structure. The same is available for the Climatix controller, which will be generated out of the Watch pages in SCOPE. Mean every Watch page in SCOPE is represented inside the controller as a View node object (aoViewNode).

The same will be done if the GenericCloud.csv mapping file from SCOPE is used. Then for every watch page where the cloud mapping is enabled will be one View node for the cloud generated, bellow the controller (plant) view node.

The Climatix controller supports a multi hierarchy level of View nodes, the cloud supports only a flat hierarchy level. The sorting is according the Watch page number and can be influenced inside SCOPE over the Page properties -> Advanced -> HMI page or view node id.

Example for Climatix Watch page engineering:

DeviceRoot (ID=1) -> Page1 (ID=6) -> Page2 (ID=2) -> Page3 (ID=5)
+> Page4 (ID=3) -> Page5 (ID=4)

Inside the controller the same structure is modelled with view nodes according the hierarchy:

DeviceRoot (ID=1) -> Page1 (ID=6) -> Page2 (ID=2) -> Page3 (ID=5) +> Page4 (ID=3) -> Page5 (ID=4)

For the cloud the following View Nodes are generated according the ID and appear in this order:

Plant View Node (<PID1>)    -> DeviceRoot (ID=1)
                                                            +> Page2 (ID=2)
                                                            +> Page4 (ID=3)

+> Page5 (ID=4)

+> Page3 (ID=5)

+> Page1 (ID=6)

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	available
/Plants/{id}/Upgrade/Commands	Controls the manual upgrade commands of the device	available
/Plants/{id}/Upgrade/Automated	Controls the automated upgrade of the device	available
/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. Also, it allows an update of the current value for a virtual cloud item.	available
/DataPoints/{id}	Address a dedicated Data Point	available
/DataPoints/{id}/History	The historical values of a dedicated data point	available
/DataPoints/{id}/EnumerateHistory	Enumerate through 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
/Account/EnforcePasswordChange	Enforce changing of the password for given users	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	available
/AlarmNotifications/{id}	Address a dedicated Alarm notification	available
/Devices	Manage all accessible virtual devices	available
/Devices/{id}/Alarms	Mange the alarms for a virtual device	available
/ReportNotifications	All accessible report notifications will be returned	available
/ReportNotifications/{id}	Address a specific report notification	available
/Analytics/Tenants	Gets all tenants for analytics	available
/Analytics/Plants	Gets all plants of the given tenant for analytics	available
/Analytics/DataPoints	Gets all cloud items of the given plant for analytics	Available
/Analytics/DataPoints/{id}	Gets info of the cloud item incl. history items for analytics in the given timestamp.	Available
/Analytics/PlantMetadata	Adds/Deleted definition for the plant metadata info to the specified tenant.	Available
/Analytics/PlantMetadata/{id}	Gets information for tenant's plant metadata items.	Available

4. Best practices and performance hints

Fetching data point history items: The best approach to fetch datapoint history items for a given time interval is to use the high performing analytics endpoint. The endpoint GET /Analytics/DataPoints/{id} does not include any pagination parameters, therefore the server delivers all history items with a single request. The clients must not deal with different requests their responses containing only 100 items each.

If the client can’t use the analytics endpoint for some reason, consider using the GET /DataPoints/{id}/EnumerateHistory endpoint. It delivers all available history items from a start point of time until no data are available or a maximum of 1000 items is reached. The second request from the client must then only adjust the start date to fetch the next available items, if any.

If the mentioned endpoints does not fit into the client requirements, then the slowest, poorly performing endpoint must be used. The endpoint GET /DataPoints/{id}/History uses too many resources to fetch only a single portion of history items, currently up to 1000. For example, if the client sends a request to fetch history items for 1 month, the server fetches all the data for this month from the storage and delivers only the first 1000 back to the client, the client must wait all the time for the server to finish retrieving the data for one month. After that the client adjusts the skip-parameter and send a new request to fetch the next items, the server goes again and fetch all the data for one month from the storage to deliver only 1000 items. To avoid waiting too long for the server, the client must specify small time intervals. How to define the best time intervals is hard and there is no general rule for that. It all depends on how often a data point is sending item updates. For example, a data point is sending 500 updates (COVs) per minute, so the best interval to set for the start- and end-parameters will be 2 minutes, to fetch exactly 1000 items with one request. But if the data point is sending only 1 item update per minute, using a time interval of 1 day is suitable.

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

/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

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

5.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"

}

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

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

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

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

7.1 Token

This interface is important to get the OAuth2 token, which is needed for all requests to the Climatix IC API. This API must be used to get the OAuth2 token which is needed for all other APIs. Pass in a body in the form grant_type=password&username={username}&password={password}&expire_minutes={minutes} to retrieve the authentication token. The password must be URL encoded (e.g: replace + with %2B). The parameter expire_minutes is optional, the maximal value is 20160 minutes (2 weeks), the default is 2880 minutes (2 days).

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	-

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

Request: /Tenants/{id}/Billing/UsageHistory

Request	Features	Result
GET	+	The usage history of the last 3 years will be aggregated to include only 36 entries (1 entry per month).
POST	-
PUT	-
DELETE	-

Request: /Tenants/{id}/M2MDevices

Request	Features	Result
GET	+	Gets a list of M2M devices for the given tenant.
POST	-
PUT	-
DELETE	-

Request: /Tenants/{id}/M2MDevices/{deviceId}

Request	Features	Result
GET	+	Gets details of the given M2M device.
POST	-
PUT	-
DELETE	-

Request: /Tenants/{id}/ActivationId/{activationId}/Validate

Request	Features	Result
GET	+	Gets information about a redeemable activation id.
POST	-
PUT	-
DELETE	-

Request: /Tenants/{id}/ActivationId/{activationId}/Redeem

Request	Features	Result
GET	-
POST	+	Redeems an activation id.
PUT	-
DELETE	-

Request: /Tenants/{id}/AlarmWebhook

Request	Features	Result
GET	+,P,F	The information for all tenant’s alarm webhooks.
POST	+	Creates a webhook for the given tenant, the following information should be sent in the request body: CallbackUrl (required): The callback URL to call the webhook HttpMethod (optional): The Http method to use for calling the webhook. Allowed methods: POST, PUT. Default: POST SharedSecret (optional): When specified, the request will send an extra X-Climatix-Signature HTTP header with an HMAC+SHA256 signature of the request body ValidateSsl (optional): When using an https endpoint for the callback, this can be set to false to ignore any certificate errors. Defaults to true. This will be useful for testing before actual production deployment of the endpoint. UseForSubTenants (optional): Then specified, the webhook will be valid for plants defined under the sub-tenants.
PUT	-
DELETE	-

Request: /Tenants/{id}/AlarmWebhook/{webhookId}

Request	Features	Result
GET	+	The detailed information for a tenant’s alarm webhook.
POST	-
PUT	+	Updates the information for alarm webhook, only those supplied in the request (See POST method for the available properties).
DELETE	+	Deletes the alarm webhook for the given tenant.

Request: /Tenants/{id}/DataPointValuesWebhook

Request	Features	Result
GET	+,P,F	The information for all tenant’s datapoint values webhooks.
POST	+	Creates a webhook for the given tenant, the following information should be sent in the request body: CallbackUrl (required): The callback URL to call the webhook HttpMethod (optional): The Http method to use for calling the webhook. Allowed methods: POST, PUT. Default: POST SharedSecret (optional): When specified, the request will send an extra X-Climatix-Signature HTTP header with an HMAC+SHA256 signature of the request body ValidateSsl (optional): When using an https endpoint for the callback, this can be set to false to ignore any certificate errors. Defaults to true. This will be useful for testing before actual production deployment of the endpoint. UseForSubTenants (optional): When specified, the webhook will be valid for plants defined under the sub-tenants.
PUT	-
DELETE	-

Request: /Tenants/{id}/DataPointValuesWebhook/{webhookId}

Request	Features	Result
GET	+	The detailed information for a tenant’s datapoint values webhook.
POST	-
PUT	+	Updates the information for datapoint values webhook, only those supplied in the request (See POST method for the available properties).
DELETE	+	Deletes the datapoint values webhook for the given tenant.

Request: /Tenants/{id}/VirtualCloudItemWriteWebhook

Request	Features	Result
GET	+	The detailed information for a tenant’s virtual cloud item write webhook.
POST	+	Creates a webhook for the given tenant, the following information should be sent in the request body: CallbackUrl (required): The callback URL to call the webhook HttpMethod (optional): The Http method to use for calling the webhook. Allowed methods: POST, PUT. Default: PUT SharedSecret (optional): When specified, the request will send an extra X-Climatix-Signature HTTP header with an HMAC+SHA256 signature of the request body ValidateSsl (optional): When using an https endpoint for the callback, this can be set to false to ignore any certificate errors. Defaults to true. This will be useful for testing before actual production deployment of the endpoint. UseForSubTenants (optional): When specified, the webhook will be valid for plants defined under the sub-tenants.
PUT	+	Updates the information for the virtual cloud item write webhook, only those supplied in the request (See POST method for the available properties).
DELETE	+	Deletes the virtual cloud item write webhook for the given tenant.

7.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	+	Adds one or more virtual alarm events for the device. The request should contain appearing alarms with a unique ID. Only acknowledged alarms are supported.
PUT	+	Add an alarm event to the plant.
DELETE	+	Removes an alarm event for the device

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 occurred 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/Info

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.

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

DELETE

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

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	-
PUT	-
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/{automatedUpgradeId}

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

Request: Plants/Licenses

Request	Features	Result
GET	+,P	Gets a list of plant licenses available for the user.
POST	+	Add a plant license for the given activation key.
PUT	-
DELETE	-

Request: Plants/Licenses/{activationKey}

Request	Features	Result
GET	+	Gets info for a specific plant license.
POST	+	Validates and purchase license features with the given activation id.
PUT	-
DELETE	-

Request: Plants/Licenses/{activationKey}/LicenseFile

Request	Features	Result
GET	+	Get the feature file for a plant license.
POST	-
PUT	-
DELETE	-

Request: Plants/Licenses/{activationKey}/Validate

Request	Features	Result
GET	+	Gets info for a specific activation id.
POST	-
PUT	-
DELETE	-

7.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 (>=D13)	Creates new view nodes, under the addressed view node (currently only plant id is supported). Parameter parentId must contain: - Parent tenants id (future) - Parent plants id - View node id (future)
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	+ (>=D13)	Update the delivered properties of the addressed view node. Currently supports: - plant id for referencing virtual pages - (virtual) pages for referencing virtual cloud items - virtual pages for updating names
DELETE	+ (>=D13)	The view node will be deleted. The referenced cloud items (Data points) will be not touched. All underlaying view nodes will be also deleted (future, because currently only flat list is supported).

Request: /ViewNodes /{id}/Values

Request	Features	Result
GET	+	Delivers only the actual values of the referenced view node.
POST	-
PUT	-
DELETE	-

7.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 (>=D13)	Create a new cloud item. Parameter parentId must contain: - Parent plant id
PUT	+	Update of a given set of datapoints, currently only webhooks enable/disable is supported.
DELETE	-

Request: /DataPoints/Values

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	+,Pr (>=D13)	Update the current value for virtual cloud items. The parentId must be used. Parameter parentId can contain: - Parent plant Id
DELETE	-

Request: /DataPoints/{id}

Request	Features	Result
GET	+	The detailed information of a data point will be returned, includes all known properties
POST	-
PUT	+ + (>=D13)	Write the new value to the data point. In the future also other properties can be updated. The following information should be sent in the request body: value: The value to write for the datapoint (require write access to datapoint) priority: The priority to write the value with (require write access level) webhookEnabled: When specified, the webhook specified by the webhookId (see below) will be called, when this datapoint has a COV. Read access level to the datapoint is required to set this property. webhookId: set the id of the webhook to enable/disable for this datapoint. OR Update the definition of the virtual cloud item. Parameter parentId must contain: Parent plant id
DELETE	+ (>=D13)	The cloud item (data point) will be deleted, historical values are still available like for normal controller cloud items.

Request: /DataPoints/{id}/History (deprecated: use GET /Analytics/DataPoints/{id} instead)

Request	Features	Result
GET	+,P,F	The historical values of the data point are returned.
POST	-
PUT	-
DELETE	-

Request: /DataPoints/{id}/EnumerateHistory

Request	Features	Result
GET	+	The historical values of the data point are returned (max 1000 cloud items).
POST	-
PUT	+,Pr (>=D13)	Update the historical value for virtual cloud items. The parentId must be used. Parameter parentId can contain: Parent plant Id
DELETE	-

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

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

Request: /Users/{id}/Assign

Request	Features	Result
GET	-
POST	-
PUT	+,Pr	Adds a user to the specified resource, e.g. to a plant.
DELETE	+,Pr	Removes a user from the specified resource.

Request: /Users/Info

Request	Features	Result
GET	+,F	Gets a list of users defined in plants or systems. All users defined in any plant or system and accessible to the caller will be delivered. Not accessible plants or systems will be ignored and not included in the list.
POST	-
PUT	-
DELETE	-

7.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	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	+	Update the application set properties, the files cannot be modified, therefore /Files has to be used.
DELETE	+	The application set will be deleted, and all references to the assigned plants, including all files.

7.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	+	Update the file properties.
DELETE	+	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.

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

7.11 AlarmNotifications

Request: /AlarmNotifications

Request	Features	Result
GET	+,P,F,Pr	All accessible alarm notifications will be returned. Parameter parentId can contain: - Parent plant Id - Parent tenant 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.

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

Request: /Devices/ActivationKey

Request	Features	Result
GET	+	Retrieve a newly generated activation key (example: 2T5F4U-6DN7U-EBPGE-YS6FA-SKET4).
POST	-
PUT	-
DELETE	-

7.13 Account

Request: /Account/RequestPasswordReset

Request	Features	Result
GET	-
POST	+	Requests an expiring token for resetting the password of the given user (by email address). A mail will be sent to the user with the token. This token must then be sent to the ResetPassword action along with a new password to change the user's password.
PUT	-
DELETE	-

Request: /Account/ResetPassword

Request	Features	Result
GET	-
POST	+	Specifies a new password to set for the given user.
PUT	-
DELETE	-