The Data Manager provides several endpoints that allow for both downloading existing files and uploading new ones. The distinction between the endpoints depends on the classification of the files. In addition to general files shared across all machines, there are asset-specific configuration files, productivity-related files written by the machine, and dynamic files written by the MAT application and modified following certain interactions with it.
Below, we will analyze the various endpoints according to the type of file they manage.
Files Written by the Asset in File Storage
This category includes all files that are specific to an asset and are written by the machine's computer following input data from PLCs. These files are generated due to the machine's operation, do not contain configurations for it, and are not dynamically written by any of the services that are part of the MAT web architecture.
The endpoint to use to retrieve a list of all such files available for a specific asset is as follows:
post
Returns an asset's file list.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
Body
pathstringOptional
Returns the list of files in this path. Use either this key or "filters", but not both together.
Example: /documentation
filtersobjectOptional
Possible filters that can be applied to the request. Use either this key or "path", but not both together.
By specifying the asset's ID in the path, you will obtain a complete list of files. However, you can specify additional fields in the body of the request. Specifically:
"path": this key allows you to specify a part of the path within which to retrieve the files. This way, you can filter the results to only get information on files located in that path. If there are subfolders, files within them will also be returned. This key and "filters" must be used exclusively. Here is an example of a body using the key:
"filters": this key allows you to filter files according to specified parameters. This key and "path" must be used exclusively. Here is an example of a body using the key:
Below is a portion of the response from the call:
To retrieve a file for which you know the path, you can use the following endpoint. In the path, you need to specify both the machine's ID and the path where the file is located. Note that the path must include the file name and its extension.
get
Returns the specified file. If filePath does not represent a file, it returns the list of files at that location.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
filePathstringRequired
Path of the desired file, it includes the file name.
Example: /rawData/aggr_2m/123_124.npz
Responses
200
OK
application/octect-stream
Responsestring · binary
400
Bad request.
401
Unauthorized.
403
Forbidden.
404
Resource not found.
500
Internal server error.
503
Service temporarily unavailable.
504
Timeout.
get
/files/{assetId}/{filePath}
An example call might be as follows. In this case, you want to retrieve the file named "950400_953280.npz" for the machine with ID "asset1" located in the path "/alarms/aggr_30m/":
In addition to retrieving an existing file, you can also upload a new one or modify an existing one using this endpoint:
put
Updates the specified file. If it doesn't exists, it creates it.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
filePathstringRequired
Path of the desired file, it includes the file name.
Example: /rawData/aggr_2m/123_124.npz
Body
objectOptional
Responses
201
OK
application/octect-stream
400
Bad request.
401
Unauthorized.
403
Forbidden.
404
Resource not found.
500
Internal server error.
503
Service temporarily unavailable.
504
Timeout.
put
/files/{assetId}/{filePath}
In addition to specifying the machine ID and the file path, including the file name and its extension, in the path, it is necessary to insert the new file content in the body.
Finally, a file can be deleted. The path must be filled out with the machine ID and the file path, including the file name and its extension.
delete
Deletes the specified file.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
filePathstringRequired
Path of the desired file, it includes the file name.
Example: /rawData/aggr_2m/123_124.npz
Responses
204
No response.
400
Bad request.
401
Unauthorized.
403
Forbidden.
404
Resource not found.
500
Internal server error.
503
Service temporarily unavailable.
504
Timeout.
delete
/files/{assetId}/{filePath}
No content
Generic and Specific Configuration Files
Each machine in a MAT project has several configuration files that allow the application to recognize the machine and display the correct information within the application. Some of these files are generic, meaning they are shared across all machines as they do not need to change from asset to asset, while others are specific to each machine as they indicate the unique characteristics of each one.
To retrieve a list of all these files, the following endpoint can be used. By analyzing the path of individual files, it can be deduced which files are generic and which are specific to the asset: a null path and the "config" path indicate that the file is generic for all assets, while a path containing the machine ID indicates that the file is specific to that machine.
post
Returns the list of all configuration files both globals and specific for every project asset.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Query parameters
filterstringOptional
Filtro basato sui campi supportati.
orderbooleanOptional
Sort based on supported fields - see order syntax for more details. (name, path, type, size, timestamp, created, updated)
Body
pathstringOptional
Returns the list of files in this path. Use either this key or "filters", but not both together.
Example: /documentation
filtersobjectOptional
Possible filters that can be applied to the request. Use either this key or "path", but not both together.
This endpoint also accepts two mutually exclusive keys in the request body:
"path": this key allows you to specify a portion of the path within which to retrieve files. This way, you can filter the results to obtain only the information of the files located in that path. If there are subfolders, files within them will also be returned. This key and "filters" must be used exclusively. Below is an example of a body using the key:
"filters": this key allows filtering the files according to specified parameters. This key and "path" must be used in exclusion of each other. Below is an example of a body using the key:
An example of the response is shown below. The call was made without specifying anything in the body, so all the global and specific files for the selected machine were returned.
To retrieve a specific file knowing its path, this endpoint can be used:
get
Returns the specified configuration file.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
filePathstringRequired
Path of the desired file, it includes the file name.
Example: /rawData/aggr_2m/123_124.npz
Responses
200
OK
application/json
Responseany of
objectOptional
or
arrayOptional
get
/configs/globals/{filePath}
200
OK
It will be sufficient to specify the file path, including name and extension, to obtain the file in the body of the response.
Specific Configuration Files for the Individual Asset
Although the endpoints discussed so far allow for the retrieval of all possible configuration files, additional endpoints have been implemented that enable the retrieval of only the files specific to the indicated asset.
The following endpoint allows for retrieving a list of files that are dedicated solely to that particular machine. This endpoint also supports the "path" and "filters" keys in the request body:
"path": this key allows you to specify a portion of the path within which to retrieve files. This way, you can filter the results to obtain only the information of the files located in that path. If there are subfolders, files within them will also be returned. This key and "filters" must be used in mutual exclusion. Here is an example of a body using the key:
"filters": this key allows you to filter files according to specified parameters. This key and "path" must be used in mutual exclusion. Here is an example of a body using the key:
post
This resource returns the list of all configuration files for the specified asset. Global configuration files are not included.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
Query parameters
filterstringOptional
Filtro basato sui campi supportati.
orderbooleanOptional
Sort based on supported fields - see order syntax for more details. (name, path, type, size, timestamp, created, updated)
Body
pathstringOptional
Returns the list of files in this path. Use either this key or "filters", but not both together.
Example: /documentation
filtersobjectOptional
Possible filters that can be applied to the request. Use either this key or "path", but not both together.
The following endpoint, however, allows for downloading a specific file of the machine when its path is known:
get
Returns the specified configuration file.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
filePathstringRequired
Path of the desired file, it includes the file name.
Example: /rawData/aggr_2m/123_124.npz
Responses
200
OK
application/json
get
/configs/{assetId}/{filePath}
200
OK
Dynamic Files of the Individual Asset
During normal operation, the application needs to write a series of files for each asset in the project that contain configuration information. These details are not known in advance but depend on the actions the user performs within the MAT application. An example of such files includes those related to the calendar, in which shifts set by the user are saved, or those specifying all possible operators of the calendar, and so forth.
To access these files, the following endpoint is used. In the body, the following keys can be specified exclusively:
"path": this key allows specifying a portion of the path within which to retrieve files. This way, it is possible to filter the results to only obtain information about the files located in that path. If there are subfolders, files within them will also be returned. This key and "filters" must be used in mutual exclusion;
"filters": this key allows filtering the files according to specified parameters. This key and "path" must be used in mutual exclusion.
post
Returns the list of shared files
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
Body
pathstringOptional
Returns the list of files in this path. Use either this key or "filters", but not both together.
Example: /documentation
filtersobjectOptional
Possible filters that can be applied to the request. Use either this key or "path", but not both together.
To retrieve a file in a specific path, the following endpoint can be used by specifying the asset ID to use and the file path, including the name and extension.
get
Returns the content of the file found at the specified filepath.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
filePathstringRequired
In this case, filepath can be a composition of levels, e.g. /something/somethingelse/filename.ext .
Example: /rawData/aggr_2m/123_124.npz
Responses
200
Success
application/json
get
/sharedFiles/{assetId}/{filePath}
200
Success
To modify a file, the following endpoint can be used, specifying the machine ID, the path of the file you want to upload or modify, and attaching the new file content in the body.
put
Updates the specified file.
Authorizations
AuthorizationstringRequired
The identity provider authentication token.
Path parameters
assetIdstringRequired
Asset instance ID.
filePathstringRequired
In this case, filepath can be a composition of levels, e.g. /something/somethingelse/filename.ext .
