1. Introduction

1.1 Track changes (TM)

Version

Date of last change

1.001

1.10.2022

1.2 Terms, Abbreviations and Symbols (TM)

Entity

It represents the basic digital object that is visualized on the Factory Dashboard. It has two types of properties:

  • Technical ones that are represented by the Entity Type
  • Semantic, which are entered when creating or managing a digital point (name, position, shape, etc.)

A logical view of Entities from a definition point of view looks like this:  An Entity contains a set of Attributes and each Attribute can be defined using Parameters.

Entity Type

It represents the technical definition of an Entity, which consists of Attributes of type Entity.

Attribute (of Entity)

It represents one property of the Entity defined using the Entity Type (e.g. object color, temperature value, etc.)

Parameter (of Attribute)

It represents the possibility of setting up and specifying certain properties of the Attribute.

JSON format

JSON stands for Javascript Object Notation, and simply put, JSON is a javascript object written as a text string.

EDGE

It represents a place where input data from various devices and software are processed and converted into JSON message format.

IPsec

In computer science, IPsec (IP security) is the name of a security extension of the IP protocol based on the authentication and encryption of each IP datagram. In the OSI architecture, security is already at the network layer, and therefore transparently provides security to any transmission (any network application).

2. Definition and structure of digital Entities

This chapter deals with the creation and management of the definition of Entity Types using the JSON format. However, it is very important to emphasize a few basic rules of the rules.

  • JSON is a text format of object definition and therefore it can be edited in a text editor. To avoid the risk of bad syntax, we recommend using an online JSON editor that checks the syntax ( e.g. jsoneditoronline.org )
  • We recommend that attribute names should always be written in lowercase letters and should not contain spaces. You can replace spaces with underscores (e.g. number_of_pieces)
  • The Entity Type itself already supports more system languages, and the attribute description is translated through language tags ( ISO 639-1)

2.1 Definition of digital Entities

Individual digital points in the WorkSys system represent real-world objects. In order to capture all key properties (attributes), individual points are represented by Entity Type, which represents the given type of object.

Each type of object has its own structure that best describes its properties, which are represented by the Entity Type Attribute (e.g. Lamp).

An Entity represents a basic digital object that is visualized on the Factory Dashboard. It has two types of properties:

  • Semantic, which are entered when creating or managing a digital point (object name – HS3.13.54.2.7, position, shape, etc.)
  • Technical, which are represented by Entity Type represented by Attributes (dimm, Status of Luminaire, switch, Address of of Luminaire, Brightness of Luminaire, icon name, etc.)

The Entity type is displayed under the Entity name when viewing the entity detail on the Factory Dashboard. In the example shown above, the Entity Name is HS3.13.54.2.5 and the Entity Type is Luminaire.

In order to ensure sufficient flexibility ensuring the ability to modify the structure of the Entity, i.e. change or supplement Attributes, so the definition is saved in JSON format. What the structure of the JSON format of the Entity Type looks like is described in the following section Structure of digital entities.

2.2 Structure of digital Entities

The Entity Type structure is defined in JSON format. JSON stands for Java Script Object Notation, and simply put, JSON is a javascript object written as a text string. Thanks to this feature, the structure can be modified at any time with minimal restrictions. Another major advantage is that it can be done during normal system operation.

A sample structure for an entity type

Sample attribute structure (web editor jsoneditoronline.org)

