Declarative Scripting Made by ESI

This document explains the principles of Declarative Scripting support, being part of the overall ESI ecosystem. We will also refer to ESI Rails or esi-r which is also the required prefix for any ESI Rails library added to this repository.

We quote the Wikipedia article about the famous Ruby on Rails programming language, in order to emphasize on the key concepts:

[…​] Rails emphasizes the use of other well-known software engineering patterns and paradigms, including convention over configuration (CoC), don’t repeat yourself (DRY), and the active record pattern.

The active record pattern plays no role in an inmation environment, as we (luckily) interact with native in-memory objects instead of database tables. CoC and DRY instead are very relevant for the esi-r concepts.

Convention over Configuration (CoC)

This software engineering pattern is explained here. We could also translate it with "Fast, reliable and repeatable results instead of highest flexibility". The flexibility we sacrifice is still available by using barebone Lua or common esi script style in places where a higher degree of flexibility is required, or no matching esi-r library exists. Due to the fact that most inmation systems are running in an industrial context, Speed-to-Production and reliability are very important aspects. Another advantage of keeping the complexity low is that external code generators can be written very quick, so that system:inmation users may enter the next level of automation. The "repeatable" aspect is also of highest importance, as large industrial environments usually have "things" to which software logic can be applied, by the hundreds, thousands and even higher counts.

Don’t Repeat Yourself

This software engineering pattern is explained here. The DRY paradigm protects developers and engineers to invest their precious time into the wrong thing. Who wants to be in the world of WET programming, commonly known as "write everything twice"? Seriously, I was there myself. Too often. Let us all be DRY now.

The ESI way

In the following section, we list the benefits and the requirements esi-r brings with itself.

Use Case-centric Scripts

esi-r libaries implement ready-made scripts for particular use cases. Such a use case can be: - Configuring 1000 assets in one go from a metadata TableHolder in the I/O Model onto the enterprise:inmation dashboard system, linking it with the 1000 corresponding data points and have provided dozens of users with the right data views in seconds. - Fetching a time series record from an external plant historian and do some statistical analysis on it, then write the result back to one or many inmation objects for historization purpose - Reading out actual batch records from an underlying system of different types and delegate it to some specific complex data processor in system:inmation (which can be esi-r, but must not)

Scripts with no branches and no loops (and very little complexity)

esi-r scripts (scripts using esi-r libraries exclusively) must be written in what we call the "typewriter mode":

  1. There is one top-down flow

  2. There are no separate functions whatsoever

  3. There are no branches, no if, no then, no else

  4. There are no loops, no repeat, no while

  5. There are esi-r libary calls exclusively

Non-adherence to one of the five rules above is always possible, but then the script is not considered to be esi-r. No excuses.

Benefits

There is a long list of benefits:

  • All esi-r scripts share the same error handling, which includes logging, E-mailing, table staging and notifications through the enterprise:inmation dashboard system (in case of any failure)

  • esi-r scripts turn simple ActionItems or GenericItems into full-blown use case objects, supplying historized variables for performance tracking, configurational control etc.

  • esi-r scripts are self-explaining to a very high degree

  • esi-r scripts are written in self-protection mode in order to avoid "the usual mistakes" when creating scripted object logic in system:inmation. An example is to limit the execution frequency, throttle data calls, set the right auxliary state management and persistence options for child objects etc.

  • esi-r scripts serve automatically into use case monitoring in an enterprise:inmation environment. They create historizing KPI source objects and the corresponding dashboard elements, so that system administrators have all options to monitor the error-free execution of the scripts, or be very fast with the root cause analysis, in case something should go wrong.

  • esi-r code can be easily machine-generated, e.g. from configurational metadata in Excel, database tables or other means

A first example

todo