GettingStarted

This document describes the basic methods in NordomaticApi and how to use them.

Dokumentation på svenska Getting Started

Base url: https://nostromo.styrportalen.se/nordomaticapi

The base url is customer specific and you will receive it together with your login credentials. The above base url is for our demo site and is therefore used in this document.

Documentation is available at {base url}/core/help and {base url}/trend/help.
Swagger is available at {base url}/core/swagger and {base url}/trend/swagger.

Appendices

API: Two main areas

  1. Core

    • Documentation: {base url}/core/help
    • Example endpoints: {base url}/core/api/login, {base url}/core/api/getonlinealarmsbytoken
    • Features (examples):
      • Alarms
        • GetOnlineAlarmsByToken
        • AcknowledgeAlarmsByToken
        • GetAlarmstypes
      • Security
        • Login
        • LoginWithMenu
        • Logout
      • Signals
        • RegisterSignalsByToken
        • UnregisterSignalsByToken
        • WriteSecuredSignalValuesByToken
        • WriteValueWithLogin
        • ReadSignalValueByToken
        • GetSignalDefinitions
        • GetUpdatesByToken
      • Tags
        • Taglist

  2. Trend

    • Documentation: {base url}/trend/help
    • Example endpoints: {base url}/core/api/logvalues, {base url}/core/api/logtags
    • Features:
      • GetLogTagsWithToken
      • LogValues

Walkthrough

To use the API, always include the following headers:

  • x-securityToken: Value from login
  • x-clientID: Same guid as used in login
  • x-sessionID: Value from login

Steps to retrieve values

The methods and properties needed are described in the API documentation mentioned above.

  1. Login
    Login credentials from Styrportalen.se cannot be used here, a separate login is required
    • Generate a clientID, the id should be a UUID (or GUID)
      The id should match the following regexp:
      /^[0-9A-F]{8}[-]?(?:[0-9A-F]{4}[-]?){3}[0-9A-F]{12}$/i
    • Use the /Login method
      Login returns sessionID and securityToken, save these for this session.
  2. RegisterSignalsByToken
    • Register signals before values can be retrieved
      If the signal(s) were registered correctly, value 0 is returned, all other values are error codes.
  3. GetUpdatesByToken
    • Call continuously (max every 2 seconds) to retrieve updated values for the registered signals
  4. UnRegisterSignalsByToken
    • Unregister signals
  5. WriteSecuredSignalValuesByToken
    • Write values to signals, accepts an array of signals with values.
  6. Keepalive
    • Send keepalive every minute to keep the session active

Flow

The following flowchart describes the login and keepalive process

Keep Alive (every 60 sec)

Keep Alive

Get Updates (max every 2 sec)

Get Updates

Login

Register Signals

Unregister Signals

Write Secured Signal Values

Logout

  • Keep Alive: Send keepalive every 60 seconds to prevent session timeout.

Payload to send keepalive:
clientId is the generated id used in login

const params = {
  securityToken,
  values: [{
      Name: 'WFSInternal_UID2_WD',
      Value: `${clientId}\\DefaultProject`
  }]
};

One-shot signalwrite

  • WriteValueWithLogin does not require login or signal registration.
    Use this for single writes as it is subject to stricter rate limits than WriteSecuredSignalValuesByToken

Test signals