Web Service Interface (v6.0)

it
Web Service Interface –

Northbound Open RESTful
Integration Service (NORIS)
API Version 6.0
Configuration
A6V10470112_en_b_60 Building Technologies

2022-08-02
2
Siemens Restricted A6V10470112_en_b_60
Building Technologies 2022-08-02
Copyright Notice
Copyright Notice
Notice
Document information is subject to change without notice by Siemens Switzerland
Ltd. Companies, names, and various data used in examples are fictitious unless
otherwise noted. No part of this document may be reproduced or transmitted in any
form or by any means, electronic or mechanical, for any purpose, without the
express written permission of Siemens Switzerland Ltd.
All software described in this document is furnished under a license agreement and
may be used or copied only in accordance with license terms.
For further information, contact your nearest Siemens Switzerland Ltd.
representative.
© Siemens Switzerland Ltd, 2022
Credits
Desigo, Desigo CC, Cerberus DMS, Cerberus PRO, and Sinteso are registered
trademarks of Siemens Switzerland Ltd.
Other product or company names mentioned herein may be the trademarks of their
respective owners.
Edition: 2022-08-02
Document ID: A6V10470112_en_b_60
3
Table of Contents
About This Document ..................................................................................................... 14

Document Revision History ............................................................................................... 17
1 Introduction....................................................................................................... 18
1.1 References ......................................................................................................... 18
1.1.1 Links .................................................................................................... 18
1.1.2 Documents .......................................................................................... 18
1.1.3 Online Documentation ........................................................................ 18
1.2 Definitions, Acronyms and Abbreviations, Conventions .................................... 19
1.2.1 Glossary .............................................................................................. 19
1.2.2 Conventions in this Document ............................................................ 20
1.3 Open Issues in this Document Version .............................................................. 20
2 System Architecture ........................................................................................ 21
2.1 System Limits ..................................................................................................... 21
3 Basic System Concepts ................................................................................... 22
3.1 Glossary of the System ...................................................................................... 22
3.2 Basic Data Concept in the System ..................................................................... 23
3.3 Alarm Concepts .................................................................................................. 24
3.4 Userinterface Concepts ...................................................................................... 26
3.5 Search Mechanism Behavior ............................................................................. 27
4 Using the Web Service Interface .................................................................... 28
4.1 Communication .................................................................................................. 28
4.1.1 Authentication ..................................................................................... 28
4.1.2 Client Certificate Authentication .......................................................... 28
4.1.3 Subscriptions (Push Notifications with SignalR) ................................. 28
4.1.4 Latency Push Notification to Request-Response ............................... 29
4.1.5 SignalR Hubs ...................................................................................... 30
4.2 Supported Client Environments ......................................................................... 30
4.3 Deployment ........................................................................................................ 30
4.4 Configuring Web Service Interface in a Project ................................................. 31
4.4.1 Stopping a Project ............................................................................... 31
4.4.2 Showing Settings ................................................................................ 32
4.4.3 Defining Protocol Type and Port ......................................................... 32
4.4.4 Creating a WSI on Server ................................................................... 32
4.4.5 Starting a Project ................................................................................ 33
4.5 Service Category ................................................................................................ 33
4.5.1 Summary ............................................................................................. 34
4.6 Service mapping with Desigo CC(Basic reference) ........................................... 35
4.7 Access rights for application services ................................................................ 38
4.8 WSI Configuration keys ...................................................................................... 38
4.9 Time sync ........................................................................................................... 39
5 Conventions ...................................................................................................... 40
5.1 Case Sensitivity .................................................................................................. 40
5
5.2 Number Format .................................................................................................. 40
5.3 Date/Time Format ............................................................................................... 40
5.4 Terminology ........................................................................................................ 40
5.5 Maximum page size ............................................................................................ 41
5.6 Request per system............................................................................................ 41
6 General API Specification ................................................................................ 42
6.1 HTTP Methods ................................................................................................... 42
6.2 Resources .......................................................................................................... 42
6.3 Status Codes ...................................................................................................... 43
6.3.1 HTTP Status Codes ............................................................................ 43
6.3.2 Error Code ........................................................................................... 43
6.4 Encoding ............................................................................................................. 43
6.5 Array in Query Parameter................................................................................... 43
6.6 HTTP caching ..................................................................................................... 43
7 Services ............................................................................................................. 44
7.1 Token Service ..................................................................................................... 44
7.1.1 Logging with Username and Password .............................................. 44
7.1.2 SSO Log in .......................................................................................... 45
7.1.3 Default Logon (Mutual TLS) ................................................................ 46
7.1.4 Logging out ......................................................................................... 47
7.2 Heartbeat Service ............................................................................................... 47
7.2.1 Extending the Lifetime of a Session and its Bearer Token ................. 47
7.3 Event Service ..................................................................................................... 47
7.3.1 Retrieving a List of Events .................................................................. 48
7.3.2 Creating a Subscription for Events (Obsolete) ................................... 50
7.3.3 Creating Channalized Events Subscription ........................................ 51
7.3.4 Modifying a Subscription for Events.................................................... 53
7.3.5 Deleting a Subscription for Events ...................................................... 53
7.4 EventsCommands Service ................................................................................. 53
7.4.1 Executing a Command on an Event ................................................... 53
7.4.2 Bulk Commanding on Events .............................................................. 54
7.5 EventCounter Service......................................................................................... 55
7.5.1 Retrieving Event Counters .................................................................. 55
7.5.2 Creating a Subscription for Event Counters (Obsolete)...................... 57
7.5.3 Creating Channalized Event Counters Subscription ........................... 58
7.5.4 Deleting a Subscription for Event Counters ........................................ 59
7.5.5 Retrieving Event Suppressed objects count ....................................... 59
7.5.6 Creating Channalized Event Supressed Objects Subscription .......... 59
7.5.7 Deleting a Subscription for Supressed Objects .................................. 60
7.6 System Browser Service .................................................................................... 60
7.6.1 Retrieving a List of Views of a System................................................ 61
7.6.2 Retrieving a List of Browser Objects ................................................... 61
7.6.3 Searching for Browser Objects ........................................................... 63
7.6.4 Search multiple Object Ids .................................................................. 65
7.6.5 Creating a Subscription for Changes in the System Browser views
(Obsolete) ........................................................................................... 67
6
7.6.6 Creating Channalized Systembrowser Subscription .......................... 68
7.6.7 Deleting a Subscription for Changes in the System Browser views ... 70
7.6.8 Update CNS Node Description ........................................................... 71
7.7 Value Service ..................................................................................................... 71
7.7.1 Retrieving a Value of an Object or Property ....................................... 71
7.7.2 Retrieving Values for a List of Objects or Properties .......................... 73
7.7.3 Creating a Subscription for a Change of a Value (Obsolete) ............. 75
7.7.4 Creating Channalized Value Subscription .......................................... 76
7.7.1 Deleting a Subscription for a Change of a Value ................................ 79
7.8 Property Value Service ....................................................................................... 80
7.8.1 Retrieving Detailed Values for Object or Property Id .......................... 81
7.9 Properties Service .............................................................................................. 84
7.9.1 Retrieving Detailed Values for Object or Property Id .......................... 84
7.9.2 Retrieving Detailed Values for multiple Object or Property Ids bulk
interface .............................................................................................. 87
7.9.1 Retrieving an Image for a Property ..................................................... 89
7.10 Command Service .............................................................................................. 89
7.10.1 Retrieving a List of Commands for a Provided Property .................... 90
7.10.2 Retrieving Lists of Commands for a List of Properties ....................... 92
7.10.3 Executing a Command........................................................................ 96
7.10.4 Bulk Commanding ............................................................................... 96
7.10.5 Bulk Commanding with different pair of property values and command
id ......................................................................................................... 98
7.10.6 Creating a Subscription for a Change of a Command (Obsolete) ...... 99
7.10.7 Push Notification ............................................................................... 100
7.11 Trend Service ................................................................................................... 104
7.11.1 Retrieving a List of All Trend Collector Objects ................................ 104
7.11.2 Retrieving a List of Trend Collector Objects ..................................... 105
7.11.3 Retrieving TrendViewDefinition object details .................................. 105
7.11.4 Create/Update TrendViewDefinition ................................................. 107
7.11.5 Delete TrendViewDefinition .............................................................. 109
7.11.6 Delete TrendLogOnline ..................................................................... 109
7.11.7 Retrieving Borders of a Trend Series ............................................... 110
7.11.8 Retrieving a List of Trends ................................................................ 110
7.11.9 Retrieving a List of Trend Aggregates .............................................. 111
7.12 History Logs Service ........................................................................................ 113
7.12.1 Retrieving Log Tables ....................................................................... 113
7.12.2 Retrieving Columns of a Log Table .................................................. 114
7.12.3 Retrieving Condition Filter Operators for a Column .......................... 115
7.12.4 Retrieving Enum Values for a Column .............................................. 115
7.12.5 Retrieving Data for Table .................................................................. 116
7.12.6 Discarding a Snapshot of a Log Table .............................................. 120
7.12.7 Validating Condition Filter ................................................................. 121
7.12.8 Retrieving Child Data for a Parent Table .......................................... 122
7.12.9 Cancel Report Processing ................................................................ 123
7.13 Diagnostics Service .......................................................................................... 124
7.13.1 Test Reachability of the Web Service Interface ................................ 124
7
7.14 Language Service ............................................................................................. 124
7.14.1 Retrieving the Language of the Logged in User ............................... 124
7.15 Image Service ................................................................................................... 124
7.15.1 Retrieving an Image .......................................................................... 125
7.16 Tables Service .................................................................................................. 125
7.16.1 Retrieving a Table or an Entry of a Table ......................................... 126
7.16.2 Retrieving a Subtable of a Table ....................................................... 127
7.16.3 Retrieving a Subtable of a Table for given row of table .................... 127
7.16.4 Retrieving Subgroups with filter ........................................................ 128
7.16.5 Retrieving Image from Global Text Table ......................................... 130
7.16.6 Retrieving Text From Global Text Table ........................................... 131
7.16.7 Retrieving all Language Text from Global Text Table ...................... 132
7.16.8 Retrieving Nested Text From Global Text Table .............................. 133
7.16.9 Retrieving Text From a Local Text Table .......................................... 134
7.16.10 Retrieving All Language Text From a Local Text Table .................... 135
7.16.11 Retrieving an Image for an Entry of a Table ..................................... 136
7.16.12 Retrieving an Entry of a Table .......................................................... 136
7.17 Systems Service ............................................................................................... 137
7.17.1 Retrieving list of installed languages (same order) as installed in
project ............................................................................................... 137
7.17.2 Retrieving list of all available systems with list of installed languages.137
7.17.3 Retrieving information of a specific system ...................................... 138
7.17.4 Retrieving information of a local system ........................................... 139
7.17.5 Get service status ............................................................................. 139
7.17.6 Create channelize Systems subscription .......................................... 140
7.17.7 Delete Subscription for a Systems .................................................... 140
7.17.9 Create channelize Services subscription .......................................... 141
7.17.10 Unsubscribe Services ....................................................................... 143
7.18 Products Service .............................................................................................. 143
7.18.1 Retrieving Product Information ......................................................... 143
7.19 Files Service ..................................................................................................... 144
7.19.1 Retrieving Files of specific type ........................................................ 144
7.19.2 Retrieve Files from system ............................................................... 145
7.19.3 Retrieve Documents from system ..................................................... 145
7.20 Graphics Service .............................................................................................. 145
7.20.1 Check if object is graphical ............................................................... 146
7.20.2 Retrieving graphic item ids ................................................................ 146
7.20.3 Retrieving a graphical item ............................................................... 147
7.20.4 Retrieving a child item ....................................................................... 148
7.21 EventCategorySound Service .......................................................................... 149
7.21.1 Get current event sound ................................................................... 149
7.21.2 Subscribe for event sound ................................................................ 150
7.21.3 Delete Subscription for a event sounds changes. ............................ 150
7.21.4 Create channelize event sound subscription .................................... 151
7.22 Settings Service ................................................................................................ 152
8
7.22.1 Read setting ...................................................................................... 152
7.22.2 Write setting ...................................................................................... 152
7.22.3 Delete setting .................................................................................... 152
7.23 Users Service ................................................................................................... 153
7.23.1 Change Password ............................................................................. 153
7.23.2 Get Login Information ....................................................................... 154
7.24 Scheduler Service ............................................................................................ 156
7.24.1 Gets BACnet schedule object based on the schedule object id ....... 156
7.24.2 Save BACnet schedule values ......................................................... 158
7.24.3 Save BACnet schedule exceptions ................................................... 160
7.24.4 Save BACnet default value for schedule .......................................... 160
7.24.5 Retrieve BACnet calendar list for schedule object id ........................ 161
7.24.6 Retrieve calendar object based on calendar object Id ...................... 161
7.24.7 Save BACnet calendar ...................................................................... 162
7.25 Objects Service ................................................................................................ 163
7.25.1 Get available Objects types .............................................................. 163
7.25.2 Create Objects .................................................................................. 164
7.25.3 Delete Objects .................................................................................. 165
7.25.4 Get Information text .......................................................................... 165
7.25.5 Put Memo text ................................................................................... 166
7.26 Related Items Service ...................................................................................... 167
7.26.1 Read Related Items .......................................................................... 167
7.27 Access rights Service ....................................................................................... 168
7.27.1 Retrieve access rights ....................................................................... 169
7.27.2 Retrieve user roles ............................................................................ 169
7.28 Operating Procedures Service ......................................................................... 173
7.28.1 Retrieve Operating procedure........................................................... 173
7.28.2 Update Operating procedure step .................................................... 173
7.29 Licenses Service .............................................................................................. 176
7.29.1 Read License Mode .......................................................................... 176
7.29.2 Read License Options ....................................................................... 176
8 Objects and Data Types................................................................................. 178
8.1 Common ........................................................................................................... 178
8.1.1 Link.................................................................................................... 178
8.1.2 Page<Name, Type> .......................................................................... 178
8.1.3 KeyValue<Name, Type> ................................................................... 178
8.1.4 NameValue ....................................................................................... 178
8.1.5 Subscription ...................................................................................... 178
8.1.6 UnSubscription .................................................................................. 179
8.1.7 Value ................................................................................................. 179
8.1.8 ColorRepresentation ......................................................................... 180
8.1.1 CommandsSubscription .................................................................... 180
8.1.2 ValuesSubscription ........................................................................... 181
8.1.3 Attributes ........................................................................................... 181
9
8.1.4 ApiDataType ..................................................................................... 181
8.1.5 Subgroups ......................................................................................... 182
8.1.6 StatusNotification .............................................................................. 182
8.2 Token Service ................................................................................................... 182
8.2.1 Login ................................................................................................. 182
8.3 Event Service ................................................................................................... 183
8.3.1 Event ................................................................................................. 183
8.3.2 EventCommand ................................................................................ 187
8.3.3 EventDetailsList ................................................................................ 188
8.4 Event Counter Service...................................................................................... 188
8.4.1 EventCounterList............................................................................... 188
8.4.2 EventCounter .................................................................................... 188
8.4.1 Category color details ....................................................................... 188
8.4.2 Subscription Status ........................................................................... 189
8.5 System Browser Service .................................................................................. 189
8.5.1 View .................................................................................................. 189
8.5.2 BrowserNode .................................................................................... 190
8.5.3 SystemBrowserSearchList ................................................................ 190
8.5.4 SystemBrowserSubscription ............................................................. 190
8.5.5 SystemBrowserSubscriptionKey ....................................................... 191
8.6 Value Service ................................................................................................... 191
8.6.1 ValueDetails ...................................................................................... 191
8.7 PropertyValue Service ...................................................................................... 192
8.7.1 Object<Type>.................................................................................... 192
8.7.2 PropertyDetails .................................................................................. 192
8.7.3 Elements ........................................................................................... 193
8.7.4 Scaled Property Details .................................................................... 193
8.7.5 DisplayType ...................................................................................... 193
8.8 Properties Service ............................................................................................ 194
8.8.1 PropertyNames ................................................................................. 194
8.9 Command Service ............................................................................................ 194
8.9.1 PropertyCommand ............................................................................ 194
8.9.2 Command .......................................................................................... 194
8.9.3 CommandParameters ....................................................................... 195
8.9.4 EnumItem .......................................................................................... 196
8.9.5 BatchExecution ................................................................................. 196
8.9.6 CommandInputForExecution ............................................................ 196
8.9.7 BatchCommandExecution ................................................................ 196
8.9.8 PropertyCommandInput .................................................................... 197
8.10 Trend Service ................................................................................................... 197
8.10.1 TrendCollector ................................................................................... 197
8.10.2 TrendBorder ...................................................................................... 197
8.10.3 TrendSeries ....................................................................................... 197
8.10.4 TrendAggregateSeries ...................................................................... 197
8.10.5 TrendAggregate ................................................................................ 197
8.10.6 TrendViewDefinitionRepresentation ................................................. 198
10
8.10.7 AxisDefinitionRepresentation ............................................................ 198
8.10.8 TimeRange ....................................................................................... 199
8.10.9 TrendSeriesDefinitionRepresentation ............................................... 199
8.10.10 RelativeTimeRange .......................................................................... 200
8.10.11 AbsoluteTimeRange ......................................................................... 200
8.10.12 TrendSeriesDefinitionCollectionRepresentation ............................... 200
8.10.13 TrendViewDefinitionUpdateRepresentation...................................... 200
8.10.14 TrendSeriesDefinitionUpdateRepresentation ................................... 200
8.10.15 TrendSeriesDefinitionUpdateCollectionRepresentation ................... 201
8.10.16 AxisDefinitionUpdateRepresentation ................................................ 201
8.11 History Logs Service ........................................................................................ 201
8.11.1 LogTable ........................................................................................... 201
8.11.2 LogColumn ........................................................................................ 202
8.11.3 LogConditionFilter ............................................................................. 202
8.11.4 LogEnumValues ................................................................................ 202
8.11.5 LogSortInfo ....................................................................................... 202
8.11.6 LogColumnList .................................................................................. 203
8.11.7 LogTableData ................................................................................... 203
8.11.8 LogDiscardedSnapshot ..................................................................... 203
8.11.9 LogConditionFilterValidation ............................................................. 203
8.11.10 LogChildData .................................................................................... 204
8.12 Language Service ............................................................................................ 204
8.12.1 Language .......................................................................................... 204
8.13 Tables Service .................................................................................................. 204
8.13.1 SubDisciplines .................................................................................. 204
8.13.2 SubObjectTypes ............................................................................... 204
8.13.3 TextTableEntry .................................................................................. 204
8.13.4 LangTextTableEntry .......................................................................... 205
8.13.5 TextTableEntry Color Calculation ..................................................... 205
8.14 Systems Service ............................................................................................... 205
8.14.1 System Languages ........................................................................... 205
8.14.2 Systems ............................................................................................ 205
8.14.3 SystemsInformation .......................................................................... 205
8.14.4 ServicesSubscriptionsRepresentation .............................................. 206
8.14.5 ServicesRequestSubscriptionsRepresentation ................................ 206
8.14.6 ServicesNotificationRepresentation .................................................. 206
8.15 Products Service .............................................................................................. 206
8.15.1 ProductInfo ........................................................................................ 206
8.16 Files Service ..................................................................................................... 207
8.16.1 BasicFiles (Enum type) ..................................................................... 207
8.16.2 File Details. ....................................................................................... 207
8.17 Graphics Service .............................................................................................. 207
8.17.1 GraphicalItem .................................................................................... 207
8.18 Scheduler Service ............................................................................................ 207
8.18.1 Calendar............................................................................................ 207
8.18.2 CalendarEntry ................................................................................... 207
11
8.18.3 CalendarDate .................................................................................... 208
8.18.4 WeeklySchedule ............................................................................... 208
8.18.5 ScheduleSetup .................................................................................. 208
8.18.6 Schedule ........................................................................................... 209
8.18.7 ReferencedOutputDetails .................................................................. 209
8.18.8 ScheduleException ........................................................................... 209
8.18.9 TimeTrigger ....................................................................................... 209
8.18.10 CalendarException ............................................................................ 209
8.19 Objects Service ................................................................................................ 209
8.19.1 Object ................................................................................................ 209
8.19.2 Descriptor .......................................................................................... 210
8.19.3 ObjectModel ...................................................................................... 210
8.19.1 ChildObjectModel .............................................................................. 210
8.19.2 ServiceTextRepresentation ............................................................... 211
8.19.3 ObjectInfo .......................................................................................... 211
8.19.4 ServiceTextMemoRepresentation..................................................... 211
8.20 Related Items Service ...................................................................................... 211
8.20.1 RelatedItemResult............................................................................. 211
8.20.2 ObjectRelatedItem ............................................................................ 211
8.20.3 RelatedItem ....................................................................................... 212
8.21 Access rights Service ....................................................................................... 212
8.21.1 AccessRightsRepresentation ............................................................ 212
8.21.2 ApplicationRightRepresentation ........................................................ 212
8.21.3 UserRoleRepresentation ................................................................... 212
8.21.4 RoleInfo ............................................................................................. 213
8.21.5 OperationsRepresentation ................................................................ 213
8.22 Operating Procedures Service ......................................................................... 213
8.22.1 Operating Procedure ......................................................................... 213
8.22.2 Operating Procedure Step ................................................................ 213
8.22.3 Operating Procedure Subscription Representation .......................... 214
8.22.4 Operating Procedure Subscription Key Representation ................... 214
8.22.5 UnsubscriptionStatus ........................................................................ 214
8.23 Diagnostics Service .......................................................................................... 215
8.23.1 DiagnosticsRepresentation ............................................................... 215
8.24 Licenses Service .............................................................................................. 215
8.24.1 LicenseMode ..................................................................................... 215
8.24.2 LicenseOptions ................................................................................. 215
9 Concepts ......................................................................................................... 216
9.1 Naming ............................................................................................................. 216
9.2 Extensibility ....................................................................................................... 216
9.3 Support for Web Service Interface extensions ................................................. 218
9.3.1 Initialization support .......................................................................... 218
9.3.2 Caching support ................................................................................ 219
9.4 Support for Browser Caching ........................................................................... 219
9.5 Support for CORS ............................................................................................ 220
10 Appendix ......................................................................................................... 221
12
10.1 Error Response ................................................................................................ 221
10.1.1 Errors Codes ..................................................................................... 221
10.1.2 Errors ................................................................................................ 222
13
About This Document
Document Revision History
About This Document

Purpose
This document describes the interface between the outside world and the
Management System through a Web Service Interface (Web API). It describes how
the interface is to be accessed and what data in what format are exchanged.
Scope
The document provides a description of the public API which can be used to
access data and the functionality provided by the system platform. This document
applies to the system version 6.0.
Target Audience
⚫ Testers of the public API
⚫ Developers/Clients accessing the public API
Cyber security disclaimer

Siemens products and solutions provide security functions to ensure the secure
operation of building comfort, fire safety, security management and physical
security systems. The security functions on these products and solutions are
important components of a comprehensive security concept.
It is, however, necessary to implement and maintain a comprehensive, state-of-the-
art security concept that is customized to individual security needs. Such a security
concept may result in additional site-specific preventive action to ensure that the
building comfort, fire safety, security management or physical security system for
your site are operated in a secure manner. These measures may include, but are
not limited to, separating networks, physically protecting system components, user
awareness programs, defense in depth, etc.
For additional information on building technology security and our offerings, contact
your Siemens sales or project department. We strongly recommend customers to
follow our security advisories, which provide information on the latest security
threats, patches and other mitigation measures.
http://www.siemens.com/cert/en/cert-security-advisories.htm
14
About This Document
Document Conventions
The following table lists conventions to help you use this document in a quick and
efficient manner.
Convention Examples
Numbered Lists (1, 2, 3…) indicate a 1. Turn OFF power to the field panel.
procedure with sequential steps. 2. Turn ON power to the field panel.
3. Open the panel.
One-step procedures are indicated by a ⚫ Expand the Event List.
bullet point.
Conditions that you must complete or must ⊳ The report you want to print is open.
be met before beginning a procedure are
designated with a ⊳. 1. Click Print .
Intermediate results (what will happen ⇨ The Print dialog box displays.
following the execution of a procedure step), 2. Select the printer and click Print.
are designated with an indented ⇨.
⇨ The print confirmation displays.
Results, after completing a procedure, are
designated with a ⇨.
Bold font indicates something you should Type F for field panels.
type or select, or when a dialog box or Click OK to save changes and close the
window is specified. dialog box.
The Create a New Project dialog box
displays.
Menu paths in procedures are indicated in Select File > Text, Copy > Group, which
bold. means from the File menu, select Text,
Copy and then Group.
File paths containing placeholders display [installation drive:]\[installation
the placeholders in italics enclosed in square folder]\[project]\...
brackets.
Error and system messages are displayed in The message Report Definition
Courier New font. successfully renamed displays in the
status bar.
Italics are used to emphasize new or The reaction processor continuously
important terms. executes a user-defined set of instructions
called the control program.
This symbol signifies a Note. Notes provide
additional information or helpful hints.
Cross references to other information in For more information on creating flowcharts,

printed material are indicated with an arrow see Flowcharts [→ 92].
and the page number, enclosed in brackets:
[→ 92]
Getting Help
For more information about our products, contact your local Siemens
representative.
15
About This Document
Safety Messages According ANSI Z535.6

The following examples show the ANSI standard safety messages used in this
document to draw the reader’s attention to important information.
ANSI distinguishes between personal injury safety messages and property damage
warning messages.
The personal injury safety messages have safety alert symbols and the following
alert level labels: DANGER!, WARNING!, CAUTION!
The label for property damage messages is: NOTICE.
Examples:
NOTICE
Property Damage Warning Message

Equipment damage or loss of data may occur if you do not follow a procedure or
instruction as specified.
CAUTION
Caution Safety Message

Minor or moderate injury may occur if you do not follow a procedure or instruction
as specified.
WARNING
Warning Safety Message

Personal injury or property damage may occur if you do not follow a procedure as
specified.
DANGER
Danger Safety Message

Electric shock, death, or severe property damage may occur if you do not perform
a procedure as specified.
16
About This Document

Document Identification
The document ID is structured as follows:
ID_Language(COUNTRY)_ModificationIndex_ProductVersionIndex
Example: A6Vnnnnnnnn_en_a_02
Document Revision History.

Modification Edition Date Brief Description
Index
a 2019-04-11 Release Edition 4.0
b 2019-07-09 Edition 4.1
c 2019-07-30 Edition 4.2
d 2020-09-29 Edition 5.0
e 2021-06-30 Edition 5.1
f 2022-08-02 Edition 6.0
17
Architecture
3
1 Introduction
1.1 References
1.1.1 Links
Ref. Abbreviation Link Description
[1] HAL http://stateless.co/hal_specification.html
[2] SignalR https://github.com/SignalR/SignalR/wiki
[3] Base64url http://www.ietf.org/rfc/rfc4648.txt
[4] OAuth https://tools.ietf.org/html/rfc6749
[5] Langauge-Tags http://tools.ietf.org/html/rfc5646
[6] JSON: http://www.ietf.org/rfc/rfc4627.txt
[7] REST http://en.wikipedia.org/wiki/Representational_state_transfer
[8] URI https://tools.ietf.org/html/rfc3986
[9] EBNF http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form
[10] Media-Types http://www.iana.org/assignments/media-types/media-types.xhtml
[11] Swagger http://swagger.io
[12] Mutual TLS https://datatracker.ietf.org/doc/html/rfc8705
1.1.2 Documents
Ref. Name Version
[20] Regional Product Customization Guide
1.1.3 Online Documentation

Web Service Interface also provides an interactive online documentation (web page).
The documentation is based on Swagger[18] and is a runtime representation of the
API. It requires a running Web Service Interface and can be accessed in two ways
using the following URL:
i) Intranet :
http(s)://[hostname]:[port]/swagger/ui/index
Example
https://myWebServiceHost:8443/swagger/ui/index
ii)Internet (i.e via IIS)

Once Web Service Application is created in SMC, append /swagger/ui/index to
WSI application URL shown.(in SMC)
Example
https://[hostname]:[websitePort]/ApplicationName/swagger/ui/ind
ex
18
Architecture
3
NOTE:
If you are using Internet Explorer make sure Compatibility View is turned off.
1.1.3.1 Exposure of Swagger via IIS is configurable

An advanced user can enable/disable the exposure of Swagger via IIS. To enable
the swagger via IIS, user has to set the enabled flag to true for
SwaggerRoutingRule under WSI web application web.config file.
By default swagger via IIS is disabled. As shown below :
Path for WSI Web Application web.config :

Example :
<Drive:>\GMSProjects\WebSites\GmsWebsite\WsiWebApplicationName\
1.2 Definitions, Acronyms and Abbreviations,

Conventions
1.2.1 Glossary
Terms Used in Web Service Interface
Term Description
HAL Simple format that gives a consistent and easy way to hyperlink between
resources in an API.
HTTP Hypertext transfer protocol:
http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
JSON JavaScript Object Notation:
http://en.wikipedia.org/wiki/JSON
OAuth 2.0 Open standard to authorization. OAuth provides client applications a 'secure
delegated access' to server resources on behalf of a resource owner.
Push Notification In this document push notifications refer to real-time notifications (see real-time
push below).
Push notifications to mobile devices (see wake-up push below) are not covered in
this document. However, a dedicated extension module is available to provide this
functionality.
REST Representational state transfer:
http://en.wikipedia.org/wiki/Representational_state_transfer
Real-time push Push notification from a server (our Web Service in this case) to a client; used for
notification of changes of values as long as client application is running. Notifies
the client about events in the system, including COV, as long as the client
application is running.
Reverse Proxy Retrieves resources on behalf of a client from a server. These resources are then
returned to the client as though they originated from the server itself.
SignalR Library for ASP.NET. SignalR allows bi-directional communication between server
and client.
Wake-up push Push notification to a mobile phone; notifies a user about an event in the system;
takes advantage of third-party notification providers (Apple, Google, …).
19
Architecture
3
1.2.2 Conventions in this Document

The product is developed for different regions and known under the following brands:
⚫ Desigo CC
⚫ Desigo DMS
⚫ Cerberus DMS
In this document, we therefore use the neutral term System for each of these brands.
1.3 Open Issues in this Document Version

At the effective date of the current document version, the following open issues are
identified:
⚫ none
20
Architecture
3
2 System Architecture
The following diagram shows the architecture for the Web Service Interface API.
2.1 System Limits

The following limits apply when using the Web Service Interface:
⚫ Number of concurrent sessions: 100

⚫ Delay for notifications: <1 second
⚫ 5’000’000 value updates / day
⚫ 20’000 value subscriptions
⚫ 250’000 event notifications / day
⚫ 250’000 event-counter notifications / day
⚫ 1’000’000 trends / min
NOTICE
IIS limits imposed by Operating System version

The Client versions of Windows (e.g. Windows 7, Windows 8) have intentionally
feature-limited versions of IIS. One limitation is the number of concurrent
connections which can be as low as 10.
This especially affects the usage of push notifications with SignalR (see [2]
[➙ 18]).
21
Architecture
3
3 Basic System Concepts
3.1 Glossary of the System

Aggregator
A parent object summarizing child objects, such as data points, displayed in the
System Browser.
Alarm
See Event.
Attribute
The Main attributes belong to all existing objects visible in the System Browser. The
Details attributts belong to each of the properties within an object defined in an Object
Model. There are two kinds of attributes:
• Simple attribute, for example, unit or text group.
• Complex attribute, for example, commands or alarms.
COV
Change of Value. An updated value that represents the extent of change in a
measured reading when change criteria have been met.
Data point
An input/output function consisting of all assigned information describing fully the data
point's meaning.
Discipline
An area of building control, such as HVAC, lighting, blind control, fire or video. Building
control disciplines can also contain subdisciplines.
Event
A change of state or value detected for processing and/or reporting.
Function
Is the semantic description for one or more data point types, for example, fire detector.
Object
A specific instance of an object type. While an object type is identified by a unique
object type property, an object is identified by its object identifier property.
Project data points imported in the system database. Instances are customized with
attributes, such as discipline or text group, during data import.
Object Model
A data point type and its attributes specific to a subsystem and protocol. Native
presentation of subsystem objects in the system, for example, analog input.
Property
Each object has a different number of properties, depending on the Object Model or
the defined Function. Properties show online values (COV or polling) and can have an
operation function assigned to them, for example, Acknowledge.
Properties collect data from the field system and need more system resources than a
static attribute in the database.
Propagation
A mechanism for relaying Common Status information up the building control system's
hierarchical tree. Propagation is based on the parent-child-grandchild model. Each
object in the system can have one or more parent objects and one or more child
objects. Each child in the system can simultaneously propagate multiple active
Common Status properties to a parent —for example, fire alarm, security fault, or
technical excluded.
System Manager
22
Architecture
3
A system application th 7at allows users to select and act on objects for monitoring
and controlling a facility. The System Manager contains the following panes: System
Browser (selection of data points), Primary, Secondary, and Contextual.
System Browser
Shows the list of hierarchical objects, such as data points, in one or more views.
Compiles objects into an aggregator object.
View
In System Browser, there are two basic views: Management View and Application
View. Additional project views can be defined as needed. The objects are displayed
hierarchically, depending on the selected view. An object can be assigned to more
than one view.
3.2 Basic Data Concept in the System

Instantiated objects for individual subsystems are always related to an Object Model
and a Function. This concept ensures that the user experiences the same operating
and monitoring philosophy for the same or similar Functions.
The system concept impacts the following main elements:

Platform data It forms the basis for the Object Model set up on the system.
type Platform tools are required in individual cases for driver develop-
ment of additional subsystems.
Object Model All system basic data types are designated Object Models. The
corresponding default value is defined per subsystem for each
Object Model.
Function Function includes the semantic description (for example, fire
detector or temperature sensor) for one or more specific data
points.
Object Imported project data can be modified specifically to the object
using the Object Configurator.
Project data The project data contains the specific information on a data point
or data point amount by the system and is responsible for system
response. Collecting data using auto-discovery is possible if
supported by the subsystem.
The Function or Object Model supplements missing information
on a project data point to ensure uniform functioning of system.
The tree structure ensures a consistent operating, commanding and alarming philoso-
phy for the various integrated subsystems. The benefits of this concept include:
23
Architecture
3
• Discipline-specific project data from fire, HVAC, intrusion, and so on can be config-
ured using the same mechanism.
• Additional or new systems can easily be added.
3.3 Alarm Concepts

The system automatically controls and monitors building services plants. Events occur
(such as a fault) that are important for the operator, requiring user intervention. The
alarm system processes such events and reports them accordingly.
The system reacts automatically to a fault with a system reaction (for example,
automatically locking a ventilation plant during a fire alarm).
For control deviations such as a dirty filter, a simple alarm is triggered and only an
alarm message is sent.
The system switches to an alarm state for both cases and a corresponding alarm is
issued. After trouble-shooting the cause of the alarm, the user resets the alarm state
and the system returns to normal status.
Alarm Types
• Field system alarms (alarm behavior configured in the field system)
• Management platform alarms
- Discrete alarm type (for example, alarm range between 10 and 20 or between 30
and 40).
- Continuous alarm type (for example, alarm range <=30 or >=70 ).
Alarm Handling
Alarm Type Name Alarm Behavior
Alarm_NoAckNoReset Simple No user action necessary

Alarm_NoReset Basic Acknowledge the alarm
Alarm Extended Acknowledge and reset the alarm
Alarm_Dynamic User defined Acknowledge and reset the alarm
executing commands defined on
the alarm source
Simple Alarm
Simple alarms do not require you to acknowledge or reset, they simply return to the
normal state when the monitored condition (for example, a dirty filter) returns to nor-
mal.
24
Architecture
3
Basic Alarm
More important alarms (for example, lack of water) must be acknowledged. After the
alarm state is eliminated, the plant is once again released after acknowledgement.
Extended Alarm
For an extended alarm (for example, velocity monitor), the reset returns the plant to
normal. Provided the monitored state returns to the normal range. The idea is that im-
portant alarms are not overlooked when the alarm condition clears (Normal, not
acknowledged situation). The plant must be reset to re-start operation.
25
Architecture
3
3.4 Userinterface Concepts

The user interface contains the information for:
• Displaying Alarms and Events in a list
• Object navigation in the System Browser tree
• Engineering dialogues to customize the objects and properties
• Operating the system
• Links to further information on an object
Displaying Alarms and Events

Alarms or events are displayed in the Event Summary bar. From there, Alarms or
events can – depending on their type - be acknowledged or reset.
System Browser Navigation
If an object (green) is selected in the System Browser tree, all associated objects and
properties (green frame) are displayed as part of the Engineering dialogue.
Engineering Dialogue
Each object in System Browser has the same number of standard attributes, that are
displayed in the Main section (light green frame). The number of properties can vary
depending on the type of the object. When selecting a property, its attributes (blue
frame) are displayed.
Operating the System
Only properties that are essential to the operation of the system are displayed in the
Operation tab (red frame). The value of a property is read from the system database
or the field network (online value).
If a property has a command attribute, an interactive element is displayed (text field,
list box or button). To change a value, you need to perform two steps:
• Set the value
• Send the value
26
Architecture
3
3.5 Search Mechanism Behavior

