# Add a transformation to a type

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:

```json
{
  "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](https://docs.cloud.google.com/static/manufacturing-data-engine/images/list-transformations-types-ui.png)

## 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*:

```json
{
    "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

1. To associate a *Transformation* to a Type open the **'Edit type version'**
   web interface section in the **'Type'** tab.

2. Expand the **'Transform \& connect'** section:

   ![Transformation list](https://docs.cloud.google.com/static/manufacturing-data-engine/images/ui-transformation-type.png)
3. To add a *Transformation* select the required transformation from the list
   and click **'ADD'**:

   ![Transformation ADD](https://docs.cloud.google.com/static/manufacturing-data-engine/images/add-transformation-type-ui.png)
4. Then proceed to provide the required parameters and click **'SAVE'**:

   ![Transformation Parameter](https://docs.cloud.google.com/static/manufacturing-data-engine/images/transformation-parameter-type-ui.png)

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()`.