NORIS Technical Training: Revision:1

NORIS Technical Training
Author: Armin Galliker

Revision:1
Agenda
Part 1 - Basic
• Definition and Architecture
• Installation
• Getting Started
• Getting Help
• Login
• Resources / Services
Part 2 - Advanced
• Core Concepts
• Real-time Updates
• Conventions
• Session Keep Alive
• Limits
• Terminologies
© Siemens AG 2017
7/10/2018 2 Armin Galliker / BT CPS R&D ZG SW BMS
Page 2 April 2017 siemens.com
Definition (1/2)
NORIS: Northbound Open RESTful Integration Service (formerly known as Web Service Interface)
Northbound vs. Southbound:
Applications
NORIS ...
Northbound
Desigo CC
Southbound
Drivers (BACnet,
SORIS
Modbus, …)
Network devices, subsystems, ...
© Siemens AG 2017
Definition (2/2)
RESTful Interface: a RESTful interface is an API (application program interface) that uses HTTP requests
to GET, PUT, POST and DELETE data. It’s based on representational state transfer (REST) technology, an
architectural style and approach to communications often used in web services.
© Siemens AG 2017
Architecture Overview
(setup with IIS as reverse proxy)
https (www.example.com/wsi)
Web Server
IIS co ntains a website, identified with a common do main name like
www.example.com which in turn contains a web application for IIS
www.example.com (website)
web services (among others). The web application name is used as
the first part of the path of a URL (right after the domain name). /wsi (web application)
http/https (default port 8080)
Application Server
NORIS
NORIS is deployed as a self-hosted web server. (WCCOAWsi.exe)
Desigo CC
© Siemens AG 2017
Installation
• NORIS comes as its own Extension Module (EM) called Web Services as part of the Connectivity suite
• Web Services EM needs to be installed and needs to be part of a project
• Start SMC (System Management Console) and create a new project
• At project creation time a local port (e.g. 8080) and a scheme (http or https) has to be set
• Note: http should only be used if IIS runs on the same box as Web Services (Desigo CC)
• If no website exists create a new website
• Create a new web services application and point to project; the name will subsequently be used as part
of the URL (www.example.com/MyWebServicesApplicationName/...)
• Save ⇓ After the project is started, NORIS is ready
• After the web application is created the snap-in shows a URL for a graphical user interface of NORIS
(Swagger UI) and the URL where IIS exposes the NORIS endpoint (URL used in production).
© Siemens AG 2017
Getting Started
• Every project containing NORIS comes with a Swagger UI. Swagger UI1 allows to visualize and interact
with the NORIS services (aka resources)
• The link to Swagger UI can be found in SMC on the web services web application as Help URL:
1 https://swagger.io
© Siemens AG 2017
Getting Started: Swagger UI
• In order to use most of the services a user needs to be logged in. Simply provide username and
password in the corresponding text box (in format username:password) and click Explore. If a user is
not logged in (or a session expired) most services return a HTTP status code 401 (unauthorized).
• A dummy service which doesn’t require a login is the Diagnostics service which always returns a 200
(OK).
© Siemens AG 2017
Getting Started: Swagger Sandbox (Siemens internal only)
• Swagger UI is not only available on running projects (running on live data) but it is also available as a
sandbox with example data for trial and development purposes.
• Currently the sandbox is available and accessible within the siemens network (intranet) only
• Repository:
https://code.siemens.com/gms/gms-swagger
• Running sandbox:
https://gms-swagger-node.horizon-dev.siemens.io/
© Siemens AG 2017
Getting Started: Fiddler
• In order to get a feeling of how requests and responses to and from NORIS look like, an HTTP traffic
sniffer can help. Most browsers like Chrome and Firefox have one built-in (Chrome Developer Tools or
Firefox Developer Tools respectively).
• Another alternative is Fiddler1, an HTTP debugging proxy server. Fiddler captures and logs
HTTP/HTTPS traffic and can be used to modify traffic (e.g. for copying headers).
1 https://www.telerik.com/fiddler
© Siemens AG 2017
Getting Help
• Besides Swagger UI, NORIS includes an extensive description of the interface in form of a pdf:
[install directory]\GMSMainProject\Help\[language culture name]\Web Service Interface.pdf
• On request additional material is available for selected partners, developers, integrators and
customers:
• Test client for NORIS

