esi-batch-data

Batch data document

Example

local BATCHCONFIG = require("esi-batch-config")
local BATCHDATA = require("esi-batch-data")
local function getCharacteristic(id)
    local charac = {
        {   active=true,
            code= syslib.model.codes.BatchField.CUSTOMMEASUREMENT,
            tag="Custom Measurement",
            meaning="Meaning1",
            proc=syslib.model.codes.BatchFieldProcessing.DIRECT,
            input="inputBD1",               -- path of tag, not needed here.
            label="Batch_Data_1",
            euoverride="",
            coll= syslib.model.codes.BatchDataCollection.TIMESERIESDISTINCT,
            fix=nil,
            map="",
            map_exclusive=false,
            script="",
            order = 20,
        },
        {   active=true,
            code= syslib.model.codes.BatchField.CUSTOMMEASUREMENT,
            tag="Custom Measurement",
            meaning="Meaning2",
            proc=syslib.model.codes.BatchFieldProcessing.DIRECT,
            input="inputBD2",               -- path of tag, not needed here.
            label="Batch_Data_2",
            euoverride="Unit2",
            coll= syslib.model.codes.BatchDataCollection.TIMESERIESDISTINCT,
            fix=nil,
            map="",
            map_exclusive=false,
            script="",
            order = 10,
        },
    }
    return charac[id]
end
local function getBatchIdCharac()
    local batchIdCharac = {
        active=true,
        code= syslib.model.codes.BatchField.BATCHID,
        tag="Batch ID",
        meaning="",
        proc=syslib.model.codes.BatchFieldProcessing.DIRECT,
        input="",               -- path of tag, not needed here.
        label="BatchId",
        euoverride="",
        coll= syslib.model.codes.BatchDataCollection.TIMESERIESDISTINCT,
        fix=nil,
        map="",
        map_exclusive=false,
        script="",
    }
    return batchIdCharac
end
local batchid = "MyBatch01"
local config= BATCHCONFIG:NEW(cfgVersion, objectpath, objecttype )
local equipment = ("/TestCompany/Plant1/Area51/BatchTest/TestUnit/TestEquipment%i"):format(1)
local partial_batch = true
config:SET_S95_EQ_ASSIGNMENT(equipment, partial_batch)
config:SET_UNIQUE_CRITERIA(syslib.model.flags.BatchUniqueCriteria.EQUIPMENT_ID)
-- second create batch obj...
local flags = {debug=false, log=false}              -- debug and log disabled
local starttime = syslib.now()
local reason
reason =  "Start condition met"
local batchdata, dataErr =BATCHDATA:NEW(config, flags, starttime, reason, true, batchid)
local time = starttime
local data = {v=batchid, q=0, t=time }
batchdata:WRITE_TO_BATCH(time, data, getBatchIdCharac() )
local def
for j=1,10 do
    time = starttime + 1000
    data = {v=("%i"):format(j), q=0, t=time }       -- norml v,q,t values
    def  = getCharacteristic(1)                     -- channel configuration
    batchdata:WRITE_TO_BATCH(time, data, def )      -- write value 1 after the other.
    data = {v=("%i"):format(j*j), q=0, t=time }     -- norml v,q,t values
    def  = getCharacteristic(2)                     -- channel configuration
    batchdata:WRITE_TO_BATCH(time, data, def )      -- write value 1 after the other.
end
batchdata:END_BATCH(time, reason)
batchdata:FINALIZE()
-- send the batch to the database.
--batchdata:SEND_BATCH()
return batchdata:TO_JSON()

Dependencies:

library version inmation core library

dkjson

5.3.0

yes

esi-string

1.0.0

yes

esi-tool

1.0.0

yes

esi-subtype

1.0.0

yes

debug

5.3.0

yes

Available functions:

All functions have to be called according to the ESI standard, using colons, e.g. lib:FUNCTIONNAME(params)

NEW

Documentation

INIT

Description

INIT

initialize this library ## Returns nil

IS_BATCH_ACTIVE

Description

IS_BATCH_ACTIVE

check if batch is active ## Returns true if batch is active

SET_BATCH_ACTIVE

Description

SET_BATCH_ACTIVE set the active state of a batch

modifies self.batch

Parameters

Name Description

active

Decides whether to set the batch active (true) or inactive (false)

reason

Allows to declare a reason which will be stored in the batch record

Returns

  1. true, if successful (2) optional error

Examples

local ret = SET_BATCH_ACTIVE(true, "batch active")

SET_BATCH_EQUIPMENT_STATE

Description

SET_BATCH_ACTIVE