The result of a search is different depend which commanding you are using:
• /properties/object.property
• /properties/object
/properties/object.property
The result shows list all data points with the requested property information.
Example:
XXX.YYY.Present_Value
XXX.YYY.Alarm.Fault
XXX.YYY.Event_State
/properties/object
The result shows list all data points with the default property information.
NOTE: The default property is defined for each Object Model as a main attribute.
Example:
XXX.YYY.Present_Value
XXX.ZZZ.Fault
YYY.ZZZ. Present_Value
27
Conventions
5 Communication
4 Using the Web Service Interface
4.1 Communication
The API can be accessed over HTTP or HTTPS. In a production environment it’s
highly recommended to use HTTPS because otherwise primary credentials are
transmitted in plaintext.
4.1.1 Authentication
For authentication we use OAuth 2.0 Resource Owner Password Credentials Grant
[4] [➙ 18]. In order to access a resource of the Web Service Interface the Client
needs a valid access token and a valid session within the system. In case no token
is presented or the token is invalid (e.g. expired) or the system session is not
available the user will get a status code 401 (Unauthorized) and needs to
request an access token. The access token can be requested through a dedicated
resource (/token) by presenting the primary credentials. In case the credentials are
provided, the system creates a new session and returns an access token.
1. Client tries to access a resource.
2. Server responses with status code 401 (Unauthorized).
 Client asks the end-user for credentials.
3. Client sends credentials to a dedicated resource.
4. Server returns an access token, the system creates an internal session.
5. Client again tries to access a resource and includes the access token in an
authorization header.
6. Server returns content with status code 200 (Succeeded).
NOTICE
Session alive
The Client either needs to subscribe for notifications (e.g. change of values) or
needs to access the API at least once every 10 minutes otherwise its system
session expires. The API provides a dedicated resource (/heartbeat) just for the
sake of keeping a session alive.
4.1.2 Client Certificate Authentication

Optionally, a client can authenticate to the server by providing a client certificate.
The Web Service Interface expects the client certificate to be provided in a header
called X-ARR-ClientCert. In case the interface is accessed through a reverse
proxy (almost always the case in a production environment), the reverse proxy
asks the client for an optional client certificate. In this case the reverse proxy
passes the client certificate to the backend server as HTTP header with the default
header configured as X-ARR-ClientCert.
4.1.3 Subscriptions (Push Notifications with SignalR)

Optionally, for specified services the API provides not only data on request (pull)
but also in case of an event determined by the respective service (push).
Any Client subscribing for any push notifications needs to support SignalR (see [2]
[➙ 18]). The Client first needs to connect to a dedicated SignalR hub and can then
28
Conventions
Communication 5
subscribe for notifications by providing a connection ID which it gets after a

connection between Client and server is established. The Client then needs to
implement a function (see signature in respective service chapters) which will be
called from the server in case a notification is due.
Noris hosts signalr url at /signalr route.

By default Javascript & C# signalr client tries to connect to /signalr route if no route
is specified. Please verify with signalr client package’s documentation for setting up
signalr url.
Signalr also generates hub proxy file for javascript clients, this can be accessed at
/signalr/hubs route.
i) Intranet :
http(s)://[hostname]:[port]/signalr
http(s)://[hostname]:[port]/signalr/hubs
ii)Internet (i.e via IIS)

https://[hostname]:[websitePort]/ApplicationName/signalr
https://[hostname]:[websitePort]/ApplicationName/signalr/hubs
Example
4.1.4 Latency Push Notification to Request-Response

In the workflow of subscription and notification it may happen that push notification
from server is received before subscription success response. This latency will be
experienced because of network communication delay of the messages on two
independent channels of SignalR hub connection for push notification and
response of subscription request.
In this kind of scenario Clients of WSI should consider received notification as a

valid notification and design their solution accordingly.
29
Conventions
5 Supported Client Environments
4.1.5 SignalR Hubs

For signalR notification client has to setup hub connection with server.
Legacy implementation of Noris provides specific hub for almost all the subscription
services respectively.
Noris also introduces singleHub solutions as NorisHub. Now client should create
only one NorisHub connection and use it for all the services for subscription-
notificaitons. It is the recommended singlanR connection approach.
Service specific list of Hubs are as below:

Subscription Service Legacy Hub Recommended
EventsSubscriptions eventsHub norisHub
EventcountersSubscriptions eventCountersHub norisHub
SystemBrowserSubscriptions systemBrowserHub norisHub
ValuesSubscriptions valuesHub norisHub
CommandsSubscriptions commandsHub norisHub
EventCategorySoundsSubscriptions eventSoundsHub norisHub
SystemsSubscription norisHub
4.2 Supported Client Environments

There are no Client dependencies except SignalR version 2.2.0 Client library (see
[2] [➙ 18] for available Client libraries) for Clients interested in push notifications.
4.3 Deployment
The Web Service Interface will be deployed as a self-hosted component. It’s an
executable and can be commanded as any other IOWA manager [12] [➙ 18].
In a production environment the Web Service Interface (and System) will most
likely only be accessible through a reverse proxy.
30
Conventions
Configuring Web Service Interface in a Project 5
Network Topology
4.4 Configuring Web Service Interface in a Project

NOTE:
A user has the same user rights as defined in the system. Therfore, you can
check the user rights in advanced in the system bevroe using the Web Service
Interface.
4.4.1 Stopping a Project

 At least one project is available under the Projects node and is started.
1. In the System Management Console tree, select the Projects node.
2. In the Projects tree, select the project that you want to stop.
3. Click the Project Settings tab, if not yet selected.
 Project Settings displays.
4. In the Project Settings toolbar, click Stop .
 A confirmation message displays.
5. Click OK to stop the started project.
31
Conventions
5 Configuring Web Service Interface in a Project
4.4.2 Showing Settings

 The Extension module Connectivity > Web Service Interface is installed.
 At least one project is available under the Projects node and is started.
2. In the Projects tree, select the project.
3. Click the WSI Settings tab.
 WSI Settings displays and shows the used protocol type and port number.
NOTE:
If you want to change the settings, you must stop the project first.
4.4.3 Defining Protocol Type and Port

 The Web Service Interface extension module installed for the selected project.
 The project is stopped.
 IIS is installed according to the settings in the Installation Manual chapter 4.
1. Click Edit .
2. Click Next .
 The Web Service Interface Settings expander displays.
3. Select the protocol:
- Unsecured
- Under Port, enter the port number (Default: 8080).
- Secured
‒ Under Port, enter the port number (Default: 8443).
‒ Under Host Certificate, click Browse.
‒ Select the appropriate certificate and click OK.
NOTE: Additional information on certificates is available in the SMC Help.
4. Click Save Project .
 The protocol settings are saved.
5. Click Start Project .
NOTE:
HTTP is insecure and is vulnerable to man-in-the-middle and eavesdropping
attacks, which can let attackers gain access to sensitive information.
Many organizations require certificates from third-party authorities instead of self-
signed certificates to remain compliant with current regulations.
4.4.4 Creating a WSI on Server

 At least one Web site is created and available under the Websites root node in
the System Management Console tree.
1. In the System Management Console tree, select the Websites node.
2. In the Websites tree, select the Website.
3. Click the Management tab.s
32
Conventions
Service Category 5
 The Details expander displays.

4. In the Website toolbar, click Web Service Interface .
 The Web Application Details expander displays.
5. In the Web Application Details expander, provide the Web application details
as follows:
- From the Project Name drop-down list, select a project that you want to
link to the Web application.
- In the Name field, type a unique name of the Web application.
- Browse for the Path to save the Web application on the disk. The default
path is [installation drive:]\[installation folder]\[WebSites]\[Web site Name].
- Browse for a web application User using the Select User dialog box. You
can select a different user than the one you selected during Web site
creation.
NOTE: The Web application must be a member of the IIS_IUSRS group. If
you select a user that is not a member of the IIS_IUSRS group, SMC
prompts you to add it.
- Enter the valid Password for the Web application user.
6. Click Save .
 A confirm message displays.
 Click OK to initiate the Web application creation (or Cancel to abort).
 If confirmed, the data is validated on successful creation.
 The Web Service Interface Settings expanders displays the defined settings.
4.4.5 Starting a Project

 The project is stopped.
2. In the Projects tree, select the project that you want to start.
3. Click the Project Settings tab, if not yet selected.
 Project Settings displays.
4. In the Project Settings toolbar, click Start Project .
 A confirmation message displays.
5. Click OK to start the stopped project
4.5 Service Category

Based on frequency of change in design, all of the services and APIs are
categorized as below three types:
Category Scope Description
Public Service Any change in APIs will not be breaking. Backward compatibility will always
and API be supported.
Code: Green
Partial Service Service contains both internal and Public APIs.
Internal only Code: Yellow
Internal Service Service is developed strictly only for internal development. Interface might
and API change with newer version. Backward compatibility is not guaranteed.
Code: Red
33
Conventions
5 Service Category
4.5.1 Summary
For quick reference of service category refer below table
S.No. Service Code Service Category
1 Token Public
2 HeartBeat Public
3 Command Public
4 CommandSubscriptions Public
5 Diagnostics Public
6 EventCategorySounds Public
7 EventCategorySoundsSubscriptions Public
8 EventCounters Public
9 EventCountersSubscriptions Public
10 EventsCommands Public
11 Events Public
12 EventsSubscriptions Public
13 Files Partially Internal
14 HistoryLog Public
15 Graphics Internal
16 Images Internal
17 Language Public
18 Products Public
19 Properties Public
20 PropertyValues Public
21 Settings Internal
22 SystemBrowser Public
23 SystemBrowserSubscriptions Public
24 Systems Public
25 Tables Partially Internal
26 TrendSeries Public
27 TrendSeriesInfo Public
28 Users Internal
29 Values Public
30 ValuesSubscriptions Public
31 Systems Public
32 SystemsSubscriptions Public
33 Scheduler Internal
34 Related Items Public
35 AccessRights Internal
36 AccessRightsSubscriptions Internal
34
Conventions
Service mapping with Desigo CC(Basic reference) 5
4.6 Service mapping with Desigo CC(Basic reference)
35
Conventions
5 Service mapping with Desigo CC(Basic reference)
36
Conventions
Service mapping with Desigo CC(Basic reference) 5
S.No. Workflow Services [44]

1 Image Download Files[144]
2 Login Support Token[44]
3 Change Password Users[153]
4 Product Details Products[141]
5 Event Counters EventCounters[55]
6 Systeme Details Systems[137]
7 System Browser SystemBrowser[60]
8 Properties 1. Value[71]
2. Properties[84]
3. PropertyValue[80]
9 Graphics Graphics[145]
10 Reports Histrory Logs[113]
11 Trends Trend[104]
12 Events 1. Event[47]
2. EventsCommands[53]
13 Scheduler 3. Scheduler[207]
37
Conventions
5 Access rights for application services
4.7 Access rights for application services

Certain services in Web service interface can be related to applications in Desi-
goCC client. Application rights for such applications are also enforced serrvice
endpoints as well .Access to operation would be denied if application rights are not
available with user.
Service Endpoints Application [ID- Name] Operation [ID- Name]

Trend Delete TrendViewDefinition 54 - Trends 1730 - Configure
Service
Delete TrendLogOnline 54 - Trends 1730 - Configure
Create/Update TrendViewDefinition 54 - Trends 1730 - Configure
Schedule Save Schedule 46 - Schedules 1474 - Configure

Service
Save Exceptions 46 - Schedules 1474 - Configure
Save Schedule Options 46 - Schedules 1474 - Configure
Save Calendar 46 - Schedules 1474 - Configure
4.8 WSI Configuration keys

Configuration keys in project config can be modified to change default behavior of
NORIS. It follows Hierarchical configuration i.e. configuration defined at instance
level can be used to override configuration at base configuration.
By default configuration at instance level is not defined and it will inherit config
from base e.g. MaxVirtualMemorySizeForProcess is defined at base config only
which can be overridden at instance level if certain instances require more
memory for operation.
Configuration Key Data Type Default Description

Value
WhiteListDomain String Update CORS policy to allow only whitelisted domains in access-
control response headers.
Mutliple domain names needs to be separated by semi colon ( ; ) .
Key is optional and default configuration allows all domains.
e.g. WhiteListDomain = http://xyz.com;https://xyz.com;https://abc.in
CachingDefaultMaxAge Unit Time duration in minutes to set Cache control max-age value in
WSI response.
Key is optional and default configuration sets max-age to 30 mins.
Setting value as 0 will disable caching headers in response.
e.g. CachingDefaultMaxAge = 60
CachingDefaultVaryHeader String Header name to revalidate/refresh cache on browser side. This will
s set the Vary header in response if caching is enabled.
Mutliple header names needs to be separated by semi colon ( ; ) .
Key is optional and default configuration sets vary to ‘Authorization’.
e.g. CachingDefaultVaryHeaders = Header1;Header2;Header3
MaxSnap- String 5 Maximum Snapshots time for single session
shotsForSingleSession
MaxSnapshotInactiveTime String 10 Maximum Inactive Time for Snapshot

MaxVir- String 429496729 Maximum Virtual Memory Size For Process
tualMemorySizeForProcess 6
maxBcmBufferSize String 100000 Maximum Bcm Buffer Size
DirectoriesAccess String Libraries, Directories Access
flexreports
38
Conventions
Time sync 5
SignalrMessageBuffer String 3000 Signalr Message Buffer size

SignalrKeepAlive String 6 Signalr Keep Alive
ExpiresUtcTicketForCo- String 5 UtcTicket Expires time For Code Grant
deGrant
LicensedClient String 40 Maximum number of clients of type ‚LicensedClient‘ allowed to
login.
NonLicensedClient String 10 Maximum number of clients of type ‚ NonLicensedClient ‘ allowed to
login.
EventNotificationPacketSize string 100 Maximum events to be notified per notification packet
4.9 Time sync

It could be scenario where NORIS server and Client application has some time dif-
ference.This time difference can result in inconsistent data – Event time repre-
sented incorrectly, during commanding incorrect data being sent to server.
To sync the time between server and client , NTP time sync could be implemented
- Clock_synchronization_algorithm.
NORIS provides server’s UTC datetime information as well as time difference be-
tween server time and client time if client pass client information to the server.
The information provided by Diagnostics Service [➙124] can be used calculate time
difference at client side.
39
Conventions
5 Case Sensitivity
5 Conventions
5.1 Case Sensitivity

Unless otherwise specified the system is case sensitive. This affects the API in
terms of filters and search results.
5.2 Number Format

The API uses an invariant culture for the number formatting regardless of the
logged in user. The decimal mark is a period.
5.3 Date/Time Format

Date and time representations under ISO-8601 acceptable formats are :
yyyy-MM-ddTHH:mm:sZ
yyyy-MM-ddTHH:mm:ssZ
yyyy-MM-ddTHH:mm:ss.FFFZ
NOTE:
Unless otherwise noted, the Zulu time zone is expected.
Examples:
2016-03-06T12:35:1Z
2016-03-06T12:35:01Z
2016-03-06T12:35:01.711Z
5.4 Terminology
Terminology
Term Description
Name1 Literal; supposedly unreadable; usually not displayed in a UI.
1
Descriptor Localized string in a readable form; supposed to be displayed to an end- user.
Designation1 Unique address of a node; supposedly unreadable; usually not displayed in a
UI.
Location1 Localized, fully expanded path of a node; supposed to be displayed to an
end-user.
ObjectId Identifies an object in the system.
PropertyId Identifies a property and its object in the system.
AttributeId Identifies an attribute, its property and its object in the system.
ObejctOrPropertyId An object ID or a property ID is expected.
PropertyName Name of a property.
1 see also Naming [➙ 216]
40
General API Specification
Maximum page size 6
5.5 Maximum page size

Maximum page size which is supported in case of paging is 100000 records per
page.
In case if page size is not specified then above mentioned size will be considered
as page size. And if valid page size is specified then minimum from the both will be
considered as page size.
5.6 Request per system

In a distributed environment (multiple systems) a request may only contain data
points to a single system. If one needs to process data points of multiple systems
multiple requests have to be invoked.
NOTE:
Unless explicitly stated, a service request may only affect a single system.
41
6 HTTP Methods
6 General API Specification

The REST API provides programmatic access to read, write and command the
system data and functionality. The API identifies users using OAuth [4] [➙ 18];
responses are available in JSON [6] [➙ 18].
6.1 HTTP Methods

Following REST principles, one can call the following HTTP methods on the API
resources: GET, POST, PUT, and DELETE.
Method Description
(HTTP Verb)
GET Retrieves a list of resources, or a specific resource.
POST Creates a resource, passes in a parameter, or performs an action on a
resource.
PUT Updates an existing resource.
DELETE Deletes an existing resource or subscription.
6.2 Resources
The Web Service Interface API follows REST principles and therefore exposes
data and functionality as resources [7] [➙ 18].
Every resource is represented as an URI (see Appendix A in [8] [➙ 18]). As a
summary a resource looks like the following:
scheme://domain:port/path?query
Part Description
scheme Usually HTTPS; HTTP should only be used for testing
domain Hostname of host where manager is running
port Usually 8080 for HTTP and 8443 for HTTPS
path Starts with api followed by the service-identifier and optional sub paths (e.g.
api/languages/en-us); see sections below
query Optional; depends on resource (see sections below)
Example
https://ch1w80012:8443/api/events?sorting=1
NOTE:
In a production environment, the API runs most likely behind a reverse proxy. In
this case, the URI might look differently and might hide some information from the
Client.
Example
https://www.example.com/example/api/events?sorting=1
Therefore the general format of a URL is:
{entry-point}/api{resource-address}
Where entry-point is http://[hostname]:[port] by default or dependent on the
deployment, and resource-address in EBNF is:
resource-address = path [ "?" query ]
path = /root-resource ¦ path "/" sub-resource
query = parameter { "&" parameter }
parameter = key [ "=" value ]
42
Status Codes 6
6.3 Status Codes
6.3.1 HTTP Status Codes

Status Code Meaning Description
200 OK Request processed.
NOTE: Although the request has been processed as a whole,
some of the sub results could still be invalid. See Error Code
[➙ 43] to check sub-results.
204 No Content The server successfully processed the request and is not
returning any content.
304 Not Modified Resources are not modified from last request.
NOTE: This status code is returned only if Etag header is
present in earlier response and request contains If-None-Match
header with Etag value and resource is not modified. See
caching support [➙219 ] .
400 Bad Request Request rejected by application.
401 Unauthorized Invalid or expired token presented. User needs to login.
403 Forbidden The server understood the request but refuses to authorize it.
404 Not Found Resource couldn’t be found for the provided URL and query
parameters.
6.3.2 Error Code

Code Description
0 No error occurred.
6.4 Encoding
Data is encoded in UTF-8.
6.5 Array in Query Parameter

In case a query parameter represents an array, the array is passed as a JSON
array [6] [➙ 18].
Example
someurl?Ids=[1,2,3]
6.6 HTTP caching

Browser can create local cache of response data based on certain headers in
HTTP headers, thus avoiding repetative calls to server for same set of data .For more
details on HTTP caching refer : https://developer.mozilla.org/en-
US/docs/Web/HTTP/Caching
Details of implemnetation for HTTP caching in NORIS is mentioned in Support for
Browser Caching[->9.4]
43
Defining Web Service Interface Settings in SMC
10 Token Service
7 Services
7.1 Token Service

Resource Service Category Requires Authentication Requires SignalR
(Push Notifications)
/token Public x (Logout only)
Note : For clients of type ‚LicensedClient, the maximum and default number of
logins allowed is 40. For clients of other types, the maximum and default number of
logins allowed is 10. The numbers can be configured in the project config file > 4.8.
But maximum values are limited to 40 and 10 for LicensedClient and
NonLicensedClient respectively.
7.1.1 Logging with Username and Password

