@inmation/inmation-api-client

inmation Web API Client

Usage no npm install needed!

<script type="module">
  import inmationInmationApiClient from 'https://cdn.skypack.dev/@inmation/inmation-api-client';
</script>

README

inmation API Client

inmation header

This API client can be used with the new inmation Web API server.

Install

Install with npm install @inmation/inmation-api-client

How to use it

Authentication

  • authority can be inmation, ad (Active Directory - domain account), machine (local account)
  • username can provided in 'User Principal Name' or 'Down-Level Logon Name'

source: https://docs.microsoft.com/en-us/windows/desktop/secauthn/user-name-formats

Optional auth authentication and authorization fields:

const options = {
    auth: {
        username: "",
        password: "",
        authority: "inmation | ad | machine",
        grant_type: "password",
        include_claims: ["email", "family_name", "given_name", "middle_name", "phone_number"],
        disconnect_on_access_denied: false
    },
    authorization: "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
};

include_claims can only be used in combination with authority set to ad. The token will not be returned to the client but passed via the req argument into ExecFunction implementation.

disconnect_on_access_denied set this to false to force the Web API server to keep the websocket connection open in an unauthorized state when the authentication request results in an access denied (401) response. A onWSConnectionChanged will be invoked informing the connection is Connected but Authenticated is set to false.
By default the connection will be closed with Close Status 1002 and reason 'Access token expired.'.

Note: check Web API version which authorization options its supports.

Example Active Directory authentication:

const options = {
    auth: {
        username: "user@domain.com",
        password: "secret",
        authority: "ad",
        grant_type: "password"
    }
};

Example Bearer token authentication:

const options = {
    auth: {
        authorization: "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
    }
};

Example Basic authentication:

const options = {
    auth: {
        authorization: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
    }
};

WebSocket Options

These options only applies for the Node.js and not for the Browser's WebSocket component. See Node.js WebSocket library.

const options = {
    wsOptions: {
        rejectUnauthorized: true
    }
};

Connect and Subscribe snippet

const { Client, model } = require('inmation/inmation-api-client');

const wsURL = 'ws://HOSTNAME:8002/ws';
const options = {
    auth: {
        username: "user@domain.com",
        password: "secret",
        authority: "ad",
        grant_type: "password"
    }
};

const client = new Client();

client.onWSConnectionChanged((connectionInfo) => {
    const webAPIStatusInfo = connectionInfo.webapi_status || {};
    const webAPIStatus = webAPIStatusInfo.status || 'unknown'
    console.log(`Connection state: ${connectionInfo.state}, ${connectionInfo.stateString}, Authenticated: ${connectionInfo.authenticated}, Web API Status: ${webAPIStatus}`);
    const auditTrail = webAPIStatusInfo.audit_trail
    if (auditTrail) {
        console.log(`Audit Trail enabled: ${auditTrail.enabled}, user_comment_mandatory: ${auditTrail.user_comment_mandatory}`);
    }
    const tokenResponse = connectionInfo.token_response
    if (tokenResponse) {
        console.log(`Token response token_type: ${tokenResponse.token_type}, expires_in: ${tokenResponse.expires_in} seconds`);
        console.log(`Token response access_token: ${tokenResponse.access_token}`);
    }
});

client.onDataChanged((err, items) => {
    if (err) console.log(err.message);
    for (const item of items) {
        console.log(`Path: ${item.p} value: ${item.v}`);
    }
});

client.onError((err) => {
    console.log(`Error: ${err.message}`);
});

console.log(`Connect to : ${wsURL}`);
client.connectWS(wsURL, (err) => {
    if (err) return console.log(err.message);

    // Make sure you have some IO, Generic or Data Holder Items in inmation and copy their path(s) over here.
    const items = [new model.Item('/System/Core/Simulation/Saw100'), new model.Item('/System/Core/Simulation/Saw200')];

    client.subscribeToDataChanges(items, (err) => {
        if (err) console.log(err.message);
    });
}, options);

Mass snippet with Scope Comment