set the active state of a batch modifies self.batch sets the equipment state of a batch (must be consistent with OMAC/PackML) modifies self.batch.equipment.state, extends self.batch.equipment.state.transitions

Parameters

Name Description

active

Decides whether to set the batch active (true) or inactive (false)

reason

Allows to declare a reason which will be stored in the batch record

state

state to set

time

timestamp of state change

Returns

    1. true, if successful (2) optional error

  • true, if successfull

Examples

local ret = SET_BATCH_ACTIVE(true, "batch active")

GET_BATCH_EQUIPMENT_STATE

Description

GET_BATCH_EQUIPMENT_STATE

returns the current batch equipment state ## Returns state, time: returns equipment state (1-17 or 0/-1 in case the state does not adhere to S88) and timestamp

IS_BATCH_RECORD_OPEN

Description

IS_BATCH_RECORD_OPEN

return the record open state ( if available ) ## Returns true if the batch record is open (state from batch.system)

IS_BATCH_RECORD_CLOSED

Description

IS_BATCH_RECORD_CLOSED return the record closed state ( if available )

Returns

true if the batch record is closed (state from batch.system), nil and error otherwise

GET_BATCH_ID

Description

GET_BATCH_ID

return the batch ID if availbale ## Returns (1) Batch ID as a string (2) optional error

GET_BATCH_DURATION

Description

GET_BATCH_DURATION

retrieves the duration of the batch (if known) ## Returns (1) duration as a numeric ms value (2) nil

SEND_BATCH

Description

SEND_BATCH

send the batch event to be stored in the database ## Returns - true or false - true on success, false on error.

ADD_EVENTS

Description

ADD_EVENTS

adds an event to an events-section

Parameters

Name Description

trackingScope

defined the part of the BPR where to add the events

eventConfigs

list of event configurations to add.

Returns

nil

Description

ADD_TRENDS

adds an trend to a trends-section

Parameters

Name Description

trackingScope

defined the part of the BPR where to add the events

trendConfigs

list of event configurations to add.

Returns

true on success, false otherwise

CLEAR_EVENTS

Description

CLEAR_EVENTS

clear all events in that trackingScope

Parameters

Name Description

trackingScope

Section of the BPR where to remove the events.

Returns

 true on success, false if not possible

Description

CLEAR_TRENDS

clear all trends in that trackingScope

Parameters

Name Description

trackingScope

Section of the BPR where to remove the trends.

Returns

 true on success, false if not possible

ADD_TREND_BATCH

Description

ADD_TREND_BATCH

add one trend config to a batch

Parameters

Name Description

trendCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_TREND_CURRENT_OPERATION

Description

ADD_TREND_CURRENT_OPERATION

add one trend config to the current operation

Parameters

Name Description

trendCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_TREND_CURRENT_EQ_PHASE

Description

ADD_TREND_CURRENT_EQ_PHASE

add one trend config to the current eq. phase

Parameters

Name Description

trendCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_TREND_CURRENT_EQ_STEP

Description

ADD_TREND_CURRENT_EQ_STEP

add one trend config to the current eq. step

Parameters

Name Description

trendCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_TREND_RECENT_OPERATION

Description

ADD_TREND_RECENT_OPERATION

add one trend config to the recent closed operation

Parameters

Name Description

trendCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_TREND_RECENT_EQ_PHASE

Description

ADD_TREND_RECENT_EQ_PHASE

add one trend config to the recent closed eq. phase

Parameters

Name Description

trendCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_TREND_RECENT_EQ_STEP

Description

ADD_TREND_RECENT_EQ_PHASE

add one trend config to the recent closed eq. step

Parameters

Name Description

trendCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_EVENT_BATCH

Description

ADD_EVENT_BATCH

add one event config to a batch

Parameters

Name Description

eventCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_EVENT_CURRENT_OPERATION

Description

ADD_EVENT_CURRENT_OPERATION

add one event config to the current operation

Parameters

Name Description

eventCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_EVENTS_CURRENT_EQ_PHASE

Description

ADD_EVENTS_CURRENT_EQ_PHASE

add one event config to the current eq. phase

Parameters

Name Description

eventCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_EVENTS_CURRENT_EQ_STEP

Description

ADD_EVENTS_CURRENT_EQ_STEP

add one event config to the current eq. step

Parameters

Name Description

eventCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_EVENTS_RECENT_OPERATION

Description

ADD_EVENTS_RECENT_OPERATION

add one event config to the recent closed operation

Parameters

Name Description

eventCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_EVENTS_RECENT_EQ_PHASE

Description

ADD_EVENTS_RECENT_EQ_PHASE