Resource Path /token
Category Public
HTTP Method POST
Content Type application/x-www-form-urlencoded
Body Property Content Description
grant_type password grant_type=password
username [username] Username provided by user.
password [password] Password provided by user.
client_id [client identifier] Optional : LicensedClient
Client identifier of application ,
certain services may require use of
license that are available with
license server .
Response HTTP 200 OK
A Login object (see Token Service Login [182])
HTTP 403 Forbidden
User password is expired and need to be changed first
Examples Request:
POST /NBWSITest/NorthboundWebApiClient/api/token
Post Data:
grant_type=password&username=testuser&password=123
Response:
{"access_token":"AQAAANCMnd8BFdERjHoAwE_Cl-
sBAAAAFxQybqCuCECyq6-
SZroFhQAAAAACAAAAAAADZgAAwAAAABAAAADdrXxgEKXSVXzs_rNGJsqaA
AAAAASAAACgAAAAEAAAAMKcrzsM7uHInDIRm3oeZWs4AQAAgyBrYpeFIXZ
gb9OQDIunvdip_P9S4PAqDbUakk-
L9R6nLTpSTIyn7KtdFOJVeL6Ar4W3h_OTC6TY40JZo1vhiYnwqAsRcsiKA
tWEykq7uOkL3pcccPQxvuXJJbLWJ7g95vhfV39oDkEnTwLbCwnzMx2y6EF
ufPoS6qO_O8AIk0wFsxiXFeBX34R6ZFIiwlbjf9Yw4S5vX0yN82n9wR3aQ
dxXMQ0s_aAkHSCFz2cm9LdUCc1VndddDXTgwrplPFnzpvB2XJ5M5EERDdb
RZhvCKbLCQqdXu8Ei7-IMpWt-
6pUV3_ZNJLjOJJ5wl9gfKCD81WJ48h3SnWjLTS03k9VEFbbvritlpM2FI7
ptOChdLAn3_VhWfKLFHBo_dHN7f5FrSqZLrP60zOXDe8QjCAMUOUO7n7Xz
IAw_FAAAAAfHvbJW_zH8QP8A61GMQn9divvP",
"token_type":"bearer","expires_in":2591999,
"user_name":"testuser",
"user_descriptor":"Test User" ,
"user_profile":"TEST.ldl",
44
Token Service 10
“flex_user_profile”:”FlexUserProfile”
}
Example: User password is expired
Request:
Post Data:
grant_type=password&username=testuser&password=123
Response:
HTTP 403 Forbidden
{"Id":2400003,"Error":"password_expired","Details":"Logon
rejected. Password of this account is expired and need to
get changed first."}
7.1.2 SSO Log in

It is only available for internal gms application developers. Get Single sign on
(SSO) token directly from Logon orchestrator and provide it to WSI using below
interface.

Category Public
HTTP Method POST
grant_type client_credential grant_type= client_credentials
s To login provide SSO token
Client_Id SSO token Retrived from Logon Orch.
A Login object (see Token Service Login [➙87])
Examples Request:
Post Data:
grant_type=client_credentials&Client_Id=
811d8bb9856598ff60c05ad525746bef40517ab51020faae303c28afe9
32a323d45469eb8b9e2ff85ef1c00dc7b4cfcf3e1bc33e6cd878e5ed6b
63d2271b9d6ef98248544bd5ea16d6fdb72aacd960ad8611c98f01d7f8
5e8e924829edb7dc689fb248ba9fd5093faf6cb942587e9516a17bf0c1
3af994c0814e53dce98923a67a0fa02015f44580e0016e862aa600a8ec
dd2a2597a3074bd1c5d8af3e2db5a2868de2176a1fa533e4dbba308279
8dde4938cdc95c086055bedc6b4d923ebec2ce16d8eab3405955ae6c88
1d6d4f274796b166cc541e18a16039282de247b3b0083508e60674088a
3f7d6fcff12c0d2144414faa09cdc376581c0e2ff1711d34
Response:
{"access_token":"AQAAANCMnd8BFdERjHoAwE_Cl-
sBAAAAFxQybqCuCECyq6-
SZroFhQAAAAACAAAAAAADZgAAwAAAABAAAADdrXxgEKXSVXzs_rNGJsqaA
AAAAASAAACgAAAAEAAAAMKcrzsM7uHInDIRm3oeZWs4AQAAgyBrYpeFIXZ
gb9OQDIunvdip_P9S4PAqDbUakk-
L9R6nLTpSTIyn7KtdFOJVeL6Ar4W3h_OTC6TY40JZo1vhiYnwqAsRcsiKA
tWEykq7uOkL3pcccPQxvuXJJbLWJ7g95vhfV39oDkEnTwLbCwnzMx2y6EF
ufPoS6qO_O8AIk0wFsxiXFeBX34R6ZFIiwlbjf9Yw4S5vX0yN82n9wR3aQ
dxXMQ0s_aAkHSCFz2cm9LdUCc1VndddDXTgwrplPFnzpvB2XJ5M5EERDdb
RZhvCKbLCQqdXu8Ei7-IMpWt-
6pUV3_ZNJLjOJJ5wl9gfKCD81WJ48h3SnWjLTS03k9VEFbbvritlpM2FI7
ptOChdLAn3_VhWfKLFHBo_dHN7f5FrSqZLrP60zOXDe8QjCAMUOUO7n7Xz
IAw_FAAAAAfHvbJW_zH8QP8A61GMQn9divvP",
"token_type":"bearer",
"expires_in":2591999,
"user_name":"testuser",
45
10 Token Service
"user_descriptor":"Test User" ,
"user_profile":"TEST.ldl",
“flex_user_profile”:”FlexUserProfile” ,
"user_inactivity_timeout": "0",
"password_reminder_counter": "0",
"personally_used": "false"
}
7.1.3 Default Logon (Mutual TLS)

This method enables the client to login with a client certificate, on page load.
GMS certificate should be configured beforehand. Login is successful if the certif-
icate is valid.
Category Public
HTTP Method POST
grant_type client_credentials grant_type= client_credentials
To login, provide client certificate
token_endpoint_auth tls_mutual_auth Fixed parameter to be passed for
_method mutual tls. [12]
Client_Id DefaultLogon Fixed string value.
A Login object (see Token Service Login [➙87])
Examples Request:
Post Data:
grant_type=client_credentials&Client_Id=LicensedClient&tok
en_endpoint_auth_method=tls_mutual_auth
Response:
{access_token: "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAA-
RE7lJ-CLEmXzGKpV5u1NAAAAAACAAAAAAADZgAAwAAAABAAAAAISv-
kHm5HO6t2gUgbwHVdAAAAAASAAACgAAAAEAAAAOTB9_au07JsTAEVr
WfW7yFoAQAAuE1jqTSMCgyCYNC6mtPYGNBnlWU8HcXE2EH836Mcez4
fVkuvwcROXqGQ_5biGniyogA994hLn1EdEVcGvsWSoG-
zUNcElKEwYltv__0B8x-
6gp6xED6oEz7Fqci5wvD4h0yvS9Yxe5sF9JoxdhS8Fj2bCvj3FbaC3
JLxfzqUPoA2R3yzJSXgjhPPzFnarvRW0JqpjmJyIPzNG6J1CZFsrE_
Bu0STba-AZmdlosyZNPtN90EwyUfRzR_-
ZN468oAo4mVYJ4myeLR_jAEjzBgxBsypXeHVwxseHrSp2WmZaLHtuo
121sAGuFMCDBV3IkOVqFdfK2f2TungtrQbmxsCikHswG5f7jqXvtaY
JwVpljeAbLamIDieBw8nuuXDdpIpF7cYjiL7Mpg-
vvD0CMSssjvSMDW2bXRg_83b-
x3xZY3ICgz9WbDhIcL2D1vOFyyjzhV595oWDuunnf8303r8o9boc72
helqXFAAAAAzns27QlTxTA2HqfryY0VfVxejD"
“expires_in”: 2591999,
“flex_user_profile”: "DEFAULT",
“password_reminder_counter”: "0",
“token_type”: "bearer",
“user_descriptor”: "",
“user_inactivity_timeout”: "0",
“user_name”: "Software1",
“user_profile”: "DEFAULT.ldl",
"user_inactivity_timeout": "0",
"password_reminder_counter": "0",
"personally_used": "false"}
46
Heartbeat Service 10
7.1.4 Logging out

Logging out a User
Category Public
HTTP Method DELETE
Examples Request:
DELETE /NBWSITest/NorthboundWebApiClient/api/token
Response:
HTTP 200 OK
7.2 Heartbeat Service

Resource Service Category Requires Requires SignalR (Push
Authentication Notifications)
/heartbeat Public x
7.2.1 Extending the Lifetime of a Session and its Bearer Token

If a Client logs in, a session is created and bound to the bearer token that the
Client receives as part of a successful login request. The session and its bearer
token expire after some time of inactivity (default: 10 minutes). Inactivity is detected
if no subscription is alive and no protected (authenticated) call is made within this
timeout.
The /heartbeat resource can be called to artificially signal activity and to reset the
timeout.
Lifetime of a Session.
Resource Path /heartbeat
Category Public
HTTP Method POST
Examples Request:
POST /NBWSITest/NorthboundWebApiClient/api/heartbeat
Response:
HTTP 200 OK
7.3 Event Service

/events Public x
/eventssubscriptions Public x x
Events depend on the event type (see [20]). The current event type can be read
with the following object ID: ManagementView_System_Settings.EventSchema.
47
10 Event Service
7.3.1 Retrieving a List of Events
NOTE:
1. In order to retrieve grouped events right combination or unique identifier have
to be provided in parameters
2. Wild card characters are supported in eventfilter search wherever applicable.
3. Events extension commands are also supported in response.(e.g. StartReno
etc)
Resource Path /events

Category Public
HTTP Method GET
Parameters Property Type Description
sorting int See EventSorting [➙ 185]
page int
size int
ids Array of string
caseSensitive bool
categories Array of int
cause string
creationTime int See EventTimeFilter [➙ 50]
creationTimeFrom DateTime
creationTimeTo DateTime
disciplines Array of int
Systemid Uint System Identifier
states Array of string See EventState [➙ 184]
designations Array of string
sourceName string
sourceDescription string
locationDescription string
locationName string
objectState Array of string See ObjectState [➙ 184]
maintenance string See MaintenanceState [➙185 ]
A Page<Events, Event>-object (see Page<Name, Type>) [➙ 178]
Examples Request:
GET /api/events?sorting=0
Response:
{
"Events": [
{
"Id":
"System1:ManagementView_ManagementSystem_Servers_Server.So
ftwareRunning:_alert_hdl.2._value~635742985171620000~0",
"EventId": 86,
"CategoryId": 9,
"CategoryDescriptor": "Fault",
"State": "Unprocessed",
"Cause": "Services running properly",
"SrcPropertyId":
48
Event Service 10
ftwareRunning:_alert_hdl.2._value",
"SrcObservedPropertyId":
ftwareRunning:_alert_hdl.2._value",
"SrcState": "Quiet",
"SrcSystemId": 1,
"SrcViewName": "ManagementView",
"SrcViewDescriptor": "Management View",
"SrcDesignation":
"ManagementView.ManagementSystem.Servers.Server",
"SrcLocation": "Project.Management
System.Servers.Main Server",
"SrcName": "Server",
"SrcDescriptor": "Main Server",
"SrcDisciplineId": 0,
"SrcDisciplineDescriptor": "Management System",
"CreationTime": "2015-08-04T09:51:57.162Z",
"Direction": "None",
“SuggestedAction”:WaitforCondition,
“NextCommand”:NoActionPossible,
"InfoDescriptor": "At least one service not running
properly",
"Commands": [
{
"Id": "Suspend",
"EventId":
"Configuration"=1
"_links": [
{
"Rel": "command",
"Href":
"api/eventscommands/System1%3aManagementView_ManagementSys
tem_Servers_Server.SoftwareRunning%3a_alert_hdl.2._value~6
35742985171620000~0/Suspend",
"IsTemplated": false
}
]
},
{
"Id": "Ack",
"EventId":
"Configuration"=1
"_links": [
{
"Rel": "command",
"Href":
"api/eventscommands/System1%3aManagementView_ManagementSys
35742985171620000~0/Ack",
}
]
}
],
"_links": [
{
49
10 Event Service
"Rel": "category",
"Href": "api/tables/categories/9",
},
{
"Rel": "discipline",
"Href": "api/tables/disciplines/0",
}
]
}
],
"Total": 1,
"Page": 1,
"Size": 100000,
"_links": [
{
"Rel": "page",
"Href": "api/events?page={page}",
"IsTemplated": true
}
]
}
7.3.2 Creating a Subscription for Events (Obsolete)

Obsolete: Use channelized subscription instead.
Resource Path /sr/eventssubscriptions/:connectionId

Category Public
HTTP Method POST
connectionId string Identifier of subscription
Required
sorting int See Event Sorting [➙ 185]
Body EventFilter[➙ 185]
Examples Request:
POST /api/sr/eventssubscriptions/983a0ade-7e7a-4812-bdf3-
ea9ea59a7e9e?sorting=0
Response:
HTTP/1.1 200 OK
If subscription Post request submitted again then latest request will be considered
and notifications will be pushed with the filter criteria of latest submitted request.
7.3.2.1 Push Notification

After subscribing for events, a list of current events will be sent in an initial
notification. Afterwards, the Client will get notified about events according to the
filter set (if any).
Type Name (case sensitive)

Hub 1. norisHub : recommended
2. eventsHub : legacy
50
Event Service 10
Function notifyEvents (data)

Property Type Description
data Array of Event See Event [➙ 183]
Check the flag Deleted for checking
whether the event got removed.
7.3.3 Creating Channalized Events Subscription

If subscription status will be pused through notifySubscriptionStatus function
available at client side. Events updates will be notified over notifyEvents [➙5057].
Resource Path /sr/eventssubscriptions/channelize/:requestId/:connectionId
Category Public
HTTP Method POST
requestId String Request Identifier of subscription
hub connection.
RequestId is to be generated and
provided by the client.
It is expected from client that client
should use unique id for for each
request.
Recommendation: Use GUID
Required
connectionId String Identifier of subscription hub
connection
Required
sorting Int See Event Sorting [➙ 185]
Body EventFilter[➙ 185]
Examples Request:
POST /api/sr/eventssubscriptions/channelize/9565ca41-8556-
4dbb-94cc-1b89451a5db5/983a0ade-7e7a-4812-bdf3-
ea9ea59a7e9e?sorting=0
Response:
HTTP/1.1 200 OK
notifySubscriptionStatus:
{
"ErrorCode": 0,
"SortingOrder": 0,
"EventFilter": {
"Ids": [],
"Categories": [
1,
2,
3,
10
],
"CreationTime": 6,
"Disciplines": [
0,
20,
100,
200
],
"States": [
51
10 Event Service
"Unprocessed",
"ReadyToBeReset",
"ReadyToBeClosed",
"WaitingOPCompletion",
"Acked"
],
"systemID": 1
},
"RequestId": "9565ca41-8556-4dbb-94cc-1b89451a5db5"
}
If subscription Post request submitted again then latest request will be considered
and notifications will be pushed with the filter criteria of latest submitted request.
7.3.3.1 Subscription Status Notification

After subscribing for event counters, the subscription status will be sent only once.

2. eventsHub : legacy
Function notifySubscriptionStatus(status)
Status EventSubscription See
Status object EventSubscriptionStatus[➙185 ]
Example {
"ErrorCode": 0,
"SortingOrder": 0,
"EventFilter": {
"Ids": [],
"Categories": [
1,
2,
3,
10
],
"CreationTime": 6,
"Disciplines": [
0,
20,
100,
200
],
"States": [
"Unprocessed",
"ReadyToBeReset",
"ReadyToBeClosed",
"WaitingOPCompletion",
"Acked"
],
"systemID": 1
},
"RequestId": "9565ca41-8556-4dbb-94cc-1b89451a5db5",
“RequestFor”:" notifyEvents"
}
52
EventsCommands Service 10
7.3.4 Modifying a Subscription for Events

Change an existing subscription for events: the same procedure as Creating a
Subscription for Events [➙ 50] but use PUT as HTTP method.
7.3.5 Deleting a Subscription for Events

Delete an existing subscription for events: the same procedure as Creating a
Subscription for Events [➙ 50] but use DELETE as HTTP method.
7.4 EventsCommands Service

Resource Service Category Requires Requires SignalR
Authentication (Push Notifications)
/eventscommands Public x
7.4.1 Executing a Command on an Event

Resource Path /eventscommands/:eventId/:commandId
Category Public
HTTP Method POST
eventId string
Required
commandId string See EventCommandId [➙ 50]
Required
commentPasswordrD ValidationData Event-command parameter details
ata See[[➙ 187] (comment ,password and
supervisor details) sent from client if
required.
treatmenttype string Optional query parameter to specify
type of treatment being performed.
This parameter is applicable only id
command is Select.
Examples Request:
POST
/api/eventscommands/System1%3aManagementView_ManagementSys
35742985171620000~0/Ack
Request Body:
{"MultiLangComments":["comment1","comment2"],
"Password":"password","SuperName":"supervisorUserName",
"SuperPassword":"supervisorPassword"}
Response:
HTTP/1.1 200 OK
53
10 EventsCommands Service
7.4.1.1 EventCommandId
:commandId must have one of the following values.
Note :Newly added commands:Events extension commands are also supported in
response.(e.g. StartReno etc)
:commandId Description
select Signals operator is treating an event
suspend Signals operator stopped treating an event
ack Acknowledge event
reset Reset event
silence Silence event
unsilenced Unsilence event
close Close event
7.4.2 Bulk Commanding on Events

Resource Path /eventscommands/:commandId
Category Public
HTTP Method POST
commandId string See EventCommandId [➙ 50]
Required
BatchEventsComman BatchEventsCo Event-command parameter details
dExecution mmandExecutio (eventid,comment ,password and
n See[➙188] supervisor details) sent from client.
Required
treatmenttype string Optional query parameter to specify
type of treatment being performed.
This parameter is applicable only id
command is Select.
Examples Request:
POST /api/eventscommands/Ack
Request Body:
{
"ValidationInput": {
"MultiLangComments": [
"Comment en-US", "Comment de-DE"
],
"Password": "currentUserPassword",
"SuperName": "Supervisor1",
"SuperPassword": "SupervisorPassword"
},
"EventIds": [
ftwareRunning:_alert_hdl.2._value~635742985171620000~0"
]
}
Response:
[
{
54
EventCounter Service 10
"EventId":
ftwareRunning:_alert_hdl.2._value~635742985171620000~0"
}
]
HTTP/1.1 200 OK
7.5 EventCounter Service

/eventcounters Public x
/eventcounterssub Public x x
scriptions
7.5.1 Retrieving Event Counters

When retrieving Event counters two options are available with parameter
categoryId which is optional. If categoryId is provided then Event counter for that
particular categoryId will be returned as EventCounter object. And if categoryId is
not provided then Event counters for all the categories in the system will be
provided as an EventCounterList object. In both the cases response will be
different depending on the request made. For more details see the examples
below.
Note : Link has also made available to provide event category colors information.
See [➙188 ]
Resource Path /eventcounters/:categoryId

Category Public
HTTP Method GET
categoryId int Identifier of category
1. When categoryId is provided: EventCounter object see [➙ 52]
2. When categoryId is not provided: EventCounterList object see [➙
52]
Examples Request1: categoryId is provided
GET api/eventcounters/9
Response1:
{
"CategoryId": 9,
"CategoryDescriptor": "Fault",
"TotalCount": 1,
"UnprocessedCount": 1,
“TotalSubsequentGrouping”:0,
“UnprocessedSubsequentGrouping”=0,
"_links": [
{
"Rel": "eventcounter",
"Href": "api/eventcounters/9",
},
{
"Rel": "categorycolor",
55
10 EventCounter Service
"Href":
"api/tables/categories/9/subtables/colors",
}
]
}
Request2: categoryId is NOT provided

GET api/eventcounters
Response2:
{
"TotalCounters": 1,
"TotalUnprocessedCounters": 1,
"EventCategoryCounters": [
{
"CategoryId": 1,
"CategoryDescriptor": "Emergency",
"TotalCount": 0,
"_links": [
{
},
{
"Href":
}
] },
{
"CategoryId": 2,
"CategoryDescriptor": "Life Safety",
"TotalCount": 0,
"_links": [
{
},
{
"Href":
}
] },
{
"CategoryId": 3,
"CategoryDescriptor": "Security",
56
"TotalCount": 0,
"_links": [
{
},
{
"Href":
}
]
}
]
}
7.5.2 Creating a Subscription for Event Counters (Obsolete)

Resource Path /sr/eventcounterssubscriptions/:connectionId

Category Public
HTTP Method POST
Required
Examples Request:
POST api/sr/eventcounterssubscriptions/448b3117-44ef-4d8f-
baa2-7274aa3050af
Response:
HTTP/1.1 200 OK

After subscribing for event counters, the current event counters will be sent in an
initial notification. Afterwards, any change will be notified.

2. eventCountersHub : legacy
Function notifyEventCounters( data )
data EventCounterList See EventCounterList [➙ 52]
57
10 EventCounter Service
7.5.3 Creating Channalized Event Counters Subscription

available at client side. EventCounter changes will be notified over
notifyEventCounters [➙57].
Resource Path /sr/eventcounterssubscriptions/channelize/:requestId/:connectionId

Category Public
HTTP Method POST
hub connection.
request.
Required
connection
Required
Examples Request:
POST
api/sr/eventcounterssubscriptions/channelize/9565ca41-
8556-4dbb-94cc-1b89451a5db5/448b3117-44ef-4d8f-baa2-
7274aa3050af
Response:
HTTP/1.1 200 OK
{
"ErrorCode":0,
“RequestFor”:"notifyEventCounters"
}

After subscribing for event counters, the subscription status will be sent only once.

2. eventCountersHub : legacy
Status Subscription See Subscription Status [189]
Response
Example {
"ErrorCode":0,
"RequestId": "9565ca41-8556-4dbb-94cc-1b89451a5db5"",
}
58
7.5.4 Deleting a Subscription for Event Counters

Delete an existing subscription for event counters: the same procedure as creating
event counters subscription [➙ 32] but use DELETE as HTTP method.
7.5.5 Retrieving Event Suppressed objects count

Event Suppressed object returns the current count of all the suppressed object. For
more details see the examples below.
Resource Path /sr/eventcounters/suppressedobjects

Category Public
HTTP Method GET
Examples Request:
GET
api/eventcounters/suppressedobjects?api_key=defaultadmin%3Aa
Response:
{
"SuppressedCount":3
}
7.5.6 Creating Channalized Event Supressed Objects

Subscription
It will subscribe the Suppressed Objects. Subscription status will be available at
client side through notifySuppressedObjects function.
Resource Path /sr/eventcounterssubscriptions/channelize/suppressedobjects/{requestId}/{connectio

nId}
Category Public
HTTP Method POST
requestId String Request Identifier of subscription hub
connection.
RequestId is to be generated and provided
by the client.
It is expected from client that client should
use unique id for each request.
Required
connectionId String Identifier of subscription hub connection
Required
Examples Request:
POST
api/sr/eventcounterssubscriptions/channelize/suppressedobjects
/0db77356-bc3f-0275-7262-c28ff19cfb73/8468d443-17b8-41c0-9e41-
b12f45a07d22
Response:
HTTP/1.1 200 OK
notifySuppressedObjects:
{
"ErrorCode":0,
"RequestId":"c8ead472-10b8-0f85-b20e-eabd58bc7054",
59
10 System Browser Service
"RequestFor":"notifySuppressedObjects"
}
7.5.6.1 Supressed Objects Subscription Status Notification

After subscribing for Suppressed object, the subscription status will be sent only
once.

Hub norisHub : recommended
Function notifySuppressedObjectsSubscription (status)

Response
Example {
"ErrorCode":0,
"RequestId": "9565ca41-8556-4dbb-94cc-1b89451a5db5"",
}
7.5.7 Deleting a Subscription for Supressed Objects

Deleting Supressed objects subscriptions.
Resource Path /sr/eventcounterssubscriptions/suppressedobjects/{connectionId

Category Public
HTTP Method DELETE
Required
Examples Request:
DELETE
api/sr/eventcounterssubscriptions/suppressedobjects/7cb4f
8c2-d524-4532-9305-8fac31db175e
Response:
HTTP/1.1 200 OK
7.6 System Browser Service

Resource Service Category Requires Authentication Requires SignalR
(Push Notifications)
/systembrowser Public x
/systembrowsersub Public x x
scriptions
60
System Browser Service 10
7.6.1 Retrieving a List of Views of a System

Retrieves list of Views in the current system. This interface have two optional query
parameters systemId and viewId. If systemId is received as zero or if it is not
provided then current systems id will be taken else received systemId will be taken
for further operations. If viewId is provided then only the view, which have viewId
same as that of in the request will be returned in the response. If viewId is not
provided then all the views in the system will be returned in the response.
Resource Path /systembrowser

Category Public
HTTP Method GET
systemId uint ID of a system
0 or Not Provided: All system will be
considered
>= 1: Specific System will be
considered
viewId uint ID of specific View to be retrieved
Not Provided : All views will be
returned
> 0: Views will be retured for
provided ViewId
An array of View objects see [➙ 55]
Examples Request:
GET api/systembrowser?systemId=1&viewId=10
Response:
[
{
"SystemId": 1,
"ViewId": 10,
"Descriptor": "Application View",
"Designation": "System1.ApplicationView",
"Name": "ApplicationView",
“SystemName”: “System1”,
“ViewType”: 0,
"_links": [
{
"Rel": "systembrowser",
"Href":
"api/systembrowser/1/10/System1.ApplicationView",
}
]
}
]
7.6.2 Retrieving a List of Browser Objects

Retrieve a list of browser objects for a specific view. To retrieve child objects of an
object pass Designation of the parent object as node parameter.
Resource Path /systembrowser/:systemId/:viewId/:node

Category Public
HTTP Method GET
61

Required
viewId uint ID of a view
Required
node string Designation of a parent browser
object (Node or View)
Required
An array of BrowserObject objects see [➙ 55]
Examples Request:
GET api/systembrowser/1/9/System1.ManagementView
Response:
[
{
"HasChild": true,
"SystemId": 1,
"ViewId": 9,
"Name": "ManagementView",
"Descriptor": "Project",
"Designation":
"System1.ManagementView:ManagementView",
"ObjectId": "System1:GMS_Aggregator_5",
"Attributes": {
"Alias": "Project Alias",
"DefaultProperty":
"StatusPropagation.AggregatedSummaryStatus",
"ObjectId": "GMS_Aggregator_5",
"DisciplineDescriptor": "Management System",
"DisciplineId": 0,
"SubDisciplineDescriptor": "System Settings",
"SubDisciplineId": 4,
"TypeDescriptor": "View Element",
"TypeId": 8000,
"SubTypeDescriptor": "System Folder",
"SubTypeId": 8014,
"ManagedType": 56
},
"Location": "System1.Management View:Project",
"_links": [
{
"Rel": "systembrowser",
"Href":
"api/systembrowser/1/9/System1.ManagementView%3aManagement
View",
},
{
"Rel": "properties",
"Href":
"api/properties/System1%3aGMS_Aggregator_5?requestType=0",
}
]
}
]
62
7.6.3 Searching for Browser Objects

Search for browser objects in a provided system.
Resource Path /systembrowser/:systemId/:viewId

Category Public
HTTP Method GET
Required
viewId uint ID of the view in which search
needs to be performed
searchString string String to be searched for
Required
searchOption int See SearchOption [➙ 37]
caseSensitive bool Only valid for search options 0 or 1
groupByParent bool If true, group search results by
parent node
size int Number of browser objects per
page
page int Current page number (default: 1)
discplineFilter string Discipline and subdiscipline filters
See Discipline- and Objecttype
Filters [➙ 657]
objecttypeFilter string Type and subtype filters
See Discipline- and Objecttype
Filters [➙ 657]
aliasFilter string Case-sensitive alias filter
alarmSuppression Boolean When a Boolean is provided, will
search for objects where the alarm
suppression is set to the Boolean
value (true or false).
outOfScan Boolean When a Boolean is provided, will
search for objects where the out of
scan flag is set to the Boolean value
(true or false).
A Page<Nodes, BrowserObject>-object (see Page<Name, Type [➙ 50]>)
Examples Request::
GET
/api/systembrowser/1?searchstring=*view*&searchOption=1&ca
seSensitive=false&groupByParent=false
Response:
{
"Total": 1,
"Page": 1,
"Size": 100000,
"Nodes": [
{
"SystemId": 1,
"ViewId": 9,
"Name": "TxG_BA_BACnetAckedTransitionsEnum",
"Descriptor": "(0000) BACnet Acked Transitions Enum
list",
"Designation":
"System1.ManagementView:ManagementView.SystemSettings.Libr
aries.Headquarter(HQ).BA.Device.BA_Device_PX_HQ_2.TextGrou
63
ps.TxG_BA_BACnetAckedTransitionsEnum",
"ObjectId":
"System1:TxG_BA_BACnetAckedTransitionsEnum",
"Attributes": {
"DefaultProperty": "Read_Only",
"ObjectId": "TxG_BA_BACnetAckedTransitionsEnum",
"DisciplineId": 0,
"SubDisciplineDescriptor": "Unassigned",
"TypeDescriptor": "Library Element",
"TypeId": 4600,
"SubTypeDescriptor": "Text Group",
"SubTypeId": 4609,
"ManagedType": 20
},
"Location": "System1.Management View:Project.System
Settings.Libraries.Headquarter.BA.Device.Desigo PX.Text
Groups.(0000) BACnet Acked Transitions Enum list",
"_links": []
}
],
"_links": [
{
"Rel": "page",
"Href":
"api/systembrowser/1?searchString=*view*&searchOption=1&ca
seSensitive=False&groupByParent=False&size=100000&page={pa
ge}&disciplineFilter=null&objectTypeFilter=null&aliasFilte
r=",
"IsTemplated": true
}
]
}
7.6.3.1 Searching with Wildcards

Two wildcard characters are supported in System Browser—the asterisk (*) and
the question mark (?). Each functions differently. The asterisk wildcard serves as a
placeholder for zero or more characters. The question mark wildcard serves as a
placeholder for exactly one character only. Therefore, each wildcard serves
different purposes.
*: Allows you to add zero or more characters to your search criteria. For example,
"a*" matches and displays, “a”, "ab", "abc", and "abcd".
?: Allows you to add one character to your search. For example, "ab?" matches
and returns "abc" but does not match or return "ab" and "abcd".
64
7.6.3.2 SearchOption
searchOption must have one of the following values.
searchOption Description
0 Search in full name (Designation); default
1 Search in full description (Location)
2 Search in ObjectId
3 Search in Alias
7.6.3.3 Discipline and Objecttype Filters

This JSON string has two level filtering options‒, group level (e.g. disciplines/types)
and subgroup level (e.g. subdisciplines/subtypes). In case if
SubGroupID/SubObjectTypeID is not provided along with GroupID/ObjectTypeID
respectively then all the SubGroups/SubObjectTypes from the metioned
Group/ObjectType will be taken for filtering.
⚫ Example
{"<GroupID>":[<SubGroupID>,..,..,<SubGroupID>],"<GroupID>":[<
SubGroupID>,..,..,<SubGroupID>]}
⚫ Concrete example
{"0":[0,1,2,4],"20":[0,21,22]}
7.6.4 Search multiple Object Ids

Along with normal searches available, This API also provides bulk search option for
searching multiple Object Ids.
Resource Path /systembrowser/:systemId/:viewId

Category Public
HTTP Method POST
Parameters systemId uint ID of a system
Required
viewId uint ID of the view in which search
needs to be performed
groupByParent bool If true, group search results by
parent node
Body Array of ObjectId String[] Array of object ids to be searched
Response HTTP 200 OK Array of Multiple Object Ids search Browser Objects see [➙ 55]
An array of searched browser objects
Examples Request:
GET
api/systembrowser/1/9?searchOption=2&caseSensitive=false&g
roupByParent=false
Post Data:
[
"System1:ManagementView_System_Settings",
"System1:JournalingRootFolder"
]
65
Response:
[
{
"ErrorCode": 0,
"ObjectId": "System1:ManagementView_System_Settings",
"Nodes": [
{
"SystemId": 1,
"ViewId": 9,
"Name": "SystemSettings",
"Descriptor": "System Settings",
"Designation":
"System1.ManagementView:ManagementView.SystemSettings",
"ObjectId":
"System1:ManagementView_System_Settings",
"Attributes": {
"DefaultProperty":
"ObjectId": "ManagementView_System_Settings",
"DisciplineId": 0,
"TypeId": 8000,
"SubTypeDescriptor": "System Folder",
"SubTypeId": 8014,
"ManagedType": 153
},
"Location": "System1.Management
View:Project.System Settings",
"_links": []
}
]
},
{
"ErrorCode": 0,
"ObjectId": "System1:JournalingRootFolder",
"Nodes": [
{
"SystemId": 1,
"ViewId": 9,
"Name": "JournalingRootFolder",
"Descriptor": "Journaling",
"Designation":
"System1.ManagementView:ManagementView.SystemSettings.Jour
nalingRootFolder",
"ObjectId": "System1:JournalingRootFolder",
"Attributes": {
"DefaultProperty":
"ObjectId": "JournalingRootFolder",
"DisciplineId": 0,
"TypeDescriptor": "Journaling",
"TypeId": 4500,
66
"SubTypeDescriptor": "Journaling Printer",

"SubTypeId": 4501,
"ManagedType": 63
},
"Location": "System1.Management
View:Project.System Settings.Journaling",
"_links": []
}
]
}
]
7.6.5 Creating a Subscription for Changes in the System

Browser views (Obsolete)
In System browser views subscription, client can provide one or many designations
for which client is interested for changes. This basically provides the feature of
subtree subscription. All the nodes matching (or underneath) the provided
designation will be subscribed for the changes. And any change happening under
the provided designation will be notified to the subscribed clients.
Resource Path /sr/SystemBrowserSubscriptions/:connectionId/

Category Public
HTTP Method POST
Parameters connectionId string Identifier of subscription
Required
Body designationsList String[] JSON Array of designation(s) for
which client want to subscribe
Response SystemBrowserSubscriptionKeyRepresentation object See [➙ 78]
Examples Request:
POST /api/sr/SystemBrowserSubscriptions/01ac873d-23ae-
49cb-86bc-6764d0b38904
Post Data:
["System1.ApplicationView","System1.ManagementView"]
Response:
{
"Designations": [
"System1.ApplicationView",
"System1.ManagementView"
],
"Key": 2,
"ErrorCode": 0,
"_links": [
{
"Rel": "unsubscribe",
"Href": "api/sr/SystemBrowserSubscriptions/01ac873d-
23ae-49cb-86bc-6764d0b38904?subscriptionKey=%5b2%5d",
}
]
}
67

After subscribing for changes in the System Browser views, for any changes in the
System Browser views a notification will be sent.

2. systemBrowserHub : legacy
Function notifySystemBrowserChanges( data )
data SystemBrowserSu See System Browser subscription
bscription object [➙ 78]
7.6.5.2 Distributed System support for subscription

• For distributed systems subscription support, A filter “*” is explicitely
supported for the System part. That means client can specify paths ‘for all
systems’ using * as shown below.
"*.ApplicationView" – this will subscribe Application View of all the
systems added in the distributed system.
• And if value of designation array is not provided then, no such filtering as
described above will be applied. In case of NULL, client will receive
notifications of all the changes in the all of the systems.
7.6.6 Creating Channalized Systembrowser Subscription

available at client side. Rest of the push notificaitons will be notified over
notifySystemBrowserChanges.
Resource Path /sr/SystemBrowserSubscriptions /channelize/:requestId/:connectionId

Category Public
HTTP Method POST
hub connection.
request.
Required
connection
Required
Examples Request:
POST
api/sr/SystemBrowserSubscriptions/channelize/9565ca41-
8556-4dbb-94cc-1b89451a5db5/448b3117-44ef-4d8f-baa2-
7274aa3050af
Post Data:
["System1.ApplicationView","System1.ManagementView"]
68
Response:
HTTP/1.1 200 OK
{
"Designations": [
],
"Key": 2,
"ErrorCode": 0,
"_links": [
{
"Href": "api/sr/SystemBrowserSubscriptions/01ac873d-23ae-49cb-86bc-
6764d0b38904?subscriptionKey=%5b2%5d",
}
]
}

After subscribing for system browser, the subscription status will be sent only once.

2. systemBrowserHub : legacy
Status Subscription System Browser subscription
Response object [➙ 191]
Example {
"Designations": [
],
"Key": 2,
"ErrorCode": 0,
“RequestFor”:”notifySystemBrowserChanges”,
"_links": [
{
"Href": "api/sr/SystemBrowserSubscriptions/01ac873d-23ae-49cb-
86bc-6764d0b38904?subscriptionKey=%5b2%5d",
}
]
}
69
7.6.7 Deleting a Subscription for Changes in the System

Browser views
7.6.7.1 Passing subscription keys in query parameter

Resource Path /sr/systemBrowsersubscriptions/:connectionId
Category Public
HTTP Method DELETE
connectionId String Identifier of subscription
Required
subscriptionKey Array of integer Querystring parameter, which
holds the JSON array of
subscription keys
Response UnsubscriptionStatus See [➙ 72]
Unsubscribe object which contains Key and ErrorCode based on whether the
request is successful ot not.
Examples Request:
DELETE /api/sr/SystemBrowserSubscriptions/01ac873d-23ae-49cb-
86bc-6764d0b38904?subscriptionKey=%5b2%5d
Response:
[
{
"ErrorCode": 0,
"Key": 2
}
]
7.6.7.2 Passing subscription keys in request body

Resource Path /sr/systemBrowsersubscriptions/withbody/:connectionId
Category Public
HTTP Method DELETE
Parameters
Body Array of Subscription
keys
Query Property Type Description
Required
Response UnsubscriptionStatus See [➙ 72]
Unsubscribe object which contains Key and ErrorCode based on whether the
request is successful ot not.
Examples Request:
DELETE /api/sr/SystemBrowserSubscriptions/01ac873d-23ae-
49cb-86bc-6764d0b38904
Body Data:
[
“2”
]
Response:
[
70
Value Service 10
{
"ErrorCode": 0,
"Key": 2
}
]
7.6.8 Update CNS Node Description

Resource Path /src/systembrowser/{designation}
Category Internal
HTTP Method GET
designation string Full view name;
Designation id of node in
systembrowser tree
(Recommendation: Double
UrlEncode parameter prior to
making it to part of URI.) Required
cnsinformation System- Descriptor text for node Object
BrowserEditRep-
resentation
Examples Request:
api/systembrowser/System1.ApplicationView%3AApplicationView.Documents?
api_key=defaultadmin%3Aa'
Response: 200
7.7 Value Service

Resource Service Category Requires Authentication Requires SignalR (Push
Notifications)
/values Public x
/valuessubscriptions Public x x
7.7.1 Retrieving a Value of an Object or Property

If no property is specified but only an object, the value of the default property is
returned.
Resource Path /values/:objectOrPropertyId

Category Public
HTTP Method GET
objectOrPropertyId string Address of object or property
Required
Optional query parameter with
readMaxAge int default value as null;
When the value is 'older' than this

number of milliseconds, it will first
be re-read at the driver (0 implies
always re-read). A negative value
71
10 Value Service
disables driver re-reading and

always returns the value from
process image.
An array of ValueDetails objects [➙62]
Examples Request 1: Object Id +Property
GET /api/values/GmsDevice_2_1504_4194306.Present_Value
Response:
[
{
"DataType":"BasicFloat",
"Value":{
"Value":"35",
"Quality":"9439544818971182337",
"QualityGood":true,
"Timestamp":"2017-12-20T08:56:06.904Z"
},
"OriginalObjectOrPropertyId":"GmsDevice_2_1504_4194306.Pre
sent_Value",
"ObjectId":"System1:GmsDevice_2_1504_4194306",
"PropertyName":"Present_Value",
"AttributeId":"System1:GmsDevice_2_1504_4194306.Present_Va
lue:_online.._value",
"ErrorCode":0,
"IsArray":false
}
]
Request 2: Designation + Property
GET
/api/values/System1.ManagementView:ManagementView.FieldNet
works.TestNet.Hardware.Devices_1504.Local_IO.AO_2;.Present
_Value
Response:
[
{
"Value":{
"Value":"35",
"Quality":"9439544818971182337",
"QualityGood":true,
"Timestamp":"2017-12-20T08:58:05.037Z"
},
"OriginalObjectOrPropertyId":"System1.ManagementView:Manag
ementView.FieldNetworks.TestNet.Hardware.Devices_1504.Loca
l_IO.AO_2;.Present_Value",
"ErrorCode":0,
"IsArray":false
}
]
Request 3: Object Id +Property
GET
/api/values/GmsDevice_2_1504_4194306.Present_Value?readMax
Age=-1
Response:
[
{
72
Value Service 10
"Value":{
"Value":"35",
"Quality":"9439544818971182337",
"QualityGood":true,
"Timestamp":"2017-12-20T08:56:06.904Z"
},
sent_Value",
"ErrorCode":0,
"IsArray":false
}
]
7.7.2 Retrieving Values for a List of Objects or Properties

Resource Path /values
Category Public
HTTP Method POST
Parameters
Body Array of
ObjectOrPropertyId
Query Optional parameter: default value
readMaxAge int as null;
When the value is 'older' than this

number of milliseconds, it will first
be re-read at the driver (0 implies
always re-read). A negative value
disables driver re-reading and
always returns the value from
process image.
An array of ValueDetails objects [➙62]
Examples Request:
POST /api/values
Post Data:
[
"GmsDevice_2_1504_4194306.Present_Value",
"System1:GmsDevice_2_1504_4194306.Present_Value",
"System1.ManagementView:ManagementView.FieldNetworks.TestN
et.Hardware.Devices_1504.Local_IO.AO_2;.Present_Value"
//Designation+Property
]
Response:
[
{
"Value":{
"Value":"35",
"Quality":"9439544818971181313",
73
10 Value Service
"QualityGood":true,
"Timestamp":"2017-12-20T08:31:40.132Z"
},
sent_Value",
"ErrorCode":0,
"IsArray":false
},
{
"Value":{
"Value":"35",
"Quality":"9439544818971181313",
"QualityGood":true,
"Timestamp":"2017-12-20T08:31:40.132Z"
},
"OriginalObjectOrPropertyId":"System1:GmsDevice_2_1504_419
4306.Present_Value",
"ErrorCode":0,
"IsArray":false
},
{
"Value":{
"Value":"35",
"Quality":"9439544818971181313",
"QualityGood":true,
"Timestamp":"2017-12-20T08:31:40.132Z"
},
"OriginalObjectOrPropertyId":"System1.ManagementView:Manag
ementView.FieldNetworks.TestNet.Hardware.Devices_1504.Loca
l_IO.AO_2;.Present_Value",
"ErrorCode":0,
"IsArray":false
}
]
Request 2:
POST /api/values?readMaxAge=-1
Post Data:
[
"GmsDevice_2_1504_4194306.Present_Value"
]
Response:
[
{
74
Value Service 10
"Value":{
"Value":"35",
"Quality":"9439544818971182337",
"QualityGood":true,
"Timestamp":"2017-12-20T08:56:06.904Z"
},
sent_Value",
"ErrorCode":0,
"IsArray":false
}
]
7.7.3 Creating a Subscription for a Change of a Value

(Obsolete)
Resource Path /sr/valuessubscriptions/:connectionId

Category Public
HTTP Method POST
Required
detailsRequired bool
Body Array of
ObjectOrPropertyId
An array of Subscription objects [➙56]
Examples Request:
POST /api/sr/valuessubscriptions/977a6389-980c-41ca-84ab-
2518fd0ca41a
Post Data:
[
et.Hardware.Devices_1504.Local_IO.AO_2;.Present_Value""//D
esignation+Property
]
Response:
[
{
"Key":1,
"PropertyId":"System1:GmsDevice_2_1504_4194306.Present_Val
ue",
"ErrorCode":0,
"_links":[
{
"Rel":"unsubscribe",
75
10 Value Service
"Href":"api/sr/valuessubscriptions/4999fe9e-
05c9-41a8-bc82-9ade768c3ced?subscriptionKey=%5b1%5d",
"IsTemplated":false
}
]
},
{
"Key":2,
ue",
"ErrorCode":0,
"_links":[
{
"IsTemplated":false
}
]
},
{
"Key":3,
ue",
"ErrorCode":0,
"_links":[
{
"IsTemplated":false
}
]
}
]

After subscribing for changes of a value, the current value(s) will be sent in an
initial notification. Afterwards, any change will be notified.

2. valuesHub : legacy
Function notifyValues( data )
data Array of See ValueDetails [➙62]
ValueDetails
7.7.4 Creating Channalized Value Subscription

If channelized subscription is done ,subscription status will be pushed through
notifySubscriptionStatus function available at client side. Value changes will be
notified over notifyValues[➙76].
Resource Path /sr/valuessubscriptions/channelize/:requestId/:connectionId
76
Value Service 10
Category Public
HTTP Method POST
hub connection.
request.
Required
connection
Required
Examples Request:
POST /api/sr/valuessubscriptions/channelize/9565ca41-8556-
4dbb-94cc-1b89451a5db5/977a6389-980c-41ca-84ab-
2518fd0ca41a
Post Data:
[
et.Hardware.Devices_1504.Local_IO.AO_2;.Present_Value""
//Designation+Property
]
Response:
HTTP/1.1 200 OK
Notification 1:
{
"Key":1,
"PropertyId":"System1:GmsDevice_2_1504_4194306.Present_Value",
"ErrorCode":0,
objectOrPropertyId: "GmsDevice_2_1504_4194306.Present_Value",
"_links":[
{
"Href":"api/sr/valuessubscriptions/4999fe9e-05c9-41a8-bc82-
9ade768c3ced?subscriptionKey=%5b1%5d",
"IsTemplated":false
}
]
}
Notification 2:
{
"Key":2,
"ErrorCode":0,
77
10 Value Service
objectOrPropertyId: "System1:GmsDevice_2_1504_4194306.Present_Value",
"_links":[
{
"IsTemplated":false
}
]
}
Notification 3:
{
"Key":3,
objectOrPropertyId:
"System1.ManagementView:ManagementView.FieldNetworks.TestNet.Hardwa
re.Devices_1504.Local_IO.AO_2;.Present_Value",
"RequestId": "9565ca41-8556-4dbb-94cc-1b89451a5db5"
"ErrorCode":0,
"_links":[
{
"IsTemplated":false
}
]
}
notifyValues:
Notification 1:
[{
"Value":
{"Value":"35",
"Quality":"9439544818971181313",
"QualityGood":true,
"Timestamp":"2019-04-10T10:21:02.527Z"},
"ErrorCode":0,
"IsArray":false,
"SubscriptionKey":1
}]
Notification 2:
[{
"Value":
{"Value":"40",
"Quality":"9439544818971181313",
"QualityGood":true,
"Timestamp":"2019-04-10T10:21:02.527Z"},
"ErrorCode":0,
"IsArray":false,
"SubscriptionKey":2
}]
78
Value Service 10
Notification 3:
[{
"Value":
{"Value":"90",
"Quality":"9439544818971181313",
"QualityGood":true,
"Timestamp":"2019-04-10T10:21:02.527Z"},
"ErrorCode":0,
"IsArray":false,
"SubscriptionKey":3
}]

After subscribing for Values, for each key subscription status will be sent through
notifySubscriptionStatus.

2. valuesHub : legacy
Status Subscription Subscription objects [➙181]
Response
Example {
"Key":1,
"ErrorCode":0,
objectOrPropertyId: "GmsDevice_2_1504_4194306.Present_Value",
“RequestFor”:”notifyValues”,
"_links":[
{
"IsTemplated":false
}
]
}
7.7.1 Deleting a Subscription for a Change of a Value
7.7.1.1 Passing subscription keys in query parameters

Resource Path /sr/valuessubscriptions/:connectionId
Category Public
HTTP Method DELETE
79
10 Property Value Service
Required
subscriptionkey Array of int List of subscription-keys
An array of unsubscription objects. See Link [➙57]
Examples Request:
DELETE /api/sr/valuessubscriptions/9d4211db-a740-44c3-93b8-
015df1a529ca?subscriptionKey=[2,3]
Response:
[
{
"ErrorCode": 0,
"Key": 2
},
{
"ErrorCode": 0,
"Key": 3
}
]
7.7.1.2 Passing subscription keys in request body

Resource Path /sr/valuessubscriptions/withbody/:connectionId
Category Public
HTTP Method DELETE
Parameters
keys
Required
Examples Request:
DELETE /api/sr/valuessubscriptions/9d4211db-a740-44c3-
93b8-015df1a529ca
Body Data:
[ “2“,“3“]
Response:
[
{
"ErrorCode": 0,
"Key": 2
},
{
"ErrorCode": 0,
"Key": 3
}
]
7.8 Property Value Service

80
Property Value Service 10
/propertyvalues Public x
7.8.1 Retrieving Detailed Values for Object or Property Id

Retrieves properties with runtime values for an Object OR Property Id. This gives
properties and attributes associated with the requested Object OR Property Id. If
input is actually an Object Id then default property for the object id along with the
attributes is returned in the response. If input is a property id then that specific
property and attributes of that object id will be returned in the response. One
optional Boolean type query string parameter readAllProperties is available in both
the cases. If readAllProperties is set to True then all the properties along with the
attributes are returned in the response for the requested Object OR Property Id
Resource Path /propertyvalues/:objectOrPropertyId

Category Public
Category Public
HTTP Method GET
objectOrPropertyId string ObjectOrPropertyId
Required
readAllProperties bool If True then all the properties for
the requested Object OR
Property Id will be returned in
the response. Default is False.
The Object<Type> see [➙ 62]
Examples Request 1:
GET api/propertyvalues/System1:HDB_ArchiveGroup_1
Response:
{
"ErrorCode": 0,
"ObjectId": "System1:HDB_ArchiveGroup_1",
"Attributes": {
"DefaultProperty":
"ObjectId": "HDB_ArchiveGroup_1",
"DisciplineId": 0,
"TypeDescriptor": "Server Software",
"TypeId": 6900,
"SubTypeDescriptor": "History Database",
"SubTypeId": 6903,
"ManagedType": 14,
“ManagedTypeName“ : "Station"
},
"Properties": [
{
"Order": 0,
"PropertyName":"StatusPropagation.AggregatedSummaryStatus",
"Descriptor": "Summary Status",
"Type": "ExtendedEnum",
"Usage": 7,
"Value": {
"Value": "0",
81
10 Property Value Service
"DisplayValue": "Normal",
"Quality": "9439544818969084161",
"QualityGood": true,
"Timestamp": "2015-05-21T05:08:56.772Z"
},
"Resolution": 0,
"PropertyAbsent": false,
"IsArray": false,
“TextTable”: TxG_PropagationSummaryStatus
}
]
}
Request 2: with scaled information
GET
api/propertyvalues/System2:GmsDevice_1_20811_1.Present_Value?
Response :
{
"ErrorCode": 0,
"ObjectId": "System2:GmsDevice_1_20811_1",
"Attributes": {
"DefaultProperty": "Present_Value",
"DisciplineDescriptor": "Building Automation",
"DisciplineId": 50,
"TypeDescriptor": "Sensor",
"TypeId": 6700,
"SubTypeDescriptor": "Unassigned",
"SubTypeId": 0,
"ManagedType": 80,
"ManagedTypeName": "BACnetPoint",
"ObjectModelName": "GMS_BACNET_EO_BA_AI_1",
"ValidationRules": {
"CommentRule": "Mandatory",
"ReAuthentication": "NoNeed",
"Configuration": 1,
"IsFourEyesEnabled": false,
"_links": []
}
},
"Properties": [
{
"Order": 2,
"PropertyName": "Present_Value",
"Descriptor": "Present Value",
"Type": "ExtendedReal",
"Usage": 7,
"Value": {
"Value": "25.5555555555556",
"DisplayValue": "25.5555555555556",
"Quality": "9439544818975376641",
"Timestamp": "2019-06-11T12:41:00.067Z"
},
"Min": -572.7777777777778,
"Max": 537.2222222222222,
82
Property Value Service 10
"UnitDescriptor": "°C",
"UnitId": 62,
"Resolution": 2,
"IsArray": false,
"ScaledInformation": {
"Factor": 0.5555555555555556,
"Index": 62,
"Offset": -17.77777777777778
}
}
]
}
Request 3: using Designation

GET
/api/propertyvalues/System1.ManagementView:ManagementView.Fie
ldNetworks.TestNet.Hardware.Devices_1504.Local_IO.AO_2;?readA
llProperties=false
Response:
{
"ErrorCode":0,
"Attributes":{
"DefaultProperty":"Present_Value",
"DisciplineDescriptor":"Building Automation",
"DisciplineId":50,
"SubDisciplineDescriptor":"Unassigned",
"SubDisciplineId":0,
"TypeDescriptor":"Command",
"TypeId":1100,
"SubTypeDescriptor":"Analog",
"SubTypeId":1101,
"ManagedType":80,
"ManagedTypeName":"BACnetPoint"
},
"Properties":[
{
"Order":0,
"Descriptor":"Present Value",
"Type":"ExtendedReal",
"Usage":7,
"Value":{
"Value":"35",
"DisplayValue":"35",
"Quality":"9439544818971182337",
"QualityGood":true,
"Timestamp":"2017-12-20T09:15:11.96Z"
},
"UnitDescriptor":"°F",
"UnitId":64,
"Resolution":0,
"PropertyAbsent":false,
"IsArray":false
}
]
83
10 Properties Service
7.9 Properties Service

/properties Public x
7.9.1 Retrieving Detailed Values for Object or Property Id

Retrieves properties without any runtime values for an Object OR Property Id. If
input is actually an Object Id then default property for the object id will be returned
in the response. If input is a property id then that specific property will be returned
in the response. Two optional query string parameters are available in this
interface. First is requestType of type int, which specifies whether the request is to
read Property Names, Properties, Attributes, Properties and Attributes. Second
parameter is readAllProperties of type bool, if this isTrue then all the properties for
the requested Object OR Property Id will be returned in the response.
Resource Path /properties/:objectOrPropertyId

Category Public
HTTP Method GET
Required
requestType Int Specifies the request type. See
[➙ 44]. Default is 2.
readAllProperties bool If True then all the properties for
the requested Object OR
Property Id will be returned in
the response. Default is False.
requestType Return Type Description
0 See [➙ 67] Property collections
contain list of all property-
names
1 Object<null> Property collections
empty; object contains
attributes
2 (default) Object<PropertyDetails> Property collections
populated; no attribute
field
3 Object<PropertyDetails> Property collections
populated;
object contains attributes
Examples Request1: Get Property Names
GET api/properties/System1:HDB_ArchiveGroup_1?requestType=0
OR
GET
/api/properties/System1.ManagementView:ManagementView.Managem
entSystem.Servers.Server.HistoryDatabase.ArchiveSchedules.Act
ivityLog;?requestType=0 //using Designation
Response1:
84
Properties Service 10
{
"Properties": [
"Export.Activated",
"Max_Retention.Activated",
"Max_Retention.Delay_Span",
"Max_Retention.Delay_Unit",
"Max_Retention.FirstDate",
"Max_Retention.Invocation_Period",
"Max_Retention.Invocation_Unit",
"Max_Retention.Max_Count",
"Min_Retention.Delay_Span",
"Min_Retention.Delay_Unit",
"Min_Retention.Min_Count",
"StatusPropagation.AggregatedSummaryStatus"
],
"FunctionProperties": []
}
Request2: Get Properties and Attributes

GET api/properties/System1:HDB_ArchiveGroup_1?requestType=3
OR
GET
/api/properties/System1.ManagementView:ManagementView.Managem
entSystem.Servers.Server.HistoryDatabase.ArchiveSchedules.Act
ivityLog;?requestType=3 //using Designation
Response2:
[
{
"ErrorCode": 0,
"Attributes": {
"DefaultProperty":
"DisciplineId": 0,
"TypeId": 6900,
"SubTypeId": 6903,
"ManagedType": 14,
},
"Properties": [
{
"Order": 0,
"PropertyName":
"Descriptor": "Summary Status",
"Usage": 7,
"Resolution": 0,
"IsArray": false
}
85
]
}
]
Request 3: with scaled information

GET
api/properties/System2:GmsDevice_1_20811_1.Present_Value?requ
estType=3
Response 3 :
{
"ErrorCode": 0,
"Attributes": {
"DisciplineId": 50,
"TypeId": 6700,
"SubTypeId": 0,
"ManagedType": 80,
"CommentRule": "Mandatory",
"Configuration": 1,
"_links": []
}
},
"Properties": [
{
"Order": 2,
"Descriptor": "Present Value",
"Type": "ExtendedReal",
"Usage": 7,
"Value": {
"Value": "25.5555555555556",
"DisplayValue": "25.5555555555556",
"Quality": "9439544818975376641",
"Timestamp": "2019-06-11T12:41:00.067Z"
},
"Min": -572.7777777777778,
"Max": 537.2222222222222,
"UnitDescriptor": "°C",
"UnitId": 62,
"Resolution": 2,
"IsArray": false,
"ScaledInformation": {
"Factor": 0.5555555555555556,
86
Properties Service 10
"Index": 62,
"Offset": -17.77777777777778
}
}
]
}
7.9.1.1 Detail Request Type

requestType must have one of the following values.
requestType Description
0 Return property names only.
1 Return attributes of object only.
2 Return properties with detailed information; default.
3 Return properties with detailed information and attributes of object.
7.9.2 Retrieving Detailed Values for multiple Object or Property

Ids bulk interface
This interface is same as that of 7.9.1 only thing is this provides bulk interface to
read properties and attributes of multiple Object OR Property Ids in the same
request using HTTP POST. Array of Object OR Property Ids is passed in the POST
data. Rest all the configuration is same as that of 7.9.1.
Resource Path /properties

Category Public
HTTP Method POST
requestType Int Specifies the request type. See [➙
44]. Default is 2.
readAllProperties bool If True then all the properties for the
requested Object OR Property Id
will be returned in the response.
Default is False.
Body Array of Object OR Property Ids
requestType Return Type Description
1 Object<null> Property collections
empty; object contains
attributes
populated; no attribute
field
populated;
object contains
attributes
Examples Request:
Post api/properties?requestType=3
87
Request Body:
["System1:HDB_ArchiveGroup_1.Min_Retention.Delay_Span","Sy
stem1:HDB_ArchiveGroup_1.Min_Retention.Delay_Unit"]
OR
//Using Designation + Property
[
"System1.ManagementView:ManagementView.ManagementSystem.Se
rvers.Server.HistoryDatabase.ArchiveSchedules.ActivityLog;
.Min_Retention.Delay_Span",
.Min_Retention.Delay_Unit"
]
Response:
[
{
"ErrorCode": 0,
"Attributes": {
"DefaultProperty":
"DisciplineId": 0,
"TypeId": 6900,
"SubTypeId": 6903,
"ManagedType": 14,
},
"Properties": [
{
"Order": 3,
"PropertyName": "Min_Retention.Delay_Span",
"Descriptor": "Min Retention Span",
"Type": "ExtendedInt",
"Usage": 11,
"Min": 1,
"Resolution": 0,
"IsArray": false
}
]
},
{
"ErrorCode": 0,
"Attributes": {
"DefaultProperty":
"DisciplineId": 0,
88
Command Service 10
"TypeId": 6900,
"SubTypeId": 6903,
"ManagedType": 14,
},
"Properties": [
{
"Order": 4,
"PropertyName": "Min_Retention.Delay_Unit",
"Descriptor": "Min Retention Unit",
"Usage": 11,
"Max": 7,
"Resolution": 0,
"IsArray": false
}
]
}
]
7.9.1 Retrieving an Image for a Property

Retrieve an icon for a property. A couple of important notes:
1) Iif the property has not been assigned an image the return will still be OK (200)
but the return will be an empty string.
2) The only supported format for the image is Base64-encoded, PNG with a size
of 32 pixels wide by 32 pixels high. This may change in the future.
Resource Path /properties/:propertyId/icon

Category Public
HTTP Method GET
propertyId string The fully-qualified property name, which includes the
system information. For example:
System1:GmsDevice_1_8166_1.Present_Value
Required
The icon as a Base64 encoded PNG of size 32x32
Examples Request:
GET
api/properties/System1:GmsDevice_1_8166_1.Present_Value/icon
Response:
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6
QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAANSURBVB
hXY/j//78GAAkkAyb6sRXrAAAAAElFTkSuQmCC
7.10 Command Service

/commands Public x
89
10 Command Service
/commandssubscript Public x x
ions
7.10.1 Retrieving a List of Commands for a Provided Property

Some commands might be non executable at this moment.
Resource Path /commands/:propertyId

Category Public
HTTP Method GET
propertyId string PropertyId
Required
commandId string Optional filter for a specific
commandId
enabledCommandsO bool If set to true only currently enabled
nly commands will be returned (default
false).
clientType string If set commands can be filtered for
specific clients (All, Headless,
Headful)
An array of PropertyCommand objects See [➙ 52]
Examples Request 1:
GET
api/commands/System1%3AHDB_ArchiveGroup_1.Min_Retention.De
lay_Span
Response:
[
{
"PropertyId":
"System1:HDB_ArchiveGroup_1.Min_Retention.Delay_Span",
"ErrorCode": 0,
"Commands": [
{
"Configuration":2
"PropertyId":
"Descriptor": "Set",
"Parameters": [
{
"Name": "Value",
"DataType": "ExtendedInt",
"DefaultValue": "0",
"Order": 0,
"Descriptor": "",
"Min": 1,
“Application”: 0,
"EnumerationTexts": []
}
],
"Id": "Write",
“IsDefault”: false,
"_links": [
{
"Rel": "self",
90
Command Service 10
"Href":
"api/commands/System1%3aHDB_ArchiveGroup_1.Min_Retention.D
elay_Span/Write",
}
]
}
]
}
]
Request 2: using Designation + Property
GET
/api/commands/System1.ManagementView:ManagementView.Manage
mentSystem.Servers.Server.HistoryDatabase.ArchiveSchedules
.ActivityLog;.Min_Retention.Delay_Span
Response:
[ {
"PropertyId":"System1.ManagementView:ManagementView.Manage
.ActivityLog;.Min_Retention.Delay_Span",
"ErrorCode":0,
"Commands":[
{
"Descriptor":"Set",
"Parameters":[
{
"Name":"Value",
"DataType":"ExtendedInt",
"DefaultValue":"4",
"Order":0,
"Descriptor":"",
"Min":1,
"EnumerationTexts":[
]
}
],
"Id":"Write",
"Configuration":0,
"_links":[
{
"Rel":"self",
"Href":"api/commands/System1.ManagementView%3aManagementVi
ew.ManagementSystem.Servers.Server.HistoryDatabase.Archive
Schedules.ActivityLog%3b.Min_Retention.Delay_Span/Write",
"IsTemplated":false
}
]
}
]
}
]
91
10 Command Service
7.10.2 Retrieving Lists of Commands for a List of Properties

Resource Path /commands
Category Public
HTTP Method POST
Required
commandId string Optional filter for a specific
commandId
enabledCommandsO bool If set to true only currently enabled
nly commands will be returned (default
false).
clientType string If set commands can be filtered for
specific clients (All, Headless,
Headful)
Body Array of PropertyId
An aArray of PropertyCommand objects See [➙ 52]
Examples Request 1:
Post : /api/commands/
Request Body:
[
"System1:HDB_ArchiveGroup_1.Min_Retention.Delay_Unit"
]
Response:
List of Commands fetched for two different PropertyId:
[
{
"PropertyId":
"ErrorCode": 0,
"Commands": [
{
"Configuration":2
"PropertyId":
"Parameters": [
{
"Name": "Value",
"Order": 0,
"Descriptor": "",
"Min": 1,
"EnumerationTexts": []
}
],
"Id": "Write",
"_links": [
92
Command Service 10
{
"Rel": "self",
"Href":
elay_Span/Write",
}
]
}
]
},
{
"PropertyId":
"System1:HDB_ArchiveGroup_1.Min_Retention.Delay_Unit",
"ErrorCode": 0,
"Commands": [
{
"Configuration":1
"PropertyId":
"System1:HDB_ArchiveGroup_1.Min_Retention.Delay_Unit",
"Parameters": [
{
"Name": "Value",
"DataType": "ExtendedEnum",
"Order": 0,
"Descriptor": "",
"Max": 7,
"EnumerationTexts": [
{
"Descriptor": "seconds",
"Value": 0
},
{
"Descriptor": "minutes",
"Value": 1
}
]
}
],
"Id": "Write",
"_links": [
{
"Rel": "self",
"Href":
elay_Unit/Write",
}
]
}
]
}
]
Request 2: Using Designation + Property
93
10 Command Service
Post : /api/commands/
Request Body:
[
.Min_Retention.Delay_Unit"
]
Response:
[
{"PropertyId":"System1.ManagementView:ManagementView.Manag
ementSystem.Servers.Server.HistoryDatabase.ArchiveSchedule
s.ActivityLog;.Min_Retention.Delay_Span",
"ErrorCode":0,
"Commands":[
{
"Descriptor":"Set",
"Parameters":[
{
"Name":"Value",
"DataType":"ExtendedInt",
"DefaultValue":"4",
"Order":0,
"Descriptor":"",
"Min":1,
"EnumerationTexts":[]
}
],
"Id":"Write",
"Configuration":0,
"_links":[
{
"Rel":"self",
Schedules.ActivityLog%3b.Min_Retention.Delay_Span/Write",
"IsTemplated":false
}
]
}
]
},
s.ActivityLog;.Min_Retention.Delay_Unit",
"ErrorCode":0,
"Commands":[
s.ActivityLog;.Min_Retention.Delay_Unit",
"Descriptor":"Set",
"Parameters":[
{
"Name":"Value",
94
Command Service 10
"DataType":"ExtendedEnum",
"DefaultValue":"4",
"Order":0,
"Descriptor":"",
"Max":7,
"EnumerationTexts":[
{
"Descriptor":"seconds",
"Value":0
},
{
"Descriptor":"minutes",
"Value":1
},
{
"Descriptor":"hours",
"Value":2
},
{
"Descriptor":"days",
"Value":3
},
{
"Descriptor":"months",
"Value":4
},
{
"Descriptor":"years",
"Value":5
},
{
"Descriptor":"week",
"Value":6
},
{
"Descriptor":"quarter",
"Value":7
}
]
}
],
"Id":"Write",
"Configuration":0,
"_links":[
{"Rel":"self",
Schedules.ActivityLog%3b.Min_Retention.Delay_Unit/Write",
"IsTemplated":false
}
]
}
]
}
]
95
10 Command Service
7.10.3 Executing a Command

