inmation-compose-vscode-extension v0.2.3

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

inmation-compose

inmation-compose Visual Studio Code Extension seamlessly integrates Visual Studio Code with system:inmation.

Use this in conjunction with:

Features

Write Lua script in VS Code and push them to inmation using:

• Execute Function
• Run Script

From the Command Palette (Windows/Linux: Ctrl+Shift+P, macOS: Cmd+Shift+P), select one of contributes commands by typing inmation-compose.

First select inmation-compose: Connect to WebAPI before any inmation-compose: Run Action can be done.

inmation-compose.json file

inmation-compose reads the 'inmation-compose.json' file which needs to be in the root of the opened folder (Workspace).

The base structure looks like:

{
    "connections": [],
    "scriptReferences": [],
    "actions": []
}

Template files can be created from the Command Palette (Windows/Linux: Ctrl+Shift+P, macOS: Cmd+Shift+P), by selecting inmation-compose: Workspace Template. Make sure one 'empty' folder (Workspace) is opened in VS Code.

First select inmation-compose: Connect to WebAPI before any inmation-compose: Run Action can be done.

Connections

inmation-compose will connect to the WebSocket interface of the inmation Web API. Default port is 8002. For encrypted connections (wss:) make sure secure is set to true.

authority can be inmation, ad (Active Directory - domain account), machine (local account).

Multiple connections can be configured to easy switch from environment, like:

{
    "connections": [
        {
            "name": "test-environment",
            "hostname": "localhost",
            "port": 8002,
            "usr": "<USERNAME>",
            "pwd": "<PASSWORD>"
        },
        {
            "name": "stage-environment",
            "hostname": "<HOSTNAME>",
            "port": 8002,
            "secure": true
        },
        {
            "name": "prod-environment",
            "hostname": "<HOSTNAME>",
            "port": 8002,
            "secure": true,
            "authority": "ad"
        }
    ]
}

When username and password are not specified, VS Code will prompt for them.

scriptReferences

Use to point to folders on disk which contain Lua files. in the 'config.json' files these scripts can be referenced by namespace referencing.

{
    "scriptReferences": [
        {
                "namespace": "scripts",
                "folderPath": "./scripts"
        }
    ]
}

actions

Actions are very versatile. Can be used to exec a function, run a script and created objects based on config on disk.

Context ctx is in which context (object) the script is running.

Action may contain comment field which will be used as Audit Trail comment.

Run 'hello-world' script example

"type": "run-script"

The action in the inmation-compose.json file looks like:

{
    "actions": [
        {
            "name": "Run 'hello-world' script",
            "type": "run-script",
            "ctx": "/System",
            "scriptRef": "scripts.hello-world"
        }
    ]
}

Returns if successful:

[{"p":"/System","v":"Hello World!","q":0}]

This action can also contain a Lua body:

{
    "actions": [
        {
            "name": "RunScript ObjectName example",
            "type": "run-script",
            "ctx": "/System",
            "script": "local selfObj = inmation.getself()\nreturn inmation.getvalue(selfObj:path() .. '.ObjectName')"
        }
    ]
}

In order to make use of Lua library scripts which aso needed to be send to the server you can specify this like:

{
    "actions": [
        {
            "name": "Run 'Lib Test' script",
            "type": "run-script",
            "ctx": "/System",
            "scriptLib": [
                {
                    "name": "my-great-lib",
                    "scriptRef": "scripts.my-great-lib"
                }
            ],
            "scriptRef": "scripts.lib-test"
        }
    ]
}

In this example the 'lib-test.lua' script can just require the library by:

local libTest = require('my-great-lib')

Exec Function example

"type": "exec-function"

Add a Script Library in the /System with Module Name: my-lib and Lua Script Body:

local lib = {}

function lib:say_hello(arg)
    local _arg = arg or {} -- in case no argument is set
    local name = _arg.name or 'unknown'
    local msg = string.format("Hello %s", name)
    return msg
end

return lib

The action in the inmation-compose.json file looks like:

{
    "actions": [
        {
            "name": "Exec Function 'say_hello' example",
            "type": "exec-function",
            "ctx": "/System",
            "lib": "my-lib",
            "func": "say_hello",
            "farg": {
                "name": "inmation user"
            }
        }
    ]
}

Returns if successful:

[{"p":"/System","v":"Hello inmation user","q":0}]

Mass config objects

"type": "mass"

Based on Wiki: mass (function). For convenience Script Libraries can be configured as a ScriptList:

Example of config.json file:

{
    "version": "1.0",
    "objects": [
        {
            "path": "/System/Core",
            "class": "Core",
            "ObjectName": "Core",
            "ScriptLibrary": {
                "ScriptList": [
                    {
                        "LuaModuleName": "my-lib",
                        "scriptReference": "scripts.exec-func-example",
                        "LuaModuleMandatoryExecution": false
                    }
                ]
            },
            "children": [
                {
                    "class": "GenItem",
                    "ObjectName": "Counter",
                    "ObjectDescription": "Counter example",
                    "GenerationPeriod": 2000,
                    "GenerationType": 5,
                    "DedicatedThreadExecution": false,
                    "advancedLuaScriptReference": {
                        "scriptReference": "scripts.counter",
                        "propertyName": "AdvancedLuaScript"
                    }
                }
            ]
        }
    ]
}

In order to preserve existing (stored) Script Libraries, the property explicit needs to be set to false. Default value is true, even if the property is omitted. Which means that the Script Libraries is overwritten with what is defined in the config.json file.

{
    "version": "1.0",
    "objects": [
        {
            "path": "/System/Core",
            "class": "Core",
            "ObjectName": "Core",
            "ScriptLibrary": {
                "explicit": false,
                "ScriptList": [
                    {
                        "LuaModuleName": "my-lib",
                        "scriptReference": "scripts.exec-func-example",
                        "LuaModuleMandatoryExecution": false
                    }
                ]
            }
        }
    ]
}

Script Library with reference to data file which will be import into the script:

{
    "version": "1.0",
    "objects": [
        {
            "path": "/System/Core/TestItem",
            "class": "GenFolder",
            "ObjectName": "TestItem",
            "ObjectDescription": "This is a TestItem",
            "ScriptLibrary": {
                "ScriptList": [
                    {
                        "LuaModuleName": "lib-name1",
                        "scriptReference": "script-name",
                        "dataReference": "data-file1.json"
                    },
                    {
                        "LuaModuleName": "lib-name2",
                        "scriptReference": "script-name",
                        "dataReference": {
                            "filename": "data-file2.json",
                            "key": "#DATA#"
                        }
                    }
                ]
            }
        }
    ]
}

Lua library script to expose data:

local data = [[#DATA#]]
return data

The action in the inmation-compose.json file looks like:

{
    "actions": [
        {
            "name": "Create Objects (mass)",
            "type": "mass",
            "ctx": "/System",
            "model": "./model/10_test"
        }
    ]
}

Mapping

In case different system environments are used with for instance different object names for the Core object, a mapping file can be used to find & replace strings in the (model) config.json files.

As example create a new file and store it as production.json in the folder mapping with:

{
    "version": "1.0",
    "mappings": [
        {
            "/System/Core": "/System/INM-CORE01-SRV"
        }
    ]
}

Place in this example "mapping": "./mapping/production.json" in the specific inmation-compose.json action like:

{
    "actions": [
        {
            "name": "Create Objects (mass)",
            "type": "mass",
            "ctx": "/System",
            "model": "./model/10_test",
            "mapping": "./mapping/production.json"
        }
    ]
}

Reinit Objects

"type": "reinit-objects"

Script body object like Action Items and Generic Items will be disabled and re-enabled again, to make sure (updated) scripts libraries gets re-imported.

The data.path should contain a inmation object path to start traversing the object tree. The data.delay is the time in seconds between disabling an re-enabling (default 5 sec).

The action in the inmation-compose.json file looks like:

{
    "actions": [
        {
            "name": "Reinit Lua Script Objects",
            "type": "reinit-objects",
            "ctx": "/System",
            "data": {
                "path": "/System",
                "delay": 5
            }
        }
    ]
}

Flow

"type": "action-flow"

Defines a set of action steps which will be executed in a sequence.

The attribute steps is an array of names of the predefined actions.

{
     "actions": [
        {
            "name": "Flow Create Objects and Reinit",
            "type": "action-flow",
            "steps": [
                "Create Objects (mass)",
                "Reinit Lua Script Objects"
            ]
        }
    ]
}

Debug

Supply a (relative) folder name and a 'request' file will be created before sending the call to inmation. Make sure this folder exists.

{
    "actions": [
        {
            "debug": "./debug",
        }
    ]
}

Output

Supply a (relative) folder name and the response data will be saved in that folder. Make sure this folder exists.

{
    "actions": [
        {
            "output": "./output",
        }
    ]
}

Requirements

• inmation-api-client.

Extension Settings

Known Issues

This is an Alfa version!

License

This extension is licensed under the MIT License.

Release Notes

Improvements.

See CHANGELOG.md for details.