• Document describing popular use cases of NORIS
• Document how to setup NORIS test client, NORIS EM and simulators
© Siemens AG 2017
First Call
In order to check if NORIS is up and running we can submit a simple HTTP request to the /diagnostics
service:
HTTP Request
GET /mynoris/api/diagnostics HTTP/1.1
Host: www.example.com
HTTP Response
HTTP/1.1 200 OK
mynoris is the name of the web services web application and is project specific. As shown in the
architecture overview this URL is exposed by IIS. For testing purposes the same request can also be
submitted directly to NORIS:
HTTP Request
GET /api/diagnostics HTTP/1.1
Host: localhost:8080
For brevity we use the second approach for the rest of the slides (host = localhost:8080).
© Siemens AG 2017
Login (1/2)
Most services (aka resources) are protected and can only be accessed by an authorized user. A client
uses an access token to access protected resources. Therefore the first step it to login in order to obtain
an access token (which is a bearer token in this case1):
HTTP Request (last line represents body of HTTP request)
POST /api/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
grant_type=password&username=myusername&password=mysecret
HTTP Response
HTTP/1.1 200 OK
{"access_token":"AQAAANCMnd8BFdERjHoAwE… //rest omitted for brevity
Note: In the request body grant_type=password is fixed while myusername and mysecret are
examples of a username and a password.
1 https://tools.ietf.org/html/rfc6750
© Siemens AG 2017
Login (2/2)
The HTTP response of the login request contains a JSON1 string which consists among others of an
access_token name/value pair. Its value has to be included in subsequent HTTP requests in the
Authorization header together with a “Bearer “-Prefix in order to access protected resources:
HTTP Request (/events is a protected resource)
GET /api/events HTTP/1.1
Authorization: Bearer AQAAANCMnd8BFdERjHoAwE…
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"Events":[{"Id":"System1:ManagementVi… //rest omitted for brevity
1 https://tools.ietf.org/html/rfc8259
© Siemens AG 2017
Resources / Services (1/4)
Resource Description
/commands Retrieve a list of commands for a list or a single property
Execute a command for list or a single property
/commandssubscriptions Subscribe for changing commands
Delete an existing subscription
/diagnostics Check if server is running
No authorization required
/eventcounters Retrieve a list of all event counters or for a given category
/eventcounterssubscriptions Subscribe for changing event counters
/events Retrieve a list of all events in all systems
/eventscommands Execute a command for a given event
/eventssubscriptions Subscribe for changing events
Apply or change filter criteria for a subscription
© Siemens AG 2017
/files Retrieve a file for a given path
Retrieve a file from a pool of public files (no authorization required)
/heartbeat Let the server know the client is still alive – extend the session lifetime
/historylogs Retrieve historical data like alarms, events, trends, values or logs
In order to keep a stable state for a some time one can refer to a snapshot
/images Retrieve images (png or svg) from Desigo CC libraries
/languages Retrieve the language of the logged in user
/products Retrieve information of the installed, branded product like Desigo CC or
Cerberus DMS (no authorization required)
/properties Retrieve configuration data for a list or a single property
/propertyvalues Retrieve configuration data and runtime data for a given property (the
runtime data is directly read from the field device)
© Siemens AG 2017
/systembrowser Browse through available systems, views their hierarchical tree structures
Search for nodes in a system (name or attribute filters available)
/systembrowsersubscriptions Subscribe for changes in a hierarchical tree or subtree of a system or view
/systems Retrieve information of any system in a distribution
Retrieve installed languages
/tables Retrieve well-known tables for key-value mappings or general settings
(e.g. textual representations of ids or colors used for categories)
/token Login and logout
/trendseries Retrieve trend series data and its borders (data reduction option available)
Retrieve aggregated timeseries (based on a time unit)
/trendseriesinfo Retrieve all offline and online trend series information for a given system
Retrieve any trend series information for a given property
© Siemens AG 2017
/values Retrieve a runtime data for a list or a single property
/valuessubscriptions Subscribe for changing runtime values
© Siemens AG 2017
Core Concepts: HTTP Verbs
HTTP Verb CRUD Description

(method)
GET Read Retrieves a list of resources, or a specific resource (entire collection e.g. /tables
or single item e.g. /tables/:tableId)
Idempotent
POST Create Creates a resource, passes in a parameter, or performs an action on a resource
(e.g. create a new subscription)
Also used for certain bulk readings
PUT Update/ Updates an existing resource (e.g. change an existing filter)
Replace Idempotent
DELETE Delete Deletes an existing resource (e.g. delete an existing subscription)
© Siemens AG 2017
Core Concepts: HTTP Status Codes
HTTP Meaning Description

Status
Code
200 OK Request processed.
Note: Although the request has been processed as a whole, some of the
sub results could still be invalid1.
400 Bad Request Request rejected by application.
401 Unauthorized Invalid or expired token presented. User needs to login.
404 Not Found Resource couldn’t be found for the provided URL and query parameters.
1Incase a result contains a collection (array) the HTTP status code is 200 as soon as the underlying
system can successfully process the request. However, every item in the collection contains its own
ErrorCode which indicates an error for this item if the code is greater than 0.
© Siemens AG 2017
Real-time Updates (SignalR)
NORIS being a RESTful interface follows the principle of client-server architecture. This means that a
client sends a request to a server and the server sends a response back to the client , making it an
unidirectional communication channel.
For certain use cases (e.g. client would like to show current runtime value) this architectural constraint
would lead to a heavy load on the system, as the client would have to poll frequently for updates. Because
of this NORIS also provides a bidirectional communication channel for certain services. These services
allow a client to subscribe for certain events. Whenever an event occurs on the server, a notification is
sent to subscribed clients by calling a method on the client side.
NORIS uses SignalR1, a software library by Microsoft, to send asynchronous notifications to clients.
Note: push notifications as known from mobile phones (e.g. WhatsApp, Facebook Messenger) are
available in their own Extension Module for Desigo CC (Push Notification EM).
1 https://www.asp.net/signalr
© Siemens AG 2017
Conventions (1/2)
• Case sensitivity: Unless otherwise specified the system is case sensitive. This affects the API in terms
of filters and search results.
• Number format: The API uses an invariant culture for the number formatting regardless of the logged in
user. The decimal mark is a period.
• Date/Time format: Date and time representations are supposed to be according to ISO-8601. Unless
otherwise noted, the UTC (Zulu) time zone is expected.
• Encoding: Data is encoded in UTF-8.
• Array in query parameter: In case a query parameter represents an array, the array is passed as a
JSON array (e.g. someurl?Ids=[1,2,3])
© Siemens AG 2017
Conventions (2/2)
• Request per system: In a distributed environment (multiple systems) a request may only contain data
points to a single system unless explicitly stated. If one needs to process data points of multiple
systems multiple requests have to be invoked.
• Maximum page size: Maximum page size which is supported in case of paging is 100’000 records per
page (default). If a page size is specified then the lesser number is considered.
© Siemens AG 2017
Session Keep Alive
A 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.
© Siemens AG 2017
NORIS Limits
The following limits apply when using NORIS:
• 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
© Siemens AG 2017
IIS Limits (imposed by Operating System version)
The Client versions of Windows (e.g. Windows 7, Windows 10) 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.
© Siemens AG 2017
Client Certificate Authentication
Optionally, a client can authenticate to the server by providing a client certificate. IIS asks the client for an
optional client certificate. In case a client certificate is provided IIS passes it on to NORIS.
The certificate needs to be known (configured) to the server.
© Siemens AG 2017
Terminologies
Term Description
Name Literal; supposedly unreadable; usually not displayed in a UI.
Descriptor Localized string in a readable form; supposed to be displayed to an end- user.
Designation Unique address of a node; supposedly unreadable; usually not displayed in a
UI.
Location 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.
ObjectOrPropertyId An object ID or a property ID is expected.
PropertyName Name of a property.
© Siemens AG 2017
Questions/Comments?
http://alphastockimages.com/
© Siemens AG 2017

NORIS Technical Training: Revision:1

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

NORIS Technical Training: Revision:1

Uploaded by

Copyright:

Available Formats

NORIS Technical Training

Author: Armin Galliker

Northbound vs. Southbound:

Network devices, subsystems, ...

http/https (default port 8080)

[install directory]\GMSMainProject\Help\[language culture name]\Web Service Interface.pdf

• Test client for NORIS

HTTP Verb CRUD Description

HTTP Meaning Description

• Encoding: Data is encoded in UTF-8.

The following limits apply when using NORIS:

• Number of concurrent sessions: 100

You might also like