Resource Path /commands/:propertyId/:commandId
Category Public
HTTP Method POST
Required
commandId string Command identifier
Required
commandInput CommandInputF command parameter details (Name,
orExecution Value pair) sent from client if
See [ ➙ 196] required.
Body An array of NameValue objects of Type(CommandInputForExecution)

Examples Request:
POST
/api/commands/System1:HDB_ArchiveGroup_1.Min_Retention.Del
ay_Span/Write
OR
//Using Designation + Property
POST
/api/commands/System1.ManagementView:ManagementView.Manage
.ActivityLog;.Min_Retention.Delay_Span/Write
Request Body:
[
{
"Name": "Value",
"Value": "3",
"comment1",
"comment2",
"comment3"
],
"Password": "password",
"SuperName": "supervisorusername",
"SuperPassword": "supervisorpassword"
}
]
Response:
HTTP 200 OK
7.10.4 Bulk Commanding

Resource Path /commands/:commandId
Category Public
HTTP Method POST
commandId string Command identifier
Required
Body bulkCommandInput BatchCommand command parameter details (Name,
Execution Value pair) sent from client if
96
Command Service 10
See [ ➙ 196] required along with array of property

ids of same type.
An array of BatchExecution objects See Link [➙ 196]
Examples Request:
POST : /api/commands/Write
Request Body:
{
"CommandInputForExecution": [
{
"Name": "Value",
"Value": "3",
"comment1",
"comment2",
"comment3"
],
"Password": "password1",
"SuperName": "supervisorusername",
"SuperPassword": "supervisorpassword"
}
],
"PropertyIds": [
.Min_Retention.Delay_Span", //Designation + Property
rvers.Server.HistoryDatabase.ArchiveSchedules.EventLog;.Mi
n_Retention.Delay_Span" //Designation + Property
]
}
Response:
HTTP 200 OK
[
{
"PropertyId":
"ErrorCode": 0
},
{
"PropertyId":
"ErrorCode": 0
},
{
"PropertyId":
"ErrorCode": 0
},
{
"PropertyId":
rvers.Server.HistoryDatabase.ArchiveSchedules.EventLog;.Mi
97
10 Command Service
n_Retention.Delay_Span",
"ErrorCode": 0
}
]
7.10.5 Bulk Commanding with different pair of property values

and command id
Resource Path /commands/propertycommand
Category Public
HTTP Method POST
Body An array of PropertyComma Array of property command object.
propertyCommandInp ndInput Each property command contains
ut Execution commandid ,propertyid and optional
See [ ➙197] command parameter details

An array of BatchExecution objects See Link [➙ 196]
Examples Request:
POST : /api/commands/propertycommand
Request Body:
[
{
"CommandInputForExecution": [
{
"Name": "Value",
"DataType": "ExtendedUint",
"Value": "1500"
}
],
"PropertyId": "LogViewer.ViewSize",
"CommandId": "Write"
},
{
"PropertyId": "LogViewer.SuppressAlarms",
"CommandId": "Enable"
}
]
Response:
HTTP 200 OK
[
{
"PropertyId": "LogViewer.ViewSize",
"ErrorCode": 0
},
{
"PropertyId": "LogViewer.SuppressAlarms",
"ErrorCode": 0
}
]
98
Command Service 10
7.10.6 Creating a Subscription for a Change of a Command

(Obsolete)
Resource Path /sr/commandssubscriptions/:connectionId

Category Public
HTTP Method POST
Required
propertyIdList String[] Array of Properties from POST
data, which will be subscribed for
Command Change notification
An array of Subscription objects See Link [➙ 46]
Examples Request:
Post :api/sr/commandssubscriptions/87a73827-f25b-41e8-
9225-2f08316ea0fb
Request Body:
[
.Min_Retention.Delay_Span" //Designation + Property
]
Response:
[
{
"Key":5,
"PropertyId":"System1:HDB_ArchiveGroup_2.Min_Retention.Del
ay_Span",
"ErrorCode":0,
"_links":[
{
"Href":"api/sr/commandssubscriptions/aa82215b-
b635-40a7-92a3-4fcc80a677d1?subscriptionKey=%5b5%5d",
"IsTemplated":false
}
]
},
{
"Key":6,
"ErrorCode":0,
"_links":[
{
"IsTemplated":false
}
]
99
10 Command Service
}
]
7.10.7 Push Notification

After subscribing for changes of a command(s) all command(s) will be sent in an
initial notification. Afterwards any change will be notified.

2. commandsHub : legacy
Function notifyCommands( data )
data Array of See PropertyCommand [➙ 194]
PropertyCommand
7.10.7.1 Creating Channalized Command Subscription

available at client side. Command changes will be notified over notifyCommands.
Resource Path /sr/commandssubscriptions/chanellize/:connectionId
Category Public
HTTP Method POST
Required
propertyIdList String[] Array of Properties from POST
data, which will be subscribed for
Command Change notification
Examples Request:
Post :api/sr/commandssubscriptions/ channelize/9565ca41-
8556-4dbb-94cc-1b89451a5db5/87a73827-f25b-41e8-9225-
2f08316ea0fb
Request Body:
[
.Min_Retention.Delay_Span" //Designation + Property
]
HTTP/1.1 200 OK
Notification 1:
{
"Key":5,
"PropertyId":"System1:HDB_ArchiveGroup_2.Min_Retention.Del
ay_Span",
"SubscriptionId":"System1:HDB_ArchiveGroup_2.Min_Retention
.Delay_Span",
"ErrorCode":0,
100
Command Service 10
“RequestFor”:”notifyCommands”,
"_links":[
{
"IsTemplated":false
}
]
}
Notification 2:{
"Key":6,
"SubscriptionId":"System1.ManagementView:ManagementView.Ma
nagementSystem.Servers.Server.HistoryDatabase.ArchiveSched
ules.ActivityLog;.Min_Retention.Delay_Span",
"ErrorCode":0,
"_links":[
{
"IsTemplated":false
}
]
}
]

After subscribing for Commands, for each key subscription status will be sent
through notifySubscriptionStatus.

2. commandsHub : legacy
Status Subscription Subscription objects See Link [➙
Response 180]
Example {
"Key":6,
"PropertyId":"System1.ManagementView:ManagementView.Management
System.Servers.Server.HistoryDatabase.ArchiveSchedules.ActivityLog;.Mi
n_Retention.Delay_Span",
"SubscriptionId":"System1.ManagementView:ManagementView.Managem
entSystem.Servers.Server.HistoryDatabase.ArchiveSchedules.ActivityLog;
"ErrorCode":0,
"_links":[
{
101
10 Command Service
"Href":"api/sr/commandssubscriptions/aa82215b-b635-40a7-92a3-
4fcc80a677d1?subscriptionKey=%5b6%5d",
"IsTemplated":false
}
]
}
]
7.10.7.3 Deleting a Subscription for a Change of a Command.

7.10.7.4 Passing subscription keys in query parameter
Resource Path /sr/commandssubscriptions/:connectionId
Category Public
HTTP Method DELETE
Required
subscriptionkey Array of int List of subscription keys
Examples Request: Delete
api/sr/commandssubscriptions/a43e4363-296e-405d-977b-
36dec9ddbafc?subscriptionKey=[1,2]
Response:
{
"ErrorCode": 0,
"Key": 1
},
{
"ErrorCode": 0,
"Key": 2
}
7.10.7.5 Passing subscrption keys in request body

Resource Path /sr/commandssubscriptions/withbody/:connectionId
Category Public
HTTP Method DELETE
Parameters
keys
Required
Examples Request:
api/sr/commandssubscriptions/a43e4363-296e-405d-977b-
36dec9ddbafc
Body Data:
[ “1“,“2“]
102
Command Service 10
Response:
{
"ErrorCode": 0,
"Key": 1
},
{
"ErrorCode": 0,
"Key": 2
}
103
10 Trend Service
7.11 Trend Service

/trendseriesinfo Public x
/trendseries Public x
7.11.1 Retrieving a List of All Trend Collector Objects

Retrieve a list of all Trend Collector objects of a given system. It includes all Online
and Offline objects as following
1. Trendlog
2. Trendlog Multiple
3. Trend Log Definitions
Resource Path /trendseriesinfo/:systemId

Category Public
HTTP Method GET
Required
An array of TrendCollector objects [➙64]
Examples Request:
GET /api/trendseriesinfo/1
Response:
[
{
"CollectorObjectOrPropertyId":
"System1:GmsDevice_1_29129_113246209",
"TrendseriesId":
"System1:GmsDevice_1_29129_113246209.general.Data:_origina
l.2._value"
},
{
"CollectorObjectOrPropertyId":
"TrendseriesId":
"System1:GmsDevice_1_29129_113246210.general.Data:_origina
l.2._value"
}
]
104
Trend Service 10
7.11.2 Retrieving a List of Trend Collector Objects

Retrieve a list of Trend Collector objects. An object ID of a trend object (e.g.
TrendLog/TrendLogMultiple) or a property ID of a trended object is to be provided.
Resource Path /trendseriesinfo/:objectOrPropertyId

Category Public
HTTP Method GET
Required
An array of TrendCollector objects [➙64]
Examples Request:
GET /api/trendseriesinfo/System1:GmsDevice_2_1500_83886081
OR
//Using Designation
GET
/api/trendseriesinfo/System1.ApplicationView:ApplicationVi
ew.Trends.OfflineTrends.TestNet.Hardware.Devices_1500.Loca
l_IO.TL_1;
Response:
[
{
"PropertyIndex":1,
"CollectorObjectOrPropertyId":"System1:GmsDevice_2_1500_83
886081",
"TrendseriesId":"System1:GmsDevice_2_1500_83886081.general
.Data:_offline.._value"
}
]
7.11.3 Retrieving TrendViewDefinition object details

Retrieve a TrendViewDefition object details. An object ID of a trend view definition.
Resource Path /trendseriesinfo/tvd/:objectId
Category Public
HTTP Method GET
objectId string ObjectId of Trend View Definition
object
Required
A TrendViewDefinitionRepresentation object [➙198]
Examples Request:
GET
api/trendseriesinfo/tvd/ApplicationView_Trends_TrendViewDe
finitions_sampletvd
OR
GET
api/trendseriesinfo/tvd/System1.ApplicationViewApplication
View.Trends.TrendViewDefinitions.sampletvd;
Response:
105
10 Trend Service
{
"AxisX": {
"AutoScale": true,
"AxisType": 0,
"ScaleMax": 100,
"ScaleMin": 0,
"ShowTitle": false,
"ShowZeroLine": false,
"Title": ""
},
"AxisYLeft": {
"AutoScale": true,
"AxisType": 1,
"ScaleMax": 100,
"ScaleMin": 0,
"ShowTitle": false,
"Title": ""
},
"AxisYRight": {
"AutoScale": true,
"AxisType": 2,
"ScaleMax": 100,
"ScaleMin": 0,
"ShowTitle": false,
"Title": ""
},
"DescriptionTvd": "",
"ObjectIdOfTvd":
"System1:ApplicationView_Trends_TrendViewDefinitions_sampl
etvd",
"IdTvd": "a6393de5-454d-4f41-8e13-043c2f01dfdb",
"NameTvd": "sampletvd",
"NumberDisplayedSamplesPerTrendSerie": 100,
"RemoveOnlineTrendLogOfDeletedTrendSerie": false,
"TimeRange": {
"ValidTimeRange": 1,
"AbsoluteTimeRange": {
"From": "2019-06-24T10:07:33.075Z",
"To": "2019-06-24T10:12:33.075Z"
},
"RelativeTimeRange": {
"AnchorMode": 1,
"AnchorTime": "2019-06-24T10:12:30.986Z",
"NumberOfTimeUnits": 1,
"TimeUnit": 3
}
},
"TitleLeft": "",
"TitleRight": "",
"TitleTop": "",
"TsdCollectionInfo": {
"TrendSeriesDefinitions": [
{
"ReservedDateTime": "1777-07-07T07:07:07Z",
"AccessDenied": false,
106
Trend Service 10
"ArchiveOn": true,
"AxisAttachment": "ToLeft",
"ChartLineStyle": "Full",
"ChartLineType": "Line",
"Color": "ffff0000",
"DescriptionTlField": "",
"DescriptionTlGms": "Log Viewer-ViewSize",
"DescriptionTo": "",
"DescriptionToProperty": "View Size",
"ObjectIdOfTrendLog": "",
"ObjectIdOfTrendLogOnline":
"System1:TLO_LogViewer_ViewSize",
"ObjectIdOfTrendedObject":
"System1:LogViewer.ViewSize:_original.._value",
"Index": -1,
"IsLineVisible": true,
"LineWidth": 1,
"MaxTimeStamp": "0001-01-01T00:00:00Z",
"MinTimeStamp": "9999-12-31T18:29:59.999Z",
"ShowDataLabels": false,
"ShowMarkers": false,
"ShowQualityIcons": false,
"Type": "Online",
"UnitText": "",
"ValueType": "Float"
}
]
},
"TvdType": 0,
"TvCovType": "Auto",
"_links": []
}
7.11.4 Create/Update TrendViewDefinition

Api to Modify Existing Tvd or Create new tvd. If Existing tvd is to be modi-
fied, then the TrendViewDefinitionUpdateRepresentation TvdObjectId must be
set. If new Tvd is to be created, then TvdObjectId must by empty and CNSDe-
scription and Location parameters must be set.
Resource Path /trendseriesinfo/tvd

Category Public
HTTP Method PUT
tvdUpdate TrendViewDefinit Trend View Definition Update object
ionUpdateRepre Required
sentation
A TrendViewDefinition object [➙198]
Examples Request:
PUT api/trendseriesinfo/tvd
Request Body:
107
10 Trend Service
"AxisX": {
"AutoScale": true,
"ScaleMax": 100,
"ScaleMin": 0,
"ShowTitle": false,
"Title": ""
},
"AxisYLeft": {
"AutoScale": true,
"ScaleMax": 500,
"ScaleMin": 0,
"ShowTitle": false,
"Title": ""
},
"AxisYRight": {
"AutoScale": true,
"ScaleMax": 100,
"ScaleMin": 0,
"ShowTitle": false,
"Title": ""
},
"ObjectIdOfTvd": "",
"CNSDescription": "tvd4",
"Location":
"System1.ApplicationView:ApplicationView.Trends.TrendViewD
efinitions",
"NumberDisplayedSamplesPerTrendSerie": 200,
"RemoveOnlineTrendLogOfDeletedTrendSerie": false,
"TimeRange": {
"ValidTimeRange": 2,
"AbsoluteTimeRange": {
"From": "2020-01-23T09:23:49.969Z",
"To": "2020-02-07T10:01:48.329Z"
},
"RelativeTimeRange": {
"AnchorMode": 1,
"AnchorTime": "2020-01-27T09:23:13Z",
"NumberOfTimeUnits": 1,
"TimeUnit": 3
}
},
"TitleLeft": "Title for Left",
"TitleRight": "Title for Right",
"TitleTop": "Top name",
"TsdCollectionInfo": {
"TrendSeriesDefinitions": [
{
"ArchiveOn": false,
"AxisAttachment": "ToLeft",
"ChartLineStyle": "Full",
"ChartLineType": "Line",
"Color": "ffff00f0",
"ObjectIdOfTrendLog":
108
Trend Service 10
"ObjectIdOfTrendLogOnline": "",
"ObjectIdOfTrendedObject":
"IsLineVisible": true,
"LineWidth": 1,
"ShowDataLabels": false,
"ShowMarkers": true,
"ShowQualityIcons": false,
"MarkerType": "Circle",
"Type": "Offline"
}
]
},
"TvCovType": "Auto"
}
Response:
A TrendViewDefinition Object[➙198]
7.11.5 Delete TrendViewDefinition

Resource Path /trendseriesinfo/tvd/:objectId
Category Public
HTTP Method DELETE
objectId string ObjectId of Trend View Definition
object
Required
A TrendViewDefinition object [➙198]
Examples Request:
DELETE api/trendseriesinfo/tvd/
System1:ApplicationView_Trends_TrendViewDefinitions_tvd42
Response:
HTTP 200 OK No Content
7.11.6 Delete TrendLogOnline

Resource Path /trendseriesinfo/tsdOnline/:objectId
Category Public
HTTP Method DELETE
objectId string ObjectId of Trend Log Online
Required
Examples Request:
DELETE api/trendseriesinfo/tvd/
System1:TLO_bac1_Hardware_proj1device_90_Local_IO_AI_1_Pre
sent_Value
109
10 Trend Service
Response:
HTTP 200 OK No Content
7.11.7 Retrieving Borders of a Trend Series

Resource Path /trendseries/:trendseriesId/borders
Category Public
HTTP Method GET
trendseriesId string Trend series identifier
Required
A TrendBorder object [➙64]
Examples Request:
GET
api/trendseries/System1%3AGmsDevice_1_1546_113246209.gener
al.Data%3A_original.1._value/borders
Response:
{
"From": "2015-05-13T12:00:34.37Z",
"To": "2015-05-13T12:06:57.9Z"
}
7.11.8 Retrieving a List of Trends

Retrives historical time-series, consisting of values, quality attributes and time-
stamps.
Resource Path /trendseries/:trendseriesId

Category Public
HTTP Method GET
Required
from DateTime Start time of trend series
Required
to DateTime End time of trend series
Required
intervals ushort If provided, the result contains the
min. and max. value per interval.
addDescriptor bool If true, adds localized value (if
applicable) to result.
Default: false
A TrendSeries object [➙64]
Examples Request:
GET
api/trendseries/System1:GmsDevice_1_29129_83886081.general
.Data:_offline.._value?from=2015-05-
13T12:05:53.000Z&to=2015-05-13T12:05:54.000Z&intervals=5&
description=true
Response:
{
"Id":
110
Trend Service 10
"System1:GmsDevice_1_29129_83886081.general.Data:_offline.
._value",
"SeriesPropertyId":
"Series": [
{
"Value": "1",
"DisplayValue": "ACTIVE",
"Quality": "8589934592",
"Timestamp": "2015-05-13T12:05:52.59Z"
},
{
"Value": "1",
"DisplayValue": "INACTIVE",
"Quality": "8589934592",
"Timestamp": "2015-05-13T12:05:55.59Z"
}
]
}
7.11.9 Retrieving a List of Trend Aggregates

For good samples of histrory data retrives mathematical aggregations for Stadard
Deviation and Least Square Regression.
Trend aggregation is not Distribution enabled. It only serves for local system only.
Resource Path /trendseries/:trendseriesId/:aggregateUnit

Category Public
HTTP Method GET
Required
from DateTime Start time of trend series
Required
to DateTime End time of trend series
Required
aggregateUnit ushort Unit on which aggregation will take
place. See [112].
Default is 7
length int Default Value = 1000
qualityMask long Mask tells you which bits you have
to take into account
qualityValue long Value tells you what value the bits
in consideration need to have
correctedValues bool Flag that signals use of corrected
values in Trends (Default
Value=True)
addDescriptor bool If true, adds localized value (if
applicable) to result.
Default: false
A TrendAggregateSeries object [➙197]
111
10 Trend Service
Examples Request:
GET
api/trendseries/System1%3AGmsDevice_1_29128_83886081.gener
al.Data%3A_offline.._value/7?from=2015-10-
27T06:01:04.510Z&to=2015-11-
27T11:44:41.660Z&length=1000&qualityMask=0&qualityValue=0&
addDescriptor=false
Response:
{
"Id":
"System1:GmsDevice_1_29128_83886081.general.Data:_offline.
._value",
"SeriesPropertyId":
"Series": [
{
"AvgX": 1445945963123.153,
"AvgY": 65.28828828828829,
"Count": 333,
"FromValueDescriptor": "65",
"FromValue": 65,
"FromTime": "2015-10-27T06:01:05.12Z",
"Min": 45,
"Max": 80,
"StDevX": 287308.05418783723,
"StDevY": 8.742276612722005,
"SumX": 481500005720010,
"SumXX": 6.962229895146511e+26,
"SumXY": 481549949961870,
"SumY": 83,
"SumYY": 1444883,
"ToTime": "2015-10-27T06:17:41.13Z",
"ToValueDescriptor": "61",
"ToValue": 61,
"VarX": 82545918001.2012,
"VarY": 76.42740037334613
},
………
]
}
7.11.9.1 Aggregate Unit

Aggregate Unit must have one of the following values.
Id Description
0 Year
1 Quarter
2 Month
3 Week
4 Day
5 Hour
6 Minute
7 Second
8 Millisecond
112
History Logs Service 10
7.12 History Logs Service

This service provides a way to retrieve data for available log tables.

/historylogs Public x
7.12.1 Retrieving Log Tables

Provides a list of all available log tables with other details which can be used in
subsequent requests for data retrieval and filtering. This method returns tables for
a specified system.
Resource Path /historylogs/:systemId

Category Public
HTTP Method GET
Required
List of LogTable objects. See [➙201]
Examples Request:
GET api/historylogs/1
Response:
[
{
"Name": "ActivityLogTable",
"Descriptor": "Activities",
"Description": "Logs Activity Data",
"HasChildColumns": false,
"HasConditionFilter": true,
"HasNameFilter": true,
"HasTimeFilter": true,
"HasTimeFilterDefinedBySource": false,
"HasAndOperatorOnly": true,
"HasMaxAge": false,
"HasSingleNameFilter":true,
"SupportedTypes": [
"*"
]
},
{
"Name": "AlarmLogTable",
"Descriptor": "Events",
"Description": "Logs Alarm Data",
"HasChildColumns": false,
"HasConditionFilter": true,
"HasNameFilter": true,
"HasTimeFilter": true,
"HasTimeFilterDefinedBySource": false,
"HasAndOperatorOnly": true,
"HasMaxAge": false,
"HasSingleNameFilter":true,
"SupportedTypes": [
113
10 History Logs Service
"*"
]
}
]
7.12.2 Retrieving Columns of a Log Table

Provides a list columns for a requested log table from the specified system. Each
column is associated with other details which can be used in subsequent requests
for displaying and filtering data.
Resource Path /historylogs/:systemId/:tableName

Category Public
HTTP Method GET
Required
tableName string Name of table for which columns
need to be retrieved
Required
isParentColumns bool If TRUE then parent table columns
will be retrieved for the requested
table. Otherwise child table columns
will be retrieved.
(Default is TRUE)
List of LogColumn objects. See [➙202]
Examples Request:
GET api/historylogs/1/ActivityLogTable
Response:
[
{
"Name": "UserName",
"Descriptor": "User Name",
"DataType": "String",
"ErrorSupport": false,
"IsArray": false,
"IsDefault": true,
"IsHidden": false,
"IsSortable": true,
"IsEnum": false,
"IsFilterable": true
},
{
"Name": "Attachment",
"Descriptor": "Attachment",
"DataType": "String",
"ErrorSupport": false,
"IsArray": false,
"IsDefault": true,
"IsHidden": false,
"IsSortable": true,
"IsEnum": false,
"IsFilterable": false
}
]
114
7.12.3 Retrieving Condition Filter Operators for a Column

Provides a list of Condition Filter operators supported by the requested column.
This operators then can be used to compose a Condition Filter.
Resource Path /historylogs/:systemId/:tableName/operators/:columnName

Category Public
HTTP Method GET
Required
tableName string Name of the Table
Required
columnName string Name of column for which Condition
Filter operators will be retrieved
Required
LogConditionFilter object. See [➙202]
Examples Request:
GET api/historylogs/1/ActivityLogTable/operators/LogType
Response:
{
"Operators": [
"=",
"<>"
],
"ErrorInfo": [
"This is Error1",
"This is Error2"
]
}
7.12.4 Retrieving Enum Values for a Column

Provides a list of enum values which are associated with the requested column if
column is of type enum. These enum values then can be used to compose a
Condition Filter. This list will be a global list from all systems i.e. union of all the
values from all systems.
Resource Path /historylogs/:systemId/:tableName/enumvalues/:columnName

Category Public
HTTP Method GET
Required
tableName string Name of the table
Required
columnName string Name of column for which enum
values will be retrieved
Required
LogEnumValues object. See [➙202]
Examples Request:
GET api/historylogs/1/ActivityLogTable/enumvalues/LogType
115
Response:
{
"EnumValues": [
"Unknown",
"Reno",
"Trend"
],
"ErrorInfo": [
"This is Error1",
"This is Error2"
]
}
7.12.5 Retrieving Data for Table

Provides page wise data for the requested table, based on specified filters and
sorting criteria. User also needs to send a list of interested columns. If no columns
are provided data for all columns will be returned.
A call without a snapshotId creates a snapshot with all filters and sorting
parameters applied. Call with a snapshotId returns data of this snapshot without
applying new filters and sorting criteria.
Resource Path /historylogs/:systemId/:tableName

Category Public
HTTP Method POST
Required
tableName string Name of table
Required
snapshotId string User defined Snapshot id.
Provided Snapshot Id can be used
to cancel report processing. If
SnapshotId is provided by client
then same Id will be received in
snapshotId as response else client
will receive system generated
snapshotId
sortColumnData string This is a JSON serialized string of
Array of LogSortInfo objects. For
LogSortInfo see [➙202]
This array conveys 3 different
information for sorting.
1. ColumnName on which
sorting needs to be
performed
2. LogSortType either
Ascending or Descending
See [➙203]
3. Order in which elements
are present in the array
will be considered as sort
priority. i.e. first element
has the highest priority
nameFilter string This is JSON serialized string of a
string array. Each element in the
array is a Name Filter which will be
used to filter data. See [➙118]
116
conditionFilter string This is Condition Filter string which