add one event config to the recent closed eq. phase

Parameters

Name Description

eventCfg

the configuration to add.

Returns

true on success, false if not possible.

ADD_EVENTS_RECENT_EQ_STEP

Description

ADD_EVENTS_RECENT_EQ_STEP

add one event config to the recent closed eq. step

Parameters

Name Description

eventCfg

the configuration to add.

Returns

true on success, false if not possible.

HAS_CURRENT_OPERATION

Description

HAS_CURRENT_OPERATION

return true if a current operation exists. ## Returns returns true if operation exists.

HAS_CURRENT_EQ_PHASE

Description

HAS_CURRENT_EQ_PHASE

return true if a current eq. phase exists. ## Returns returns true if operation exists.

HAS_CURRENT_EQ_STEP

Description

HAS_CURRENT_EQ_STEP

return true if a current eq. step exists. ## Returns returns true if operation exists.

GET_CURRENT_OPERATION

Description

GET_CURRENT_OPERATION

returns the current operation or nil. ## Returns returns the current operation or nil.

GET_CURRENT_EQ_PHASE

Description

GET_CURRENT_EQ_PHASE

returns the current eq. phase or nil. ## Returns returns the current eq. phase or nil.

GET_CURRENT_EQ_STEP

Description

GET_CURRENT_EQ_PHASE

returns the current eq. phase or nil. ## Returns returns the current eq. step or nil.

GET_RECENT_OPERATION

Description

GET_RECENT_OPERATION

returns the recent closed operation or nil. ## Returns returns the recent closed operation or nil.

GET_RECENT_EQ_PHASE

Description

GET_RECENT_EQ_PHASE

returns the recent closed eq. phase or nil. ## Returns returns the recent closed eq. phase or nil.

GET_RECENT_EQ_STEP

Description

GET_RECENT_EQ_STEP

returns the recent closed eq. step or nil. ## Returns returns the recent closed eq. step or nil.

CREATE_NEW_OPERATION

Description

CREATE_NEW_OPERATION

creates a new operation

Parameters

Name Description

time

timestamp for the cration

curopdata

data of the operation to create

reason

start reason for that operation

trendsCfgs

list of lists of trend configurations e.g. \{\{\{name="..", pens=\{…​},…​}}}

eventsCfgs

list of lists of event configurations e.g. \{\{\{name="..", type=..,…​}}}

Returns

  • opEnd, phaseEnd, stepEnd

  • opEnd==true if operation was ended.

  • phaseEnd==true if phase was ended.

  • stepEnd==true if step was eneded.

CREATE_NEW_EQ_PHASE

Description

CREATE_NEW_EQ_PHASE

creates a new eq. phase

Parameters

Name Description

time

timestamp for the cration

epdata

data of the eq. phase to create

reason

start reason for that operation

trendsCfgs

list of lists of trend configurations e.g. \{\{\{name="..", pens=\{…​},…​}}}

eventsCfgs

list of lists of event configurations e.g. \{\{\{name="..", type=..,…​}}}

Returns

  • true, phaseEnd, stepEnd

  • phaseEnd==true if phase was ended.

  • stepEnd==true if step was eneded.

CREATE_NEW_PHASE

Description

CREATE_NEW_PHASE

creates a new phase

Parameters

Name Description

time

timestamp for the cration

phdata

data of the phase to create

reason

start reason for that operation

Returns

true on success

CREATE_NEW_EQ_STEP

Description

CREATE_NEW_EQ_STEP

creates a new eq. step

Parameters

Name Description

time

timestamp for the cration

esdata

data of the eq. step to create

reason

start reason for that operation

trendsCfgs

list of lists of trend configurations e.g. \{\{\{name="..", pens=\{…​},…​}}}

eventsCfgs

list of lists of event configurations e.g. \{\{\{name="..", type=..,…​}}}

Returns

  • stepStart, stepEnd

  • stepStart==true if step started successfully.

  • stepEnd==true if previous step was eneded.

END_BATCH

Description

END_BATCH

ends the currently running BATCH

Parameters

Name Description

time

timestamp of batch end

reason

reason of the batch end.

Returns

  • opEnd, phaseEnd, stepEnd

  • opEnd==true if an operation was ended.

  • phaseEnd==true if an eq. phase was ended.

  • stepEnd==true if an eq. step was ended.

FINALIZE

Description

FINALIZE

this function finalizes the batch record before it gets detached

CLOSE_BATCH_RECORD

Description

CLOSE_BATCH_RECORD

closes a batch (data management-wise) Modifies: self.batch.equipment.state ## Returns (1) true, if the structural integrity exists, (2) optional error