In the textual detail of the JSON definition it looks like this.

				
					{
  "status": {
    "type": "telemetry",
    "unit": null,
    "trans": {
      "cs": "Stav",
      "de": "Status",
      "en": "Status",
      "sk": "Stav"
    },
    "value_type": "string",
    "value_default": "virtual",
    "attribute_rules": {
      "fill_color": [
        {
          "value": "#adadad",
          "condition": "virtual"
        },
        {
          "value": "#1eff00",
          "condition": "OK"
        },
        {
          "value": "#ff2a00",
          "condition": "NOK"
        }
      ]
    }
  },
  "icon_name": {
    "type": "static",
    "unit": "",
    "trans": {
      "cs": "Méno ikony",
      "de": "Symbolname",
      "en": "Icon name",
      "sk": "Meno ikony"
    },
    "value_type": "string",
    "value_default": "first-aid-kit"
  },
  "fill_color": {
    "type": "static",
    "unit": null,
    "trans": {
      "cs": "Barva výplně",
      "de": "Füllfarbe",
      "en": "Fill color",
      "sk": "Farba vyplnenia"
    },
    "rich_type": "color",
    "value_type": "string",
    "value_default": "#ff2a00"
  },
  "atribut_1": {
    "type": "static",
    "unit": "",
    "trans": {
      "cs": "Popis attributu 1 v cs jazyku",
      "de": "Popis attributu 1 v de jazyku",
      "en": "Popis attributu 1 v en jazyku",
      "sk": "Popis attributu 1 v sk jazyku"
    },
    "value_type": "string",
    "value_default": ""
  },
  "atribut_2": {
    "type": "telemetry",
    "unit": "",
    "trans": {
      "cs": "Popis attributu 2 v cs jazyku",
      "de": "Popis attributu 2 v de jazyku",
      "en": "Popis attributu 2 v en jazyku",
      "sk": "Popis attributu 2 v sk jazyku"
    },
    "value_type": "string",
    "value_default": ""
  },
  "atribute_date": {
    "type": "telemetry",
    "unit": " ",
    "trans": {
      "cs": "Popis attribute_date v cs jazyku",
      "de": "Popis attribute_date v de jazyku",
      "en": "Popis attribute_date v en jazyku",
      "sk": "Popis attribute_date v sk jazyku"
    },
    "rich_type": "datetime",
    "value_type": "number",
    "value_default": 0
  },
  "atribute_flow": {
    "type": "static",
    "unit": "",
    "trans": {
      "cs": "Popis attribute_flow v cs jazyku",
      "de": "Popis attribute_flow v de jazyku",
      "en": "Popis attribute_flow v en jazyku",
      "sk": "Popis attribute_flow v sk jazyku"
    },
    "value_type": "number",
    "value_default": "0.001"
  },
  "atribute_url": {
    "type": "static",
    "unit": " ",
    "trans": {
      "cs": "Popis attribute_url v cs jazyku",
      "de": "Popis attribute_url v de jazyku",
      "en": "Popis attribute_url v en jazyku",
      "sk": "Popis attribute_url v sk jazyku"
    },
    "rich_type": "url",
    "value_type": "string",
    "value_default": ""
  }
}

List of mandatory Attributes

Each Type of Entity has a so-called mandatory attributes so that everything works reliably in the system despite its enormous genetics and adaptability. Mandatory attributes are:

status

This attribute represents the state of objects from the point of view of operation. Its values can be as follows:

  • virtual – represents a ready digital object that is not yet connected to any incoming telemetry. The virtual value is also the default value
  • OK – represents a telemetry-recorded value representing a properly functioning digital object
  • NOK – represents a telemetry-recorded value representing a malfunctioning digital object (i.e. an object showing an anomaly with respect to the OK state)

icon_anme

This attribute expresses the technical name of the icon representing the given Entity Type.

fill_color

This attribute expresses the color value in hexadecimal representation of the given digital object. And it doesn’t matter if it’s an icon or a polygon.

Technically, the definition of mandatory fields in JSON format looks like this.

				
					{
  "status": {
    "type": "telemetry",
    "unit": null,
    "trans": {
      "cs": "Stav",
      "de": "Status",
      "en": "Status",
      "sk": "Stav"
    },
    "value_type": "string",
    "value_default": "virtual",
    "attribute_rules": {
      "fill_color": [
        {
          "value": "#adadad",
          "condition": "virtual"
        },
        {
          "value": "#1eff00",
          "condition": "OK"
        },
        {
          "value": "#ff2a00",
          "condition": "NOK"
        }
      ]
    }
  },
  "icon_name": {
    "type": "static",
    "unit": "",
    "trans": {
      "cs": "Méno ikony",
      "de": "Symbolname",
      "en": "Icon name",
      "sk": "Meno ikony"
    },
    "value_type": "string",
    "value_default": "first-aid-kit"
  },
  "fill_color": {
    "type": "static",
    "unit": null,
    "trans": {
      "cs": "Barva výplně",
      "de": "Füllfarbe",
      "en": "Fill color",
      "sk": "Farba vyplnenia"
    },
    "rich_type": "color",
    "value_type": "string",
    "value_default": "#ff2a00"
   },
//  ...
// ďalšie atribúty
//  ...
  }

