inmation-compose
inmation-compose Visual Studio Code Extension is a versatile and powerful tool designed to streamline the configuration process of AspenTech Inmation platforms.
Use this in conjunction with:
| extension |
publisher |
purpose |
| Lua |
sumneko |
Lua Language Server coded by Lua |
Disclaimer
AspenTech Inmation is a registered trademark of Aspen Technology, Inc. further referred to as AspenTech.
This application, is provided for convenience purposes only and is not an official product of AspenTech. While every effort has been made to ensure its functionality and reliability, it is important to note that this tool has not undergone formal quality assurance testing or approval by AspenTech.
The creators of this application have developed it to facilitate easy and powerful configuration of inmation platforms. However, AspenTech does not endorse or guarantee the accuracy, completeness, or suitability of this application for any particular purpose.
Users of this application should understand that it is provided on an "as-is" basis, and AspenTech shall not be held liable for any direct, indirect, incidental, special, or consequential damages arising from its use.
By using this application, you acknowledge and agree that you do so at your own risk. While efforts have been made to minimize errors and bugs, AspenTech cannot guarantee that the application will be free from defects or that it will meet your specific requirements.
This disclaimer is subject to change without notice. Please review the latest version of this disclaimer regularly.
Thank you for your understanding.
Features
Write Lua script in VS Code and push them to inmation using mass:
See what other actions are available.
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.
Commands
| Command |
Description |
| inmation-compose: Connect to WebAPI |
Connect to inmation Web API. |
| inmation-compose: Disconnect from WebAPI |
Disconnect from inmation Web API. |
| inmation-compose: Run Action |
Run an action. |
| inmation-compose: Workspace Template |
Create a workspace template. |
The inmation-compose: Workspace Template command will create/overwrite in the root of the opened folder (Workspace).
Create when not already present:
inmation-compose.json filescripts foldermodel folder
Overwrite when already present:
Note: Best practice is to use git to manage changes in your project folder even if it is a local repository.
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.
Connection settings can also be provided via .env file. Create a .env file in the root of the workspace and add the following:
USERNAME=my-username
PASSWORD=my-password
The inmation-compose.json file, the properties should be surrounded by < and > and can look like this:
{
"connections": [
{
"name": "test-environment",
"hostname": "localhost",
"port": 8002,
"usr": "<USERNAME>",
"pwd": "<PASSWORD>"
}
]
}
The connection properties which can be set via the .env file are hostname, port, secure, usr and pwd.
This is an example to provide all the connection properties in the .env file:
HOSTNAME=127.0.0.1
PORT=8002
SECURE=false
USERNAME=my-username
PASSWORD=my-password
The connections in the inmation-compose.json file, looks like this:
{
"connections": [
{
"name": "test-environment",
"hostname": "<HOSTNAME>",
"port": "<PORT>",
"secure": "<SECURE>",
"usr": "<USERNAME>",
"pwd": "<PASSWORD>"
}
]
}
In case the password contains a # character, the password should be surrounded by double quotes. Those double quotes will be removed before sending the password to the server.
### 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.
```json
{
"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 false, even if the property is omitted. If true it means that all Script Libraries are 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"
}
]
}
Data Reference
Properties can be configured with content from a file. The dataReference needs to have a propertyName, filename and optional convert depending on the property type, the data needs to be decoded (dejson) from a JSON string.
{
"version": "1.0",
"objects": [
{
"path": "/System/Core/MyTableHolder",
"class": "TableHolder",
"ObjectName": "MyTableHolder",
"dataReference": {
"propertyName": "TableData",
"filename": "table-data.json",
"convert": "dejson"
}
}
]
}
For CustomOptions.CustomProperties and CustomOptions.CustomTables there is the same convenience configuration like ScriptLibrary. This is available from WebAPI v1.106.
{
"version": "1.0",
"objects": [
{
"path": "/System/Core/MyFolder",
"class": "GenFolder",
"ObjectName": "MyFolder",
"CustomOptions.CustomProperties": {
"explicit": false,
"PropertyList": [
{
"name": "My-Simple-Prop-Value",
"value": "Hello World"
},
{
"name": "My-Prop-Value-from-a-File-1",
"dataReference": "./data-file-1.json"
},
{
"name": "My-Prop-Value-from-a-File-2",
"dataReference": {
"filename": "./data-file-2.json"
}
}
]
},
"CustomOptions.CustomTables": {
"explicit": false,
"TableList": [
{
"name": "My-Simple-Table-Data",
"value": [
{
"City": "Cologne",
"Temp": 26
},
{
"City": "Eindhoven",
"Temp": 24
}
]
},
{
"name": "My-Simple-Table-Data-from-File-1",
"dataReference": "./data-file-1.json"
},
{
"name": "My-Simple-Table-Data-from-File-2",
"dataReference": {
"filename": "./data-file-2.json"
}
}
]
}
}
]
}
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",
}
]
}
Output File
Supply a (relative) file name and the response data will be saved to that file. Make sure the folder path exists.
{
"actions": [
{
"outputFile": "./output/result.txt",
}
]
}