END_OPERATION

Description

END_OPERATION

ends the currently running operation

Parameters

Name Description

time

timestamp of batch end

reason

reason of the batch end.

Returns

  • opEnd, phaseEnd, stepEnd

  • opEnd==true if an operation was ended.

  • phaseEnd==true if an eq. phase was ended.

  • stepEnd==true if an eq. step was ended.

END_CURRENT_EQ_PHASE

Description

END_CURRENT_EQ_PHASE

ends the currently running eq. phase

Parameters

Name Description

time

timestamp of batch end

opdate

data of the operation, under which the eq. phase runs.

reason

reason of the batch end

Returns

  • phaseEnd, stepEnd

  • phaseEnd==true if an eq. phase was ended.

  • stepEnd==true if an eq. step was ended.

END_CURRENT_PHASE

Description

END_CURRENT_PHASE

ends the currently running eq. phase

Parameters

Name Description

time

timestamp of batch end

opdate

data of the operation, under which the phase runs.

reason

reason of the batch end

Returns

returns true, if phase wan ended.

END_CURRENT_EQ_STEP

Description

END_CURRENT_EQ_STEP

ends the currently running eq. step

Parameters

Name Description

time

timestamp of batch end

opdate

data of the operation, under which the eq. step runs.

epdate

data of the eq. phase, under which the eq. step runs.

reason

reason of the batch end

Returns

  • stepEnd

  • stepEnd==true if an eq. step was ended.

WRITE_TO_TARGET

Description

WRITE_TO_TARGET

write data to target

Parameters

Name Description

time

timestamp of the write operation

data

data in the format: \{ \{res=\{v, q, t, vorg, eu, error}, def=<characteristics definition>, suc=true/false} }

def

the definition record from the characterisics map

batch

whether the returned value shall be assigned to the batch

operation

whether the returned value shall be assigned to the current operation

recphase

whether the returned value shall be assigned to the current recipe phase

eqphase

whether the returned value shall be assigned to the current equipment phase

eqstep

whether the returned value shall be assigned to the current equipment step

alt_target

an alternative target for the data

Returns

nil

WRITE_TO_BATCH

Description

WRITE_TO_BATCH

write data to the batch

Parameters

Name Description

time

timestamp of the write operation

data

data in the format: \{ \{res=\{v, q, t, vorg, eu, error}, def=<characteristics definition>, suc=true/false} }

def

the definition record from the characterisics map

WRITE_TO_CURRENT_OPERATION

Description

WRITE_TO_CURRENT_OPERATION

write data to the current operation

Parameters

Name Description

time

timestamp of the write operation

data

data in the format: \{ \{res=\{v, q, t, vorg, eu, error}, def=<characteristics definition>, suc=true/false} }

def

the definition record from the characterisics map

WRITE_TO_CURRENT_EQ_PHASE

Description

WRITE_TO_CURRENT_EQ_PHASE

write data to the current eq. phase

Parameters

Name Description

time

timestamp of the write operation

data

data in the format: \{ \{res=\{v, q, t, vorg, eu, error}, def=<characteristics definition>, suc=true/false} }

def

the definition record from the characterisics map

WRITE_TO_CURRENT_EQ_STEP

Description

WRITE_TO_CURRENT_EQ_STEP

write data to the current eq. step

Parameters

Name Description

time

timestamp of the write operation

data

data in the format: \{ \{res=\{v, q, t, vorg, eu, error}, def=<characteristics definition>, suc=true/false} }

def

the definition record from the characterisics map

WRITE_TO_RECENT_OPERATION

Description

WRITE_TO_RECENT_OPERATION

write data to the recent closed operation

Parameters

Name Description

time

timestamp of the write operation

data

data in the format: \{ \{res=\{v, q, t, vorg, eu, error}, def=<characteristics definition>, suc=true/false} }

def

the definition record from the characterisics map

Returns

returns true on success, and false on error

WRITE_TO_RECENT_EQ_PHASE

Description

WRITE_TO_RECENT_EQ_PHASE

write data to the recent closed eq. phase

Parameters

Name Description

time

timestamp of the write operation

data

data in the format: \{ \{res=\{v, q, t, vorg, eu, error}, def=<characteristics definition>, suc=true/false} }

def

the definition record from the characterisics map

Returns

returns true on success, and false on error

WRITE_TO_RECENT_EQ_STEP

Description

WRITE_TO_RECENT_EQ_STEP

write data to the recent closed eq. step

Parameters

Name Description

time

timestamp of the write operation

data

