esi-variables

A library for upserting variables and variable groups. This is very helpful to implement complex state and perfomance tracking which can be easily linked to KPI model objects, such as KPIs, Charts, Trends etc. Variables are much more lightweight for the purpose, in comparison to the classic DataHolder (HolderItem) object.

Please note: As of version 1.0.0 of the library it will be saved under the new file name convention, which is without the -lib part, and in this case just esi-variables.lua The original source file is deprecated and will be removed within the next months.

Changes

Version	Date	Description	s:i Release
1.0.2	2020-12-08	TFS code synchronisation	1.72
1.0.1	2020-10-03	Fix links and section titles in the docs. Proper name for the docs file.	-
1.0.0	2018-09-05	Promoted to be in the product, changed file name to new style (without -lib)	1.42
0.1.6	2018-09-05	Support for variable persistency	-
0.1.4	2018-05-27	documentation and formating	-
0.1.4	2018-05-27	hist (off) option, SET/GET aliases	-
0.1.3	2018-05-25	Update esi standard	-
0.1.2	2018-04-24	Bugfix SETVARIABLE, esi-object UPSERTOBJECT function	-
0.1.1	2018-01-10	Initial release	-

dependencies

library	version	inmation core library
dkjson	2.5	yes
esi-objects	0.1.1	no

library

version

inmation core library

dkjson

2.5

yes

esi-objects

0.1.1

Available functions

function description

function	description
SET	the short version of the function `SETVARIABLE`
SETVARIABLE	update value, quality and timestamp of a variable and creates the variable if it doesn’t exists
GET	the short version of the function `GETVARIABLE`
GETVARIABLE	return the value, quality and timestamp of a variable (automatically converts json sting to a lua table )

SET

the short version of the function SETVARIABLE

SETVARIABLE

update value, quality and timestamp of a variable and creates the variable if it doesn’t exists

GET

the short version of the function GETVARIABLE

GETVARIABLE

return the value, quality and timestamp of a variable (automatically converts json sting to a lua table )

SETVARIABLE

Upserts a variable object underneath the code-executing object and sets its value. Tables are automatically converted to json. The function arguments can be set with "single" arguments described in possibility 1, or can be provide as a table with enhanced functionality described in possibility 2.

Possibility 1: provide the path of the variable, value, quality and timestamp as separate arguments

V:SET(path,v,q,t)

field data type required meaning

field	data type	required	meaning
path	`string`	yes	the path of the variable
v	`object`	yes	the new value to be set
q	`string`	no	the quality of the value. By default, it is `0` (equivalent to "good")
t	`string`	no	the timestamp of the value. By default, it is the current time
hist	`bool`	no	when set to `true` the value will be archived in the production archive. By default, it is set to `true`

path

string

yes

the path of the variable

object

yes

the new value to be set

string

the quality of the value. By default, it is 0 (equivalent to "good")

string

the timestamp of the value. By default, it is the current time

hist

bool

when set to true the value will be archived in the production archive. By default, it is set to true

example 1: set variable py path

local V=require('esi-variables')
local success = V:SET("group1/value 1",1)
-- note: same as
-- local success = V:SETVARIABLE("group1/value 1",1)
return success

Possibility 2: provide a table with the arguments

V:SET(args)

field data type required meaning

field	data type	required	meaning
path	`string`	yes	the path of the variable
v	`number`, `bool`, `string` or `table`	yes	the new value to be set
q	`string`	no	the quality of the value. By default, it is `0` (equivalent to "good")
t	`number`	no	The posix timestamp of the value, in milliseconds. By default, it is the current time
hist	`bool`	no	when set to `true` the value will be archived in the production archive. By default, it is set to `true`
object	`table`	no	the inmation object where the variable is underneath, when this field is `nil`, then the code-executing object will be used
json	`table`	no	ths state of the `json.encode` function, read more about is in the dkjson documentation. By default, it is set to `{indent = false}`

path

string

yes

the path of the variable

number, bool, string or table

yes

the new value to be set

string

the quality of the value. By default, it is 0 (equivalent to "good")

number

The posix timestamp of the value, in milliseconds. By default, it is the current time

hist

bool

when set to true the value will be archived in the production archive. By default, it is set to true

object

table

the inmation object where the variable is underneath, when this field is nil, then the code-executing object will be used

json

table

ths state of the json.encode function, read more about is in the dkjson documentation. By default, it is set to {indent = false}

example 2: set variable path and value

local V=require('esi-variables')
local success = V:SET{path="group2/value 2",v=1}
-- note: same as
-- local success = V:SETVARIABLE{path="group2/value 2",v=1}
return success

example 3: set variable path, value as table, no history and custom json formating

local V=require('esi-variables')
local tab = {{v=1},{v=2}}
local success = V:SET{path="group3/value 3",v=tab,hist=false,json={indent=true}}
-- note: same as
-- local success = V:SETVARIABLE{path="group3/value 3",v=tab,hist=false,json={indent=true}}
return success

response:

example 4: set variable path of other object and value

local V=require('esi-variables')
local obj = inmation.getobject("../SETVARIABLE 01")
local success = V:SET{object=obj,path="group4/value 4",v=4}
-- note: same as
-- local success = V:SETVARIABLE{object=obj,path="group4/value 4",v=4}
return success

GETVARIABLE

Retrieves a variables from underneath the code-executing object (example 1 and 2), or and provided object( example 3). The function arguments can be set with "single" arguments described in possibility 1, or can be provide as a table described in possibility 2.

Possibility 1: provide only the path of the variable and read value, quality and timestamp

V:GET(path)

field data type required meaning

field	data type	required	meaning
path	`string`	yes	the path of the variable

path

string

yes

the path of the variable

example 1: get variable py path

local J=require('dkjson')
local V=require('esi-variables')
local path = "group/value1"
local v,q,t = V:GET(path)
-- note: same as
-- local v,q,t = V:GETVARIABLE(path)
return J.encode({["v"]=v,["q"]=q,["t"]=t})

response:

{
    "v": 1,
    "q": 0,
    "t": 1527841751032
}

Possibility 2: provide a table args and read value, quality and timestamp of a variable

V:GET(args)

field data type required meaning

field	data type	required	meaning
object	`table`	no	the inmation object where the variable is underneath, when this field is `nil`, then the code-executing object will be used
path	`string`	yes	the path of the variable underneath the object

object

table

the inmation object where the variable is underneath, when this field is nil, then the code-executing object will be used

path

string

yes

the path of the variable underneath the object

example 2: variable by path

local J=require('dkjson')
local V=require('esi-variables')
local v,q,t = V:GET{path ="group 02/value 02"}
-- note: same as
-- local v,q,t = V:GETVARIABLE{path ="group 02/value 02"}
return J.encode({["v"]=v,["q"]=q,["t"]=t})

response:

{
    "v": 2,
    "q": 0,
    "t": 1527843310846
}

example 3 provide object and variable path

local J=require('dkjson')
local V=require('esi-variables')
local obj = inmation.getobject("../GETVARIABLE 01")
--local v,q,t = V:GETVARIABLE{path="group/value1",object=obj} -- note: same as V:GET{path="group/value1",object=obj}
local v,q,t = V:GET{path="group/value1",object=obj}
return J.encode({["v"]=v,["q"]=q,["t"]=t})

response:

{
    "v": 1,
    "q": 0,
    "t": 1527841751032
}

Breaking changes

Not Applicable