Transformations

This guide describes how to add a transformation to a given Type in Manufacturing Data Engine (MDE).

Choosing a transformation

There are several transformations available in MDE. The default configuration package provides two transformations that can be associated to any of the Types available in that default configuration package:

Group Event Change Transformation: This Transformation monitors any field in a Tag or a group of Tags and generates an event every time the monitored values change in any of those Tags. This Transformation can be associated to a Type of any Archetype.
Windowing Transformation: This Transformation applies a Windowing function to all Tags of a Type. Windowing refers to the summarization of multiple records over a period of time in a single record. The Windowing Transformation can be associated to any Type of any Archetype. It can summarize the records of Tags from 1 minute to 60 minutes. The result of the Transformation is a raw message containing the summary values for the value expression during the selected period of time.

The default configuration package provides the Message Classes, Parsers and Types required to process the raw messages emitted by these two transformations. The two Types provided to process the raw messages generated by each Transformation are the following:

group-event-change-records: destination Type for the output messages of Group Event Change Transformation.
window-transformation-records: destination Type for the output messages of Windowing Transformation.

To activate a Transformation, the specified Transformation should be selected in the Type web interface or associated to the Type using the Configuration API endpoint.

Listing available transformations

To explore the list of available transformations in any MDE system follow these steps:

REST

There is a dedicated Configuration Manager API endpoint to list the available transformations:

GET /configuration/v1/transformations

It returns the following JSON with the available Transformations and its capabilities:

{
  "transformations": [
    {
      "name": "eventChange",
      "displayName": "MDE Event Change",
      "description": "Monitors the value of one or more tag that has a common group key. Fires an event whenever any of the contributing tags changes its value",
      "disabled": false,
      "sample": {
        "keyExpression": {
          "displayName": "Key Expression",
          "description": "A SpEL expression that extracts the group key from the MDE message.proto which groups one or more tags as one unit whose values will be monitored for a change. The key must evaluate to a string",
          "value": "#message['tagName']"
        },
        "valueExpression": {
          "displayName": "Value Expression",
          "description": "A SpEL expression that extracts the value from the MDE message.proto to be monitored for a change. The value must evaluate to a string",
          "value": "#message['data']['numeric'].toString()"
        }
      }
    },
    {
      "name": "window",
      "displayName": "MDE Numeric Value Windowing",
      "description": "Create a periodic stats event that provides values such as average, min, and max for an expression that extracts a numeric value from the tag messages",
      "disabled": false,
      "sample": {
        "durationMinutes": {
          "displayName": "Window Duration in Minutes",
          "description": "A positive integer that represents how long the window will summarize events before producing the summary tag, this is in the granularity of minutes and it cannot be higher than 2 hours",
          "value": "1"
        },
        "valueExpression": {
          "displayName": "Value Expression",
          "description": "A SpEL expression that extracts the value from the MDE message.proto to be used as the numeric value of the tags that will be summarized. The value must evaluate to a number, and it's internally out",
          "value": "#message['data']['numeric']"
        },
        "id": {
          "displayName": "Window Unique ID",
          "description": "A unique ID that represents this instance of the window transformation, this should be unique if you are adding multiple instances of the window transformation to the same type",
          "value": "1-min-window"
        }
      }
    }
  ]
}

Console

Using the web interface, under the 'Types' section, open the Edit type version menu for a given type and expand the Transform & connect section of the panel.

Transformation list

Associating a transformation to a Type

Associating any existing Type to an available Transformation, transforms all Tags of that Type. The result of the transformation is ingested as new Tags in MDE of the Transformed Types. The transformed Tagnames have a new name derived from the original Tagname and the name of the transformation.

These are the steps to associate a Type to a Transformation:

REST

To associate a transformation to a give Type call the PATCH method in this endpoint of the Configuration Manager API:

PATCH /configuration/v1/types/TYPE_NAME/versions/VERSION_NUMBER

The Body of the request should contain the list of Transformations to be attached to the Type and the value for its Configuration Parameters:

{
    "transformations": [
        {
            "window": {
                "id": "WINDOW_TRANSFORMATION_IDE",
                "durationMinutes": WINDOW_TRANSFORMATION_MINUTES,
                "valueExpression": "VALUE_EXPRESSION_VALUE"
            }
        },
        {
            "eventChange": {
                "keyExpression": "KEY_EXPRESSION_VALUE",
                "valueExpression": "VALUE_EXPRESSION_VALUE"
            }
        }
    ]
}

Replace the following items in the previous sample call:

TYPE_NAME: the name of the Type to be modified.
VERSION_NUMBER: the version of the Type to be modified.

Replace the following items in the Body for configuring a Window Transformation:

WINDOW_TRANSFORMATION_ID: a unique identifier of the transformation that will also be attached to the original tag names after being processed by the transformation.
WINDOW_TRANSFORMATION_MINUTES: the duration, in minutes, of the window to apply
VALUE_EXPRESSION_VALUE: the element of the tag proto that will be monitored as value field. For a numeric default tag is #message['data']['numeric'].

Replace the following items in the Body for configuring an Event Change Transformation:

KEY_EXPRESSION_VALUE: the element in the tag proto that is used to group tags that should be monitored together. To monitor a single tag should be #message['tagName']
VALUE_EXPRESSION_VALUE: the element in the tag proto that is used as to monitor the value change. Needs to resolve to a String. In a numeric default tag is #message['data']['numeric'].toString().

Console

To associate a Transformation to a Type open the 'Edit type version' web interface section in the 'Type' tab.
Expand the 'Transform & connect' section:
To add a Transformation select the required transformation from the list and click 'ADD':
Then proceed to provide the required parameters and click 'SAVE':

For the Window Transformation the parameters are:

WINDOW_TRANSFORMATION_ID: a unique identifier of the transformation that will also be attached to the original tag names after being processed by the transformation.
WINDOW_TRANSFORMATION_MINUTES: the duration, in minutes, of the window to apply
VALUE_EXPRESSION_VALUE: the element of the tag proto that will be monitored as value field. For a numeric default tag is #message['data']['numeric'].

For the Event Change Transformation the parameters are:

KEY_EXPRESSION_VALUE: the element in the tag proto that is used to group tags that should be monitored together. To monitor a single tag should be #message['tagName']
VALUE_EXPRESSION_VALUE: the element in the tag proto that is used as to monitor the value change. Needs to resolve to a String. In a numeric default tag is #message['data']['numeric'].toString().