esi-examples

A library for setting up various examples to demonstrate various features of the system or for showcasing the capabilites of built-in Lua libraries.

The following esi-examples can be installed using this library:

  • DemoData: Creates example data to demonstrate the use of I/O Model, KPI Model and ISA-95 Equipment Model.

  • RemoteMongoDB: Except for the local Data Store for logfiles, all other Data Stores will be redirected to a remote standalone Mongodb server. Only "simple" standalone connections are currently supported: No security settings, no encryption, no replica sets!

  • SendMail: Sends an HTML-formatted test eMail to a given recipient.

  • WeatherData: Fetches live weather data and weather warnings from the German Weather Service and parses the returned html data.

  • BatchTracker: Simulates a bread factory to illustrate various uses of the batch tracker feature.

  • ODBC: Accesses SQL databases with Lua scripts.

  • USAirportData: Another example for HTTP requests, including XML parsing.

  • JSON: Converts JSON data into system objects.

  • OEESimulation: Creates a complete simulation for OEE functionality.

  • WebStudio Demo Data: Creates the Demo Data for the WebStudio widgets.

  • WebStudio OEE Dashboard: Adds the OEE Dashboard to the WebStudio index page.

Changes

Version Date Description s:i Release

1.1.0

2022-05-01

General availability

1.84


Dependencies

library version inmation core library

esi-examples-demodata

0.1.1

yes

esi-examples-mongodb

0.1.1

yes

esi-examples-smtp

0.1.1

yes

esi-examples-weatherdata

0.1.1

yes

esi-examples-batch-tracker

0.1.1

yes


Available functions

All functions have to be called according to the ESI standard, using colons, e.g.

lib:FUNCTIONNAME(params)
Function Description

SETUP

Sets up one or more requested examples


SETUP

Function head:

lib:SETUP( { {"example", "parameter"} [, {"example2", "parameter2"}, {...} ] } )

Installs the chosen example in a folder named Examples underneath the system core object.

The function expects a multi-dimensional Lua table containing the name of the example(s) to be installed and possible additional parameters.

Available examples:

Example Paramaters

DemoData

iomodel, kpimodel, isamodel or data for all models

RemoteMongoDB

 — 

SendMail

 — 

WeatherData

 — 

BatchTracker

 — 

ODBC

 — 

USAIRPORTDATA

 — 

JSON

 — 

OEESimulation

 — 

WebStudio Demo Data

 — 

WebStudio OEE Dashboard

 — 


Valid Lua usages:

local exm = require('esi-examples')
--
-- Populate I/0 Model:
exm:SETUP({{"demodata", "iomodel"}})
--
-- Note that the following options all implicitly create I/O model data if it not already exists!
--
-- Create random historical data for objects in I/O model:
exm:SETUP({{"demodata", "history"}})
--
-- Populate I/O Model and create random historical data in one step:
exm:SETUP({{"demodata", "iomodel", "history"}})
--
-- Populate KPI Model:
exm:SETUP({{"demodata", "kpimodel"}})
--
-- Populate ISA-95 Equipment Model:
exm:SETUP({{"demodata", "isamodel"}})
--
-- Do all of the above in one simple step:
exm:SETUP({{"demodata", "all"}})
--
-- Creates an action itm that reconfigures the local data stores to use a different MongoDB server:
exm:SETUP({{"RemoteMongodb"}})
--
-- Creates an action item that can send HTML formatted eMails:
exm:SETUP({{"SendMail"}})
--
-- Creates a sample folder for live DWD weather data:
exm:SETUP({{"WeatherData"}})
--
-- Creates a sample folder for demonstrating the batch tracker feature.
exm:SETUP({{"BatchTracker"}})
--
-- Creates a sample folder for live US airport data.
exm:SETUP({{"usairportdata"}})
--
-- Creates a sample folder for demonstrating the useage of ODBC.
exm:SETUP({{"odbc"}})
--
-- Creates a sample folder for demonstrating JSON processing.
exm:SETUP({{"json"}})
--
-- Creates all DataStudio demo data and the sendmail example in one call:
exm:SETUP({{"demodata","all"},{"sendmail"}})
--
-- Creates the demo data for WebStudio widgets.
exm:SETUP({{"webstudio"}})
--
-- Creates the folders in the I/O Model which are necessary for the OEE Dashboard in WebStudio.
exm:SETUP({{"oeedashboards"}})