Due to the effort to keep incoming data to individual Entities in a flawless state, it is not yet possible to change the structure of the Entity Type through the user interface. The new or modified Entity Type created by you will be uploaded to the system by the platform operator via the help desk request you entered. The change will be made free of charge, and this activity is already part of the monthly fee. At the same time, it will check the consistency of the changes and, if discrepancies are detected, it will alert you to potential risks and at the same time help you eliminate them.

Attribute structure

Parameters are used to define the attribute, with the help of which we can “model” the attribute in such a way that its use is simple and intuitive. In the following section, we will describe the individual parameters of the attribute:

type

(mandatory parameter)

This parameter defines the type of the Attribute from the point of view of the data acquisition method. It can have the following values:

  • static – data is entered and changed manually via Factory Studio
  • telemetry – the data will be sent as input telemetry from the device or software integration
  • computed – the field will be calculated from other parameters of Attributes and Attributes of other Entities in the system defined by type static or telemetry.

unit

(mandatory parameter)

This parameter defines the unit of the physical quantity of the given Attribute (e.g. pcs, %, €, etc.)

value_type

(mandatory parameter)

This parameter defines the type of variable stored in the given Attribute. It can acquire the following values:

  • string – text string
  • number – An integer or a number with decimal places.
  • bool – status flag i.e. boolean (true, false)

value_default

(mandatory parameter)

This parameter specifies the initial value of the attribute at creation. If the value_type is a number, then through the initial value we can set whether it is a whole number or a decimal. For example if the initial value is 0, it will be whole numbers. If the initial value is 0.01, it will be a value with decimal places.

trans

(mandatory parameter)

This parameter acts as an object and allows specifying translations of the Attribute name. For each language it is translated through language tags ( ISO 639-1)

				
					    "trans": {
      "cs": "Méno ikony",
      "de": "Symbolname",
      "en": "Icon name",
      "sk": "Meno ikony"
    },

value_min

(optional parameter)

It represents the setting of the lower limit of the possible value of the field in the case of input by the user via the web interface. This restriction only applies if the field type is numeric (integer).  

value_max

(optional parameter)

It represents the setting of the upper limit of the possible value of the field in the case of input by the user via the web interface. This restriction only applies if the field type is numeric (integer).  

rich_type

(optional parameter)

Extending the value_type parameter allows you to display a special UI element or formatting.

You can see more about this in the Digital Entity Attribute Types section.

2.3 Digital Entity Attribute Types

There are situations when it is necessary to bring the visual attribute even closer to the object of its use. For example, if you want a switch, you don’t want an Attribute where you change the value to 0 or 1. You want a switch (graphical component). This is always a challenge with such a generically designed system as WorkSys. In this section, we will show how WorkSys can easily solve these needs.

Precisely for this purpose, the rich_type Attribute Parameter was created, which in this way gives information to the developer, how to visualize the given Attribute on the web user interface.

As we already wrote in the previous chapter, expanding the value_type parameter by another rich_type parameter allows displaying a special element of the user interface or formatting. The rich_type parameter is optional and is added only if necessary.

The list of options is as follows:

color

This parameter is defined if value_type is “string”. The value of the Attribute is then the hexadecimal representation of the color (see Color HEX) 

				
					...
  "fill_color": {
    "type": "static",
    "unit": null,
    "trans": {
      "cs": "Barva výplně",
      "de": "Füllfarbe",
      "en": "Fill color",
      "sk": "Farba vyplnenia"
    },
    "rich_type": "color",
    "value_type": "string",
    "value_default": "#ff2a00"
  },
  ...

url

 