const e1 = {
    path: "/System/Core/Playground/Item01",
    operation: 'REMOVE'
};
const e2 = {
    path: "/System/Core/Playground/Item02",
    ObjectName: "Item02",
    class: 123
};
const e3 = {
    path: "/System/Core/Playground/ItemWithProps",
    ObjectName: "ItemWithProps",
    class: 'HolderItem',
    "CustomOptions.CustomProperties.CustomPropertyName": ["Message", "Value"],
    "CustomOptions.CustomProperties.CustomPropertyValue": ["Hello World", "100"]
}
const e4 = {
    path: "/System/Core/Playground/ItemLibArray",
    ObjectName: "ItemLibArray",
    class: 'GenFolder',
    "ScriptLibrary.LuaModuleName": ['script01', 'script02'],
    "ScriptLibrary.AdvancedLuaScript": ["return 'Hello'", "return 'World'"]
}
const e5 = {
    path: "/System/Core/Playground/ItemLibArrayDict",
    ObjectName: "ItemLibArrayDict",
    class: 'GenFolder',
    ScriptLibrary: {
        ScriptList: [
            {
                LuaModuleName: 'script01',
                AdvancedLuaScript: "return 'Hello'"
            },
            {

                LuaModuleName: 'script02',
                AdvancedLuaScript: "return 'World'"
            }
        ]
    }
}
const e6 = {
    path: "/System/Core/Playground/ActionItem",
    ObjectName: "ActionItem",
    class: 'ActionItem',
    AdvancedLuaScript: "return 100"
}
const items = [e1, e2, e3, e4, e5, e6];

const client = new Client();


client.connectWS(wsURL, (err, connectionInfo) => {
    if (err) return console.log(err.message);
    client.mass(items, (err, data) => {
        if (err) return console.log(`Error: ${err.message}`);
        if (data) {
            console.log(`Data: ${JSON.stringify(data)}`);
        }
    },{
        scc: "This is my scope comment"
    });
}, options);

Re-authenticate snippet

Same attributes as in the auth part of the options for the connectWS.

let auth = {
    username: "USERNAME",
    password: "PASSWORD"
    grant_type: "password"
};

Example Bearer token authentication:

const auth: {
    authorization: "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
};

Example Basic authentication:

const auth: {
    authorization: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
};

client.authenticate(auth, () => {
});

Release Notes

1.9.0

  • Updated ws (WebSocket) package.

1.8.0

  • Added support for WebSocket Options to set for instance the rejectUnauthorized.

1.7.11

  • Improvements.

1.7.10

  • Added robustness when parsing WebSocket message.

1.7.9

  • Improvements.

1.7.8

  • Removed console logging.

1.7.7

  • Checks WebSocket 'onerror' callbacks whether the error contains a message.

1.7.6

  • Improvements re-authentication.

1.7.5

  • Improvements.

1.7.4

  • authorization using Bearer or Basic are now part of the auth options.

From inmation Web API v1.66 and higher:

  • ConnectionInfo now contains Audit Trail configuration info.
  • Added authenticate function to be able to re-authenticate without re-connection.
  • ConnectionInfo now contains token info.
  • In order to not 'hammer' on the Web API, disconnect_on_access_denied can be set to false.

1.7.3

  • Improvements.
  • Improvements for using in node-red-contrib-inmation.

1.7.2

  • Improvements.
  • Rolled back connection event data which change was introduced in 1.7.0.

1.7.1

  • Improvements.

1.7.0

  • Improvements.
  • from inmation Web API v1.54.1 and higher:
  • Improved ConnectionInfo in case Web API to Core connection is lost.
  • Improved reconnection in case the connection to the Web API or Web API to Core was lost.

1.6.0

  • Improvements.
  • Added support for token based authentication. (from inmation Web API v1.48.1 and higher)

1.5.0

  • Improvements.
  • Added readHistoricalDataAtTime. (from inmation Web API v1.48 and higher)
  • Changed typo sloped_extrapolation at readHistoricalData. (from inmation Web API v1.48 and higher)

1.4.0

  • Improvements.
  • Support for include_claims.
  • Added webapi_status in ConnectionInfo.

1.3.0

  • Improvements.
  • Support for mass configuration (from Web API v1.44).
  • readRawHistoricalDataByQuery can now contain post execution functions.

1.2.0

  • Improvements.
  • Support for authorization via other authorities.

1.1.0

  • Improvements.
  • Added readRawHistoricalData and readRawHistoricalDataByQuery

1.0.0

  • Initial release of inmation API Client.

inmation

inmation is a vendor-independent industrial real-time information management system. Dedicated to modern technologies such as OPC UA (Unified Architecture), Web API and document-oriented schema-less repositories, inmation opens up new horizons for enterprise real-time data management.

More information on inmation.com