will be used to filter data. See
[➙119]
fromDate DateTime From date time for the Time Filter
Note: fromDate and toDate both
should be present to Time filter the
data
toDate DateTime To date time for the Time Filter
Note: fromDate and toDate both
should be present to Time filter the
data
isDefinedBySourceTi bool Flag which denotes whether Time
meFilter Filter defined by source should be
applied
If TRUE then Time Filter received in
the request will be ingnored and
instead Time Filter defined by
source will be used to filter data
(Default is FALSE)
clientTimeSpan string Client’s timezone UTC offset
converted to timespan.
Used to localize datetime data as
per client’s time zone.
page int Current page number
(Default is 1)
size int Number of records per page
isChildDataRequired bool Flag which denotes that user is also
interested in child data, if supported
by the requested table
(Default is FALSE)
Body columnList ColumnList JSON serialized object of type
LogColumnList. See [➙203]
LogTabeData object. See [➙203]
Examples Request:
Post : api/historylogs/1/ActivityLogTable?size=2&
isChildDataRequired=true
Request Body:
{
"Parent": [
"UserName",
"Workstation",
"DpeName1",
"Action",
"MessageText"
],
"Child": [
"ParentId",
"RDbId",
"RowNum",
"DpeName",
"Id",
"LogType"
]
}
Response:
{
117
"TableName": "ActivityLogTable",
"Size": 2,
"Page": 1,
"Result": [
{
"UserName": "DefaultAdmin",
"Workstation": "_#WEBCLIENT#_",
"DpeName1": "System1:Gms_Security_Users",
"Action": "Login"
},
{
"UserName": "root",
"Workstation": "AAEINPU742011D",
"DpeName1": "System1:Gms_Security_Users",
"Action": "Automatic Logoff"
}
],
"SnapshotId": "ceffdb59-6b5d-4b2a-a3e5-
e127867ed299:fe671773-1d76-4f13-8630-a338263565ca",
"Total": 2919,
"_links": [
{
"Rel": "discardsnapshot",
"Href":
"api/historylogs/1/ActivityLogTable/ceffdb59-6b5d-4b2a-
a3e5-e127867ed299%3afe671773-1d76-4f13-8630-a338263565ca",
},
{
"Rel": "page",
"Href":
"api/historylogs/1/ActivityLogTable?snapShotId=ceffdb59-
6b5d-4b2a-a3e5-e127867ed299%3afe671773-1d76-4f13-8630-
a338263565ca&page=1&size=2",
},
{
"Rel": "next",
"Href":
"api/historylogs/1/ActivityLogTable?snapShotId=ceffdb59-
6b5d-4b2a-a3e5-e127867ed299%3afe671773-1d76-4f13-8630-
a338263565ca&page=2&size=2",
}
],
"ErrorInfo": [
"This is error 1",
"This is error 2"
]
}
7.12.5.1 Name Filter

• Name filter allows to filter data on the basis of Designation of the object
• If no Name filter is specified, data will be retrieved for all objects of current
system.
• While specifying Name filter, following wild cards are supported: * and ?
118
• To retrieve child nodes of an object, Name filter string should end with .*
(<dot><star>)
7.12.5.2 Condition Filter

• Condition filter can be provided on multiple columns
• Multiple conditions on same or different columns can be ANDed
• If Condition filter is available on invalid column, data is zero records
• Condition filter specification formats for different types of columns:
1. String column
<'Column Descriptor'>[space]<Operator>[space]<"Value">
e.g. 'Location' = "\"text\""
Column Descriptor is in single quotes and Value is in

double quotes. If an input string contains double quotes (“”),
it needs to be escaped with backslash(\).
2. Integer/float/double column
<'Column Descriptor'>[space]<Operator>[space]<Value>
Column Descriptor is in single quotes and Value is NOT in

double quotes.
3. Date Time column

<'Column Descriptor'>[space]<Operator>[space]<Value>
Column Descriptor is in single quotes and Value is NOT in

double quotes. Here date time value format should be
based on client/logged in User’s culture.
4. Enum (Test Group) column (type of String)


double quotes.
5. GmsDuration column

double quotes. Gms duration is special kind of case for
which value should be specified in specific format. Its fixed
format is DD:HH:MM:SS.fff
• Specifying multiple values for a column:
<'Column Descriptor'>[space]<Operator>[space]{<Value 1>;[<value
2>;[value N]]}
e.g., Discipline = {Fire ; HVAC}
This is nothing but OR operator supported between conditions for a

single column. This format is supported only for equal-to(=) operator.
• Condition filter specification with Array values:

Some columns support display of array data. To specify condition filter
on these columns, <-(IN) operator shall be used.
119
7.12.6 Discarding a Snapshot of a Log Table

Discards a snapshot of log table from memory. The data of this snapshot cannot be
accessed afterwards.
Resource Path /historylogs/:systemId/:tableName/:snapshotId

Category Public
HTTP Method DELETE
Required
Required
snapshotId string Id of snapshot which is to be
discarded
Required
LogDiscardedSnapshot object. See [➙203]
Examples Request:
DELETE api/historylogs/1/ActivityLogTable/ceffdb59-6b5d-
4b2a-a3e5-e127867ed299%3afe671773-1d76-4f13-8630-
a338263565ca
Response:
{
"TableName": "ActivityLogTable",
"SnapshotId": "c4005c4b-2d00-4a9c-b22a-
750d55fba609:591ce21f-11a2-42e6-b875-21ec59abea70",
"IsSnapshotDiscarded": true
}
7.12.6.1 Discard Snapshot strategy used by the WSI manager

Every Snapshot can consists of millions of records from the log table, it’s a very
heavy object to maintain. Maintaining multiple such snapshots for every session
can intern increase the load of WSI in terms of Memory and Performance. So WSI
have to have its own strategy to discard any snapshots which are not in use.
For this following configurable parameters will be used:

Property Value Description
MaxSnapshotsForSin 5 Maximum number of Snapshots that a single session can
gleSession have at any time
MaxSnapshotInactive 10 minutes Maximum time in Minutes for which snapshot will be
Time maintained by WSI if it is not used. After 10 minutes of
unused time Snapshot will be discarded
MaxVirtualMemorySi bytes Default Value: 4294967296 bytes (4 GB)
zeForProcess Memory band for WSI manager. If WSI is running out of
this memory band then before creating a new snapshot,
an existing Snapshot from the system will be discarded
first.
120
For discarding Snapshots following strategy will be used:

Greedy or fair share:
1. First check if current session is having any snotshots associated with it. If
YES then the Snapshot with the oldest LastUsedTime will be identified to
discard.
2. If current session is not having any Snapshot associated with it. Then the
session for which maximum number of Snapshots are present will be
identified first. And from that session Snapshot with the oldest
LastUsedTime will be identified to discard.
Below are the 4 different cases in which force discard of snapshot will be called:
1. Request to creat a new Snapshot and WSI manager is running out of
decided Memory band
- In this case till the time sufficient memory is not available and WSI
runs within the decided memory band one by one Snapshots will be
discarded by applying above meintioned strategy.
2. Request to create a new Snapshot and limit for maximum number of
Snapshots is reached for that session
- In this case applying above strategy one snapshot will be discarded
first and after that request to create a new Snapshot will be
processed
3. Snapshot is idle (not used) for 10 minutes
- Any Snapshot for any session will be discarded if it is not in use for
10 minutes
4. User logs out/ Session timeout
- If user logs out from WSI or if session timeout is called then all the
snapshots for that session if any will be discarded.
7.12.7 Validating Condition Filter

Validates the Condition Filter which will be used to filter the data. If filter is not valid
then a to-do message is provided.
Resource Path /historylogs/:systemId/:tableName/validateconditionfilter/:conditionFilter

Category Public
HTTP Method GET
Required
tableName string Name of the Table
Required
conditionFilter string Condition filter string to validate
Required
LogConditionFilterValidation object. See [➙203]
Examples Request:
GET
api/historylogs/1/EventLogTable/validateconditionfilter/'A
ction'%20=%20%22Add%20Camera
Response:
{
"ErrorPosition": 11,
"IsValidConditionFilter": false,
121
"ErrorMessageDescriptor": "The symbol/term could not be

recognized: \"Add Camera",
"ToDoMessageDescriptor": "Correct the condition filter
expression as per rules:\r\nCondition filter name:
'HdbId', 'HRdbId', 'Event ID', 'Event Category', 'Event
Time', ...,\r\nCondition filter operator: =, <>, <, <=, >,
>=, <-,\r\nCondition filter data: textual data (e.g.
'\"Any text\"'), numeric data (e.g. '42'), date time data
(e.g. '07/05/1976 14:07:00'), #COM, N/A, #ERR,
null,\r\nBoolean operator: AND, OR, NOT, ;,\r\nSymbol: (,
), {, },"
}
7.12.8 Retrieving Child Data for a Parent Table

Retrieves child data for a parent table. To retrieve child data a call ‘Retrieving Data
for Table’ with isChildDataRequired set to true is required first. User also needs to
send a list of interested columns for child data. If no columns are provided data for
all columns will be returned. See [➙Error! Bookmark not defined.]
Resource Path /historylogs/:systemId/:tableName/:snapshotId/:parentId

Category Public
HTTP Method POST
Required
Required
snapshotId string Snapshot Id for which child data will
be retrieved
Required
parentId string Parent Id for which child data needs
to be retrieved
Required
Body
LogChildData object. See [➙204]
Examples Request:
POST api/historylogs/1/EventLogTable/78b71424-bcce-44e1-
9d7e-ffdfc11a0179:f6139cbd-5854-467f-be0e-227cab6b88fa/235
Request Body:
Response:
{
"Result": [
{
"RowNum": "2",
"DpeName":
ftwareRunning",
"Id": "235"
},
{
"RowNum": "1",
"DpeName":
122
ftwareRunning",
"Id": "354",
"LogType": "Property Changes"
}
],
"Total": 2,
"Page": 1,
"Size": 100000,
"_links": [
{
"Rel": "discardsnapshot",
"Href": "api/historylogs/1/EventLogTable/78b71424-
bcce-44e1-9d7e-ffdfc11a0179%3af6139cbd-5854-467f-be0e-
227cab6b88fa",
},
{
"Rel": "page",
"Href": "api/historylogs/1/EventLogTable/78b71424-
bcce-44e1-9d7e-ffdfc11a0179%3af6139cbd-5854-467f-be0e-
227cab6b88fa/235?page=1&size=100000",
}
],
"ErrorInfo":[
"This is error 1",
"This is error 2"
]
}
7.12.9 Cancel Report Processing

Cancels in-process report generation for the SnapshotId that was provided in
Retrive Data Pagewise Request [116]. If cancellation is successful then Retrive
Data Pagewise Request will return Http status Bad Request(400) with below error:
Id":2402098
Error:"htlog_cancelled"
Details:"Request preliminary canceled by the user."}
Resource Path /historylogs/:systemId/:snapshotId

Category Public
HTTP Method DELETE
Required
snapshotId string Id of snapshot which is to be Cancel
Required
LogDiscardedSnapshot object. See [➙203]
Examples Request:
DELETE
https://aaeinpun00166l.ad001.siemens.net:444/WSIApp/api/hi
storylogs/1/sdsfsdfsdfffff3333
Response:
HTTP 200 OK
123
10 Diagnostics Service
7.13 Diagnostics Service

/diagnostics Public
7.13.1 Test Reachability of the Web Service Interface

A test whether or not the Web Service Interface replies to requests.This service
also returns Server’s UTC datetime as json response.
Resource Path /diagnostics

Category Public
HTTP Method GET
clientDatetime string Client’s UTC datetime.
Optional
Response HTTP 200 OK [➙215]
Examples Request:
GET /NBWSITest/NorthboundWebApiClient/api/diagnostics/
Response:
HTTP 200 OK
7.14 Language Service

/languages Public x
7.14.1 Retrieving the Language of the Logged in User

Resource Path /languages
Category Public
HTTP Method GET
A Language object [➙64]
Examples Request:
GET /api/Languages?api_key=username:password
Response:
{
"Descriptor": "English (United States)",
"Code": "en-US"
}
7.15 Image Service

/images Internal x
124
Tables Service 10
7.15.1 Retrieving an Image
NOTE:
In order to successfully process this request, the image needs to be present in a
feasible format and size in the system.
Resource Path /images/:imageId

Category Internal
HTTP Method GET
imageId string Image name (file name without extension). Note
that while XAML files can contain multiple images,
only one image per file is supported.
Required
path string Path within a library. As of this writing, the path
must not include the file extension: only XAML files
are supported.
Required
format string Image format (png or svg)
Required
width int Image width in pixels
height int Image height in pixels
encodeAsBase64 bool If true, the image is returned as a base64-encoded
string.
The returned data depends on encodeAsBase64.
encodeAsBase64 Return Type Description
false (default) image Image in the requested format
(image media type; see
[10] [➙ 18])
true string base64-encoded string
Examples Request:
/api/images/Evt_Discp_Infrastr_None_001?format=png&width=1&h
eight=1&path=System1:libraries%5CGlobal_Base_HQ_1%5Cicons&en
codeAsBase64=true
Response:
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c
6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAANSURB
VBhXY/j//78GAAkkAyb6sRXrAAAAAElFTkSuQmCC
7.16 Tables Service

/tables Partially Internal x
125
10 Tables Service
7.16.1 Retrieving a Table or an Entry of a Table

Resource Path /tables/:tableName/:tableEntryId
Category Public
HTTP Method GET
tableName string Table identifier (table name)
[126]
Required
id string Table entry identifier (key of row
of table)
The returned data depends whether or not id is provided.
id Return Type Description
Not provided Array of List of all key-value pairs in
KeyValue<keyname,string> this table
Provided string Localized value of this
column
Examples Request1: id Not provided
GET api/tables/disciplines
Response1:
{
"0": "Management System",
"20": "Building Infrastructure",
"50": "Building Automation",
"100": "Fire",
"150": "Security",
"200": "Energy Management",
"250": "Notification"
}
Request2: id provided
GET api/tables/disciplines/100
Response2:
"Fire"
7.16.1.1 Table Names

TableId must have one of the following Name:
Name Description
Categories Categories defined for the System
Disciplines Disciplines supported by Manage System
ObjectTypes Object types used in Subsystems
Timefilter Timefilter supported in Management System
Units Supported units in Management System
126
Tables Service 10
7.16.2 Retrieving a Subtable of a Table

Resource Path /tables/:tableName/subtables/:subtableName
Category Public
HTTP Method GET
Required
subtableName string Subtable identifier (limited to “icons” or “colors”)
Required
systemId Int System Identifier (query parameter)
Optional
The returned data depends on the subtable id. Note that the example below is for
the “icons” subtable id.
Subtable Id Return Type Description
icons Key-value pairs (int, string) Icons are only available from the
containing the index and Disciplines table
relative path to the icon
colors Key-value pairs (int, Colors are only available from the
Dictionary<int, Color>) Categories table
indicating the valid colors
Examples Request:
GET api/tables/disciplines/subtables/icons
Response:
{
"0":
"System1:libraries\\Global_Base_HQ_1\\icons\\Evt_Discp_System
_None_001.xaml|Evt_Discp_System_None_001",
"20":
"System1:libraries\\Global_Base_HQ_1\\icons\\Evt_Discp_Infras
tr_None_001.xaml|Evt_Discp_Infrastr_None_001",
"50":
"System1:libraries\\Global_Base_HQ_1\\icons\\Evt_Discp_BA_Non
e_001.xaml|Evt_Discp_BA_None_001"
}
7.16.3 Retrieving a Subtable of a Table for given row of table

Resource Path /tables/:tableName/:Id/subtables/:subtableName
Category Public
HTTP Method GET
Required
id int Table entry identifier (key of row of table)
Required
subtableName string Subtable Identifier
Required
The returned data depends on the subtable id. Note that the example below is for
the “colors” subtable id.
127
10 Tables Service
Subtable Id Return Type Description

icons Key-value pairs (int, string) Icons are only available from the
containing the index and Disciplines table
relative path to the icon
colors Key-value pairs (int, Colors are only available from the
Dictionary<int, Color>) Categories table
indicating the valid colors See Object [➙ 188]
Examples Request:
GET api/tables/categories/1/subtables/colors
Response:
{
"1": "255, 255, 0",
"2": "255, 255, 0",
"3": "255, 255, 0",
"4": "0, 0, 0",
"5": "255, 255, 0",
"6": "239, 105, 38",
"7": "201, 43, 39",
"8": "167, 73, 27",
"9": "147, 40, 16",
"10": "152, 150, 154",
"11": "90, 93, 96",
"12": "230, 148, 113",
"13": "250, 189, 155"
}
7.16.4 Retrieving Subgroups with filter

This method help retrieves subgroups of the Disciplines OR ObjectTypes. Filter is
also available for retrieving specific Disciplines, SubDisciplines OR ObjectTypes,
SubObjectTypes. This filter parameter is query string parameter. If no
SubDisciplines/SubObjectTypes are specified while requesting
Disciplines/ObjectTypes respectively then all the SubDisciplines/SubObjectTypes
which comes under the requested Discipline/ObjectType will be returned.
Otherwise only the requested SubDisciplines/SubObjectTypes will be returned.
Resource Path /tables/:tableName/subgroups

Category Public
HTTP Method GET
Required
filter string This is query string parameter.
Filter for Disciplines,
SubDisciplines OR
ObjectTypes, SUbObjectTypes
Required
Based on the request is for Disciplines OR ObjectTypes response will be returned.
1. Disciplines : See [➙ 63]
2. ObjectTypes : See [➙ 63]
Examples Request1: Disciplines and SubDisciplines request
GET
api/tables/disciplines/subgroups?filter={"0":[0,1],"100":[101
128
Tables Service 10
,102]}
Response1:
[
{
"DisciplineId": 0,
"SubDisciplines": [
{
"Id": 0,
"Descriptor": "Unassigned"
},
{
"Id": 1,
"Descriptor": "Applications"
}
]
},
{
"DisciplineId": 100,
"DisciplineDescriptor": "Fire",
"SubDisciplines": [
{
"Id": 101,
"Descriptor": "Evacuation"
},
{
"Id": 102,
"Descriptor": "Extinguishing"
}
]
}
]
Request2: ObjectTypes and SubObjectTypes request

GET
api/tables/objecttypes/subgroups?filter={"1000":[1001,1002],"
1100":[1101,1102]}
Response2 :
[
{
"ObjectTypeId": 1000,
"ObjectTypeDescriptor": "Client Software",
"SubObjectTypes": [
{
"Id": 1001,
"Descriptor": "Control Room"
},
{
"Id": 1002,
"Descriptor": "Mobile"
}
]
},
{
"ObjectTypeId": 1100,
"ObjectTypeDescriptor": "Command",
"SubObjectTypes": [
129
10 Tables Service
{
"Id": 1101,
"Descriptor": "Analog"
},
{
"Id": 1102,
"Descriptor": "Binary"
}
]
}
]
7.16.5 Retrieving Image from Global Text Table
NOTE:
If the request is for a PNG image, the image file must be in a format that is either
PNG or can be converted to PNG. If the request is for an SVG image, no
conversion can be made, so the image file must be SVG.
Resource Path /tables/global/:tableName/icons/:entryId

Category Internal
HTTP Method GET
tableName string Well-known global text table name [➙ 131]
Required
entryId int Entry within the table; only values greater than or
equal to zero are valid.
Required
format string Image format(s) in the order in which to attempt to
load them – separated by a comma (currently
only “png”and “svg” are supported). The default is
“svg,png” but if only one format is acceptable, the
string should be “png” or “svg”.
Optional
width int Image width in pixels. The default is 32.
Optional
height int Image height in pixels. The default is 32.
Optional
Response HTTP 200 OK.
Examples Request:
/api/tables/global/Disciplines/icons/0
Response:
One of the following:
1) Base64 encoded PNG: with the specified dimensions.
2) SVG: the entire contents of the SVG file
3) Blank: there is no icon assigned to the entry, it could
not be loaded, or the specified icon was not in one of
the supported formats.
130
Tables Service 10
7.16.5.1 Well-Known Global Text Table Names

Global text tables are tables that are found on all online systems in a distributed
environment. Within DCC, there is a limited number of tables that are considered
“well-known global text tables:” they are specified below.
Name Description
Disciplines Disciplines supported by the system.
Subdisciplines Subdisciplines supported by the system; a subdiscipline will normally refer to a
discipline.
ObjectTypes Object types used in the system.
ObjectSubtypes Object subtypes used in the system; a subtype will normally refer to an object
type.
Categories Categories defined for the system.
7.16.6 Retrieving Text From Global Text Table

Note that Color is an optional property of a text table entry and will only appear in
the JSON string if a color has been assigned to that entry. The sample response
below includes the color property on some (but not all) of the entries. See [➙ 205]
for further discussion of the color property.
Resource Path /tables/global/:tableName/text
Category Internal
HTTP Method GET
Required

A list of objects containing value and text properties [➙ 204]
Examples Request:
/api/tables/global/Disciplines/text
Response:
[
{
"Value": 0,
“Color: 4290764270,
"Text": "Management System"
},
{
“Value”: 20,
“Text”: "Building Infrastructure"
},
{
“Value”: 50,
“Color: 4290764270,
“Text”: "Building Automation"
},
{
“Value”: 100,
“Color: 4290764270,
“Text”: "Fire"
},
{
“Value”: 150,
“Text”: "Security"
},
{
“Value”: 200,
131
10 Tables Service
“Text”: "Energy Management"

},
{
“Value”: 250,
“Text”: "Notification"
}
]
7.16.7 Retrieving all Language Text from Global Text Table

The returned table will contain text for every language that is installed; in the
example below there are three languages (en-US, de-DE, fr-CA).
Resource Path /tables/global/:tableName/langText
Category Internal
HTTP Method GET
Required
An array of objects containing a value, text for each language, and optionally a
color [➙ 205]
Examples Request:
/api/tables/global/Categories/langText
Response:
[
{
"Value": 1,
"Color": 4290764270,
"LangText": [
"Status",
"Zustand",
"État",
"Status"
]
},
{
"Value": 2,
"Color": 4292203223,
"LangText": [
"Fault",
"Störung",
"Défaut",
"Fault"
]
},
{
"Value": 3,
"Color": 4294501476,
"LangText": [
"Trouble",
"Problem",
"Problème",
"Trouble"
]
},
132
Tables Service 10
7.16.8 Retrieving Nested Text From Global Text Table

The returned table will contain entries from the specified text table and any subtext.
The example below is of the Disciplines table: the Subdisciplines table considers
the Disciplines table as a ‘parent’ and an entry in the Subdisciplines table normally
refers to an entry in the Disciplines table.
Resource Path /tables/global/: tableName /nestedText
Category Internal
HTTP Method GET
Required

The return is an array of TextTableEntry objects [➙ 204]
Examples Request:
/api/tables/global/Disciplines/nestedText
Response:
[
{
"Value": 0,
"Text": "Management System",
“Color: 4290764270,
"SubText": [
{
"Value": 0,
“Color: 4290764270,
"Text": "Unassigned"
},
{
"Value": 1,
"Text": "Applications"
},
{
"Value": 2,
“Color: 4290764270,
"Text": "Communication"
},
{
"Value": 3,
"Text": "Supervision"
},
{
"Value": 4,
“Color: 4290764270,
"Text": "System Settings"
}
]
},
{
"Value": 20,
"Text": "Building Infrastructure",
"SubText": [
133
10 Tables Service
{
"Value": 0,
"Text": "Unassigned"
},
{
"Value": 21,
“Color: 4290764270,
"Text": "Elevators"
},
{
"Value": 22,
“Color: 4290764270,
"Text": "Escalators"
},
{
"Value": 23,
"Text": "Data Network"
},
{
"Value": 24,
"Text": "I/O Monitoring"
}
]
},
{ ... more entries ... }
]
7.16.9 Retrieving Text From a Local Text Table

Resource Path /tables/local/:systemId/:tableName/text
Category Internal
HTTP Method GET
systemId int The id of the system from which the text table is to be
retrieved; zero is not a legal id but can be used to
indicate the “local” system.
Required
tableName string Local text table name
Required

A list of objects containing value, text, and optionally color properties. [➙ 204]
Examples Request:
/api/tables/local/0/TxG_Discipline/text
Response:
[
{
"Value": 0,
“Color: 4290764270,
"Text": "Management System"
},
{
“Value”: 20,
134
Tables Service 10
“Text”: "Building Infrastructure"

},
{
“Value”: 50,
“Color: 4290764270,
“Text”: "Building Automation"
},
{
“Value”: 100,
“Color: 4290764270,
“Text”: "Fire"
},
{
“Value”: 150,
“Text”: "Security"
},
{
“Value”: 200,
“Text”: "Energy Management"
},
{
“Value”: 250,
“Text”: "Notification"
}
]
7.16.10 Retrieving All Language Text From a Local Text Table

The returned table will contain text for every language that is installed; in the
example below there are three languages (en-US, de-DE, fr-CA).
Note that if a color has been assigned to the text table entry it will be included in
the returned JSON string. The sample response below includes color in some of
the entries to illustrate this fact. See [➙ 205] for further discussion of the color
property.
Resource Path /tables/local/:systemId/: tableName /langText

Category Internal
HTTP Method GET
systemId int The id of the system from which the text table is to be
retrieved; zero is not a legal id but can be used to
indicate the “local” system.
Required
tableName string Local text table name
Required
A list of objects that includes value, text for every installed language, and
optionally a color (if one has been assigned to the entry [➙ 205]
Examples Request:
/api/tables/local/0/TxG_Categories/langText
Response:
[
{
"Value": 1,
"Color": 4290764270,
"LangText": [
"Status",
"Zustand",
135
10 Tables Service
"État",
"Status"
]
},
{
"Value": 2,
"Color": 4292203223,
"LangText": [
"Fault",
"Störung",
"Défaut",
"Fault"
]
},
{
"Value": 3,
"Color": 4294501476,
"LangText": [
"Trouble",
"Problem",
"Problème",
"Trouble"
]
},
7.16.11 Retrieving an Image for an Entry of a Table

Resource Path /tables/local/:systemId/:tableName/icons/:tableEntryId
Category Internal
HTTP Method GET
tableName string Identifies a text table (such as “TxG_ValidationProfile”)
Required
tableEntryId uint Table entry identifier (key of row of table)
The returned data will be an empty string if no image has been assigned to the
entry.
Examples Request:
GET api/tables/local/0/TxG_ObjectType/icons/100
Response:
iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c
6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvq
7.16.12 Retrieving an Entry of a Table

Note that if a color has been assigned to the text table entry it will be included in
the returned JSON string. The sample response below includes color to illustrate
this fact, but color is not guaranteed to appear in all cases. See [➙ 205] for further
discussion of the color property.
Resource Path /tables/local/:systemId/:tableName/text/:tableEntryId
Category Internal
HTTP Method GET
tableName string Identifies a text table (such as “TxG_ValidationProfile”)
Required
tableEntryId uint Table entry identifier (key of row of table)
An object containing the value, text, and optionally a color. [➙ 204]
136
Systems Service 10
Examples Request:
GET api/tables/local/0/TxG_ValidationProfile/text/0
Response:
{
"Value": 0,
"Text": "Disabled",
"Color": 4278190080
}
7.17 Systems Service

/systems Public x
/sytemsSubscription Public x x
s
7.17.1 Retrieving list of installed languages (same order) as

installed in project
Resource Path /systems/languages
Category Public
HTTP Method GET
A SystemsLanguages object [➙ 205]
Examples Request:
GET / api/systems/languages
Response:
{
"ArrayIndex": 0,
"Code": "en-US"
},
{
"ArrayIndex": 1,
"Descriptor": "French (France)",
"Code": "fr-FR"
},
{
"ArrayIndex": 2,
"Descriptor": "German (Germany)",
"Code": "de-DE"
}
7.17.2 Retrieving list of all available systems with list of installed

languages.
Resource Path /systems
Category Public
HTTP Method GET
A SystemsRepresentation object [➙ 205]
137
10 Systems Service
Examples Request:
GET / api/systems
Response:
{
"Systems": [
{
"Name": "System14",
"Id": 14,
"IsOnline": true
},
{
"Name": "System15",
"Id": 15,
"IsOnline": true
}
],
"Languages": [
{
"ArrayIndex": 0,
"Code": "en-US"
},
{
"ArrayIndex": 1,
"Code": "de-DE"
}
],
"IdLocal": 14,
"IsDistributed": true
}
7.17.3 Retrieving information of a specific system

Resource Path /systems/{systemid}
Category Public
HTTP Method GET
Examples Request:
GET / api/systems/1
Response:
{
"Systems": [
{
"Name": "System14",
"Id": 14,
"IsOnline": true
}
],
"Languages": [
{
"ArrayIndex": 0,
"Code": "en-US"
138
Systems Service 10
},
{
"ArrayIndex": 1,
"Code": "de-DE"
}
]
}
7.17.4 Retrieving information of a local system

Resource Path /systems/local
Category Public
HTTP Method GET
Examples Request:
GET / api/systems/local
Response:
{
"Systems": [
{
"Name": "System2",
"Id": 2,
"IsOnline": true
}
],
"Languages": [
{
"ArrayIndex": 0,
"Code": "en-US"
},
{
"ArrayIndex": 1,
"Code": "de-DE"
},
{
"ArrayIndex": 2,
"Descriptor": "French (France)",
"Code": "fr-FR"
}
]
}
7.17.5 Get service status

This will return the current status (‘isConnected‘) of all services. If user has scope of
multiple system, it will return the service statuses of multiple systems.
Note: Currently, only the status for Report Manager (id 58) is returned.
Resource Path /systems/services
Category Public
HTTP Method GET
139
10 Systems Service
A List<ServicesNotificationRepresentation> object
Examples Request:
GET / api/systems/services
Response:
[
{
"SystemId":4,
"ServiceId":58,
"IsConnected":false
}
]
7.17.6 Create channelize Systems subscription

If subscription response and notifications are needed on signalr channel.
Subscription response will be pushed through notifySubscriptionStatus function
available at client side. Sound changes will be notified via notifySounds.
Resource Path /api/sr/systemssubscriptions/channelize/:requestId/:connectionId
Category Public
HTTP Method POST
requestId String Request Identifier of subscription hub connection.
RequestId is to be generated and provided by the
client.
It is expected from client that client should use
unique id for for each request.
Required
Required
Examples Request:
POST api/sr/systemssubscriptions/channelize/9565ca41-
8556-4dbb-94cc-1b89451a5db5/c6c95ece-133b-480b-af1f-
067a173e0f5b
{
"ErrorCode":0,
“RequestFor”:”notifySystems”
}
7.17.7 Delete Subscription for a Systems

Resource Path /api/sr/ systemssubscriptions /{connectionId}
Category Public
HTTP Method DELETE
Required
Examples Request:
DELETE /api/sr/systemssubscriptions/e3d90a35-1f7a-4ec2-8b3b-
140
Systems Service 10
2fba71b76bc7
Response:
HTTP/1.1 200 OK

After subscribing for event sounds, the current sound file with a link to download it
will be sent in an initial notification. Afterwards, any change will be notified.

Hub norisHub
Function notifySystems ( data )
data SystemsRepresent System details [➙ 205]
ation
NOTE:
If in JSON response the value of “FileName” and “_links” are empty then no
sound has to be played.

After subscribing for event sounds, the subscription status will be sent only once.

Hub 1. norisHub
2. eventSoundsHub (lagacy)
Response
Example {
"ErrorCode":0,
“RequestFor”:"notifySystems"
}
7.17.9 Create channelize Services subscription

This allows subscription of services according to system. If the system id is within
the scope of the logged in user and if the service id is valid, then user will be sub-
scribed to that service id for that particular system and will get notifications when
the state of the service changes.
Currently, the only supported Service ID is 58 (for Report Manager). Other
services will not be subscribe.
Resource Path /api/sr/systemssubscriptions/channelize/:requestId/:connectionId/services/
Category Public
HTTP Method POST
141
10 Systems Service

client.
Required
Required
Body Services ServicesReq Contains a list of the systems and their
uestSubscrip corresponding services which the client wants to
tionsReprese subscribe to.
ntation[] Required
Response HTTP 200 OK as List<ServicesSubscriptionsRepresentation>
Examples Request:
POST api/sr/systemssubscriptions/channelize/9565ca41-
067a173e0f5b/services
Body: serviceIds
[{"SystemId":1,"Ids":[58,60,78]},{"SystemId":4,"Ids":[58,60]},{"SystemId":5,"Ids":[58,
61,62]}]
Response:
[{"SystemId":1,"ServiceId":58,"ErrorCode":1},{"SystemId":1,"ServiceId":60,"ErrorC
ode":1},{"SystemId":1,"ServiceId":78,"ErrorCode":1},{"SystemId":4,"ServiceId":60,"
ErrorCode":1},{"SystemId":5,"ServiceId":61,"ErrorCode":1},{"SystemId":5,"ServiceI
d":62,"ErrorCode":1},{"SystemId":4,"ServiceId":58,"ErrorCode":0},{"SystemId":5,"S
erviceId":58,"ErrorCode":0}]
ErrorCode: 0, Re-
questFor: "notifyServices",RequestId: "9565ca41-8556-
4dbb-94cc-1b89451a5db5"
Note: For a particular connectionId, subscription request can be sent only once. If
more systems or services are to be included in the subscription, then unsubscribe
and subscribe again.
If no valid combination of systemid and service id is passed in the request, it wil
return an error with 400 code.
7.17.9.1 Services Notification

After successful subscription, an initial notification will be generated with the current statuses
of the subscribed services. After that, a notification will be generated whenever the state of the sub-
scribed service id(s) changes.
Hub 1. norisHub
Function notifyServices (status)
142
10
Status List<ServicesN See

otificationRep ServicesNotificationReprese
resentation> ntation
in case of
initial
notification.
ServicesNotifi
cationRepresen
tation in case
of change in
service
status(for
subsequent
notifications)
Example
7.17.10 Unsubscribe Services

This will unsbscribe all services which have been subscribed for a particular con-
nection id.
Resource Path /api/sr/ systemssubscriptions /services/{connectionId}
Category Public
HTTP Method DELETE
Required
Examples Request:
DELETE /api/sr/systemssubscriptions/services/e3d90a35-1f7a-
4ec2-8b3b-2fba71b76bc7
Response:
HTTP/1.1 200 OK
7.18 Products Service

/Products Public x
7.18.1 Retrieving Product Information

Retrieve a list of all Trend Collector objects of a given system. It includes all Online
Resource Path /Products
143
10 Files Service
Category Public
HTTP Method GET
ProductInfo object [➙206Error! Bookmark not defined.]
Examples Request:
GET /api/Products
Response:
{
"ProductNameShort": "Desigo CC",
"ProductName": "Desigo™ CC",
"VendorName": "Siemens Switzerland Ltd.",
"ProductCopyRights": "© Siemens Switzerland Ltd, 2016",
"ProductVersion": "V3.0",
"ServerVersion": "1.0.0.0",
"SupportLink": "www.siemens.com/SBT",
"_links": [
{
"Rel": "self",
"Href": "api/products",
},
{
"Rel": "downloadfile",
"Href":
"api/repository/ProductPictures/files?names=entrypage_image.JPG",
},
{
"Rel": "downloadfile",
"Href":
"api/repository/ProductPictures/files?names=SplashScreenImage.jpg",
}
]
}
7.19 Files Service

/files/{fileType} Partially Internal
/files/{systemId}/{rela X
tiveFilePath}
7.19.1 Retrieving Files of specific type

Resource Path /files/{fileType}
Category Internal
HTTP Method GET
fileType BasicFiles Supported file types
See [➙ 207] Required
names String[] This is query string parameter.
Contains only the name of the
files. or array of file names.
Examples Request:
GET /api/files/0?names=entrypage_image.JPG
Response:
Returns stream content down to the client, chunk by chunk
144
Graphics Service 10
7.19.2 Retrieve Files from system

Currently access is provided for "libraries" folder path
Resource Path /files/{systemId}/{relativeFilePath}
Category Public
HTTP Method GET
systemId uint System identifier
Required
relativeFilePath String Relative file path.e.g. see below
Required
Examples Request:
GET /
api/files/1/libraries\BA_Cooling_HQ_1\Symbols\DYN_2D_Chiller_None_Analog_C
entral_001.ccs
Response:
Returns byte array content.
7.19.3 Retrieve Documents from system

Documents can be retrieved by passing designation of Systembrowser tree nodes
Resource Path /files/documents/{designation}
Category Public
HTTP Method GET
designation string Designation id of node in
systembrowser tree
making it to part of URI.)
Required
Content-Type header set to particular filetype
Examples Request:
GET /
api/files/documents/System1.ApplicationView%253AApplicationView.Documents.p
dfSample
Response:
Returns byte array content.
7.20 Graphics Service

Resource Service Requires Requires SignalR
Category Authentication (Push Notifications)
/graphics/{objectId} Internal x
/graphics/itemIds/{objectDesignation} Internal x
/graphics/items/{objectId} Internal x
/children/itemIds/{objectDesignation} Internal x
This service provides the following functionality:

• To determine whether an object is relevant to a client that processes graphics. By
relevant we mean: (a) the object itself is one of the known graphic types (such as a
graphic or a graphic viewport), (b) the object is related to a graphic type (such as
145
10 Graphics Service
an object that is found in a graphic), or (c) one of the object’s ancestors is either a
graphic type or is related to a graphic type. This functionality is generally referred to
as the “preselect” operation.
• To retrieve the list of graphic objects related to this object. If the object is one of the
graphic types it will be returned; if it is not one of the graphic types, the list will con-
tain all graphic types related to the object and all graphic types related to all ances-
tors of the object. This functionality is generally referred to as the “select” opera-
tion.
• To retrieve a specific graphic object, such as a graphic or graphic viewport. This
functionality is generally referred to as the “load” operation.
• To retrieve the first child (of a node in a view) that is either graphical or has a relat-
ed graphics.
Note that the term ancestor in this context means objects higher in a hierarchy, up to
and including the root object. During a preselect or a select operation all hierarchies on
the system where the object is defined are checked.
7.20.1 Check if object is graphical

Determine if an object, an object it references, or one of its ancestors is graphical
in nature. For example, an object will be considered “graphical in nature” if it is a
DCC graphic, template, or viewport (within a graphic). The object itself may not be
graphical but can refer to another object that is graphical (such as a non-graphical
object that appears on a graphic).
Resource Path /graphics/{objectId}
Category Internal
HTTP Method GET
objectId String Object identifier, including system information
Required
Response HTTP 200 Ok
HTTP 204 No Content
Examples Request:
GET /api/graphics2/System1:ObjectName
Response:
Returns status code 200 if the object (or something it references) or one of its
ancestors is graphical in nature; otherwise code 204 is returned.
7.20.2 Retrieving graphic item ids

Retrieve all graphic items ids related to an object or its ancestors: this may include
the object itself. Note a couple of things about the graphic items:
1) Graphic items that reference a graphical template will include the designation
of the ‘owning’ object (see ‘Context’ in example below).
2) There will be no duplicate references to a graphic.
3) There will be no duplicate references to a template for the same ‘owning’ ob-
ject. For example: if an object is determined to be an ancestor in two or more
situations, only one of the situations will be reflected in the results.
Resource Path /graphics/itemIds/{objectDesignation}
Category Internal
HTTP Method GET
objectDesignation String The “fully assembled” name of an object within a
hierarchy. This name is also commonly referred to
as the “designation.” The name specifies the
146
Graphics Service 10
system, hierarchy, and position of the object within

the hierarchy.
Required
Response HTTP 200 OK (one or more GraphicalItems [➙ 207] will be returned)
HTTP 204 No Content (there are no graphic items associated with the object)
Examples Request:
This example is a loop object found within a BACnet device (8166) on a BACnet
network (“bacnetNetwork”).
GET
/api/graphics/itemIds/System1:ManagementView:ManagementView.Fi
eldNetworks.bacnetNetwork.Hardware.8166.Local_IO.LP_1
Response:
Returns a list of related graphic items, possibly including the object itself (if it is
graphical in nature).
[
{
"Context": "Sys-
tem1:ManagementView:ManagementView.FieldNetworks.bacnetNetwork.Hardware
.8166.Local_IO.LP_1",
"ObjectId": "Sys-
tem1:GraphicsTemplate_TEM_Object_Loop_None_None_001",
"ManagedType": "Graphic Template",
"DisplayName": "TEM_Object_Loop_None_None_001"
},
{
"Context": "Sys-
tem1:ManagementView:ManagementView.FieldNetworks.bacnetNetwork.Hardware
.8166.Local_IO.LP_1",
"ObjectId": "System1:Graphics_AnotherGraphic",
"ManagedType": "Graphic",
"DisplayName": "SomeGraphic"
}
]
7.20.3 Retrieving a graphical item

Retrieve the content for a graphical item. The content will be in the form of XML
containing SVG with two sections: <graphic> and <libraries>. The <graphic> sec-
tion will include the definition of the graphical item, while the <libraries> section will
contain any symbols referenced by the item – note that a symbol may refer to oth-
er symbols, and these will also be in this section.
Resource Path /graphics/items/{objectId}
Category Internal
HTTP Method GET
objectId String Object identifier; this must include the system
information. For example: “System1:MyGraphic”
Required
HTTP 204 No Content
Examples Request:
GET /api/graphics/items/System1:MyGraphicalObject
Response:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "">
<graphicItems version="0.9">
<graphic>
<svg>
... graphical item is defined here ...
</svg>
</graphic>
<libraries>
<svg>
... symbol definition ...
</svg>
147
10 Graphics Service
<svg>
... another symbol definition ...
</svg>
</libraries>
</graphicItems>
7.20.4 Retrieving a child item

Retrieve the first “interesting” child of a node, where “interesting” means:
1) The child is a graphical object itself
2) The child has a related template
3) The child has a related graphical object (such as being in a graphic)
Note that the method requires a fully qualified view node name and that the chil-
dren of that node are searched for one that is interesting.
Resource Path /graphics/children/itemIds/{objectDesignation}
Category Internal
HTTP Method GET
Parameters objectDesignation String Object designation (a fully qualified node
name). For example:
“System.View:View.Level”
Required
generations UInt32 The number of generations to search
(downward). The range is 1 to 20; if the value
is not provided a default of 1 is used.
Optional
searchOptions UInt64 Search options as a bitmask. Currently only
one option (value 0x1) has been defined: to
return a single object (the alternative is to
return all interesting children). As of right now
this parameter is ignored and only the first
interesting child is returned.
Optional
types UInt32 The types of objects to consider ‘graphical.’
As of right now this parameter is ignored; the
types to be considered ‘graphical’ for this
method are custom graphics and templates.
Optional
Response HTTP 200 OK (a browser object will be returned)