data in the format: \{ \{res=\{v, q, t, vorg, eu, error}, def=<characteristics definition>,

def

the definition record from the characterisics map

Returns

returns true on success, and false on error

AGGREGATE_BATCH

Description

AGGREGATE_BATCH

(re)calculate the aggregated value for characteristics on Batch level

Parameters

Name Description

open_only

if true, only characteristics which are still open are recalculated

Returns

returns false, if no self.batch is available, else true

AGGREGATE_RECENT_OPERATION

Description

AGGREGATE_RECENT_OPERATION

(re)calculate the aggregated value for characteristics of the recent operation

Parameters

Name Description

open_only

if true, only characteristics which are still open are recalculated

Returns

returns false, if no recent operation available, else true

AGGREGATE_RECENT_EQ_PHASE

Description

AGGREGATE_RECENT_EQ_PHASE

(re)calculate the aggregated value for characteristics of the recent equipment phase

Parameters

Name Description

open_only

if true, only characteristics which are still open are recalculated

Returns

returns false, if no recent operation available, else true

AGGREGATE_RECENT_EQ_STEP

Description

AGGREGATE_RECENT_EQ_STEP

(re)calculate the aggregated value for characteristics of the recent equipment step

Parameters

Name Description

open_only

if true, only characteristics which are still open are recalculated

Returns

returns false, if no recent operation available, else true

SET_PHASE_EQUIPMENT

Description

SET_PHASE_EQUIPMENT

set equipment for the current equipment phase

Parameters

Name Description

equipment

equipment configuration to add to the BPR

Returns

  • true if equipment was assigned

  • false if no current equipment phase exists.

SET_MATERIAL_TYPE

Description

SET_MATERIAL_TYPE

Set functions for the material type

Parameters

Name Description

matType

material type

SET_MATERIAL_TYPE_CODE

Description

SET_MATERIAL_TYPE_CODE

Set functions for the material type code

Parameters

Name Description

matTypeCode

material type code

SET_ERP_ORDER

Description

SET_ERP_ORDER

Set functions for the erp order

Parameters

Name Description

erpOrder

erp order

SET_MES_ORDER_ID

Description

SET_MES_ORDER_ID

Set functions for the mes order id

Parameters

Name Description

mesOrderId

mes order id

SET_MES_ID

Description

SET_MES_ID

Set functions for the mes id

Parameters

Name Description

mesId

mes id

GET_MATERIAL_TYPE

Description

GET_MATERIAL_TYPE

get functions for the material type ## Returns returns the material type

GET_MATERIAL_TYPE_CODE

Description

GET_MATERIAL_TYPE_CODE

get functions for the material type code ## Returns returns the material type code

GET_ERP_ORDER

Description

GET_ERP_ORDER

get functions for the erp order ## Returns returns the erp order

GET_MES_ORDER_ID

Description

GET_MES_ORDER_ID

get functions for the mes order id ## Returns returns the mes order id

GET_MES_ID

Description

GET_MES_ID

get functions for the mes id ## Returns returns the mes id

ADD_MESSAGE

Description

ADD_MESSAGE

adds a message to the batch record Modifies: self.batch.system.messages

Parameters

Name Description

time

the time of the message

text

The message text

Returns

returns true

GET_CONFIG

Description

GET_CONFIG

get function for the _config content. ## Returns returns _config

GET_STATE

Description

GET_STATE

get function for the _state content.

ADD_MONITORING_SESSION

Description

ADD_MONITORING_SESSION

adds a monitoring session

Parameters

Name Description

time

starttime of the monitoring

calls

calls entry

regular

regular entry

cfgversion

version of the BT configuration.

SET_SYSTEM_SETTINGS

Description

SET_SYSTEM_SETTINGS

configures the system settings.

Parameters

Name Description

config

BT configuration object (esi-batch-config)

NEW

Description

NEW

create new BPR

Parameters

Name Description

config

BT configuration object (esi-batch-config)

flags

flags for debugging and logging

time

starttime of the monitoring session and the BPR

reason

reason for BPR creation

active

active flag of the BPR

id

batchId of the BPR

Returns

BPR object or nil

TO_JSON

Description

TO_JSON

serialize the BPR to JSON.

Parameters

Name Description

config

configuration container, to include config information into the serialization

state

state container, to include state information into the serialization

Returns

 returns a serialized version of the BPR object.

TO_SHORT_JSON

Description

TO_SHORT_JSON

serialize the BPR to JSON, exclude some characteristics data to provide a short version

Parameters

Name Description

config

configuration container, to include config information into the serialization

state

state container, to include state information into the serialization

Returns

 returns a serialized version of the BPR object.