This parameter is defined if value_type is “string”. The Attribute value is then a URL link that is clickable as a hyperlink from the Entity detail.

				
					...
  "atribute_url": {
    "type": "static",
    "unit": " ",
    "trans": {
      "cs": "Popis attribute_url v cs jazyku",
      "de": "Popis attribute_url v de jazyku",
      "en": "Popis attribute_url v en jazyku",
      "sk": "Popis attribute_url v sk jazyku"
    },
    "rich_type": "url",
    "value_type": "string",
    "value_default": "https://online.worksys.space/worksys/"
  }
...

switcher

 

This parameter is defined if value_type is “bool“. The value of the Attribute is then a visual toggle.

				
					...
  "state_of_contactor": {
    "type": "telemetry",
    "unit": "",
    "trans": {
      "cz": "Stav stykače",
      "de": "Zustand des Schützes",
      "en": "State of contactor",
      "sk": "Stav stýkača"
    },
    "rich_type": "switcher",
    "value_type": "bool",
    "controllable": {
      "method": "set_command",
      "command": "switch",
      "maintenance_by": "local_energy"
    },
    "value_default": false
  },
  ...

datetime

This parameter is defined if value_type is “number“. Transforms the timestamp from the UNIX format ( Epoch format ) to the format required by the user. The output is formatted to e.g.: “YYYY-MM-DDTHH:mm:ssZ”, uses the formatting method from moment.js) 

				
					...
  "maintenance_date": {
    "type": "static",
    "unit": null,
    "trans": {
      "cz": "Datum údržby",
      "de": "Wartungsdatum",
      "en": "Maintenance date",
      "sk": "Dátum údržby"
    },
    "rich_type": "datetime",
    "value_type": "number",
    "value_default": 0
  },
  ...

duration

This parameter is defined if value_type is “number”. It transforms the result of the time difference in UNIX format (Epoch format) into an understandable expression of the time difference, e.g. 12:43:18.

The output is formatted to e.g.: “YYYY-MM-DDTHH:mm:ssZ”, it uses the method moment.js duration extension)

				
					...
  "duration": {
    "type": "telemetry",
    "unit": null,
    "trans": {
      "cz": "Doba trvání",
      "de": "Dauer",
      "en": "Duration",
      "sk": "Trvanie"
    },
    "format": "HH:mm:ss",
    "rich_type": "duration",
    "value_type": "number",
    "value_default": 0
  },
...

Dalším parametrom format môžete nastaviť očakávaný formát výstupu.

switch_profile_select

This parameter is defined if value_type is “string“. Shows selection to change switch profiles. A component without permissions is not active and cannot be controlled by the user.

				
					...
  "profile_line": {
    "type": "telemetry",
    "unit": null,
    "rich_type": "switch_profile_select",
    "value_type": "number",
    "controllable": {
      "method": "set_profile",
      "maintenance_by": "local_setup"
    },
    "value_default": null
  },
...

dimming_profile_select

 

This parameter is defined if value_type is “string“. Shows selection to change switch profiles. A component without permissions is not active and cannot be controlled by the user.

				
					...
  "dimming_profile": {
    "type": "telemetry",
    "unit": null,
    "rich_type": "dimming_profile_select",
    "value_type": "string",
    "controllable": {
      "method": "set_profile",
      "maintenance_by": "local_setup"
    },
    "value_default": ""
  },
...

attribute_rules