HTTP 204 No Content (no interesting child was found)
Examples Request:
GET /api/graphics/children/itemIds/System.View:View.Level
Response:
{
"HasChild": false,
"ViewId": 11,
"ViewType": 4,
"Attributes": {
"DisciplineId": 50,
"TypeId": 6700,
"SubTypeId": 0,
"ManagedType": 80,
"CommentRule": "Optional",
"Configuration": 0,
148
10
"_links": []
}
},
"Location": "System.View:View.Level.Analog Input 1",
"SystemId": 1,
"Name": "AI_1",
"Descriptor": "Analog Input 1",
"Designation": "System.View:View.Level.AI_1",
"_links": [
{
"Href": "api/properties/System1%253AGmsDevice_1_8166_1?requestType=0",
}
]
}
7.21 EventCategorySound Service

Resource Service Catego- Requires Requires SignalR
ry Authentication (Push Notifications)
/api/eventcategorysounds Public x
api/sr/eventcategorysoundss Public x x
ubscriptions
7.21.1 Get current event sound
NOTE:
Resource Path api/eventcategorysounds

Category Public
HTTP Method GET
disableCatego query:(string) Filter to disable categories.
ries List of disable category. i.e. category Ids for which
sound information is not required
Optional
File details object See [➙207]
Examples Request:
GET / api/eventcategorysounds?disableCategories=[1,2]
Response:
{
"FileName": "0dfe9579-2c20-4cad-9a07-7bc14f4164a5.wav",
"_links": [
{
"Rel": "DownloadSoundFile",
"Href":
"api/files/1/Libraries%5cGlobal_Events_HQ_1%5cMediaLibrary%5c0dfe9579-
2c20-4cad-9a07-7bc14f4164a5.wav",
}
149
10 EventCategorySound Service
]
}
7.21.2 Subscribe for event sound
Resource Path /api/sr/eventcategorysoundssubscriptions/{connectionId}

Category Public
HTTP Method POST
Required
Examples Request:
POST api/sr/eventcategorysoundssubscriptions/c6c95ece-
133b-480b-af1f-067a173e0f5b
Response:
HTTP/1.1 200 OK
7.21.3 Delete Subscription for a event sounds changes.

Resource Path /api/sr/eventcategorysoundssubscriptions/{connectionId}
Category Public
HTTP Method DELETE
Required
Examples Request:
DELETE /api/sr/eventcategorysoundssubscriptions/e3d90a35-
1f7a-4ec2-8b3b-2fba71b76bc7
Response:
HTTP/1.1 200 OK

After subscribing for event sounds, the current sound file with a link to download it
will be sent in an initial notification. Afterwards, any change will be notified.

2. eventSoundsHub : lagacy
Function notifySounds ( data )
data FileRepresentation File details . See [➙207]
150
EventCategorySound Service 10
NOTE:
7.21.4 Create channelize event sound subscription

If subscription response and notifications are needed on signalr channed.
Subscription response will be pushed through notifySubscriptionStatus function
available at client side. Sound changes will be notified via notifySounds.
Resource Path /api/sr/eventcategorysoundssubscriptions/channelize/:requestId/:connectionId
Category Public
HTTP Method POST
client.
Required
Required
Examples Request:
POST
api/sr/eventcategorysoundssubscriptions/channelize/956
5ca41-8556-4dbb-94cc-1b89451a5db5/c6c95ece-133b-480b-
af1f-067a173e0f5b
{
"ErrorCode":0,
“RequestFor”:” notifySounds”
}

After subscribing for event sounds, the subscription status will be sent only once.

Hub 2. norisHub
3. eventSoundsHub (lagacy)
Response
Example {
"ErrorCode":0,
“RequestFor”:"notifySounds"
}
151
10 Settings Service
7.22 Settings Service

Settings are stored on a “per user” basis.

/settings/{settingId} Internal x
7.22.1 Read setting

Read a setting; the setting value is returned ad the body of the response.
Resource Path /settings/:settingId
Category Internal
HTTP Method GET
settingId String Identifies the setting to be retrieved.
Required
HTTP 204 No Content
Examples Request:
GET /api/settings/MySettingId
Response:
Returns status code 200 if the setting exists; otherwise code 204 is returned.
7.22.2 Write setting

Write a setting; the setting id is required as part of the URL while the content must
be provided as part of the body of the request (a null or empty string is not valid
and will result in a Bad Request response code). Note that a setting does not have
to exist prior to writing it.
Category Internal
HTTP Method PUT
settingId String Identifies the setting to be written.
Required
Body The content of the setting to be stored for the current user.
HTTP 204 No Content
HTTP 400 Bad Request
Examples Request:
PUT /api/settings/MySettingId
Post Data:
A string
Response:
Returns status code 200
7.22.3 Delete setting

Delete a setting for the current user; note that deleting a non-existent setting re-
turns success (200).
152
Users Service 10

Category Internal
HTTP Method DELETE
settingId String Identifies the setting to be deleted.
Required
Examples Request:
DELETE /api/settings/MySettingId
Response:
7.23 Users Service

/users/password Internal
7.23.1 Change Password

Change password by providing user details.
NOTE:
If user has a valid token and password is changed, token remains valid.
If the new password does not follow the password policy (configured in SMC),
then password will not be allowed to be changed and HTTP 400 error will be
returned.
Resource Path api/users/password

Category Internal
HTTP Method PUT
Body Property Type Description
userName string Username
Required
currentPasswo string Current password
rd Required
newPassword string New password
Required
Examples Request:
PUT /api/users/password
Body: (new password follows policy)
{
"userName": "GmsUser",
"currentPassword": "XXXX",
"newPassword": “ZZZZ"
}
Response:
HTTP 200 OK
Body: (new password does not follow policy)
153
10 Users Service
{
"userName": "GmsUser",
"currentPassword": "aaaa",
"newPassword": “bbbb"
}
Response:
Details: "Password does not meet policy requirements."
Error: "password_not_compatible"
Id: 2400004
7.23.2 Get Login Information

Get login information for the requested user. This is open API, i.e. it does not re-
quires any authentication. Provided a user, it will return account type of that user
as integer. Based on this account type client of this API (especially Flex Client)
can take decision on how to accept the password by showing correct UI to the end
user. For any user which is not present in the DesigoCC, AccountType will be re-
turned as DesigoCC (AccountType = 0)
Following are possible account type values:

0 = DesigoCC Account
1 = Windows Account
2 = Software Account (Not used for login from UI as of now)
3 = OpenID Account
Incase if the account type is OpenID (AccountType = 3), Additional information re-
garding OpenID LoginUri and LogoutUri will be sent in the same response as
shown in the below example. In all the other cases this will be null.
When the OpenID configuration is missing in the system, fallback will happen for
account type from OpenID to DesigoCC even though the user is correctly mapped
to OpenID account in the system. Because if the necessary configuration is miss-
ing then we cannot prepare LoginUri and LogoutUri which are mandatory for the
OpenID authentication.
Resource Path api/users/logininfo/{username}

Category Public
HTTP Method GET
username string Username to login with.
(Recommendation: Double UrlEncode parameter
prior to making it to part of URI.)
Required
HTTP 503 Service Unavailable
154
Users Service 10
Example1 AccountType of the user is DesigoCC/Windows
Request:
GET /api/users/test
Response:
HTTP 200 OK
{
"UserName": "test",
"AccountType": 0
}
Example2 AccountType of the user is OpenID, but the OpenID configuration is missing
in DesigoCC system.
Request:
GET /api/users/test.test%40test.com
Response:
HTTP 200 OK
{
"UserName": "test.test@test.com",
"AccountType": 0
}
Example3 AccountType of the user is OpenID, OpenID configuration is present in the
DesigoCC system.
Request:
GET /api/users/test.test%40test.com
Response:
HTTP 200 OK
{
"UserName": "test.test@test.com",
"AccountType": 3,
"OpenIdUri": {
"Login":
"https://MyAuth0Domain.com/authorize?client_id=MyTestC
lientId&response_type=code&scope=openid profile
email&connection=main-tenant-oidc",
"Logout":
"https://MyIdServerDomain.com/v2/logout?returnTo=https
:// MyAuth0Domain.com/v2/logout"
}
}
As this API will be used while performing the login. There are some steps that
needs to be additionly performed by client of this API. These steps are only appli-
cable to users of type OpenID (AccountType = 3).
In case of such users, authentication will be performed by the ID server. For this
client needs to redirected to ID server. And after the authentication is done, it
needs to redirected back to the login page of the client to continue the authentica-
tion process.
On similar note, while performing the logout as well, client needs to logout from ID
sever as well, otherwise on next OpenID login, user will not be asked for creden-
tials. Logout from ID server also takes advantage of redirection of the browser.
That’s why in case of logout as well client needs to add redirect url as callback.
a. OpenIdUri.Login
Redirect URI of the client which is register on Auth0 for the client application
needs to be appended at the received login uri in following format:
Query string operator: &
155
10 Scheduler Service
Query string parameter Name: redirect_uri

Query string parameter Value: URI of the client
Final OpenIdUri.Login will look like following:
https://MyAuth0Domain.com/authorize?client_id=MyTestClientId&res
ponse_type=code&scope=openid profile email&connection=main-
tenant-oidc&redirect_uri= https://MyMachineDomain:446/FlexApp
Text in the bold is the appended text.
b. OpenIdUri.Logout
Allowed Logout URI of the client which is register on the Auth0 for the client
application needs to be appended at the received logout uri as following:
Query string operator: ?
Query string parameter Name: returnTo
Query string parameter Value: URI of the client
Final OpenIdUri.Logout will look like following:
https://MyIdServerDomain.com/v2/logout?returnTo=https://
MyAuth0Domain.com/v2/logout?returnTo=https:// MyMachine-
Domain:446/FlexApp
Text in the bold is the appended text.
7.24 Scheduler Service

/scheduler Internal x
7.24.1 Gets BACnet schedule object based on the schedule

object id
Resource Path /scheduler/schedule/:objectId
Category Public
HTTP Method GET
objectId string Required
Object of WeeklySchedule [->208]
Examples Request:
GET
/api/scheduler/schedule/System1%253AGmsDevice_1_180
0_71303169
Response:
{
156
Scheduler Service 10
"DeviceId": "System1:GmsDevice_1_1800_33556232",
"Name": "System1:GmsDevice_1_1800_71303169",
"Setup": {
"DefaultValue": "1.1",
"StartDate": {
"Date": "0001-01-01T00:00:00Z"
},
"EndDate": {
"Date": "0001-01-01T00:00:00Z"
},
"Priority": 16,
"DataType": "BACnetDataTypeReal",
"ScheduleMin": -3.402823e+38,
"ScheduleMax": 3.402823e+38,
"TextGroupId": "TxG_EngineeringUnits",
"Unit": 64
},
"Outputs": [
"Sys-
tem1:GmsDevice_1_1800_8388609.Present_Value"
],
"ScheduleType": "BACnet",
"Schedules": [
{
"Day": "monday",
"Entries": [
{
"Time": "07:00:00",
"Value": 18.5
},
{
"Time": "21:00:00",
"Value": 15.5
}
]
}
],
"Exceptions": [
{
"Priority": 6,
"Mode": 3,
"CalendarException": {
"CalendarObjectId": "Sys-
tem1:GmsDevice_1_1800_25165825",
"CalendarEntries": [
{
"StartDate": {
"Date": "0001-01-01T00:00:00Z",
"Days": [
6
],
"Months": [
1
],
"DaysInMonth": [
1
],
"Years": [
2005
]
},
"Mode": 0
},
{
"StartDate": {
"Date": "0001-01-01T00:00:00Z",
"Days": [
4
157
],
"Months": [
6
],
"DaysInMonth": [
27
],
"Years": [
2019
]
},
"Mode": 0
}
],
"CalendarName": ""
},
"ExceptionTimes": [
{
"Time": "00:00:00",
"Value": 13.78
},
{
"Time": "08:32:32.3200000",
"Value": 66.6
},
{
"Time": "10:56:56.5600000",
"Value": 13.78
},
{
"Time": "12:11:11.1100000",
"Value": 66.6
},
{
"Time": "23:59:59.5900000",
"Value": 13.78
}
]
}
]
}
7.24.2 Save BACnet schedule values

Resource Path /scheduler/schedule/save
Category Public
HTTP Method POST
Body schedule WeeklySchedule [->208]

true or false as body
Examples Request:
POST
/api/scheduler/schedule/save
{
"DeviceId": "System1:GmsDevice_1_1800_33556232",
"Name": "System1:GmsDevice_1_1800_71303169",
"Setup": {
"DefaultValue": "1.1",
158
"StartDate": {
"Date": "0001-01-01T00:00:00Z"
},
"EndDate": {
"Date": "0001-01-01T00:00:00Z"
},
"Priority": 16,
"DataType": "BACnetDataTypeReal",
"ScheduleMin": -3.402823e+38,
"ScheduleMax": 3.402823e+38,
"TextGroupId": "TxG_EngineeringUnits",
"Unit": 64
},
"Outputs": [
"Sys-
tem1:GmsDevice_1_1800_8388609.Present_Value"
],
"ScheduleType": "BACnet",
"Schedules": [
{
"Day": "monday",
"Entries": [
{
"Time": "09:54:00",
"Value": 18.5
},
{
"Time": "21:00:00",
"Value": 15.5
}
],
"OutputValuesActive": [],
"OutputValuesInActive": []
}
],
"Exceptions": [
{
"Priority": 6,
"Mode": 3,
"CalendarException": {
"CalendarObjectId": "Sys-
tem1:GmsDevice_1_1800_25165825",
{
"StartDate": {
"Date": "0001-01-01T00:00:00Z",
"Days": [
6
],
"Months": [
1
],
"DaysInMonth": [
1
],
"Years": [
2005
]
},
"Mode": 0
},
{
"StartDate": {
"Date": "0001-01-01T00:00:00Z",
"Days": [
4
],
"Months": [
159
6
],
"DaysInMonth": [
27
],
"Years": [
2019
]
},
"Mode": 0
}
],
"CalendarName": ""
},
"ExceptionTimes": [
{
"Time": "00:00:00",
"Value": 13.78
},
{
"Time": "08:32:32.3200000",
"Value": 66.6
},
{
"Time": "10:56:56.5600000",
"Value": 13.78
},
{
"Time": "12:11:11.1100000",
"Value": 66.6
},
{
"Time": "23:59:59.5900000",
"Value": 13.78
}
]
}
]
}
Response:
200 OK
true
7.24.3 Save BACnet schedule exceptions

Resource Path /scheduler/exception/save
Category Public
HTTP Method POST
schedule WeeklySchedule
[->208 ]
Examples Request:
7.24.4 Save BACnet default value for schedule

Resource Path /scheduler/schedule/saveDefaultValue
160
Category Public
HTTP Method GET
defaultValue string Required
objectId string
Examples Request:
7.24.5 Retrieve BACnet calendar list for schedule object id

Resource Path /scheduler/calendarList/:objectId
Category Public
HTTP Method GET
Examples Request:
7.24.6 Retrieve calendar object based on calendar object Id

Resource Path /scheduler/calendar/:objectId
Category Public
HTTP Method GET
Object of Calendar [->207]
Examples Request:
GET
/api/scheduler/calendar/System1%253AGmsDevice_1_180
0_25165825
Response:
200 OK
{
"ScheduleCalendarType": 0,
{
"StartDate": {
"Date": "0001-01-01T00:00:00Z",
"Months": [
1
],
"DaysInMonth": [
1
],
"Years": [
2005
]
},
"Mode": 0
}
],
161
"AppliedSchedules": [
"System1:GmsDevice_1_1800_71303169"
],
"ContainerObjectId": "Sys-
tem1:GmsDevice_1_1800_33556232",
"Device": 1800
}
7.24.7 Save BACnet calendar

Resource Path /scheduler/calendar/save
Category Public
HTTP Method POST
calendar Calendar [->207
]
true or false in body
Examples Request:
POST
/api/scheduler/calendar/save
Body:
{
"ScheduleCalendarType": 0,
{
"Mode": 0,
"StartDate": {
"Years": [
2005
],
"Months": [
1
],
"DaysInMonth": [
1
]
}
},
{
"Mode": 0,
"StartDate": {
"Years": [
2019
],
"Months": [
6
],
"DaysInMonth": [
27
]
}
}
],
"AppliedSchedules": [
"System1:GmsDevice_1_1800_71303169"
162
Objects Service 10
],
"ContainerObjectId": "System1:GmsDevice_1_1800_33556232",
"Device": 1800,
"ObjectId": "System1:GmsDevice_1_1800_25165825"
}
Response:
200 OK
true
7.25 Objects Service

/objects Internal x
7.25.1 Get available Objects types

Resource Path /objects/:designation
Category Internal
HTTP Method GET
designation string Full view name;
Designation id of node in
systembrowser tree
making it to part of URI.) Required
includeChildInfo bool If true, response will include child
object type information
Default: false
An array of ChildObjectType objects See [➙ 210]
Examples Request:
api/Objects/System1.ApplicationView%3AApplicationView.Trends.TrendViewD
efinitions
Response:
{
"Designation":
"System1.ApplicationView:ApplicationView.Trends.TrendViewDefinitions",
"Description": "Trends Folder",
"ObjectType": "_GmsTrendsFolder",
"IsGenericDeleteAllowed": false,
"ChildObjects": [
{
"IsGenericCreateAllowed": false,
"MaxChild": 4294967295,
"ExistingChildCount": 0,
"Description": "Trend View Definition",
"ObjectType": "GMS_TVD",
"IsGenericDeleteAllowed": true
},
{
163
10 Objects Service
"IsGenericCreateAllowed": true,
"MaxChild": 4294967295,
"ExistingChildCount": 0,
"Description": "Trends Folder",
"ObjectType": "_GmsTrendsFolder",
"IsGenericDeleteAllowed": false
}
]
}
7.25.2 Create Objects

Resource Path /objects
Category Internal
HTTP Method POST
Body childObject ObjectRepresent Child node details which user needs
ation. See [➙ to create.
209]
BrowserNode objects See [➙209 ]
Examples Request:
api/Objects
Body Parameter:
{
"Designation": "Sys-
tem1.ApplicationView:ApplicationView.Trends.TrendViewDefinitions",
"NameChildNode": "TestFolderTVD1",
"ObjectModelName": "_GmsTrendsFolder",
"Descriptor": {
"CommonText": "TestFolderTVDNode",
"MultiLangText": [
"TestFolderTVDNodeLang1",
"TestFolderTVDNodeLang1"
] }}
Response:
{
"HasChild": false,
"SystemId": 1,
"ViewId": 10,
"ViewType": 1,
"Name": "TestFolderTVD1",
"Descriptor": " TestFolderTVDNode",
"Designation":
"System1.ApplicationView:ApplicationView.Trends.TrendViewDefinitions.TestF
olderTVD1",
"ObjectId": "System1:TestFolderTVD1",
"Attributes": {
"DefaultProperty": "StatusPropagation.AggregatedSummaryStatus",
"ObjectId": "System1:TestFolderTVD1",
"DisciplineId": 0,
"TypeId": 8000,
"SubTypeDescriptor": "User Defined Folder",
164
Objects Service 10
"SubTypeId": 8016,
"ManagedType": 59,
"ManagedTypeName": "TrendsFolder",
"ObjectModelName": "_GmsTrendsFolder",
"CommentRule": "Optional",
"Configuration": 0,
"_links": []
}
},
"Location": "System1.Application View:Applications.Trends.Trend View
Definitions.string",
"_links": [
{
"Href": "api/properties/System1%253ATestFolderTVD1?requestType=0",
}
]
}
7.25.3 Delete Objects

Resource Path /objects/:designation
Category Internal
HTTP Method DELETE
designation string
Response
Examples Request:
DELETE
api/Objects/System1.ApplicationView%3AApplicationVi
ew.Trends.TrendViewDefinitions.TestFolderTVD1
Response:
7.25.4 Get Information text

Resource Path /objects/servicetext/:objectId
Category Internal
HTTP Method GET
Parametrers Property Type Description
objectId string Object id
Recommendation: Double
making it to part of URI
Array of ObjectInfoRepresentation[➙211]
Examples Request:
GET
api/Objects/servicetext/System1:ManagementView_Mana
gementSystem_Servers_Server
Response:
165
10 Objects Service

[
{
"ObjectId":
"System1:ManagementView_ManagementSystem_Servers_Server",
"ServiceText": {
"InformationText": "",
"Memo": ""
}
},
{
"Error": {
"Id": 2402709,
"Error": "obj_invalid_object",
"Details": "Failed to resolve passed object id to a valid object"
},
"ObjectId": "InvalidObjectId"
}
]
7.25.5 Put Memo text

Resource Path /objects/servicetext/:objectid/memo
Category Internal
HTTP Method PUT
Parameters objectId string Object id
Recommendation: Double
UrlEncode parameter prior
to making it to part of URI
Body memodetail ServiceTextMem Memo details
oRepresentation
[➙211]
Array of ObjectInfoRepresentation[➙211]
Examples Request:
PUT
api/Objects/servicetext/System1:ManagementView_Mana
gementSystem_Servers_Server/memo
BODY
{
"Memo": "Sample Memo"
}
Response:
166
Related Items Service 10
7.26 Related Items Service

The purpose of the related items API is to access items that are associated to another
object. For example, an object in a graphic is said to be `related to` that graphic. In most
situations the relationship between that object and the graphic is discovered by request-
ing the graphic – but it is often useful to know where that object is used (such as a
graphic or re report) or if there is something external (such as a file or a website) that
has a connection to the object.

/relateditems Public
7.26.1 Read Related Items

Return related items for a list of objects. Please keep in mind that:
• The system information for each object is optional and if not provided, the WSI
will assume that the object is on the “local” system. If the object does not exist
in that system the list of related items for that object will be empty.
• The list of objects must all be from the same system. If they are not, the entire
call will fail with an HTTP error code return of 400.
• A related item is just another object in the system and can appear in multiple lo-
cations within a hierarchy or within multiple hierarchies. Each related item will
contain a BrowserNode for each location, where the BrowserNode has the ob-
ject and view information.
Resource Path api/relateditems

Category Internal
HTTP Method POST
Parameters None
Body Array of Object Ids
Response HTTP 400 Bad Request
HTTP 200 OK
The top level object contains an array of results, one element for each incoming
object id. Each element holds the object id, an error code, and an array of
RelatedItem objects for that object id. For the full description of a RelatedItem go
here.
Example Request:
POST /api/relateditems
Body:
[
"SystemName:Object1",
"SystemName:Object2"
]
Response:
HTTP 200 OK
{
RelatedResults: [
{
ObjectId: “SystemName:Object1”,
ErrorCode: 0,
RelatedItems: [
<related item 1 for Object1>
{
"ItemDescriptor": "",
"Reference": "",
"Mode": 1,
"SourceType": 1,
167
10 Access rights Service
"Nodes": [
{
<BrowserNode: see [➙ 55]>
},
{
}
]
},
{
"Reference": "",
"Mode": 2,
"SourceType": 1,
"Nodes": [
{
}
]
},
<... more related items for Object1>
]
},
{
ObjectId: “SystemName:Object2”,
ErrorCode: 0,
RelatedItems: [
{
"Reference": "",
"Mode": 1,
"SourceType": 1,
"Nodes": [
{
},
{
}
]
},
{
"Reference": "",
"Mode": 2,
"SourceType": 1,
"Nodes": [
{
}
]
},
<... more related items for Object2>
]
}
]
}
7.27 Access rights Service

Application rights assigned to user group can be retrieved by this service.

/accessrights Internal x x
168
Access rights Service 10
7.27.1 Retrieve access rights
Resource Path /accessrights

Category Internal
HTTP Method GET
Array of AccessRightResponseRepresentation object [➙Error! Bookmark not
defined.]
Examples Request:
GET /api/accessrights
Response:
Returns status code 200 with applications and their respective access.
{
"ApplicationRights": [
{
"Name": "BACnet Configuration",
"Id": 6,
"Operations": [
{
"Name": "Show",
"Id": 192
},
{
"Name": "Configure",
"Id": 194
}
]
}
]
}
7.27.2 Retrieve user roles

Resource Path /accessrights/roles
Category Internal
HTTP Method GET
Array of UserRoleRepresentation object
Examples Request:
GET /api/accessrights/roles
Response:
Returns status code 200 with applications and their respective access.
{
"RolesMapping": [
{
"RoleId": 101,
"RoleState": false,
"RoleName": "DefaultAdmins",
"RoleDescription": "Default Administrator Group"
},
{
"RoleId": 100,
"RoleState": false,
"RoleName": "DefaultAdmins1",
"RoleDescription": "Default Administrator Group"
}
]
}
169

Subscription for any changes in application rights configuration for logged in user
will be notified.

Hub norisHub
Function notifyAccessRights ( data )
data AccessRightsRepre See AccessRightsRepresentation
sentation [➙ 214]
7.27.3.1 Create channelize Access rights subscription

Subscription response will be pushed through notifySubscriptionStatus func-
tion available at client side. Application rights changes will be notified via noti-
fyAccessRights.
Resource Path /api/sr/accessrightssubscriptions/channelize/:requestid
/:connectionId?includedetails=:includedetails
Category Public
HTTP Method POST
client.
Required
Required
includedetails bool Default set to false, This flag will tell server to send
all application rights as soon as something changes
on server.Setting this flag to false, will result in
empty object in push notification stating something
is changed.
Optional
[Setting it to true could be resource heavy if
changes are done too frequently]
Examples Request:
POST
/api/sr/accessrightssubscriptions/channelize/9565ca41-
067a173e0f5b?includedetails=false
{
"ErrorCode":0,
“RequestFor”:” notifyAccessRights”
}
170
Access rights Service 10
7.27.3.2 Create User Roles Subscription

Resource Path /api/sr/accessrightssubscriptions/channelize/:requestid
/:connectionId?includedetails=:includedetails/userroles
Category Public
HTTP Method POST
client.
Required
Required
includedetails bool Default set to false, Setting this flag to false, will
result in empty object in push notification stating
something is changed.
[Currently setting it to true does not change the
response. This might be implemented in the
future.]
Examples Request:
POST
/api/sr/accessrightssubscriptions/channelize/9565ca41-
067a173e0f5b?includedetails=false/userroles
{
"ErrorCode":0,
“RequestFor”:”userRoles”
}
7.27.3.3 Delete Subscription for a Access Rights

Resource Path /api/sr/ accessrightssubscriptions /{connectionId}
Category Public
HTTP Method DELETE
Required
Response Object of UnsubscriptionStatus See Link [➙214]
Examples Request:
DELETE api/sr/ accessrightssubscriptions/aa82215b-b635-40a7-
92a3-4fcc80a677d1
Response:
HTTP/1.1 200 OK
171
7.27.3.4 Delete Subscription for User Roles

Resource Path /api/sr/ accessrightssubscriptions /{connectionId}/userroles
Category Public
HTTP Method DELETE
Required
Examples Request:
DELETE api/sr/ accessrightssubscriptions/aa82215b-b635-40a7-
92a3-4fcc80a677d1/userroles
Response:
HTTP 200 OK
172
Operating Procedures Service 10
7.28 Operating Procedures Service

/operatingprocedures Internal x x
7.28.1 Retrieve Operating procedure

Resource Path /operatingprocedures
Category Public
HTTP Method GET
Object of Operating procedure [➙213]
Examples Request:
GET /api/operatingprocedures?
id=1.832765.2.23.2.131675.637082217374440000.0
Response:
Returns status code 200.
{
"AlertCount": 1,
"AlertSource": "System1",
"AlertTime": "2019-11-07T11:03:04.325Z",
"Id": "1.832765.2.23.2.131675.637082217374440000.0",
"InTreatmenBy": "#DefaultAdmin",
"IsClosed": true,
"ResetSteps": 0,
"Sequential": true,
"Steps": [
{
"HasConfirmedExecution": true,
"IsCompleted": true,
"Operator": "Admin",
"RuntimeStatus": "Runtime text",
"Status": "Failed",
"StepId": "System1:GraphicsStep",
"StepName": "GraphicsStep"
}
],
"TemplateName": "GraphicsOperation"
}
7.28.2 Update Operating procedure step

Resource Path /operatingprocedures/{id}/step
Category Internal
HTTP Method PUT
Parameters id string Required
Operating Procedure id
Body operatingStep OperatingProced Required
ureStep Object of Operating Procedure Step
All properties are not updatable,
please refer Operating procedure
step [➙213]
173
10 Operating Procedures Service

Object of Operating procedure step [➙213]
Examples Request:
PUT
api/operatingprocedures/1.832765.2.23.2.131675.6370
82217374440000.0/step
BODY:
{
"Status": "Failed",
"StepId": "System1:GraphicsStep"
}
Response:
{
"Status": "Failed",
"StepId": "System1:GraphicsStep",
"StepName": "GraphicsStep"
}

After subscribing for Operating Procedures initial notification will be sent.
Afterwards any change will be notified.

Hub norisHub
Function notifyOperatingProcedures ( data )
data OperatingProcedure See
SubscriptionRepres OperatingProcedureSubscriptionR
entation epresentation [➙ 214]
7.28.3.1 Create channelize Operating procedures subscription

Subscription response will be pushed through notifySubscriptionStatus func-
tion available at client side. Operating procedure changes will be notified via noti-
fyOperatingProcedures.
Resource Path /api/sr/operatingproceduressubscriptions/channelize/:requestId/:connectionId
Category Public
HTTP Method POST
client.
Required
174

Required
id string Operating procedure id
Optional
Examples Request:
POST api/sr/operatingproceduressubscriptions
/channelize/9565ca41-8556-4dbb-94cc-
1b89451a5db5/c6c95ece-133b-480b-af1f-067a173e0f5b
{
“Id”:”c6c95ece-133b-480b-af1f-067a173e0f5b”,
“Key”:”1a”,
"ErrorCode":0,
“RequestFor”:” notifyOperatingProcedures”
}

After subscribing for OperatingProcedure, for each key subscription status will be
sent through notifySubscriptionStatus.

Hub norisHub
Status OperatingProcedur Subscription objects See Link
eSubscriptionKey [➙214]
Response
Example {
“Id”:”c6c95ece-133b-480b-af1f-067a173e0f5b”,
“Key”:”1a”,
"ErrorCode":0,
“RequestFor”:” notifyOperatingProcedures”,
"_links":[
{
"Href":"api/sr/operatingproceduressubscriptions/aa82215b-b635-
40a7-92a3-4fcc80a677d1?subscriptionKey=1a",
"IsTemplated":false
}
]
}
]
7.28.3.3 Delete Subscription for a Operating procedure

Resource Path /api/sr/operatingproceduressubscriptions/{connectionId}
Category Public
HTTP Method DELETE
175
10 Licenses Service

Required
subscriptionKey String Query Parameter with
subscription key
Required
Response Object of UnsubscriptionStatus See Link [➙214]
Examples Request:
DELETE api/sr/operatingproceduressubscriptions/aa82215b-b635-
40a7-92a3-4fcc80a677d1?subscriptionKey=1a
Response:
HTTP/1.1 200 OK
{
“Key”:”1a”,
"ErrorCode":0
}
7.29 Licenses Service

Settings are stored on a “per user” basis.

/licenses Public x
7.29.1 Read License Mode

Read current Licences Mode; the License mode informaiton is returned in the
body of the response.
Resource Path /licenses
Category Public
HTTP Method GET
Response Object of License Mode See Link [➙215]
Examples Request:
GET /api/licenses
Response:
{
"LicenseModeName": "Siemens Developer License",
"LicenseModeValue": 4,
"ExpirationTime": 0
}
7.29.2 Read License Options

Read current Licences Mode; the License mode informaiton is returned in the
body of the response.
Resource Path /licenses/ licenseoptions
Category Public
HTTP Method GET
Response Object of License Option See Link [➙8.24]
176
Licenses Service 10
Examples Request:
GET /api/licenses/licenseoptions
Response:
[
{
"Id": "sbt_gms_intOnly_allfeature",
"Required": 0,
"Remaining": 4,
"Available": 1,
"Description": "Unlimited use for Development Pur-
poses"
},
{
"Id": "sbt_gms_ext_sm",
"Required": 0,
"Remaining": -1,
"Available": -1,
"Description": "System Manager Application"
}
]
177
10 Common
8 Objects and Data Types

NOTE:
In case a property has an empty or null value it may be omitted.
8.1 Common
8.1.1 Link
Models a hyperlink to another resource.
Href string Hyperlink to a resource (URI [RFC3986] or URI template [RFC6570])
IsTemplated bool If true, Href contains a placeholder in its link.
Rel string Link relation type (RFC5988)
8.1.2 Page<Name, Type>

_links Array of Link See Link [➙ 50]
Events Array of <Type> List of events See Link [➙183 ]
Page int Number of current page (first page = 1)
Size int Number of items per page
Total Int Total number of items
CreationTim DateTime
eFrom
CreationTim DateTime
eTo
8.1.3 KeyValue<Name, Type>

<Name> <Type> Name and type depend on current instance
8.1.4 NameValue
DataType ApiDataType Data type of the property
Name string Name of the property
Value string Value of the property
8.1.5 Subscription
Key int Subscription key is specific for the requested ID
ErrorCode int If value is >0, an error occurred.
PropertyId string Address of a property
178
Common 10
8.1.6 UnSubscription
8.1.7 Value
Value string Raw value
DisplayValue string Value for display purpose (textual representation of the raw value)
Timestamp DateTime Timestamp of this value
QualityGood bool
Quality string See Quality Flags [➙ 179]
IsPropertyAbsent bool Driver reported that property is not present
Note: Only set if true and not available for trends
8.1.7.1 Quality Flags