DemoData

Description

This creates various sets of Demo Data for training and testing purposes. Demo data and objects for I/O Model, KPI Model and ISA-95 model, including historical data, can be created.

Installation

local exm = require('esi-examples')
--
-- Populate I/0 Model:
exm:SETUP({{"demodata", "iomodel"}})
--
-- Note that the following options all implicitly create I/O model data if it not already exists!
--
-- Create random historical data for objects in I/O model:
exm:SETUP({{"demodata", "history"}})
--
-- Populate I/O Model and create random historical data in one step:
exm:SETUP({{"demodata", "iomodel", "history"}})
--
-- Populate KPI Model:
exm:SETUP({{"demodata", "kpimodel"}})
--
-- Populate ISA-95 Equipment Model:
exm:SETUP({{"demodata", "isamodel"}})
--
-- Do all of the above in one simple step:
exm:SETUP({{"demodata", "all"}})

RemoteMongoDB

Description

This example provides an Action Item with a Lua script to point local data stores to a different Mongodb instance.

Installation

The example can be loaded from a Console Display in DataStudio with the following simple Lua code:

local exm = require('esi-examples')
exm:SETUP({{"RemoteMongoDB"}})

The code above will create a folder structure "Examples/Remote Mongodb" underneath the Core object in I/O Model. In this folder will be a single, disabled Action Item named "Repoint Data Stores". This Action Item contains a Lua script body that illustrates how to repoint the several of the standard data stores to a different standalone Mongodb server.

  • Note: Only "simple" standalone connections are supported - no security settings, no encryption, no replica sets!

SendMail

Description

This example connects to an SMTP server to send emails using the esi-SMTP library

Installation

The example can be loaded from a Console Display in DataStudio with the following simple Lua code:

local exm = require('esi-examples')
exm:SETUP({{"SendMail"}})

The code above will create a folder structure "Examples/Sendmail" underneath the Core object in I/O Model.

WeatherData

Description

The Weather Data example uses the esi-lcurl-http-client library to fetch weather data from the German Weather Service ("DWD - Deutscher Wetterdienst") servers.

This is an official public server and the data is made available in an HTML file that can be downloaded from this URL: https://www.dwd.de/DWD/wetter/aktuell/deutschland/tabelle/wx_brd_akt.html

A Lua script parses this HTML file and then creates objects in I/O model that contain this data.

Installation

The example can be loaded from a Console Display in DataStudio with the following simple Lua code:

exm=require("esi-examples")
exm:SETUP({{"WeatherData"}})

The code above will create a folder structure "Examples/Weather Data" underneath the Core object in I/O Model. After the initial setup, the Fetch Weather Data object is disabled. To start fetching data, enable this object.

BatchTracker

Description

In order to illustrate the use of the batch tracker feature, an example use case was chosen to is relatively easy to comprehend for everyone. A bread factory represents a scenario everybody can relate to, and baking simple wheat bread, for example, is something everybody can do in their kitchen at home.

Installation

The example can be loaded from a Console Display in DataStudio with the following simple Lua code:

exm=require("esi-examples")
exm:SETUP({{"batchtracker"}})

The code above will create a folder structruce "Examples/Bread Factory" underneath the Core object in I/O Model, and it will also create an enterprise structure in the ISA95 Equipment Model.

After the initial setup, the simulated bread factory will not be active and its objects in I/O model will appear disabled. To activate the simulation, enable the "00 MES" object.

USAirportData

The FAA US Airport data web service used in this example is no longer servicing http requests and will return an error when called. However, the example is being left up as it demonstrates how to call an http web service using Lua and how to process a returned XML data file in the system. The Lua script used in this example can be modified to work with other web services.

Description

