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.

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

Request

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

where:

• assetId : machine ID to consider.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

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

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 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

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

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

Response

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"
    }
}

Code

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)

OpenAPI

get

This endpoint returns the list of all the available event types. Note that events have to be configured into the machine-profile.json file correctly.

Authorizations

bearerAuthbasicAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

assetIdstringRequired

Query parameters

subAssetIdstringOptional

Sub-machine ID. If the machine for which the assetId has been specified is a multi-machine, then this field must always be specified as well.

Responses

200

A list of all the available event types.

application/json

400

Bad Request.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

503

Service Unavailable.

504

Gateway Timeout.

get

/apis/events/{assetId}

HTTPcURLJavaScriptPython

GET /apis/events/{assetId} HTTP/1.1
Host: localhost:3001
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": {
    "associatedTable": "text",
    "availableColumnsForParetoConstruction": [
      "text"
    ],
    "category": "text",
    "eventId": "text",
    "uniqueId": [
      1
    ]
  }
}

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, you can specify the event to request from the obtained "uniqueId" parameters.

Request

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

where:

• assetId : machine ID to consider.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

• 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.

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

Example

Request

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"
}

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".

The response is provided below:

Response

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"
    },
    ...
]

Example - limit

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

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

Body

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

The response is indicated below:

Response

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"
    }
]

Example - filterBy

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

Request

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"}
}

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

Response

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"
    },
    ...
]

Code

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.

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)

OpenAPI

post

This endpoint allows a user to select an event id and it returns all events of that kind. Some parameters can be specified to restrict the analysis.

Authorizations

bearerAuthbasicAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

assetIdstringRequired

Query parameters

subAssetIdstringOptional

Sub-machine ID. If the machine for which the assetId has been specified is a multi-machine, then this field must always be specified as well.

Body

application/json

uniqueIdstringOptional

Unique id associated with the event type in which the user is interested. This parameter is mandatory.

Example: 1

fromstringOptional

Initial moment of the interval within which the events must be returned. The timestamp must be expressed in UTC and follow the format 'YYYY-MM-DDThh:mm:ssZ'. If both "from" and "to" parameters are null, the last state will be returned.

Default: NoneExample: 2024-04-18T10:30:00Z

tostringOptional

Final moment of the interval within which the events must be returned. The timestamp must be expressed in UTC and follow the format 'YYYY-MM-DDThh:mm:ssZ'. The value can be omitted to default to the current timestamp.

Default: Actual timestampExample: 2024-04-18T10:30:00Z

filterByobjectOptional

Object indicating for each key which value is allowed. All data that do not meet this condition will not be taken into consideration. Notice that filters can only be applied to aggregator columns, i.e., those columns whose names follow the format "aggr" + number. Applying a filter to a table that doesn't have these columns will result in obtaining no data. Filters can only be applied to aggregator columns.

Default: NoneExample: {"aggr0":"Waluigi","aggr1":"recipe1"}

limitintegerOptional

This field can be used instead of "from" and "to" to return the last {n} events. If a range is specified with "from" and "to", the last {n} events within the indicated range will be returned. If only "from" is specified, the last {n} rows will be returned. Specifying only "to" is not allowed. The "limit" operation has no effect if a value for the "resampleBy" field is specified, as that command takes precedence over "limit". You can use "limit" by itself, with "from", and with both "from" and "to". You can never use "limit" with only "to". It is not allowed to use the "limit" field with events of type 3 or type relative to state transitions.

Default: nullExample: 10

Responses

200

A list of events of the specified type.

application/json

400

Bad Request.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

503

Service Unavailable.

504

Gateway Timeout.

post

/apis/events/{assetId}

HTTPcURLJavaScriptPython

POST /apis/events/{assetId} HTTP/1.1
Host: localhost:3001
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "uniqueId": "1",
  "from": "2024-04-18T10:30:00Z",
  "to": "2024-04-18T10:30:00Z",
  "filterBy": {
    "aggr0": "Waluigi",
    "aggr1": "recipe1"
  },
  "limit": 10
}

[
  {
    "aggr{n}": "prod2",
    "code": "al_M1_2",
    "duration": 916.1494750976562,
    "eventId": 2,
    "timeEnd": "2024-05-14T06:03:29.874",
    "timeStart": "2024-05-14T05:48:13.724525"
  }
]

/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.

Request

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

where:

• assetId : machine ID to consider.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

• 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 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.

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.

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

Request

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"
}

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:

Response

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"
        }
    }
]

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".

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

Request

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"}
}

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:

Response

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"
        }
    }
]

Example - groupBy

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.

Request

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"
}

The response is as follows:

Response

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"
        }
    }
]

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.

Code

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.

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)

OpenAPI

post

This endpoint allows a user to request some events data formatted in a Pareto style. It is mandatory to specify on which kind of event and on which column the Pareto has to be constructed.

Authorizations

bearerAuthbasicAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

assetIdstringRequired

Query parameters

subAssetIdstringOptional

Sub-machine ID. If the machine for which the assetId has been specified is a multi-machine, then this field must always be specified as well.

Body

application/json

fromstringOptional

Initial moment of the interval within which the events must be returned. The timestamp must be expressed in UTC and follow the format 'YYYY-MM-DDThh:mm:ssZ'. If both "from" and "to" parameters are null, the last state will be returned.

Default: NoneExample: 2024-04-18T10:30:00Z

tostringOptional

Final moment of the interval within which the events must be returned. The timestamp must be expressed in UTC and follow the format 'YYYY-MM-DDThh:mm:ssZ'. The value can be omitted to default to the current timestamp.

Default: Actual timestampExample: 2024-04-18T10:30:00Z

uniqueIdstringOptional

Unique id associated with the event type in which the user is interested. This parameter is mandatory.

Example: 1

paretoColumnstringOptional

Name of the column belonging to the event's table that has to be used to construct the Pareto. Available values can be retrieved using the GET method of this same endpoint. This parameter is mandatory.

Example: code

filterByobjectOptional

Object indicating for each key which value is allowed. All data that do not meet this condition will not be taken into consideration. Notice that filters can only be applied to aggregator columns, i.e., those columns whose names follow the format "aggr" + number. Applying a filter to a table that doesn't have these columns will result in obtaining no data. Filters can only be applied to aggregator columns.

Default: NoneExample: {"aggr0":"Waluigi","aggr1":"recipe1"}

groupBystringOptional

Aggregator to be used for grouping the data. Group by can only be applied to aggregator columns.

Default: NoneExample: aggr0

Responses

200

A list of events data formatted in a Pareto style.

application/json

400

Bad Request.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

503

Service Unavailable.

504

Gateway Timeout.

post

/apis/events/{assetId}/pareto

HTTPcURLJavaScriptPython

POST /apis/events/{assetId}/pareto HTTP/1.1
Host: localhost:3001
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "from": "2024-04-18T10:30:00Z",
  "to": "2024-04-18T10:30:00Z",
  "uniqueId": "1",
  "paretoColumn": "code",
  "filterBy": {
    "aggr0": "Waluigi",
    "aggr1": "recipe1"
  },
  "groupBy": "aggr0"
}

{
  "data": [
    {
      "aggr{n}": "text",
      "genericParetoColumn": "text",
      "count": 1,
      "duration": 1
    }
  ],
  "groupByValues": [
    {
      "genericParetoColumn": "text",
      "aggr{n}": "text"
    }
  ]
}

/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.

Request

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

where:

• assetId : machine id.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

• 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.

Example

Request

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"
}

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.