Quality is a string representation of a 64-bit bit-set. The string contains a ulong
numeric value. Bits not listed are not in use.
Bit Description QualityGood Effect on Value

0 variable active/inactive TRUE value ok
1 default value set explicitly TRUE value ok
2 default value set automatically TRUE value ok
3 WinCC OA value range violated FALSE value not ok
4 value of the variable "out of range" FALSE value not ok
5 explicit invalid FALSE value not ok
6 invalid set by an interface driver FALSE value not ok
8 default value invalid TRUE value ok
9 set during general query TRUE value ok
10 set during an individual query TRUE value ok
11 interface driver active TRUE value ok
12 value corrected TRUE value ok
value condensed or compressed, used TRUE value ok
(HDB & RAIMA) with
13 archiving/compression.
14 corrected value condensed TRUE value ok
15 additional correction value TRUE value ok
16 compressed value invalid TRUE value ok
source time invalid (corrected by the TRUE value ok
17 Event Manager)
19 disable last value storage TRUE value ok
20 value changed TRUE value ok
21 value up (or set to same value) TRUE value ok
24 for internal use only TRUE value ok
32 driver out of service TRUE value ok
179
10 Common
33 driver alarm TRUE value ok

34 driver fault TRUE unreliable
35 driver overridden TRUE value ok
36 driver subscribed TRUE value ok
37 driver property absent FALSE value not ok
40 trend: time shift FALSE no value, is event
41 trend: log enabled FALSE no value, is event
42 trend: error FALSE no value, is event
43 trend: purge FALSE no value, is event
44 trend: rollover FALSE no value, is event
45 trend: value is status FALSE value is status/error
46 trend: log interrupted FALSE no value, is event
48 trend: start logging TRUE value ok
49 trend: value reduced TRUE value ok
501 priority 1 (0 bit; 2^0) TRUE value ok
1
1
1 Bit 50 / Bit 51 / Bit 52 are to be combined into a single value (priority 0..7)
8.1.8 ColorRepresentation
A byte Color code
R byte Red color code
G byte Green color code
B byte Blue color code
8.1.1 CommandsSubscription

RequestId string Channelized subscription request identifier

Note: Only available for channelize requests
RequestFor string Notification function name where client will receive
further updates
SubscriptionId string Original requested string for subscription
180
Common 10
8.1.2 ValuesSubscription
_links Array of See Link [➙ 178]
Link
RequestFor string Notification function name where client will receive
further updates
OriginalObjectOrPropertyId string Original requested string for subscription
ObjectOrPropertyId string Original requested string for subscription
AttributeId string Object Name
ObjectId string Object Id only of requested ObjectOrPropertyId
PropertyName string PropertyName of requested ObjectOrPropertyId
8.1.3 Attributes
DefaultProperty string Default property of object-model
DisciplineDescriptor string Localized name of discipline
DisciplineId int ID of discipline
FunctionDefaultProperty string Default property of assigned function
FunctionName string
ManagedType uint
ManagedTypeName string
ObjectModelName string
ObjectId string
SubDisciplineDescriptor string Localized name of subdiscipline
SubDisciplineId int ID of subdiscipline
SubTypeDescriptor string Localized name of subtype
SubTypeId int ID of subtype
TypeDescriptor string Localized name of type
TypeId int ID of type
8.1.4 ApiDataType
Name Description BaseType
None
BasicChar char
BasicUint uint
BasicInt int
BasicFloat double
BasicBool boolean
BasicBit32 uint
BasicString string
BasicTime DateTime
181
10 Token Service
BasicObjectOrPropertyId string
BasicLangText string
BasicBlob string
ExtendedBool Extends BasicBool with a language text for true/false.
ExtendedInt Extends BasicInt with Min, Max, Default, Unit.
ExtendedUint Extends BasicUint with Min, Max, Default, Unit.
ExtendedReal Extends BasicFloat with Min, Max, Default, Unit.
ExtendedEnum Extends BasicUInt with enumeration texts.
ExtendedBitString Extends BasicUInt with bit set texts.
ExtendedDateTime Extends BasicString with semantics for a DateTime string
format.
ExtendedApplSpecific Extends BasicString with the knowledge that the string
has a dedicated meaning for some application. Typically,
the string will be XML-encoded.
ExtendedAny Extends BasicFloat with the permission to switch its type.
ExtendedComplex Extends BasicBlob.
ExtendedDuration Extends BasicUint with Min, Max, Default and time
duration specific configurations.
8.1.5 Subgroups
Id Uint Id of the SubGroup
Descriptor string Descriptor of the SubGroup
8.1.6 StatusNotification
ErrorCode int Error code of operation:
0 – Success
1 - Error
RequestId string Unique Identifier passed by client in subscription request
RequestFor string Client Method where push notification will be served
8.2 Token Service
8.2.1 Login
access_token string Token to be provided for requesting protected resources.
expires_in int Seconds until token expires at the latest
NOTE: Token will expire sooner in case of inactivity; see
Authentication [➙ 28].
token_type string Only Bearer is supported at this time.
user_name string Logged in user name
user_descriptor string Localized user descriptor in user language
user_profile string name of currently logged in user’s profile
flex_user_profile string name of currently logged in flex-user profile
user_inactivity_timeout string Inactivity timeout of user’s group (uint) in minutes.
182
Event Service 10
password_reminder_cou string Days remainingfor password expiry

nter
personally_used string “true” : machine is personally used
“false” : machine is not personally used for provided client
certificate
8.3 Event Service
8.3.1 Event
_links Array of See Link [➙ 178]
Link
CategoryDescriptor string Localized textual representation of CategoryId
CategoryId int Alarm category
Cause string Cause came with alarm (localized)
Commands Array of List of available commands. See Event Command [➙ 187]
EventComm
and
CreationTime DateTime Time when alarm created.
Deleted bool Flag whether an event was deleted. This is for server sent
notifications only.
Direction EventDirecti See EventDirection [➙ 184]
on
EventId uint Event counter (non-unique)
EventText string Service text attached to an event.
Id string Desigo CC alarm identifier
→ Invariant across sessions
InfoDescriptor string Additional information to an event
SrcDescriptor string Tree node descriptor
OBSOLETE : use DescriptionList instead
SrcDesignation string Concatenated tree node names
OBSOLETE : use DesignationList instead
SrcDisciplineDescript string Localized textual representation of DisciplineId
or
SrcDisciplineId int Alarm discipline
SrcLocation string Concatenated tree-node descriptors
OBSOLETE :use DescriptionLocationsList instead
SrcName string Tree node name
SrcObservedProperty string Observed property which lets SrcPropertyId trigger an event
Id
SrcPropertyId string Source of an event
SrcState SourceState See SourceState [➙ 184]
SrcSystemId uint Unique system identifier
SrcViewDescriptor string View descriptor
SrcViewName string View name
State EventState See EventState [➙ 184]
SuggestedAction SuggestedA See SuggestedAction[➙186 ]
ction
NextCommand NextComm See NextCommand [➙186 ]
and
183
10 Event Service
SourceDesignationLi Array of List of node name.

st Event See EventDetailsList [➙188]
Designation
List
DescriptionLocations Array of List of Concatenated tree-node descriptors
List EventsLocat See EventDetailsList [➙188]
ions
DesignationList Array of List of Concatenated tree node names
EventsDesi See EventDetailsList [➙188]
gnation
DescriptionList Array of List of Tree node descriptor
EventsDesc See EventDetailsList [➙188]
ription
MessageText Array of Information Texts of events
string
SrcAlias string Event Source Alias
OperatingProcedureI string Operating procedure id associated with event
d
Sound string Path of sound file associated with event
AutomaticTreatment AutomaticTr See Automatic Treatment Data[➙186]
Data eatmentDat
a
8.3.1.1 SourceState
SrcState must have one of the following values.
SrcState Description
Active Object is active
Quiet Object is quiet
8.3.1.2 EventState
State must have one of the following values.
State Description
UnprocessedWithTimer Unprocessed with Timer for user action
Unprocessed Unprocessed
ReadyToBeResetWithTimer Ready to be reset with timer for user action
ReadyToBeReset Ready to be reset
ReadyToBeClosed Ready to be closed
WaitingOPCompletion Waiting for completion
Acked Acknowledged
Closed Closed
8.3.1.3 EventDirection
Direction must have one of the following values:
Direction Description
In IN alarm
Out OUT alarm
None Neither IN nor OUT alarm
184
Event Service 10
8.3.1.4 EventTimeFilter
creationTime must have one of the following values:
creationTime Description
0 All events (default, can be omitted)
1 Events generated in the last 15 minutes
2 Events generated in the last 30 minutes
3 Events generated in the last hour
4 Events generated last night
5 Events generated yesterday
6 Events generated today
8.3.1.5 EventSorting
sorting must have one of the following values.
sorting Description
0 Sort by StateId, CategoryId, and descending CreationTime
1 Sort by StateId, CategoryId, DirectionId, and ascending CreationTime
8.3.1.6 EventFilter
ids Array of strings Event identifier
caseSensitive bool
categories Array of int
cause string
creationTime int See EventTimeFilter [➙185 ]
creationTimeFrom DateTime
creationTimeTo DateTime
disciplines Array of int
systemId Uint System identifier
states Array of int
8.3.1.7 EventSubscriptionStatus
ErrorCode int 0: success
1: Failure
Sorting int See Event Sorting [➙ 185]
EventsFilter EventFilter See EventFilter [➙185 ]
object
RequestFor string Notification function name where client will receive further
updates.
185
10 Event Service
8.3.1.8 Maintenence State

“Maintenance” must have one of the following values.
SrcState Description
All Maintenance is All
MaintenanceOnly MaintenanceState is Maintenance
GenuineOnly MaintenanceState is Geniune
8.3.1.9 SuggestedAction
“SuggestedAction” must have one of the following values.
SuggestedAction Description
Acknowledge
Silence
Suspend
Reset
Close
CompleteOP Complete operation
WaitforCondition
None
8.3.1.10 Next Command

“NextCommand” must have one of the following values.
NextCommand Description
None
Acknowledge
Reset
NoActionPossible
StepMandatory
Silence
Close
8.3.1.11 Automatic Treatment data

HasFilter boolean
Stations string[]
Timeout uint
Users uint[]
CloseTreatmentWhe string Configuration value specifying condition for closing the
n treatment.
186
Event Service 10
Valid values:
1.SourceToNormal
2.UponUserRequest
3.EventAcknowledged
4.EventReset
5.EventClosed
6.Timeout
OnNewEvent string Configuration value specifying action on new event.
Valid values:
1.DoNothing
2.OpenEventList
3.StartFastTreatment
4.StartInvestigativeTreatment
5.StartAssistedTreatment
OnNewHigherPrioEv string Configuration value specifying action on new higher priority
ent event.
Valid values:
1. DoNothing
2. SwitchToNew
3. AskUser
8.3.2 EventCommand

EventId string Unique identifier of an event
Id EventCommandId See Event Command ID [➙ 50]
Configuration Int ValidationId of a propertyid
If Configuration :0 ->None is required
If Configuration :1 -> Only comment is required
If Configuration : 2->Both Comment and Password(to re-
authenticate) are required.
if Configuration =3 : Comment , Current logged in user's
credentials, Supervisor's Username and Supervisor's Password is
expected
if Configuration =4 : Supervisor's Username and Supervisor's
Password is expected
8.3.2.1 ValidationData
Password String Password required to re-authenticate event-commands
MultiLangComments String[] Comments are required before execution of an event-
command.
Comments should be provided in same order as
languages are installed for a project.
Check Systems Service[➙ 137] to get the order of
installed languages.
NOTE : array with length equals number of languages
installed in project.
SuperName String Supervisor’s username required to authenticate event-
commands
SuperPassword String Supervisor’s password required to authenticate event-
commands
187
10 Event Counter Service
8.3.2.2 BatchEventsCommandExecution
ValidationInput ValidationData Validation information of command execution See Link
[➙ 187]
EventIds String[] List of Event Id’s for execution
8.3.3 EventDetailsList
ViewId uint Unique identifier of a view
Descriptor string View details (Tree node or node details)
8.4 Event Counter Service
8.4.1 EventCounterList
EventCategoryCounters Array of Categorized list of event counters
EventCounter
TotalCounters int Total counters in the system for logged-in user
TotalUnprocessedCounters int Total unprocessed counters in the system for logged-
in user
8.4.2 EventCounter
CategoryId int Category key
CategoryDescriptor string Localized category name
TotalCount int Total events of this category
UnprocessedCount int Total unprocessed events of this category
TotalSubsequentGroup int Total number of grouped for subsequent Events for a
ing category
UnprocessedSubseque int Total number of unprocessed subsequent Events for a
ntGrouping category
8.4.1 Category color details

EColorPalette EColorPalette description
Type(int)
1 TextButtonNormal
2 TextButtonPressed
3 TextEventSelected
4 TextEventNormal
5 TextEventHover
188
6 ButtonGradientBright
7 ButtonGradientDark
8 ButtonPressedGradientBright
9 ButtonPressedGradientDark
10 ButtonBlinkingBright
11 ButtonBlinkingDark
12 EventDescriptorSelected
13 EventDescriptorNormal
8.4.2 Subscription Status

Key Type description
ErrorCode int 0: Success
1: Failure
RequestFor string Notification function name where client will receive further
updates
8.5 System Browser Service
8.5.1 View
Designation string Full view name
Descriptor string Localized view name
Name string View name
SystemId uint Unique ID of a system
SystemName String Name of system
ViewId uint Unique ID of a view within a system
ViewType int The type of view in Desigo CC:
-3: Reserved (used internally)
-2: Isolated (used for isolated nodes)
-1: Undefined
0: Management
1: Application
2: Logical
3: Physical
4: UserDefined
189
8.5.2 BrowserNode
Attributes Attributes See Attributes [➙ 51]
Descriptor string Localized browser object name
Designation string Full view name
HasChild bool Flag whether child nodes are available
Note: Property omitted for searches and in notifications
Name string View name
Location string Localized full browser object name
ObjectId string Node address
SystemId uint Unique ID of a system
ViewId uint Unique ID of a view within a system
8.5.3 SystemBrowserSearchList
ErrorCode int If value is >0, an error occurred
ObjectId string Searched Object Id
Nodes Array of Array of Browser nodes returned as search result for
BrowserNode ObjectId see [➙ 77]
8.5.4 SystemBrowserSubscription
Action ObservationActio Enumeration to convey additional information about the
n action. See Enum for Action [➙ 78]
Change ObservationCha Enumeration to convey the possible reasons for the event
nge to have occurred. See Enum for Change [➙ 78]
Node BrowserObject See BrowserObject [➙ 77]
View View See View [➙ 77]
SubscriptionKey int Subscription Key of View
8.5.4.1 ObservationChange
Change type Description
0 Reserved for 'no reason known'
1 System name changed
2 View separator changed
3 Change in the Nodes display name OR Views display name
4 Tree data changed
5 Structural change in the specified View, Tree OR Node. This also handles
creation/deletion of System Browser-Views, a System Browser-Node OR
System Browser-Subtree
100 Provider Reconnect
190
Value Service 10
8.5.4.2 ObservationAction
Action type Description
0 Reserver for ‘no action known’
1 Changes in the System name
2 Creation of System Browser-View
3 Deletion of System Browser-View
5 Editing of System Browser-View
6 Editing of System Browser-View separator
7 Creation of System Browser-Tree
8 Deletion of System Browser-Tree
9 Editing of System Browser-Tree
10 Adding of a System Browser-Tree i.e. a new node somewhere in the Tree
11 Changes in the Node name
12 Changes in the Node data
100 All nodes in the client-hosted tree have been collapsed.
8.5.5 SystemBrowserSubscriptionKey
Designations String[] String array of designations for which client requested subscription
RequestFor string Notification function name where client will receive further updates
8.6 Value Service
8.6.1 ValueDetails
_links Array of Link See [➙ 42]
AttributeId string Address of attribute to which value belongs to
Note: In channelized subscription response data, this

property is not set
DataType ApiDataType
ErrorCode int If value is >0, an error occurred
ObjectId string Address of object to which value belongs to

property is not set
OriginalObjectOrProper string Address of requested object or property
tyId
property is not set
PropertyName string Name of property
191
10 PropertyValue Service

property is not set
Value Value See Value [➙ 179]
IsArray bool Flag whether value is array or not
BackgroundColor ColorRepresenta Background color of the icon,which denotes alarm state.
tion[See➙ 180]
SubscriptionKey Int Subscription Key of OriginalObjectOrPropertyId
8.7 PropertyValue Service
8.7.1 Object<Type>
Attributes Attributes See Attributes [➙ 181]
Properties Array of <Type>
FunctionProperties Array of <Type>
8.7.2 PropertyDetails
AllowWildcards bool Boolean flag for BACnet date/time values; indicates if
the user can provide wildcards for any of the fields.
AllowDayOfWeek bool Boolean flag for BACnet date/time values; indicates if
the day-of-week field is supported.
BackgroundColor Color
BACnetDateTimeDetail uint Indcates which parts of the BACnet date/time value to
use:
1: date
2: time
3: date and time
BACnetDateTimeResolution uint When the time part of the BACnet date/time value is to
be used, what is the resolution of the seconds?
0: seconds
1: tenths of seconds
2: hundredths of seconds
Descriptor string
DisplayOffNormalOnly Boolean When true, the user interface should only display the
property when the value is off normal.
DisplayType integer Provides a ‘hint’ as to how the property value should be
displayed. See DisplayType [➙ 193]
DurationDisplayFormat unsigned If the property is of type “duration” this field will indicate
integer how the duration is to be displayed.
DurationValueUnits unsigned If the property is of type “duration” this field will indicate
integer the units of the raw property value (the raw value is an
unsigned integer that can represent anything from
milliseconds to days).
192
PropertyValue Service 10

ElementLabels Array of [Obsolete]
strings Will be non-null (and contain string(s)) when a
secondary text group has been assigned to the
property. Normally used when the property value
contains either an array of values or the value is a bit
string. Strings will be in sorted order of Array indexes.
Elements Array of Will be non-null when a secondary text group has been
Elements assigned to the property. Normally used when the
property value contains either an array of values or the
value is a bit string. Elements will be in sorted order of
indexes. [➙ 193]
MappedPropertId string Identifier of property to which a function property maps
to.
Max string Allowed maximum value; empty if maximum value of
datatype
Min string Allowed minimum value; empty if minimum value of
data type
Normal String The „normal“ value for the property. Used primarily to
determine when the property is in the „off-normal“ state.
Order int Order of the properties
PropertyAbsent Boolean True if the property is defined in the model but does not
exist in the actual object.
PropertyName string The property's name. Name is invariant and serves as
property identifier.
Resolution int If the property is floating point, this will be the desired
resolution for display of values.
TextTable string If the property is of type enumeration, boolean, or bit
string: this field will contain the name of the text table
used to represent the property value.
Type ApiDataType
UnitDescriptor string Localized representation of unit
UnitId uint Unit of value
Usage uint
Value Value
ScaledInformation ScaledFactor Scaled details of the property if applied. [➙ 193]
Representati
on
8.7.3 Elements
Id uint Id assigned to the
Descriptor string raw unit (index) of a property if configured
8.7.4 Scaled Property Details
Property Description
Factor scaling factor of a property if configured
Index raw unit (index) of a property if configured
Offset scaling offset of a property if configured
8.7.5 DisplayType
193
Change type Description

0 Reserved for 'use default display'
1 Property is of type “command priority array” (normally 16 values, where any or all of
those values can be “null”)
2 Property is of type “event timestamps” (an array of three timestamps)
8.8 Properties Service
8.8.1 PropertyNames
Properties Array of string Array of property names corresponding to the ObjectId
FunctionProperties Array of string Array of function property names corresponding to the
ObjectId
8.9 Command Service
8.9.1 PropertyCommand
Commands Array of See Command [➙ 194]
Command
PropertyId int
ErrorCode int -ErrorCode >0, an error occurred.
-ErrorCode = 0 , Success
SubscriptionKey int -subscription key of propertyId
8.9.2 Command
Descriptor string Localized command name
GroupNumber int If provided, commands with same GroupNumber belong
together
Parameters Array of See CommandParameter [➙ 195]s
CommandParame
ter
PropertyId string Address of property to which command belongs to
Id string Unique identifier of command
IsDefault bool True if this is the default command for the property.
Configuration int ValidationId of a propertyid
If Configuration :0 ->None is required
If Configuration :1 -> Only comment is required
If Configuration : 2-> Comment and Password(to re-
authenticate) are required.
194
Command Service 10
8.9.3 CommandParameters
AllowWildcards bool Boolean flag for BACnet date/time command
parameters; indicates if the user can provide wildcards
for any of the fields.
AllowDayOfWeek bool Boolean flag for BACnet date/time command
parameters; indicates if the day-of-week field is
supported.
Application int Integer indicating the application use of the parameter
Application: 0 -> Normal
Application: 1 -> The parameter is an index
BACnetDateTimeDetail uint Indcates which parts of the BACnet date/time value to
use:
1: date
2: time
3: date and time
BACnetDateTimeResolution uint When the time part of the BACnet date/time value is to
be used, what is the resolution of the seconds?
0: seconds
1: tenths of seconds
2: hundredths of seconds
DefaultValue string Default value of parameter
Descriptor string Localized command parameter name
DurationDisplayFormat uint How the duration is to be displayed. The following
abbreviations are used: d: days, h: hours, m: minutes,
s: seconds, ms: milliseconds
0: display raw value as-is
1: display is to be in units of d
2: display is to be in d + h
3: display is to be in d + h + m
4: display is to be in d + h + m + s
5: display is to be in d + h + m + s + ms
6: display is to be in h
7: display is to in h + m
8: display is to in h + m + s
9: display is to be in h + m + s + ms
10:display is to be in m
11: display is to be in m + s
12: display is to be in m + s + ms
13: display is to be in s
14: display is to be in s + ms
DurationValueUnits uint The content of the unsigned integer representing a
duration value:
1: number of days
2: number of hours
3: number of minutes
4: number of seconds
5: number of deciseconds
6: number of centiseconds
7: number of milliseconds
EnumerationTexts Array of See EnumItem [➙ 196]
EnumItem
IsPassword Bool Boolean indicating if the parameter represents a
password. This flag will only exist when the parameter
is of type “BasicString“
195
10 Command Service
Max string Maximum value if applicable

Min string Minimum value if applicable
Name string Unique identifier of command parameter within
command
Order int Order of parameters within command
Resolution int For floating point parameters, the resolution
UnitDescriptor string For parameters of type real / integer / unsigned integer,
if an engineering unit has been assigned (and can be
found) this field will contain the localized text.
8.9.4 EnumItem
Descriptor string Localized value
Value int Numeric value (unique within enumeration)
8.9.5 BatchExecution
PropertyId string Address of property to which command belongs to
ErrorCode int -ErrorCode >0, an error occurred.
-ErrorCode = 0 , Success
ErrorMessage string Error message containing reason for failure – comments
not passed or missing validation information in request.
8.9.6 CommandInputForExecution
Inherits ValidationData See[[➙ 187]
Name string Parameter name
Value int Value of the parameter
MultiLangComments string[] Validation Profile : String array of comments for validation
profile. Number of items in array should match the number
of languages installed in project.
Password string Validation Profile : Logged in user’s password for
reauthentication
SuperName string Validation Profile : Supervisor’s username
SuperPassword string Validation Profile : Supervisor’s password
8.9.7 BatchCommandExecution
CommandInputForEx CommandInputFor Command parameter required for execution of commands
ecution Execution[]
PropertyIds string[] String array of propertyids required for batch commanding
196
Trend Service 10
8.9.8 PropertyCommandInput
CommandInputForEx CommandInputFor Command parameter required for execution of commands
ecution Execution[]
PropertyId string Property Id for execution
CommandId string Command Id for execution
8.10 Trend Service
8.10.1 TrendCollector
CollectorObjectOrPro string Address of collector object
pertyId
PropertyIndex uint Index of Trended Property in the Trended Object.
Start index: 1
ObjectId string Object ID of trended object
PropertyName string Trended property name
TrendseriesId string Identifier of corresponding trend series
8.10.2 TrendBorder
From DateTime Minimum date/time from available values for requested
trend series ID
To DateTime Maximum date/time from available values for requested
trend series ID
8.10.3 TrendSeries
Id string ID of trend series
Series Array of Value See Value [➙ 179]
SeriesPropertyId string Trended object
8.10.4 TrendAggregateSeries
Id string ID of trend series
Series Array of See Value [➙197]
TrendAggregate
SeriesPropertyId string Trend Aggregate object
8.10.5 TrendAggregate
Statistical analysis will be done for the samples of Values. All details are below are
in reference of a Sample of Values
197
10 Trend Service

AvgX double mean x = ( Σ xi ) / n
AvgY double mean y = ( Σ yi ) / n
Count double Total numbers of values taken for calculatioin
FromValue double First value in the Sample
FromValueDescriptor string Localized value to display FromValue
FromTime DateTime Time of the first value in the sample
Min double Minimum value in the Sample
Max double Maximum Value in the Sample
StDevX double Standard Deviation X
StDevY double Standard Deviation Y
SumX double Sum of all X Values
SumXX double Sum of all X2
SumXY double Sum of all X*Y
SumY double Sum of all Y
SumYY double Sum of all Y2
ToTime DateTime Last value in the Sample
ToValueDescriptor double Localized value to display ToValue
ToValue double Time of the last value in the sample
VarX double Variance of X
VarY double Variance of Y
8.10.6 TrendViewDefinitionRepresentation
AxisX AxisDefinitionRepresentation [➙ 198]
AxisYLeft AxisDefinitionRepresentation [➙ 198]
AxisYRight AxisDefinitionRepresentation [➙ 198]
DescriptionTvd string
ObjectIdOfTvd string
IdTvd string
NameTvd string
NumberDisplayedSampl integer
esPerTrendSerie
RemoveOnlineTrendLog boolean
OfDeletedTrendSerie
TimeRange TimeRange [➙199]
TitleLeft string
TitleRight string
TitleTop string
TsdCollectionInfo TrendSeriesDefinitionCollectionRepresent
ation [➙200]
TvdType integer
TvCovType string
_links Array of Link [➙178]
8.10.7 AxisDefinitionRepresentation
198
Trend Service 10

AutoScale boolean
AxisType integer
ScaleMax number
ScaleMin number
ShowTitle boolean
ShowZeroLine boolean
Title string
8.10.8 TimeRange
ValidTimeRange integer
AbsoluteTimeRange AbsoluteTimeRange [➙200 ]
RelativeTimeRange RelativeTimeRange [➙ 200]
8.10.9 TrendSeriesDefinitionRepresentation
ReservedDateTime string
AccessDenied boolean
Alias string
ArchiveOn boolean
AxisAttachment string
ChartLineStyle string
ChartLineType string
Color string
DescriptionTlField string
DescriptionTlGms string
DescriptionTo string
DescriptionToProperty string
ObjectIdOfTrendLog string
ObjectIdOfTrendLogOnline string
ObjectIdOfTrendedObject string
Index integer
IsLineVisible boolean
LineWidth integer
ManagedType string
MaxTimeStamp string
MinTimeStamp string
ShowDataLabels boolean
ShowMarkers boolean
ShowQualityIcons boolean
TimeZoneServer string
Type string
UnitText string
ValueType string
199
10 Trend Service
8.10.10 RelativeTimeRange
AnchorMode integer
AnchorTime string
NumberOfTimeUnits integer
TimeUnit integer
8.10.11 AbsoluteTimeRange
From string
To string
8.10.12 TrendSeriesDefinitionCollectionRepresentation
Array of
TrendSeriesDefinitionReprese
TrendSeriesDefinitions ntation [➙178]
8.10.13 TrendViewDefinitionUpdateRepresentation
AxisX AxisDefinitionUpdateRepresentation [➙
198]
AxisYLeft AxisDefinitionUpdateRepresentation [➙
198]
AxisYRight AxisDefinitionUpdateRepresentation [➙
198]
CNSDescription string
Location string
TvdObjectId string
NumberDisplayedSampl integer
esPerTrendSerie
RemoveOnlineTrendLog boolean
OfDeletedTrendSerie
TimeRange TimeRange [➙199]
TitleLeft string
TitleRight string
TitleTop string
TsdCollectionInfo TrendSeriesDefinitionUpdateCollectionRe
presentation [➙200]
TvCovType string
8.10.14 TrendSeriesDefinitionUpdateRepresentation
ArchiveOn boolean
200
AxisAttachment string
ChartLineStyle string
ChartLineType string
Color string
TrendLogObjectId string
TrendLogOnlineObjectId string
ObjectPropertyId string
TrendedObjectId string
IsLineVisible boolean
LineWidth integer
ShowDataLabels boolean
ShowMarkers boolean
ShowQualityIcons boolean
Type string
Smoothing boolean
CustomDescription string
8.10.15 TrendSeriesDefinitionUpdateCollectionRepresentation
Array of
TrendSeriesDefinitionUpdateR
TrendSeriesDefinitions epresentation
8.10.16 AxisDefinitionUpdateRepresentation
AutoScale boolean
ScaleMax number
ScaleMin number
ShowTitle boolean
ShowZeroLine boolean
Title string
8.11 History Logs Service
8.11.1 LogTable
Name string Name of table which is unique and will be used for further
operations in subsequest requests
Descriptor string Display name of table
Description string Description of table
HasChildColumns bool Flag whether table supports child columns or not
HasConditionFilter bool Flag whether table supports Condition Filter or not
HasNameFilter bool Flag whether table supports Name Filter or not
201
HasTimeFilter bool Flag whether table supports Time Filter or not

HasTimeFilterDefined bool Flag whether table supports Time Filter defined by source
BySource or not. Used in case of trend data retrieval.
If set to TRUE then Time Filter provided in the request will
be ignored and instead Time Filter defined by source will
be considered to filter data
HasAndOperatorOnly bool Flag whether table only supports And-operator or not
HasMaxAge bool Flag whether table supports Max Age or not
HasSingleNameFilter bool Flag whether table supports Single Name Filter or not
SupportedTypes Array of string This is array of Managed Types which are supported by
the table
8.11.2 LogColumn
Name string Name of column which is unique and will be used for
further operations in subsequest requests
Descriptor string Display name of column
DataType string Data type of the data which column supports
ErrorSupport bool Flag whether column supports display of error data (e.g.,
#COM, #ERR) or not
IsArray bool Flag whether column contains a data array or not
IsDefault bool Flag whether column is displayed by default or not. This
will be useful while developing a user interface to create
tables.
IsHidden bool Flag whether column is hidden or not
IsSortable bool Flag whether column is sortable or not
IsEnum bool Flag whether column contains enumerated data or not
IsFilterable bool Flag whether data from the column can be filtered using
condition filter or not
8.11.3 LogConditionFilter
Operators Array of strings Supported condition filter operators for column
ErrorInfo Array of strings Localized list of error information. It describes specific
error cases.
8.11.4 LogEnumValues
EnumValues Array of strings Supported enum values for column
error cases.
8.11.5 LogSortInfo
Name string Name of the Column which is to be sorted
Required
202
SortType LogSortType See LogSortType [➙ 203]

Required
8.11.5.1 LogSortType
LogSortType must have one of the following values.
LogSortType Description
Ascending Sorts data in ascending order
Descending Sorts data in descending order
8.11.6 LogColumnList
Parent Array of string Column list for parent table
Child Array of string Column list for child table
8.11.7 LogTableData
TableName string Name of the table
Page int Current page number
Size int Number of records per page
Result Array of objects At runtime each object is composed using selected
columns to retrieve data and there value.
SnapshotId string Snapshot id of the snapshot created
Total long Total number of records found for the requested
configuration
error cases.
_links Array of Link See [➙178]
8.11.8 LogDiscardedSnapshot
TableName string Name of the table
SnapshotId string Snapshot Id which is discarded
IsSnapshotDiscarded bool Status of the discard request. If TRUE then discard is
successful.
8.11.9 LogConditionFilterValidation
ErrorPosition int In case of invalid string, Error position in the invalid string
ErrorMessageDescrip string In case of invalid string, Localized Error message if string
tor is not valid as per the standards
TodoMessageDescri string In case of invalid string, Localized to-do message using
ptor which client can correct the Condition filter string if it is
incorrect
203
10 Language Service
IsValidConditionFilter bool Status of Condition filter string validation. If TRUE then

string as per the standards.
8.11.10 LogChildData
Page int Current page number
Size int Number of records per page
Total long Total number of records found for the requested
configuration
Result Array of objects At runtime each object is composed using selected
columns to retrieve data and there value.
error cases.
_links Array of Link See [➙178]
8.12 Language Service
8.12.1 Language
Descriptor string Full localized language name
Code string IETF language tag according to RFC5646 [5] [➙ 18]
8.13 Tables Service
8.13.1 SubDisciplines
DisciplineId Uint Id of the Discipline
DisciplineDescriptor string Descriptor of the Discipline
SubDisciplines Array of Array of SubDisciplines in SubGroups form for which filter
SubGroups is applied. See [➙ 55]
8.13.2 SubObjectTypes
ObjectTypeId Uint Id of the ObjectType
ObjectTypeDescriptor string Descriptor of the ObjectType
SubObjectTypes Array of Array of SubObjectTypes in SubGroups form for which
SubGroups filter is applied. See [➙ 55]
8.13.3 TextTableEntry
Value uint Numeric value of the entry
204
Systems Service 10
Text string Text of the entry.

Color uint? The color assigned to the entry; this field is optional
and if it does not exist, the property will not be included
in the JSON representation.
Subtext Array of TextTableEntry Can be nullCollection of subtext.
8.13.4 LangTextTableEntry
Value uint Numeric value of the entry
Color uint? The color assigned to the entry; this field is optional and if
it does not exist, the property will not be included in the
JSON representation.
LangText String[] Array of strings, one for each installed language.
8.13.5 TextTableEntry Color Calculation

the JSON string if a color has been assigned to that entry. If a color property is
provided, it is in the form of an unsigned 4 byte integer containing the following
information:
Channel Calculation
Alpha ( Color >> 24 ) & 0xFF
Red ( Color >> 16 ) & 0xFF
Green ( Color >> 8 ) & 0xFF
Blue Color & 0xFF
8.14 Systems Service
8.14.1 System Languages

Descriptor string Full localized language name
Code string IETF language tag according to RFC5646 [5] [➙ 18]
ArrayIndex Int Index of the installed language
8.14.2 Systems
Systems SystemsInformatio Array of systems information. See[➙205 ]
n
Languages SystemsLanguage Array of systems languages See[➙205 ]
s
IsDistributed bool System is in distribution environment or not
IdLocal uint Id of system that is currently serving requests
8.14.3 SystemsInformation
205
10

Name string System name
Id uint System id
IsOnline bool Obsolete: If system is available or not.
MP4.0 onward: This field is not available in notification
8.14.4 ServicesSubscriptionsRepresentation
SystemId int System id
Serviceid int Service id of the respective system id
ErrorCode int If that particular subscription for the respective system
AND service is successful or not. 1 for error, 0 for
success.
8.14.5 ServicesRequestSubscriptionsRepresentation
SystemId int System id
Ids List<int> List of Service ids of the respective system which are to
be subscribed
8.14.6 ServicesNotificationRepresentation
SystemId uint System id
Serviceid int Service id of the respective system id
Description string Name/description of the particular service for which
notification is being received. NOTE: this will only be non-
null when the service is connected.
IsConnected bool The current status of the service
8.15 Products Service
8.15.1 ProductInfo
ProductNameShort string The name of the product; not localizable
e.g. “Desigo CC” or “Cerberus DMS”
ProductName string The long name of the product;
not localizable
e.g. “Desigo CC ™”
VendorName string The name of the vendor of the product;
not localizable
e.g. “Siemens Switzerland Ltd.”
or “Daikin Ltd.”
ProductCopyRights string Any statement;
not localizable:
© Siemens Switzerland Ltd, 2016
ProductVersion string Desigo CC project version
206
Files Service 10
SupportLink String Technical support URL

Links Array of Links Direct URLs to access
- Product picture wide
- Product picture tall
8.16 Files Service
8.16.1 BasicFiles (Enum type)

Contain different file types.

ProductPictures int a file type
8.16.2 File Details.

FileName string contains file name
_links Link See Link [➙ 178]
8.17 Graphics Service
8.17.1 GraphicalItem
Objects that are graphical in nature will be represented by this object type.
Context String The designation of the object that ‘owns’ the graphical item.
ObjectId String The id of the object within DCC. Note that this id must include the system
information to distinguish the object in a multi-system configuration.
ManagedType String The DCC managed type of the object.
DisplayName String A string that can be displayed to the user.
8.18 Scheduler Service
8.18.1 Calendar
ScheduleCalendarType integer
CalendarEntries Array of CalendarEntry[-
>207 ]
AppliedSchedules Array of string
ContainerObjectId string
ObjectId string
Device integer
8.18.2 CalendarEntry
207
StartDate CalendarDate [->208]

EndDate CalendarDate [->208]
Restrictions CalendarDate [->208]
Mode integer
8.18.3 CalendarDate
Date string
IsAny boolean
Days Array of integer
Months Array of integer
DaysInMonth Array of integer
LastDayInMonth boolean
Years Array of integer
Weeks Array of integer
LastWeekInMonth boolean
8.18.4 WeeklySchedule
DeviceId string
Name string
Setup ScheduleSetup [->208]
Outputs Array of string
ScheduleType string
Schedules Array of Schedule [->208]
Array of
ReferencedOutputDetails [-
ReferencedOutputDetails >209]
Array of ScheduleException
Exceptions [->209]
8.18.5 ScheduleSetup
DefaultValue string
StartDate CalendarDate [->208]
EndDate CalendarDate [->208]
Priority integer
DataType string
ScheduleMin number
ScheduleMax number
TextGroupId string
Unit integer
208
Objects Service 10
8.18.6 Schedule
Day String
Array of TimeTrigger [-
Entries >209]
OutputValuesActive Array of string
OutputValuesInActive Array of string
8.18.7 ReferencedOutputDetails
Output string
TextGroupId string
Unit integer
8.18.8 ScheduleException
Priority integer
Mode integer
CalendarException CalendarException [->209]
CalendarEntry CalendarEntry[->207 ]
ExceptionTimes Array of TimeTrigger [->209]
ExceptionValuesActive Array of string
ExceptionValuesInActive Array of string
8.18.9 TimeTrigger
Time string
Value number
8.18.10 CalendarException
CalendarObjectId string
Array of CalendarEntry [-
CalendarEntries >207 ]
CalendarName string
8.19 Objects Service
8.19.1 Object
Objects will be represented by this type.

Designation string Full node name under which child is supposed to be added
209
10 Objects Service
NameChildNode string Name of the newly created system browser node.

ObjectType string The type of the object to create.
Descriptor Descript Display name of the browser node. Multilingual text
or
8.19.2 Descriptor
Priority based text value definition.

CommonText string Text to be initiated for all the languages
Prio 1: If value is assigend to CommonText then attribute
MultiLangText will not be considered.
To assign value in MultiLangText set Descriptor to null.
To be created node display name. Common descriptor will be applied
in all languages.
MultiLangText string[] Language specific text for object
Prio 2: MultiLangText has lower priority to Descriptor. It will not be
considered if any value is assigned to attribute Descriptor
Set Descriptor to null to assign MultiLangText. Language specific text
will be updated for the node.
8.19.3 ObjectModel
Objects type will be represented by this type.

Designation string Full node name
Description string Description of the object type.
IsGenericDelete bool Generic delete configuration for the object
Allowed
ChildObjects ChildObjectModel List of available child types.
Representation[]
8.19.1 ChildObjectModel
Objects type will be represented by this type.

Description string Description of the object type.
IsGenericDelete bool Generic delete configuration for the object
Allowed
IsGenericCreate bool Generic create configuration for the object
Allowed
MaxChild uint Max number of Childs allowed for particular type
ExistingChildCou int Count of the Childs already added under the parent for current
nt object types.
Difference of ExistingChildCount and MaxChild can be used to
identify that how many more childs can be added.
210
Related Items Service 10
8.19.2 ServiceTextRepresentation
Information Text and Memo information will be represented by this type.
InformationText string Information Text saved for an object in loggedin user's
language.
Memo string Memo content for an object.
8.19.3 ObjectInfo
Response type for Information Text and Memo content.
ObjectId string Object Id.
ServiceText ServiceTextRepres Information text and Memo details for an object.
entation [->211] In case of failed request, this field is missing in Json
response.
8.19.4 ServiceTextMemoRepresentation
Request type for accepting Memo text.
Memo string Memo content for an object
8.20 Related Items Service
8.20.1 RelatedItemResult
This is the top level object returned from the “get related items” API call. It contains
a single property at this time.

RelatedResults ObjectRelatedItem[] An array: each element corresponds to an object id
passed into the API call, where each element contains
information about the related items for that object.
8.20.2 ObjectRelatedItem
This object contains the related item information for each object id passed to the
“get related items” API.

ErrorCode integer 0: No error
1: Error
ObjectId string The object id passed into the API.
RelatedItems RelatedItem[] A collection of the related items for the object; this collection can
be empty.
211
8.20.3 RelatedItem
As described elsewhere, two objects can be associated with each other – for ex-
ample, an object in a report is ‘related to’ that report. This table defines the infor-
mation that returned for each item that the object is related to.

GroupDescriptor string If provided and non-blank, can be used to group items.
GroupOrder ushort? If a group descriptor is provided, this property can be used
to sort the items within a group
ItemDescriptor string If provided and non-blank, should be used for the item's
display name
Mode ushort The Mode in which the item should be visible:
0: All
1: Operation
2: Engineering
Nodes BrowserNode[] The array will contain one BrowserNode [➙ 77] for each
reference in a hierarchy to the object.
Parameter string An optional parameter added by a dynamic link provider.
Reference string If the related item is an external entity, this property will
contain a URL – where the URL is of the form {key-
word}{reference}. The list of valid keywords include:
- file:// (reference is to a file)
- file:/// (alternate form of file://)
- http:// (HTTP location)
- https:// (Secured HTTP location)
- ftp:// (file transfer location)
SourceType ushort The source of the link:
0: NotSpecified
1: System
2: User
3: Dynamic
8.21 Access rights Service
8.21.1 AccessRightsRepresentation
Application Array of Collection of application rights assigned to logged in user
Rights ApplicationRightR
epresentation [-
>Error!
Bookmark not
defined. ]
8.21.2 ApplicationRightRepresentation
Name string
Name of AccessRight in loggedin user's current language
Id uint Unique identifier assigned to access right
Operations Array of Operations applicable within current access right
OperationsRepres
entation [->212]
8.21.3 UserRoleRepresentation
212
RolesMappi List of type Collection of roles assigned to logged in user

ng RoleInfo
8.21.4 RoleInfo
RoleName string
Name of Role in loggedin user's current language
RoleId uint Unique identifier assigned to role
RoleDescrip string Decription of role functionality
tion
RoleState bool Active or not.
8.21.5 OperationsRepresentation
Name string Name of AccessRight in loggedin user's current language
Id uint Unique identifier assigned to operation within access right
8.22 Operating Procedures Service
8.22.1 Operating Procedure

AlertCount uint
AlertSource string
AlertTime datetime
Id string Id of Operating procedure
InTreatmen string User performing the treatment
By
IsClosed boolean
ResetSteps uint
Sequential boolean Steps need to be sequential
Steps Array of Operating Steps available in Operating procedure
Procedure Step [-
>213]
Subsequent uint
TemplateNa string Name of Operating procedure template
me
8.22.2 Operating Procedure Step

Attachments string [Property can be updated]
Attributes string
AutomaticDP
E string
Configuration string
ErrorText string [Property can be updated]
FixedLink string
213
10 Operating Procedures Service
HasConfirmed [Property can be updated]

Execution bool
IsCompleted bool [Property can be updated]
ManagedType string Internal managed type of Operating procedure step
Notes string Notes configured during Operating procedure step creation
[Property can be updated]
Operator string Operator name
RuntimeStatu [Property can be updated]
s string
[Property can be updated]
Status of Operating procedure step
Valid values are:
Status string Unknown, PartiallyFailed, Failed, Succesfull
[Required]
StepId string Id of Operating procedure step
StepName string Name of Operating procedure step
8.22.3 Operating Procedure Subscription Representation

AlertCount uint
AlertSource string
AlertTime datetime
InTreatmen string User performing the treatment
By
IsClosed boolean
ResetSteps uint
Sequential boolean Steps need to be sequential
Steps Array of Operating Steps available in Operating procedure
Procedure Step [-
>213]
Subsequent uint
TemplateNa string Name of Operating procedure template
me
Subscription string Subscription key for which Notification is recieved
Key
8.22.4 Operating Procedure Subscription Key Representation

Key string Subscription Key
ErrorCode Int Success = 0, Failure= -1
RequestId string Unique Id passed by client during subscription request
RequestFor string Hub method where notification will arrive
8.22.5 UnsubscriptionStatus
214
Diagnostics Service 10
Key string Subscription Key

ErrorCode Int Success = 0, Failure= -1
8.23 Diagnostics Service
8.23.1 DiagnosticsRepresentation
ServerDate DateTime Server's UTC Datetime
Time
ClientDateTi DateTime [optional] Client's UTC Datetime passed as input
me
NTPt1t0 string [optional] Total milliseconds difference between server time and
client time. Server’s datetime – Client’s datetime
NOTE: This value would be double value and could be negative .
8.24 Licenses Service
8.24.1 LicenseMode
LicenseMod string The mode name of License Service
eName
LicenseMod uint License mode value
eValue
ExpirationTi uint ExpirationTime of relative mode espression in second
me
8.24.2 LicenseOptions
Id string The License option Id
Required Int Required property as int
Remainin Int Remaining property as int
g
Descript string Description of licensing option
ion
Availabl int Available property as int
e
215
10 Naming
9 Concepts
9.1 Naming
The following is an overview about data hierarchies and naming conventions in the
system.
Name: The name is a fixed (untranslatable) literal of a node. In order to uniquely

identify nodes deeper in the hierarchy, nodes can be concatenated. Further, to
ensure uniqueness sibling nodes can never have the same name. Concatenated
Names are called Designation.
<Designation> ::= <SystemName>.<ViewName>:{<TreeNodeName>}
Example of Designation (node HW [Hardware]):
Sys1.View1:Apps.Scds.Bac.Clds.HW
Descriptor: The descriptor is a multilingual text of a node. Although nodes deeper
in the hierarchy can be concatenated, they DO NOT have to be unique!
Concatenated Descriptors are called Location.
<Location> ::=
<SystemDescriptor>.<ViewDescriptor>:{<TreeNodeDescriptor>}
Example of Location (node HW [Hardware]):
London Airport.Application View:Applications.Schedules.BACnet
Schedules.Calendar.Hardware
9.2 Extensibility
In order to deploy its own Web Service Interface extension one can create and
deploy its own DLL. The DLL has to meet the following prerequisites:
- DLL needs to have literal “WsiExtension” as part of its name

- DLL needs to be deployed into the GMSMainProject\bin folder
- Class Attribute [Authorize]: It is an optional attribute and that is required if GMS
user authorization is required.
- Class Attribute [ControllerLicense(<Put License Name>)]: It is a mandatory
attribute. Provide here a valid GMS License information against which
extension module feature should be available.
216
Extensibility 10
- For 3rd party license key “sbt_gms_opt_ws_3rd” can be used.

- If WSI extention wants license verification feature to be implemented then
extention team should inform WSI team to incorporate License key alsong with
it’s Service ApiController name.
Each service comes as a class named with the service-name and a “Controller”-
suffix. It derives from the ApiController base class. The following service could be
reached at http://[Your Host]/api/extensions/ :
Example with controller mapping:

namespace Siemens.Gms.WsiExtensionTest.Controller
{
[Authorize]
[ControllerLicense(ControllerNames.ServiceApiController, Licensin-
gOptions.sbt_gms_opt_ws_base)]
[RoutePrefix("api/MyService")]
public class ExtensionsApiController : ControllerBase
{
private const string TraceChannel = "MyService";
public MyServiceController()
: base(TraceChannel){}
public MyServiceController(IStaticManager staticManager)

: base(staticManager, TraceChannel){ }
}
public HttpResponseMessage Get()

{
return Request.CreateResponse(HttpStatusCode.OK);
}
}
}
Example without controller mapping:

namespace Siemens.Gms.WsiExtensionTest.Controller
{
[Authorize]
[ControllerLicense(<Put License Name>)]
[RoutePrefix("api/MyService")]
public class MyServiceController : ControllerBase
{
private const string TraceChannel = " MyService";
public MyServiceController()
: base(TraceChannel){}
public MyServiceController(IStaticManager staticManager)

: base(staticManager, TraceChannel){ }
}
public HttpResponseMessage Get()

{
}
}
}
For using push-notifications one can take advantage of the existing push
infrastructure.
217
10 Support for Web Service Interface extensions
[System.Web.Http.Authorize]
[ControllerLicense("sbt_gms_opt_ws_base")]
[RoutePrefix("api/sr/SubExtensions")]
public class SubExtensionsController : ControllerBase
{
#region SignalR Hub
private const string TraceChannel = "SubExtensions";
readonly Lazy<IHubContext> _hub = new Lazy<IHubContext>(() =>
GlobalHost.ConnectionManager.GetHubContext<ExtensionsHub>());
protected IHubContext Hub { get { return _hub.Value; } }
#endregion
public SubExtensionsController(): base(TraceChannel){}
public SubExtensionsController(IStaticManager staticManager)

: base(staticManager, TraceChannel)
public HttpResponseMessage Post(string id)

{
//send message to all clients
Hub.Clients.All.notifyMessage(id);
}
}
For details on how push notifications work check out SignalR documentation [19].
9.3 Support for Web Service Interface extensions
9.3.1 Initialization support

