# Events

For the machines configured within MAT, events are recorded, each of which is described by a series of information such as its code, type, the aggregators set at the time the event occurs, etc.&#x20;

Some examples of events that are usually recorded are:

* **alarms**: a dedicated table is used to log all the alarms triggered by the machine when certain conditions are met;
* **notifications**: these events, usually triggered by the machine, are recorded in a dedicated table;
* **state changes**: in the MAT system, the transition from one state to another is considered an event. Although there isn't a dedicated table to log this event, state change occurrences can still be viewed among the events as they are dynamically calculated by the application;
* **button presses**: every time an operator interacts with the machine by pressing a button, the event is logged in the appropriate table;
* **parameter changes**: a dedicated table is used to monitor the changes of certain parameters selected during the machine's configuration;
* **image acquisition**: for machines equipped with cameras, this table is maintained to record each image acquisition.

The endpoints described in this section allow you to retrieve information about the events and perform an analysis based on various interesting parameters.

## /apis/events/\<assetId>

## GET Method

<details>

<summary>Request</summary>

```
HTTP
GET https://{BASE_URL}/apis/events/<assetId>
```

where:&#x20;

* `assetId` : machine ID to consider.&#x20;

#### Query

```
JSON
{
    "subAssetId": "subAssetId"
}
```

where:&#x20;

* `subAssetId` : sub-machine ID to consider. This field can be omitted if the asset in question is not a multi-machine setup.

</details>

The purpose of this endpoint is to retrieve all types of events recorded by the system for the selected machine. The response returns some useful information for each event type, such as the unique ID that identifies that type, a descriptive ID that helps better understand which event it is, the table in which those events are recorded, and the set of data columns that can be used to create a Pareto chart based on the data from that event.