This parameter contains the conditions for the rules module. See: RuleEngine . It is most often used when setting the color visualization depending on the value of the Attribute.

				
					...
  "status": {
    "type": "telemetry",
    "unit": null,
    "trans": {
      "en": "Status",
      "sk": "Stav",
      "de": "Status",
      "cz": "Stav"
    },
    "value_type": "string",
    "value_default": "virtual",
    "attribute_rules": {
      "fill_color": [
        {
          "value": "#adadad",
          "condition": "virtual"
        },
        {
          "value": "#1eff00",
          "condition": "OK"
        },
        {
          "value": "#ff2a00",
          "condition": "NOK"
        }
      ]
    }
...

Or, for example, when interpreting the level of illumination, where the color is determined by an interval of values.

				
					...
"dimming": {
    ...
    "attribute_rules": {
        "fill_color": [
            {
              "condition": "(,50]",
              "value": "#fcfeff"
            },
            {
              "condition": "(50,80]",
              "value": "#f0f7ff"
            },
            {
              "condition": "(80,)",
              "value": "#deebf7"
            }
        ]
    }
    ...
}
...

controllable

This parameter enables the active authorization elements to insert conditions of additional authorization required directly in the user profile definition for active use of the given graphic element.

				
					...
    "controllable": {
      "maintenance_by": "lighting",
      "method": "set_command",
      "command": "dimming"
    },
...

With the other Parameters “method” and “command” we set the graphic element to be affected. Supported “command” values are:

  • dimming
  • switch
				
					...
    "controllable": {
      "maintenance_by": "lighting",
      "method": "set_command",
      "command": "switch"
    },
...

Rule Engine

Rule Engine sets entity attribute based on defined condition rules. The condition can be an interval rule (eg: (50,80]) or any valid JSON value to compare (eg: true, “notokstring”, 12, …)

  • ( <value> , <value> ) – open interval
  • [ <value> , <value> ] – closed interval (including endpoint)

2.4 Computed Attributes of digital entities

Computed attributes represent another possibility to quickly and effortlessly prepare data already during the process of processing them into the WorkSys system. It is a very efficient tool that allows you to asynchronously calculate a value from static or measured fields.

Typical examples of use are e.g. electricity consumption in local currency, where we calculate real financial costs through tariff prices and consumed energy.

It is similar, for example, when calculating OEE – Quality, where we can express the value of the parameter as a percentage through the ratio of qualitatively identical manufactured pieces / number of total manufactured pieces * 100.

You can certainly find other useful examples yourself, and then we will briefly show how to define it in the Entity Type. It is important to remember the basic facts:

  • it is applicable for Attributes with a parameter “type” : “computed”    
  • only Attributes with a parameter can be included in the field calculation “type” : “static” or “type” : “telemetry”
  • the values are calculated asynchronously, but they are always added up, so the calculation can sometimes take more than 1-2 seconds
  • it is also possible to count with the attributes of other entities, but the condition is that the Entities are in the same logical line (at the same or higher level).

If you use a context Attribute from the current Entity instance and the result of the expression depends on its value and needs to be evaluated every time the value changes, you must add a parameter computed_attributes with a reference to the name of the computed attribute to the definition of the dependent attribute.


The following example describes the calculation of costs in local currency for the Electricity Meter Entity that measures the Total Energy Attribute. The attributes in the “computed_attributes” section determine which Computed fields are to be calculated if a value is entered in the “total_energy” field.

Let’s look at the definitions of the Attributes of the selected fields contained in computed_attributes.

				
					...
  "ee_dane_var_EUR": {
    "type": "computed",
    "unit": "€",
    "trans": {
      "en": "Taxes - var.part",
      "sk": "Dane - var.časť",
      "de": "Steuern - var. Teil",
      "cz": "Daně - var. část"
    },
    "evaluation": {
      "context": {
        "mega": 1000000
      },
      "entity_ids": {
        "tarify": 864
      },
      "expression": "(entity.attributes['total energy'] / mega) * tarify.attributes['ee_dane_var']"
    },
    "value_type": "number",
    "value_default": 0
  },
  },
				
			
				
					...
  "total_energy": {
    "type": "telemetry",
    "unit": "Wh",
    "trans": {
      "en": "Total Energy",
      "sk": "Celková Energia",
      "de": "Gesamtenergie",
      "cz": "Celková Energie"
    },
    "value_type": "number",
    "value_default": 0,
    "computed_attributes": {
      "ee_dane_var_EUR": {},
      "ee_total_power_kW": {},
      "ee_total_power_EUR": {},
      "ee_odchylka_var_EUR": {},
      "ee_poplatky_tps_EUR": {},
      "ee_poplatky_tss_EUR": {},
      "ee_obchodnik_var_EUR": {},
      "ee_komodita_dokup_EUR": {},
      "ee_total_power_target_kW": {},
      "ee_distribucia_el_njf_EUR": {},
      "ee_distribucia_var_vn_EUR": {},
      "ee_distribucia_straty_vn_EUR": {}
    }
...

The following example shows the definition of an Attribute with a conversion to kW, also an Attribute contained in computed_attributes. 

				
					...
  "ee_total_power_kW": {
    "type": "computed",
    "unit": "kW",
    "trans": {
      "en": "Total Power in kW",
      "sk": "Celkový Výkon v kW"
    },
    "evaluation": {
      "context": {
        "kilo": 1000
      },
      "expression": "entity.attributes['total_power'] / kilo"
    },
    "value_type": "number",
    "value_default": 0
  },
...

If necessary, it is also possible to define local variables via the “context” parameter (such as the kilo variable). The calculation formula itself is defined using the “expression” parameter.

				
					...
 "context": {
    "kilo": 1000
  },
  "expression": "entity.attributes['total_power'] / kilo"
...

If it is necessary to include in the calculation an Attribute of an entity other than the one defined, it is possible to use the Parameter “entity_ids“, where you define the ID of the selected Entity. (see following image.)

				
					...
    "entity_ids": {
      "tarify": 864
      },
...

In case you need to process more entities, the “entity_ids” field can be defined as an object with multiple values. (See the following picture)

				
					...
      "entity_ids": {
        "entities": [
          890,
          891,
          892,
          893,
          894,
          904,
          905
        ]
      },
...

Then the order of the objects in the “entities” definition is taken into account in the “expression” parameter in the patterns.

				
					...
      "expression": "(entities[0].attributes['total power'] + entities[1].attributes['total power'] + entities[2].attributes['total power'] + entities[3].attributes['total power'] + entities[4].attributes['total power'] + entities[5].attributes['total power'] + entities[6].attributes['total  power'] + entities[7].attributes['total power']) / kilo"
...

3. Sending data to WorkSys

In the previous chapters, we showed how to correctly define objects, and in this one we will show how to send data to them correctly.

3.1 Structure of sent data

Data is sent to the system via messages in JSON format using the MQTT protocol. The basic structure of the data sent is as follows:

object identifier

It is a unique object identifier that is unique in the system. It is not possible for the system to have two identical object identifiers. The ej value can be copied from Factory Studio from the TB name field.

ts

It represents a time stamp assigning the values in the “values” section to the timeline according to the time of their creation. Data is entered in UNIX format (Epoch format).

values

It represents the list and values of the Attributes sent to the given timestamp.

Sample JSON message structure

				
					{
  "<object identifier>": [
    {
      "ts": <timestamp>,
      "values": {
        ...
      }
    }
  ]
}

An example of a report format for a parking space

				
					{
  "1092": [
    {
      "ts": 1666178890739,
      "values": {
        "available": false,
        "status": "OK",
        "vehicle_type": "Car",
        "start_time": 1666155187000,
        "duration": 23703
      }
    }
  ]
}

3.2 Principles of sending data

Data is sent to the system from the level of EDGE devices. It is a place where data can be pre-prepared, combined in various ways and a report of the required format can be constructed.

Messages are sent from EDGE over an IPsec secure connection. In computer science, IPsec (IP security) is the name of a security extension of the IP protocol based on the authentication and encryption of each IP datagram. In the OSI architecture, security is already at the network layer, and therefore transparently provides security to any transmission (any network application).

Security mechanisms of higher layers (above TCP/UDP protocols, where TLS/SSL, SSH, etc. work) require support inside applications. IPsec is defined in several dozens of RFCs issued by the IETF – RFC 2401 and RFC 2411 are the main ones.

IPsec uses cryptographic security services to protect communications over the IP protocol. It provides data verification, data origin, data integrity, confidentiality (encryption) and protection against replay attacks (see replay attack).

This is also one of the proofs that the security of the data sent and stored is taken very seriously, and measures have already been taken at the system architecture level so that the WorkSys system meets the highest security standards.

See the following image for better understanding.