- WSI now provides support for an extension module to initialize.
namespace Siemens.Gms.WsiExtensionTest.Init
{
public class ServiceInitialization : ExtensionBase
{
public IDpProxy DpProxy { get; private set; }
public override void CleanUp()
{
}
public override void Initialize()
{
WsiTracingManager.Instance.TraceDebug("Client1");
DpProxy = new DpProxy(StaticManager.OperationContext,
GlobalDefinitions.ClientName, null, GlobalDefinitions.ClientName);
var dpConn = DpProxy.Connect(null, null);
dpConn.WaitCompleted();
}
}
}
218
Support for Browser Caching 10
9.3.2 Caching support
WSI now provides support for an extension module to cache.

namespace Siemens.Gms.WsiExtensionTest.Init
{
public class CacheInitialization : InitializeCacheExtensionBase
{
public override void Initialize()
{
}
}
}
9.4 Support for Browser Caching

WSI now support browser caching support via Cache-Control and Etag headers.
Browser handles caching based on response headers thus client application does
not need to make any explicit change to take advantage of caching.
Following services now returns Cache-Control headers in response.

- Files service [➙144 ]
- Graphics service [➙145]
- Image service [➙ 124]
- Properties service [➙84 ]
- Tables service [➙125 ]
Following services returns Etag headers in response.

- Graphics service [➙145]
WSI also returns Access-Control-Max-Age for preflight requests allowing browsers

to cache preflight response.
In default configuration, Caching max time is set to 30 minutes and Vary header is
set with value Authorization to refresh cache based on user login session.
Caching configuration can be modified in config file [➙Error! Bookmark not
defined.] .
Developer Resources:
- Cache-Control : https://developer.mozilla.org/en-
US/docs/Web/HTTP/Headers/Cache-Control
- Access-Control-Max-Age : https://developer.mozilla.org/en-
US/docs/Web/HTTP/Headers/Access-Control-Max-Age
- Etag : https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag
- Vary : https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary
219
10 Support for CORS
NOTE:
Browser supports only GET response to be cached. POST ,PUT and DELETE
response is not cached by browsers.
In case of HTTPS connection , Chrome supports caching only on valid certificate.
9.5 Support for CORS

WSI provides support to apply CORS policy for list of known domains.
In default configuration , CORS policy allows all domains.
White list of domains can be provided in config file to modify default configuration
and apply CORS policy for specific domains. See [➙Error! Bookmark not
defined. ].
220
Error Response 10
10 Appendix
10.1 Error Response

To identify errors in the responses WSI follows standards so that error location and
service can be easily identitied. Any error response shall contain below information:

Id Int Error codes. It will be return code from service specific
range mentioned in Error Codes [221]
Error String Hint text to identify error and service. For details refer
Errors [222]
Details String One liner information for short description of error
10.1.1 Errors Codes

S.No. Service Max Min
1 Authentication/ Token 2400000 2400099
2 Licensing 2400100 2400199
3 General 2400200 2400299
4 Command 2400300 2400399
5 commandSubscriptions 2400400 2400499
6 EventCounters 2400500 2400599
7 EventCountersSubscriptions 2400600 2400699
8 EventsCommands 2400700 2400799
9 Events 2400800 2400899
10 EventsSubscriptions 2400900 2400999
11 Images 2401000 2401099
12 Properties 2401100 2401199
13 PropertyValues 2401200 2401299
14 SystemBrowser 2401300 2401399
15 SystemBrowserSubscriptions 2401400 2401499
16 Tables 2401500 2401599
17 TrendSeries 2401600 2401699
18 TrendSeriesInfo 2401700 2401799
19 Values 2401800 2401899
20 ValuesSubscriptions 2401900 2401999
21 HistoryLog 2402000 2402099
22 Files 2402100 2402199
23 Graphics 2402200 2402300
24 EventCategorySounds 2402400 2402499
25 EventCategorySoundsSubscriptions 2402301 2402399
26 SystemsSubscriptions 2402500 2402599
27 Schedule 2402600 2402699
28 Licenses 2403200 2403299
221
10 Error Response
10.1.2 Errors
S.No. Resource Path Error Id Details Remarks

1 1 POST invalid_grant 2400000 The user name or password is incor- Details not displayed because of some design constraint
/token rect. of OAuthGrantResourceOwnerCredentialsContext
2 inva- 2400001 The SSO Token is incorrect or Expired Provided SSO Token is either expired or invalid, contin-
lid_token_grant ue with new SSO Token.
3 pass- 2400003 Credentials of account are expired Credentials of account are expired and should be
word_expired and need to get changed first. changed from DesigoCC first.
4 li- 2400100 A needed license is missing or expired Required license is consumed or not available
cense_not_avail
able
5 2 li- 2400102 A required license option is missing This resource requires a license option which is not
cense_option_no available.
t_available
6 PUT invalid_details 2400002 The user name or password is incor- Provided user details are invalid or missing.
/users/password rect or missing.
server_error 240009 Server is not able to process the Problem with reading from the server.
8 request
pass- 240000 The password does not meet policy The password does not meet policy requirements.
word_not_comp 4 requirements.
atible
7 4 GET cmd_missing_in 2400300 propertyIds are missing propertyIds is blank or Null
/commands/:propertyId put
8 5 cmd_invalid_inp 2400301 Unknown clientType Invalid Client Type
ut
9 5 cmd_failure 2400399 Couldn't retrieve a list of commands Exception occurred
10 6 GET cmd_missing_in 2400300 propertyIds are missing propertyIds is blank or Null

/commands put
11 7 cmd_invalid_inp 2400301 Unknown clientType Invalid Client Type
ut
12 8 cmd_failure 2400399 Couldn't retrieve a list of commands Exception occurred
222 13 9 POST cmd_missing_in 2400300 propertyIds are missing propertyIds is blank or Null
Siemens /commands/:propertyId/:comman put Restricted A6V10470112_en_b_60
Error Response 10

14 1 dId cmd_invalid_inp 2400301 propertyId is invalid Invalid Property Id - DpIdentifier instantiation
0 ut
15 1 cmd_execution_f 2400398 command execution failed! Command execution could not succeed
1 ailed
16 1 cmd_failure 2400399 Command execution failed Command execution could not succeed
2
17 1 POST cmd_missing_in 2400300 propertyIds are missing propertyIds is blank or Null
3 /commands/:commandId put
18 1 cmd_execution_f 2400398 command execution failed! Command execution could not succeed
4 ailed
19 1 cmd_failure 2400399 Command could not execute Exception occurred

5
20 1 POST cmd- 2400400 Specify a valid propertyIdList
6 /sr/commandssubscriptions/:conn sub_invalid_inpu
ectionId t
21 1 or cmd- 2400401 connectionId is missing
7 POST sub_missing_inp
/sr/commandssubscriptions ut
/channelize/:requestId/:connectio
22 1 nId cmd- 2400402 Error occurred while creating com-
8 sub_subscription mand subscription
_failed --> Command subscription failed
23 1 cmdsub_failure 2400499 Could not retrive command(s) Exception occurred
9
24 2 DELETE cmd- 2400399 connectionId or subscriptionkey not subscriptionkey or connectionId null or whitespace
0 /sr/commandssubscriptions/:conn sub_missing_inp available
ectionId ut
25 2 cmd- 2400498 Command unsubscription falied for
1 sub_unsubscribe commands with subscriptionkey
_failed
26 2 cmdsub_failure 2400499 Command unsubscription falied for Exception occurred
2 commands with connectionId
27 2 GET evtcnt_failure 2400599 Could not retrive Event Counters

3 /eventcounters/:categoryId
28 2 POST ev- 2400600 connectionId is missing
4 /sr/eventcounterssubscriptions/:c tcntsub_missing
onnectionId _input
29 2 or evtcntsub_failure 2400699 Event Counter subscription unsuc- Exception occurred
5 POST cessful for connection-id
/sr/eventcounterssubscriptions
nId
223
10 Error Response

30 2 DELETE ev- 2400600 connectionId is missing
6 /sr/eventcounterssubscriptions/:c tcntsub_missing
onnectionId _input
31 2 evtcntsub_failure 2400699 Event-counters unsubscription unsuc- Exception occurred
7 cessful for connection-id
32 2 POST ev- 2400700 Unknown command

8 /eventscommands/:eventId/:com tcmd_unknown_
mandId command
33 ev- 2400794 Missing supervisor credentials for
tcmd_missing_s validation input
upervisor
34 ev- 2400795 Invalid supervisor’s credential passed
tcmd_invalid_su
pervisor
35 ev- 2400796 Mandatory comments not passed in
tcmd_invalid_co case validation profile is applicable
mment
36 ev- 2400797 Invalid user credentials are passed in
tcmd_invalid_pa case validation profile is applicable
ssword
37 2 ev- 2400798 Command execution failed
9 tcmd_execution_
failure
38 3 evtcmd_failed 2400799 Command execution failed
0
39 3 GET evt_failure 2400899 Could not retrieve Events List Exception occurred
1 /events
40 3 POST ev- 2400900 connectionId is missing
2 /sr/eventssubscriptions/:connectio tsub_missing_in
nId put
41 3 or evtsub_failure 2400999 Event Subscription unsuccessful for Exception occurred
3 POST connection-id
/sr/eventssubscriptions
nId
42 3 PUT ev- 2400900 connectionId is missing
4 /sr/eventssubscriptions/:connectio tsub_missing_in
nId put
43 3 evtcntsub_failure 2400699 Error occurred while changing an Exception occurred
5 event subscription
44 3 DELETE eventsub_missin 2400900 connectionId is missing
6 /sr/eventssubscriptions/:connectio g_input
nId
224
Error Response 10

45 3 GET img_format_unk 2401000 Image format unknown!, format
7 /images/:imageId nown
46 3 img_invalid_path 2401001 Image path not allowed!

8
47 3 img_failure 2401099 Could not retrive image Exception occurred
9
48 4 GET prop_missing_in 2401100 ObjectOrPropertyId is missing
0 /properties/:objectOrPropertyId put
49 4 prop_invalid_inp 2401101 Invalid Request TyperequestType
1 ut
50 4 prop_invalid_inp 2401101 Specify a valid Object OR Property Id
2 ut
51 4 prop_failure 2401199 Failed to read properties for ObjectOr- Exception occurred
3 PropertyId
52 4 POST prop_missing_in 2401100 Object OR Property Ids are missing!

4 /properties put
53 4 prop_invalid_inp 2401101 Invalid Request Type
5 ut
54 4 prop_failure 2401199 Failed to read properties Exception occurred
6
55 4 GET propVal_missing 2401200 Object OR Property Ids are missing!
7 /propertyvalues/:objectOrProperty _input
Id
56 4 propVal_invalid_i 2401201 Specify a valid Object OR Property Id
8 nput
57 4 propVal_failure 2401299 Failed to get values for properties Exception occurred

9
58 5 GET sysbrow_failure 2401399 Failed to retriev Views Exception occurred
0 /systembrowser
59 5 GET sys- 2401300 View OR Node details are missing

1 /systembrowser/:systemId/:viewId brow_missing_in while retrieving Browser Objects
/:node put
60 5 sysbrow_failure 2401399 Failed to retrive Nodes Exception occurred
2 GET
/systembrowser/:systemId/:viewId
61 5 POST sys- 2401300 Object Ids are missing
3 /systembrowser/:systemId/:viewId brow_missing_in
put
62 5 sysbrow_failure 2401399 Failed to search multiple object Exception occurred
4
225
10 Error Response

63 5 POST sys- 2401400 connectionId is missing
5 /sr/SystemBrowserSubscriptions/: browsub_missin
connectionId g_input
64 5 or sys- 2401499 SystemBrowser Subscribtion failed Exception occurred
6 POST browsub_failure
/sr/SystemBrowserSubscriptions
nId
65 5 DELETE sys- 2401400 connectionId is missing
7 /sr/SystemBrowserSubscriptions/: browsub_missin
connectionId g_input
66 5 sys- 2401499 Failed to unsubscribe Cns Exception occurred
8 browsub_failure
67 5 GET tbl_missing_inpu 2401500 tableId is missing
9 /tables/:tableId t
68 6 tbl_unknown_tab 2401500 Unknown table
0 leid
69 6 tbl_failure 2401599 Failed to Get Tables using TableId Exception occurred
1
70 6 GET tbl_missing_inpu 2401500 tableId is missing
2 /tables/:tableId/:tableEntryId t
71 6 tbl_failure 2401599 Failed to get table Exception occurred

3
72 6 tbl_unknown_id 2401501 Unknown id
4
73 6 tbl_unknown_tab 2401502 Unknown table
5 leid
74 6 GET tbl_missing_inpu 2401500 subtableId is missing!
6 /tables/:tableId/subtables/:subtabl t
75 6 eId tbl_unknown_su 2401503 Unknown subtable
7 btable
76 6 tbl_failure 2401599 Failed to Get Sub Tables Exception occurred

8
77 6 GET tbl_missing_inpu 2401500 tableId is missing!

9 /tables/:tableId/subgroups t
78 7 tbl_unknown_su 2401504 Unknown subGroups
0 bgroup
79 7 tbl_failure 2401599 Failed to Get Sub Groups Exception occurred

1
226
Error Response 10

80 7 GET tnd_missing_inp 2401600 TrendSeriesId is missing
2 /trendseries/:trendseriesId/border ut
81 7s tnd_failure 2401699 Could not retrive Borders Exception occurred
3
82 7 GET tnd_missing_inp 2401600 one or some of the input fields are
4 /trendseries/:trendseriesId ut missing
83 7 tnd_notfound 2401601 Timeseries data not availble
5
84 7 tnd_failure 2401699 Could not retrive Timeseries data Exception occurred
6
85 7 GET tndinfo_notfound 2401700 Get All TrendSeriesInfo Trendseries
7 /trendseriesinfo/:systemId not available
86 7 GET tndinfo_notfound 2401702 Trendseriese not avaialble.
8 /trendseriesinfo/:objectOrProperty
Id
87 7 tndinfo_failure 2401799 Could not retrive Trendseriess Infor- Exception occurred
9 mation
88 GET tnd_missing_inp 2401600 one or some of the input fields are
/trendseriesinfo/tvd/:tvdDpIdNam ut missing
89 e tndinfo_failure 2401799 Could not retrive Trendseriess Infor- Not a valid objectid or Exception occurred
mation
90 8 GET val_missing_inp 2401800 Object OR Property Ids are missing!
0 /values/:objectOrPropertyId ut
91 8 val_failure 2401899 Could not retrive Value Exception occurred
1
92 8 POST val_missing_inp 2401800 objectOrPropertyIds not provided
2 /values ut
93 8 val_failure 2401899 Could not retrive Value Exception occurred
3
94 8 POST valsub_missing_i 2401900 connectionId or objectOrPropertyIds
4 /sr/valuessubscriptions/:connectio nput not available
nId
95 8 or valsub_subscript 2401901 Subscription unsuccessful
5 POST ion_unseccessfu
/sr/valuessubscriptions l
96 8 nId valsub_failure 2401999 Could not subscribe Exception occurred
6
97 8 DELETE valsub_missing_i 2401900 connectionId or subscriptionkey not
7 /sr/valuessubscriptions/:connectio nput available
nId
98 8 valsub_notfound 2401902 subscription not available for provided unsubscription not done for any of the input
8 subscription key
99 8 valsub_failure 2401999 Could not remove subscription Exception occurred

9
227
10 Error Response

100 9 GET htlog_failure 2402099 Could not retrieve list of available Exception occurred
0 /historylogs/:systemId Tables.
101 9 GET htlog_missing_in 2402000 Table name is missing while retrieving tableName is blank or Null
1 /historylogs/:systemId/:tableName put column names for the table.
102 9 htlog_failure 2402099 Could not retrieve list of column details Exception occurred
2 for Table
3 /historylogs/:systemId/:tableName put condition filter operators for the col-
/operators/:columnName umn.
104 9 htlog_missing_in 2402000 Column name is missing while retriev- columnName is blank or Null
4 put ing condition filter operators for the
Table
105 9 htlog_failure 2402099 Could not retrieve Condition filter Exception occurred
5 operators for Column
6 /historylogs/:systemId/:tableName put Enum values for the column.
/enumvalues/:columnName
107 9 htlog_missing_in 2402000 Column name is missing while retriev- columnName is blank or Null
7 put ing Enum values for Table
108 9 htlog_failure 2402099 Could not retrieve Enum values for Exception occurred
8 Column
9 /historylogs/:systemId/:tableName put Table Data.
110 1 /:snapshotId htlog_missing_in 2402000 Column names not available while No valid list of columns
0 put retrieving Table Data from Table
0
111 1 htlog_failure 2402099 Could not retrieve page wise data for Exception occurred
0 Table
1
112 1 DELETE htlog_missing_in 2402000 Table name is missing in the request tableName is blank or Null
0 /historylogs/:systemId/:tableName put to discard the snapshot.
2 /:snapshotId
113 1 htlog_missing_in 2402000 Snapshot id is missing in the request snapshotId is blank or Null
0 put to discard the snapshot for Table
3
114 1 htlog_failure 2402099 Could not discard snapshot with Exception occurred
0 SnapshotId
4
228
Error Response 10

115 1 GET htlog_missing_in 2402000 Table name is missing in the request tableName is blank or Null
0 /historylogs/:systemId/:tableName put to validate condition filter string.
5 /validateconditionfilter/:conditionFi
116 1 lter htlog_missing_in 2402000 Condition filter string is missing in the conditionFilter is blank or Null
0 put request to validate condition filter
6 string for Table
117 1 htlog_failure 2402099 Could not validate condition filter string Exception occurred
0
7
118 1 GET htlog_missing_in 2402000 Table name is missing in the request tableName is blank or Null
0 /historylogs/:systemId/:tableName put to retrieve child data.
8 /:snapshotId/:parentId
119 1 htlog_missing_in 2402000 Snapshot Id is missing in the request snapshotId is blank or Null
0 put to retrieve child data for Table
9
120 1 htlog_missing_in 2402000 Parent information is missing in the parentId is blank or Null
1 put request to retrieve child data
0
121 1 htlog_missing_in 2402000 Column names not available while No valid list of columns
1 put retrieving child Data for Table
1
122 1 htlog_cancelled 2402098 Request preliminary canceled by the Report cancellation request aborted report generation
1 user
2
123 1 htlog_failure 2402099 Could not retrieve Child data for Table Exception occurred
1
3
124 1 GET file_retrieval_fail 2402199
1 /files/:filetype ed
4
125 1 GET file_directorynotf 2402100
1 /files/:systemId/:relativeFilePath ound
5
126 1 file_filenotfound 2402101
1
6
127 1 file_inputdatainv 2402102
1 alid
7
128 1 file_inputdatanot 2402103
1 expected
8
229
10 Error Response

129 1 file_pathinvalid 2402104
1
9
130 1 file_pathnull 2402105
2
0
131 1 file_pathtoolong 2402106
2
1
132 1 file_unauthoirzed 2402107
2 access
2
133 1 file_retrieval_fail 2402199
2 ed
3
134 GET file_inputdatainv 2402102
/files/documents/:designation alid
135 file_retrival_faile 2402199

d
136 1 GET ob- 2402200 The object id is invalid.

2 /graphics/:objectId ject_not_known
4
137 1 failure 2402201 Could not identify the object or could
2 not determine if it is graphical.
5
2 /graphics/itemIds/:objectId ject_not_known
6
139 1 failure 2402201 Could not identify the object or there
2 was a problem finding graphical items
7 related to the object.
2 /graphics/items/:objectId ject_not_known
8
141 1 failure 2402201 Could not identify the object or there The object id must specify a graphical item.
2 was a problem finding (or loading) the
9 specified graphic.
142 1 GET ev- 2402499
3 api/eventcategorysounds tsound_retrieval
0 _failure
230
Error Response 10

143 1 POST evtsound- 2402301 Connection id missing
3 api/sr/eventcategorysoundssubsc sub_missing_inp
1 riptions/:connectionId ut
or
POST
144 api/sr/eventcategorysoundssubsc evtsound- 2402302
riptions sub_client_alrea
/channelize/:requestId/:connectio dysubscribed
nId
145 evtsound- 2402399
sub_failure
146 1 DELETE evtsoundUn- 240398

3 api/sr/eventcategorysoundssubsc sub_failure
2 riptions/:connectionId
147 POST systems- 2402500
/api/sr/systemssubscriptions/chan sub_missing_inp
nelize/:requestId/:connectionId ut
148 and systems- 2402501
DELETE sub_invalid_con
/api/sr/systemssubscriptions/chan nectionId
nelize/:connectionId
149 POST systemsun- 2402598
/api/sr/systemssubscriptions/chan sub_failure
nelize/:requestId/:connectionId
150 POST systems- 2402599
/api/sr/systemssubscriptions/chan sub_failure
nelize/:requestId/:connectionId
151 GET sch_Invalid_sch 2402600
/api/scheduler/schedule/:objectId edule
152 sch_unkown_sc 2402603

hedule
153 sch_failure 2402602
154 POST sch_Invalid_sch 2402600

/api/scheduler/schedule/save edule

hedule
231
10 Error Response

157 POST sch_Invalid_sch 2402600

/api/scheduler/exception/save edule

hedule
160 GET sch_Invalid_sch 2402600

/api/scheduler/schedule/saveDefa edule
ultValue
hedule
163 GET sch_Invalid_Cale 2402601

/api/scheduler/calendarList/:objec ndar
tId
164 cal_unkown_cal 2402606
endar
166 GET cal_failure 2402607

/api/scheduler/calendar/:objectId
167 sch_Invalid_Cale 2402601

ndar
168 cal_unkown_cal 2402606

endar
232
Error Response 10

170 GET obj_invalid_obje 2402709
/api/objects/:designation ct
171 obj_failure 2402700
172 POST obj_object_valid 2402708

/api/objects ation_failed
173 obj_object_creati 2402703

on_failed
174 obj_new_object_ 2402704

not_allowed
175 obj_object_alrea 2402705

dy_exists
176 obj_failure 2402700
177 DELETE obj_deletion_fail 2402710

/api/objects/:designation ed
178 GET license_failure 2403299

/api/licenses
179
233
s
Issued by © Siemens Switzerland Ltd, 2021

Siemens Switzerland Ltd Technical specifications and availability subject to change without notice.
Smart Infrastructure
International Headquarters
Theilerstrasse 1a
CH-6301 Zug
Tel. +41 58-724 24 24
www.siemens.com/buildingtechnologies
Document ID A6V10470112_en_b_40
Edition 2021-06-30

Web Service Interface (v6.0)

Uploaded by

Web Service Interface (v6.0)

Uploaded by

it

Web Service Interface –

A6V10470112_en_b_60 Building Technologies

About This Document ..................................................................................................... 14

About This Document

Cyber security disclaimer

Cross references to other information in For more information on creating flowcharts,

Safety Messages According ANSI Z535.6

Property Damage Warning Message

Caution Safety Message

Warning Safety Message

Danger Safety Message

Document Revision History

Document Revision History.

1.1.3 Online Documentation

ii)Internet (i.e via IIS)

1.1.3.1 Exposure of Swagger via IIS is configurable

Path for WSI Web Application web.config :

1.2 Definitions, Acronyms and Abbreviations,

1.2.2 Conventions in this Document

1.3 Open Issues in this Document Version

2.1 System Limits

⚫ Number of concurrent sessions: 100

IIS limits imposed by Operating System version

3 Basic System Concepts

3.1 Glossary of the System

3.2 Basic Data Concept in the System

The system concept impacts the following main elements:

3.3 Alarm Concepts

Alarm_NoAckNoReset Simple No user action necessary

3.4 Userinterface Concepts

Displaying Alarms and Events

3.5 Search Mechanism Behavior

4 Using the Web Service Interface

4.1.2 Client Certificate Authentication

4.1.3 Subscriptions (Push Notifications with SignalR)

subscribe for notifications by providing a connection ID which it gets after a

Noris hosts signalr url at /signalr route.

ii)Internet (i.e via IIS)

4.1.4 Latency Push Notification to Request-Response

In this kind of scenario Clients of WSI should consider received notification as a

4.1.5 SignalR Hubs

Service specific list of Hubs are as below:

4.2 Supported Client Environments

4.4 Configuring Web Service Interface in a Project

4.4.1 Stopping a Project

4.4.2 Showing Settings

4.4.3 Defining Protocol Type and Port

4.4.4 Creating a WSI on Server

 The Details expander displays.

4.4.5 Starting a Project

4.5 Service Category

4.6 Service mapping with Desigo CC(Basic reference)

S.No. Workflow Services [44]

4.7 Access rights for application services

Service Endpoints Application [ID- Name] Operation [ID- Name]

Schedule Save Schedule 46 - Schedules 1474 - Configure

4.8 WSI Configuration keys

Configuration Key Data Type Default Description

MaxSnapshotInactiveTime String 10 Maximum Inactive Time for Snapshot

SignalrMessageBuffer String 3000 Signalr Message Buffer size

4.9 Time sync

5.1 Case Sensitivity

5.2 Number Format

5.3 Date/Time Format

1 see also Naming [➙ 216]

5.5 Maximum page size

5.6 Request per system

6 General API Specification

6.1 HTTP Methods

6.3 Status Codes

6.3.1 HTTP Status Codes

6.3.2 Error Code

6.5 Array in Query Parameter

6.6 HTTP caching

7.1 Token Service