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.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

Available functions

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 )

INFO

this is a mandatory function for every ESI library


SETVARIABLE or SET

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:GET(path,v,q,t)

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

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:GET(args)

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

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

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}

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 or GET

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

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

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

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
}

INFO

This is a mandatory function for any ESI library. See ESI Coding Standards for more information.


Breaking changes

  • Not Applicable