This example uses the esi-lcurl-http-client library to fetch data in XML format from an official US government server: https://soa.smext.faa.gov/asws/api/airport/status/

A Lua script parses the XML file and then creates an object representing the data in I/O model.

Installation

The example can be loaded from a Console Display in Data Studio with the following simple Lua code:

exm=require("esi-examples")
exm:SETUP({{"usairportdata"}})

The code above will create a folder structruce "Examples/US Airport Data" underneath the Core object in I/O Model.

Using the US airport data example

The sample automatically initializes itself and directly begins downloading the data and creating the I/O model objects for each US airport. On installation the US Airport Data > Create Airport KPI Model object is disabled, so the related structure in the KPI Model is not created on installation. To create this structure automatically in the KPI Model, enable said object.

ODBC

Description

This example demonstrates ODBC access using Lua scripts.

Installation

The example can be loaded from a Console Display in Data Studio with the following simple Lua code:

exm=require("esi-examples")
exm:SETUP({{"odbc"}})

The code above will create a folder structruce "Examples/ODBC" underneath the Core object in I/O Model.

Using the ODBC example

The created objects contain Lua script bodies to showcase the use of ODBC.

JSON

Description

This example demonstrates JSON processing using Lua scripts.

Installation

The example can be loaded from a Console Display in Data Studio with the following simple Lua code:

exm=require("esi-examples")
exm:SETUP({{"json"}})

The code above will create a folder structruce "Examples/JSON" underneath the Core object in I/O Model.

Using the JSON example

The created objects contain Lua script bodies to showcase JSON processing.

OEESimulation

This example provides a quick way to get an impression of the OEE functionality of the system.

Installation

The example can be loaded from a Console Display in Data Studio with the following simple Lua code:

exm=require("esi-examples")
exm:SETUP({{"oeesimulation"}})

The code above will create a folder structure 'Examples/OEE' underneath the Core object in I/O Model. This structure hosts the OEE Simulator Action Item and all objects providing simulated data. In the ISA-95 Equipment Model 'The OEE Demo Enterprise' hierarchy will be added. This is the simulation enterprise with all it’s subsections. The OEE Equipment Monitor and the configuration objects are located in this structure (see below). When the OEE Equipment Monitor is running, the Output Objects for the OEE indices will also be found there, underneath the OEE Equipment Monitor object. In the KPI Model the 'OEE Demo KPI Root Node' is generated.

Using the OEE Simulation

The OEE Simulator Action Item in the I/O Model starts producing simulation data on installation.

To launch the calculation of OEE Indices for this simulation, go to the ISA-95 Equipment Model and select the OEE Equipment Monitor object which is located at …​

 - The OEE Demo Enterprise
   - The OEE Demo Site
     - The OEE Demo Area
       - The OEE Demo Cell
         - *The OEE Demo Equipment Monitor*

... and in the Properties Panel go to the Common section. For the Processing Mode property select 'Production' from the drop-down list, then click 'Apply' for the Properties Panel.

WebStudio Demo Data

The WebStudio Demo Data, which is used for the initial configuration of widgets which are newly added to a WebStudio Compilation, can be easily added to the system.

Installation

To add the WebStudio Demo Data, run the following Lua code in the Console Display in DataStudio:

local exm = require('esi-examples')
exm:SETUP({{"webstudio"}} )

When this code is executed, a new branch Examples/WebStudio will be added underneath the Core object in the I/O Model tree. The objects in the WebStudio folder provide the demo data used for the initial configuration for widgets newly added to a WebStudio Compilation.

WebStudio OEE Dashboard

This section addresses how the tree structure necessary for storing data for the WebStudio OEE Dashboard can be easily added to the system.

A folder called OEE Main forms the starting point of this branch. Where this folder is located depends on the selected installation option and the system configuration. This will be addressed in detail in the individual installation options.

Default Installation (Enabling the WebStudio Index Page)