Note that all elements in the "uniqueId" key of each object can be used to invoke the endpoint with a [POST method](#post-method) to obtain events of that type, as explained later in the documentation. If the "uniqueId" key is associated with a list of values, then it is possible to choose one of those values.

## Example

<details>

<summary>Request</summary>

```
HTTP
GET https://matdev.40mat.com/apis/events/40-line?subAssetId=M1
```

#### Query

```
JSON
{
    "subAssetId": "M1"
}
```

</details>

An example of a response could be as follows. Note that for each event, an object describing that event is returned.

<details>

<summary>Response</summary>

```json
JSON
{
    "1": {
        "associatedTable": "alarms",
        "availableColumnsForParetoConstruction": [
            "code"
        ],
        "category": "alarms",
        "eventId": "alarms",
        "uniqueId": [
            1,
            2
        ]
    },
    "1bis": {
        "associatedTable": "signalations",
        "availableColumnsForParetoConstruction": [
            "code"
        ],
        "category": "signalations",
        "eventId": "signalations",
        "uniqueId": [
            "1bis",
            "2bis"
        ]
    },
    "2": {
        "associatedTable": "alarms",
        "availableColumnsForParetoConstruction": [
            "code"
        ],
        "category": "alarms",
        "eventId": "alarms",
        "uniqueId": [
            1,
            2
        ]
    },
    "2bis": {
        "associatedTable": "signalations",
        "availableColumnsForParetoConstruction": [
            "code"
        ],
        "category": "signalations",
        "eventId": "signalations",
        "uniqueId": [
            "1bis",
            "2bis"
        ]
    },
    "3": {
        "associatedTable": "stateTransition",
        "availableColumnsForParetoConstruction": [
            "state"
        ],
        "category": "states",
        "eventId": "stateChanges",
        "uniqueId": 3
    },
    "7": {
        "associatedTable": "historyButton",
        "availableColumnsForParetoConstruction": [
            "code"
        ],
        "category": "buttons",
        "eventId": "historyButton",
        "uniqueId": 7
    },
    "historyParams": {
        "associatedTable": "historyParams",
        "availableColumnsForParetoConstruction": [
            "from",
            "to",
            "code"
        ],
        "category": "historyParams",
        "eventId": "historyParams",
        "uniqueId": "historyParams"
    },
    "imgData": {
        "associatedTable": "imgData",
        "availableColumnsForParetoConstruction": [
            "triggerId",
            "camId"
        ],
        "category": "Not Specified During Configuration",
        "eventId": "imgData",
        "uniqueId": "imgData"
    }
}
```

</details>

### Code

{% tabs %}
{% tab title="Python" %}

```python
import requests
import json

# Example data for the header
headers = {
    'App-Name': 'matdev-be',
    'Authorization': 'Bearer ey....xy1w'
}

# URL of the third-party API
myDomain = 'matdev.40mat.com'
myAssetId = '40-line'
endpoint = f'/apis/events/{myAssetId}'
url = f'https://{myDomain}{endpoint}'

# Example data for the query string
query_params = {
    "subAssetId": "M1"
}

# Make the POST request
response = requests.get(url, headers=headers, params=query_params )

# Check the response status and return the data
if response.status_code == 200:
    print('Success:')
    print(json.dumps(response.json(), indent=4))
else:
    print('Request failed:')
    print(f'Status code: {response.status_code}')
    print(response.text)
```

{% endtab %}
{% endtabs %}

### OpenAPI

{% openapi src="<https://content.gitbook.com/content/L65nhvmBlLI1fH4sd9ut/blobs/KAvOsMKNpCkRaukQxFnU/OpenAPI_simpliefiedAPIs.yml>" path="/apis/events/{assetId}" method="get" %}
[OpenAPI\_simpliefiedAPIs.yml](https://content.gitbook.com/content/L65nhvmBlLI1fH4sd9ut/blobs/KAvOsMKNpCkRaukQxFnU/OpenAPI_simpliefiedAPIs.yml)
{% endopenapi %}

## POST Method

The functionality of this endpoint allows you to retrieve data related to a specific event. After retrieving all possible events by calling the endpoint with a [GET method](#get-method), you can specify the event to request from the obtained "uniqueId" parameters.

<details>

<summary>Request</summary>

```
HTTP
POST https://{BASE_URL}/apis/events/<assetId>
```

where:&#x20;

* `assetId` : machine ID to consider.&#x20;

#### Query

```
JSON
{
    "subAssetId": "subAssetId"
}
```

where:&#x20;

* `subAssetId` : sub-machine ID to consider. This field can be omitted if the asset in question is not a multi-machine setup.

**Body**

```
JSON
{
    "uniqueId": "1",
    "from": "2024-03-31T22:00:00.000Z",
    "to": "2024-04-05T21:59:59.999Z",
    "filterBy": None,
    "limit": None,
    "calendar": 0
}
```

In the request body, you can specify the following parameters:

* `uniqueId`: a unique ID representing the event type. If this information is unknown, it can be retrieved by calling the endpoint with a GET method, as specified above.
* `from`: the start timestamp from which you want to begin downloading the data, expressed in UTC in the format "YYYY-MM-DDThh:mm

  .sssZ" (ISO 8601 Standard).
* `to`: the end timestamp of the interval for which you want to download the data, expressed in UTC in the format "YYYY-MM-DDThh:mm

  .sssZ" (ISO 8601 Standard). If this field is omitted or set to null, it will automatically be set to the current timestamp at the time of the request.
* `limit`: this numeric field specifies the maximum number of events to return. The value specified in this field allows you to request the most recent {n} events. This field can be used in various ways:
  * "limit" without "from" and "to": the most recent {n} events will be retrieved;
  * "limit" with "from" and without "to": the behavior in this case is the same as the previous scenario. The most recent {n} events will be returned;
  * "limit" with "from" and "to": in this case, the most recent {n} events will be returned, with the end of the interval being the "to" field. The events will be the most recent ones recorded before the timestamp specified in the "to" field;
  * "limit" with "to" and without "from": this option is not allowed and will result in an error;
* `filterBy`: this field allows you to specify a filter to apply to the events. The value should be a dictionary where the keys represent the fields to filter on, and the value represents what is to be accepted for that field. Events that do not match the filter criteria will be discarded;
* `calendar` : boolean value indicating whether the calendar should be considered in data analysis. By default, this value is set to false.

</details>

The response will return the requested events along with some supplementary information, such as the duration, their code, and the aggregators.

## Example

<details>

<summary>Request</summary>

```
HTTP
POST https://matdev.40mat.com/apis/events/40-line?subAssetId=M1
```

#### Query

```
JSON
{
    "subAssetId": "M1"
}
```

#### Body

```
JSON
{
    "from": "2024-03-10T00:00:00.000Z",
    "to": "2024-03-10T04:00:00.000Z",
    "uniqueId": "1bis"
}
```

</details>

In this example, we want to retrieve the events of type "notification" that occurred within the specified interval. In the example, the notification events have the ID "1bis".&#x20;

The response is provided below:

<details>

<summary>Response</summary>

```json
JSON
[
    {
        "aggr0": "prod5",
        "aggr1": "Peach",
        "aggr2": "format-D",
        "alarmCode": "warning_M2_8",
        "duration": 30.0369930267334,
        "eventId": "1bis",
        "timeEnd": "2024-03-10T00:59:37.497006",
        "timeStart": "2024-03-10T00:59:07.460013"
    },
    {
        "aggr0": "prod5",
        "aggr1": "Peach",
        "aggr2": "format-D",
        "alarmCode": "warning_M2_14",
        "duration": 10.813385963439941,
        "eventId": "1bis",
        "timeEnd": "2024-03-10T01:08:16.527614",
        "timeStart": "2024-03-10T01:08:05.714228"
    },
    {
        "aggr0": "prod4",
        "aggr1": "Peach",
        "aggr2": "format-E",
        "alarmCode": "warning_M2_9",
        "duration": 42.250789642333984,
        "eventId": "1bis",
        "timeEnd": "2024-03-10T01:18:18.070210",
        "timeStart": "2024-03-10T01:17:35.819420"
    },
    ...
]
```

</details>

## Example - limit

In this example, we want to obtain the most recent alarm that occurred on the machine.&#x20;

<details>

<summary>Request</summary>

```
HTTP
POST https://matdev.40mat.com/apis/events/40-line?subAssetId=M1
```

#### Query

```
JSON
{
    "subAssetId": "M1"
}
```

#### Body

```
JSON
{
    "uniqueId": "1bis",
    "limit": 1
}
```

</details>

The response is indicated below:

<details>

<summary>Response</summary>

```json
JSON
[
    {
        "aggr0": "prod1",
        "aggr1": "Waluigi",
        "aggr2": "format-C",
        "alarmCode": "al_M1_1",
        "duration": 6.207925796508789,
        "eventId": "1",
        "timeEnd": "2024-05-17T17:12:31.652074",
        "timeStart": "2024-05-17T17:12:25.444148"
    }
]
```

</details>

## Example - filterBy

In the following example, we want to retrieve all state changes that occurred while the operator "Luigi" was on duty.

<details>

<summary>Request</summary>

```
HTTP
POST https://matdev.40mat.com/apis/events/40-line?subAssetId=M1
```

#### Query

```
JSON
{
    "subAssetId": "M1"
}
```

#### Body

```
JSON
{
    "uniqueId": "3",
    "from": "2024-05-15T22:00:00.000Z",
    "filterBy": {"aggr1": "Mario"}
}
```

</details>

The response is provided below. As noted, in this case both the starting state and the ending state are reported.

<details>

<summary>Response</summary>

```json
JSON
[
    {
        "aggr0": "prod1",
        "aggr1": "Mario",
        "aggr2": "format-E",
        "eventId": 3,
        "stateFrom": 0.0,
        "stateTo": 1.0,
        "timestamp": "2024-05-16T11:39:17.768"
    },
    {
        "aggr0": "prod1",
        "aggr1": "Mario",
        "aggr2": "format-E",
        "eventId": 3,
        "stateFrom": 1.0,
        "stateTo": 0.0,
        "timestamp": "2024-05-16T11:50:15.380"
    },
    {
        "aggr0": "prod1",
        "aggr1": "Mario",
        "aggr2": "format-E",
        "eventId": 3,
        "stateFrom": 0.0,
        "stateTo": 2.0,
        "timestamp": "2024-05-16T12:21:07.473"
    },
    {
        "aggr0": "prod4",
        "aggr1": "Mario",
        "aggr2": "format-E",
        "eventId": 3,
        "stateFrom": 2.0,
        "stateTo": 0.0,
        "timestamp": "2024-05-16T12:26:11.448"
    },
    ...
]
```

</details>

### Code

{% tabs %}
{% tab title="Python" %}
The following script can be used to make a call to the endpoint `/apis/events/<assetId>` with the POST method. Be sure to correctly configure the parameters in the body of the request.

```python
import requests
import json

# Example data for the header
headers = {
    'App-Name': 'matdev-be',
    'Authorization': 'Bearer ey....xy1w'
}

# Example data for the body
body = {
    "uniqueId": "1",
    "paretoColumn": "code",
    "from": "2024-03-31T22:00:00.000Z",
    "to": "2024-04-05T21:59:59.999Z",
    "filterBy": None,
    "groupBy": None
}


# Example data for the query string
query_params = {
    "subAssetId": "M1"
}

# URL of the third-party API
myDomain = 'matdev.40mat.com'
myAssetId = '40-line'
endpoint = f'/apis/events/{myAssetId}'
url = f'https://{myDomain}{endpoint}'

# Make the POST request
response = requests.post(url, headers=headers, json=body, params=query_params )

# Check the response status and return the data
if response.status_code == 200:
    print('Success:')
    print(json.dumps(response.json(), indent=4))
else:
    print('Request failed:')
    print(f'Status code: {response.status_code}')
    print(response.text)
```

{% endtab %}
{% endtabs %}

### OpenAPI

{% openapi src="<https://content.gitbook.com/content/L65nhvmBlLI1fH4sd9ut/blobs/KAvOsMKNpCkRaukQxFnU/OpenAPI_simpliefiedAPIs.yml>" path="/apis/events/{assetId}" method="post" %}
[OpenAPI\_simpliefiedAPIs.yml](https://content.gitbook.com/content/L65nhvmBlLI1fH4sd9ut/blobs/KAvOsMKNpCkRaukQxFnU/OpenAPI_simpliefiedAPIs.yml)
{% endopenapi %}

## /apis/events/\<assetId>/pareto

## POST Method

A Pareto chart is a data visualization tool that represents the cumulative frequencies of variables in descending order. It is based on the Pareto principle, which states that a small number of causes (or categories) tend to produce the majority of effects (or results).

In a Pareto chart, the categories are arranged on the x-axis in descending order of frequency, while the cumulative frequencies are represented on the y-axis. This type of chart is often used to identify and focus on the main causes of a problem, allowing for efficient resource allocation to achieve the greatest impact.

<details>

<summary>Request</summary>

```
HTTP
POST https://{BASE_URL}/apis/events/<assetId>/pareto
```

where:&#x20;

* `assetId` : machine ID to consider.

#### Query

```
JSON
{
    "subAssetId": "subAssetId"
}
```

where:&#x20;

* `subAssetId` : sub-machine ID to consider. This field can be omitted if the asset in question is not a multi-machine setup.

**Body**

```
JSON
{
    "uniqueId": "1",
    "paretoColumn": "code",
    "from": "2024-03-31T22:00:00.000Z",
    "to": "2024-04-05T21:59:59.999Z",
    "filterBy": None,
    "groupBy": None,
    "calendar": 0
}
```

In the request body, you can specify the following parameters:

* `uniqueId`: a unique ID representing the type of event. If this information is unknown, it can be retrieved by invoking the endpoint with the GET method, as specified above.
* `paretoColumn`: the column on which the Pareto chart should be built. Note that a Pareto chart is essentially a group-by operation. This field can be considered as the data on which the group-by operation is performed. To know which fields can be used for constructing the Pareto chart, you can invoke the[ endpoint with the GET method](#get-method) and refer to the key named "availableColumnsForParetoConstruction."
* `from`: the start timestamp from which you want to begin downloading the data, expressed in UTC in the format "YYYY-MM-DDThh:mm

  .sssZ" (ISO 8601 Standard).
* `to`: the end timestamp of the interval for which you want to download the data, expressed in UTC in the format "YYYY-MM-DDThh:mm

  .sssZ" (ISO 8601 Standard). If this field is omitted or set to null, it will automatically be set to the current timestamp at the time of the request.
* `filterBy`: this field allows you to specify a filter to apply to the events. The value should be a dictionary where the keys represent the fields to filter on, and the value represents what is to be accepted for that field. Events that do not match the filter criteria will be discarded.
* `groupBy`: this field allows you to group the data according to one of the specified values. The value should be a string indicating the field on which you want to aggregate. For more advanced usage, you can specify a list of strings;
* `calendar` : boolean value indicating whether the calendar should be considered in data analysis. By default, this value is set to false.

</details>

This endpoint allows the user to request event data formatted in Pareto style. It is mandatory to specify the type of event and the column on which the Pareto chart should be built. These two pieces of information can be obtained by invoking the endpoint [`/apis/events/<assetId>` with the GET method](#get-method).

The column used for constructing the Pareto chart is crucial, as it will be used for grouping the data. For each value taken by this column, an object representing a Pareto bar will be returned, including relevant information.

## Example

<details>

<summary>Request</summary>

```
HTTP
POST https://matdev.40mat.com/apis/events/40-line/pareto?subAssetId=M1
```

#### Query

```
JSON
{
    "subAssetId": "M1"
}
```

#### Body

```
JSON
{
    "uniqueId": 1,
    "from": "2024-05-15T22:00:00.000Z",
    "paretoColumn": "code"
}
```

</details>

In this example, we want to create a Pareto chart of alarms to identify which category of alarms lasted the longest. To do this, the "paretoColumn" is specified as the column containing the alarm code, while the "uniqueId" used is the code associated with the alarms.

The response is as follows:

<details>

<summary>Response</summary>

```json
JSON
[
    {
        "data": {
            "aggr0": "prod1$$prod4",
            "aggr1": "Wario$$Luigi$$Mario",
            "aggr2": "format-C$$format-E",
            "code": "al_M1_2",
            "count": 3.0,
            "duration": 1118.6155834197998,
            "isFirst": "True"
        },
        "groupByValues": {
            "code": "al_M1_2"
        }
    },
    {
        "data": {
            "aggr0": "prod1",
            "aggr1": "Yoshi",
            "aggr2": "format-E",
            "code": "al_M1_1",
            "count": 1.0,
            "duration": 1512.469482421875,
            "isFirst": "True"
        },
        "groupByValues": {
            "code": "al_M1_1"
        }
    },
    {
        "data": {
            "aggr0": "prod5",
            "aggr1": "Wario",
            "aggr2": "format-C",
            "code": "al_M1_3",
            "count": 1.0,
            "duration": 525.048583984375,
            "isFirst": "True"
        },
        "groupByValues": {
            "code": "al_M1_3"
        }
    }
]
```

</details>

As you can see, each element in the list represents a Pareto bar. Each object contains two keys: the first, "groupByValues", contains the value taken from the "code" column, while the second, "data", contains the information for the Pareto bar associated with that value of "code".&#x20;

If we were to interpret this response, we could say:

"*For the machine 40-line, from May 15 until now, a total of five alarms have occurred. Three alarms had the code 'al\_M1\_2' and had a total duration of 1118.61 seconds. One alarm of type 'al\_M1\_1' occurred within the interval and lasted 1512.46 seconds, and the same situation applies to alarms of type 'al\_M1\_3' as only one occurred with a duration of 525.04 seconds.*"

## Example - filterBy

<details>

<summary>Request</summary>

```
HTTP
POST https://matdev.40mat.com/apis/events/40-line/pareto?subAssetId=M1
```

#### Query

```
JSON
{
    "subAssetId": "M1"
}
```

#### Body

```
JSON
{
    "uniqueId": 1,
    "from": "2024-05-10T22:00:00.000Z",
    "paretoColumn": "code",
    "filterBy": {"aggr1" : "Luigi"}
}
```

</details>

In this example, we want to construct a Pareto chart of the alarms that occurred when the active operator was Luigi. This condition has been specified in the request using the "filterBy" field.

The response is as follows:

<details>

<summary>Response</summary>

```json
JSON
[
    {
        "data": {
            "aggr0": "prod1$$prod4",
            "aggr1": "Luigi",
            "aggr2": "format-C$$format-E",
            "code": "al_M1_2",
            "count": 2.0,
            "duration": 603.7560558319092,
            "isFirst": "True"
        },
        "groupByValues": {
            "code": "al_M1_2"
        }
    },
    {
        "data": {
            "aggr0": "prod3",
            "aggr1": "Luigi",
            "aggr2": "format-B",
            "code": "al_M1_4",
            "count": 1.0,
            "duration": 142.77536010742188,
            "isFirst": "True"
        },
        "groupByValues": {
            "code": "al_M1_4"
        }
    },
    {
        "data": {
            "aggr0": "prod4",
            "aggr1": "Luigi",
            "aggr2": "format-C",
            "code": "al_M1_10",
            "count": 1.0,
            "duration": 1740.9677734375,
            "isFirst": "True"
        },
        "groupByValues": {
            "code": "al_M1_10"
        }
    },
    {
        "data": {
            "aggr0": "prod2",
            "aggr1": "Luigi",
            "aggr2": "format-C",
            "code": "al_M1_1",
            "count": 1.0,
            "duration": 299.3717956542969,
            "isFirst": "True"
        },
        "groupByValues": {
            "code": "al_M1_1"
        }
    }
]
```

</details>

## Example - groupBy&#x20;

The following example demonstrates how to create a Pareto chart of alarms based on both the alarm code column and the active operator at that time. To achieve this, it is sufficient to include the "groupBy" field in the request body.

<details>

<summary>Request</summary>

```
HTTP
POST https://matdev.40mat.com/apis/events/40-line/pareto?subAssetId=M1
```

#### Query

```
JSON
{
    "subAssetId": "M1"
}
```

#### Body

```
JSON
{
    "uniqueId": 1,
    "from": "2024-05-10T22:00:00.000Z",
    "paretoColumn": "code",
    "groupBy": "aggr1"
}
```

</details>

The response is as follows:

<details>

<summary>Response</summary>

```json
JSON
[
    {
        "data": {
            "aggr0": "prod2$$prod1$$prod4",
            "aggr1": "Wario",
            "aggr2": "format-C$$format-D",
            "code": "al_M1_2",
            "count": 5.0,
            "duration": 3318.7407836914062,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Wario",
            "code": "al_M1_2"
        }
    },
    {
        "data": {
            "aggr0": "prod1$$prod4",
            "aggr1": "Luigi",
            "aggr2": "format-C$$format-E",
            "code": "al_M1_2",
            "count": 2.0,
            "duration": 603.7560558319092,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Luigi",
            "code": "al_M1_2"
        }
    },
    {
        "data": {
            "aggr0": "prod2$$prod4",
            "aggr1": "Mario",
            "aggr2": "format-C$$format-E",
            "code": "al_M1_2",
            "count": 2.0,
            "duration": 663.6513862609863,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Mario",
            "code": "al_M1_2"
        }
    },
    {
        "data": {
            "aggr0": "prod1",
            "aggr1": "Yoshi",
            "aggr2": "format-E",
            "code": "al_M1_1",
            "count": 1.0,
            "duration": 1512.469482421875,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Yoshi",
            "code": "al_M1_1"
        }
    },
    {
        "data": {
            "aggr0": "prod5",
            "aggr1": "Wario",
            "aggr2": "format-C$$format-B",
            "code": "al_M1_3",
            "count": 2.0,
            "duration": 720.9004516601562,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Wario",
            "code": "al_M1_3"
        }
    },
    {
        "data": {
            "aggr0": "prod2",
            "aggr1": "Mario",
            "aggr2": "format-C",
            "code": "al_M1_6",
            "count": 1.0,
            "duration": 72.8862533569336,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Mario",
            "code": "al_M1_6"
        }
    },
    {
        "data": {
            "aggr0": "prod1$$prod5",
            "aggr1": "Mario",
            "aggr2": "format-B$$format-D",
            "code": "al_M1_0",
            "count": 2.0,
            "duration": 1066.3148345947266,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Mario",
            "code": "al_M1_0"
        }
    },
    {
        "data": {
            "aggr0": "prod1$$prod3",
            "aggr1": "Mario",
            "aggr2": "format-D$$format-A",
            "code": "al_M1_1",
            "count": 2.0,
            "duration": 849.8421325683594,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Mario",
            "code": "al_M1_1"
        }
    },
    {
        "data": {
            "aggr0": "prod2",
            "aggr1": "Yoshi",
            "aggr2": "format-C",
            "code": "al_M1_2",
            "count": 1.0,
            "duration": 222.07571411132812,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Yoshi",
            "code": "al_M1_2"
        }
    },
    {
        "data": {
            "aggr0": "prod2",
            "aggr1": "Yoshi",
            "aggr2": "format-C",
            "code": "al_M1_0",
            "count": 1.0,
            "duration": 808.0211791992188,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Yoshi",
            "code": "al_M1_0"
        }
    },
    {
        "data": {
            "aggr0": "prod5",
            "aggr1": "Peach",
            "aggr2": "format-C",
            "code": "al_M1_3",
            "count": 1.0,
            "duration": 582.9430541992188,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Peach",
            "code": "al_M1_3"
        }
    },
    {
        "data": {
            "aggr0": "prod5$$prod4",
            "aggr1": "Waluigi",
            "aggr2": "format-C",
            "code": "al_M1_14",
            "count": 2.0,
            "duration": 1004.2427368164062,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Waluigi",
            "code": "al_M1_14"
        }
    },
    {
        "data": {
            "aggr0": "prod1$$prod5",
            "aggr1": "Mario",
            "aggr2": "format-C",
            "code": "al_M1_14",
            "count": 2.0,
            "duration": 1194.4803771972656,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Mario",
            "code": "al_M1_14"
        }
    },
    {
        "data": {
            "aggr0": "prod3",
            "aggr1": "Luigi",
            "aggr2": "format-B",
            "code": "al_M1_4",
            "count": 1.0,
            "duration": 142.77536010742188,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Luigi",
            "code": "al_M1_4"
        }
    },
    {
        "data": {
            "aggr0": "prod4",
            "aggr1": "Luigi",
            "aggr2": "format-C",
            "code": "al_M1_10",
            "count": 1.0,
            "duration": 1740.9677734375,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Luigi",
            "code": "al_M1_10"
        }
    },
    {
        "data": {
            "aggr0": "prod2",
            "aggr1": "Luigi",
            "aggr2": "format-C",
            "code": "al_M1_1",
            "count": 1.0,
            "duration": 299.3717956542969,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Luigi",
            "code": "al_M1_1"
        }
    },
    {
        "data": {
            "aggr0": "prod3",
            "aggr1": "Wario",
            "aggr2": "format-E",
            "code": "al_M1_6",
            "count": 1.0,
            "duration": 510.8413391113281,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Wario",
            "code": "al_M1_6"
        }
    },
    {
        "data": {
            "aggr0": "prod4",
            "aggr1": "Peach",
            "aggr2": "format-A",
            "code": "al_M1_1",
            "count": 1.0,
            "duration": 740.7252807617188,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Peach",
            "code": "al_M1_1"
        }
    },
    {
        "data": {
            "aggr0": "prod3",
            "aggr1": "Peach",
            "aggr2": "format-A",
            "code": "al_M1_5",
            "count": 1.0,
            "duration": 473.7920837402344,
            "isFirst": "True"
        },
        "groupByValues": {
            "aggr1": "Peach",
            "code": "al_M1_5"
        }
    }
]
```

</details>

As you can see, the Pareto chart in this case is constructed using two columns: "code" and "aggr1". The various values taken by these two columns are specified in each object within the "groupByValues" key.&#x20;

### Code

{% tabs %}
{% tab title="Python" %}
The following script can be used to make a call to the endpoint `/apis/events/<assetId>/pareto` with the POST method. Be sure to correctly configure the parameters in the body of the request.

```python
import requests
import json

# Example data for the header
headers = {
    'App-Name': 'matdev-be',
    'Authorization': 'Bearer ey....xy1w'
}

# Example data for the body
body = {
    "uniqueId": "1",
    "paretoColumn": "code",
    "from": "2024-03-31T22:00:00.000Z",
    "to": "2024-04-05T21:59:59.999Z",
    "filterBy": None,
    "groupBy": None
}


# Example data for the query string
query_params = {
    "subAssetId": "M1"
}

# URL of the third-party API
myDomain = 'matdev.40mat.com'
myAssetId = '40-line'
endpoint = f'/apis/events/{myAssetId}/pareto'
url = f'https://{myDomain}{endpoint}'

# Make the POST request
response = requests.post(url, headers=headers, json=body, params=query_params )

# Check the response status and return the data
if response.status_code == 200:
    print('Success:')
    print(json.dumps(response.json(), indent=4))
else:
    print('Request failed:')
    print(f'Status code: {response.status_code}')
    print(response.text)
```

{% endtab %}
{% endtabs %}

### OpenAPI

{% openapi src="<https://content.gitbook.com/content/L65nhvmBlLI1fH4sd9ut/blobs/KAvOsMKNpCkRaukQxFnU/OpenAPI_simpliefiedAPIs.yml>" path="/apis/events/{assetId}/pareto" method="post" %}
[OpenAPI\_simpliefiedAPIs.yml](https://content.gitbook.com/content/L65nhvmBlLI1fH4sd9ut/blobs/KAvOsMKNpCkRaukQxFnU/OpenAPI_simpliefiedAPIs.yml)
{% endopenapi %}

## /apis/breakdowns/\<assetId>

## POST Method

A specific type of Pareto chart that can be viewed within MAT is the Downtime Pareto. A downtime occurs when the machine switches from a productive state to a non-productive state due to an alarm. The application includes a dedicated section for analyzing this type of event through the visualization of a Pareto chart. To obtain the exact same analysis performed in MAT, the following endpoint can be used.

<details>

<summary>Request</summary>

```
HTTP
POST https://{BASE_URL}/apis/breakdowns/<assetId>
```

where:&#x20;

* `assetId` : machine id.

#### Query

```
JSON
{
    "subAssetId": "subAssetId"
}
```

where:&#x20;

* `subAssetId` : ID of the sub-machine to be considered. This field can be omitted if the asset in question is not a multi-machine system.

**Body**

```
JSON
{
    "from": "2024-03-31T22:00:00.000Z",
    "to": "2024-04-05T21:59:59.999Z",
    "paretoType": "historyBreakdowns",
    "filterBy": None,
    "groupBy": None,
    "oeeLoss": 1,
    "filterUnknown": 1,
    "unknownBreakdownsName": "ukw",
    "calendar": 0
}
```

In the request body, the following parameters can be specified:

* `from`: Start timestamp from which to begin downloading data, expressed in UTC in the format `"YYYY-MM-DDThh:mm:ss.sssZ"` (ISO 8601 standard);
* `to`: End timestamp of the interval for which to download data, expressed in UTC in the format `"YYYY-MM-DDThh:mm:ss.sssZ"` (ISO 8601 standard). If this field is omitted or set to `null`, it will automatically default to the current request time;
* `paretoType`: String indicating the type of Pareto chart to retrieve. To get the Downtime Pareto, specify the string `"historyBreakdowns"`. Alternatively, you can specify other Pareto types as configured in the `dashboard-breakdowns-alarms.json` file of the machine;
* `filterBy`: This field allows you to apply a filter to the events. The value must be a dictionary where the keys represent the fields to filter on, and the values specify the accepted values for those fields. Events that do not match the filter will be excluded;
* `groupBy`: This field allows you to group the data by one of the specified values. The value should be a string indicating the field to group by. For advanced usage, a list of strings can be provided;
* `oeeLoss`: Boolean indicating whether to include in the response the OEE loss caused by each type of downtime/alarm;
* `filterUnknown`: Specifies whether to ignore downtimes with an unknown cause during the analysis;
* `unknownBreakdownsName`: String specifying the label to use for downtimes with unknown causes;
* `calendar`: Boolean value indicating whether the calendar should be considered in the data analysis. By default, this value is set to `false`.

</details>

## Example

<details>

<summary>Request</summary>

```
HTTP
POST https://matdev.40mat.com/apis/breakdowns/40-line?subAssetId=M1
```

#### Query

```
JSON
{
    "subAssetId": "M1"
}
```

#### Body

```
JSON
{
    "from": "2024-05-15T22:00:00.000Z",
    "paretoType": "historyBreakdowns",
    "oeeLoss": 1,
    "filterUnknown": 1,
    "unknownBreakdownsName": "ukw"
}
```

</details>

The response will include both data related to KPIs calculated from the data and the list of all downtime categories that make up the Pareto.