In the default installation, the OEE Dashboard will be added to the WebStudio webapps:webstudio:UserDocs/webstudio-basics.adoc#index-page automatically. If this index page is already enabled, the OEE Main folder will be created underneath the existing WebStudio folder. Otherwise the default variant of the OEE Dashboard script automatically enables the WebStudio index page by generating a WebStudio folder underneath the Core object.

local exm = require('esi-examples')
exm:SETUP({{"oeedashboards"}} )

Installation Without Enabling the WebStudio Index Page

If the OEE Dashboard should be installed without enabling the WebStudio index page, the enableIndexPage parameter needs to be set to false (default value is true). In this case the OEE Dashboard can be accessed via the URL (see below).

Therefore run the following snippet in DataStudio’s Console Display to install the OEE Dashboard:

local exm = require('esi-examples')
exm:SETUP({{"oeedashboards",{enableIndexPage=false}}} )

When this code is executed, the exact location of the 'OEE Main' folder depends on which other folders are already available in the I/O Model.

If a folder called 'WebStudio' exists in the main branch of the I/O Model tree, 'OEE Main' will be created inside this folder. Otherwise the setup looks for a folder called 'Examples'. If this exists, the 'OEE Main' folder will be created inside 'Examples/WebStudio/'. If neither a 'WebStudio' nor 'Examples' folder exists in the main branch, the 'OEE Main' folder will be created underneath the Core object.

When the OEE Dashboard is opened in WebStudio, the system traverses the I/O Model from top to bottom, looking for one of the following folders.

  • /system/core/OEE Main

  • /system/core/WebStudio/OEE Main

  • /system/core/Examples/WebStudio/OEE Main

The first of these folders which is found AND has the Custom Options > Custom String property set to OEE_MAIN will be used for the OEE Dashboard. This value is automatically set on installation.

If a possible location of higher priority is added to the I/O Model later, and this OEE Dashboards setup script is launched again, another OEE Main folder will be created at the new, higher, level. By default this will then be used by the OEE Dashboard. In this case, changing the Custom Options > Custom String property of a OEE Main folder to anything but OEE_MAIN, can be used to force the system to ignore this folder and use the next OEE Main folder in the hierarchy.

Installation Without Entry in the WebStudio Index Page (Custom Location)

If the OEE Dashboard is not meant to show up in the WebStudio index page but be accessible via the URL, it can be installed to a custom location. This alternative location is defined by the basePath parameter as in the example below.

local exm = require('esi-examples')
exm:SETUP({{"oeedashboards",{basePath="/System/Core/myBaseFolder"}}} )

Instead of installing to a custom location, the OEE Dashboard can also be hidden from the WebStudio index page.

Opening the OEE Dashboard via URL

To open the OEE Dashboard in WebStudio directly, use the URL below, but replace <hostname_webapi> and <port> with the actual values for your installation. You probably also have to adjust the argument for the ctx parameter in the URL. This parameter contains the path to the OEE Main folder discussed above. In this example, this path is: /System/Core/WebStudio/OEE Main.

 http://<hostname_webapi>:<port>/apps/webstudio/?ctx=/System/Core/WebStudio/OEE Main&lib=syslib.app-webstudio-oee&func=dashboard_compilation

Opening the OEE Dashboard From Other Dashboards in WebStudio

The functionality to open the OEE Dashboard can be integrated into other dashboards in WebStudio by adding a function action as in the following example:

{
    "type": "button",
    "name": "Button",
    "label": "Load OEE Demo",
    "actions": {
        "onClick": {
            "type": "load-compilation",
            "subType": "function",
            "ctx": "/system/Core/Examples/WebStudio/OEE Main",
            "func": "dashboard_compilation",
            "lib": "syslib.app-webstudio-oee"
        }
    }
}

Hiding the OEE Dashboard from WebStudio

The OEE Dashboard can be hidden from WebStudio by setting the Custom Options > Custom String property for all OEE Main folders in the system to anything other than OEE_MAIN. Set this property back to OEE_MAIN to make the OEE Dashboard visible in WebStudio again. If this property is set to OEE_MAIN for more than one OEE Main folder, the highest in the I/O Model hierarchy is used.