AMAGE REST API Interface - Execution Supervision
Introduction/Context
Context for operations on Supervision module objects in the AMAGE system, which should be extended with the appropriate method in the query.
-
rest/amage/v1/supervisions
Data structures
Structures and data types used in queries and responses.
Result:
The ID/UUID fields contain the identifier of the newly created or edited object. If the operation is performed correctly, the success field is set to true
. If an error occurs, the success field is set to false
, and the message field contains a description of the error. The error code then contains an HTTP code of the NOT_FOUND or BAD_REQUEST type. The BAD_REQUEST code is also returned in the query. Depending on the type of error during query processing, the error code may be different than the main query code returned. The query code will be BAD_REQUEST, and the internal code will be set to NOT_FOUND in the case when the query sets an object property to another object in the system. The JSON parameter will be correct (record UUID), but there will be no such record in the system. Therefore, the NOT_FOUND code will appear in the errorCode field. In the message
description field, a message informing what record was not found, and the main query error code will be BAD_REQUEST.
{
"id": 1,
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Source of information. Enumerated field as a comma-separated list of values. Available values:
-
FROM_DESKTOP,
-
FROM_MOBILE,
-
FROM_IDENTIFIER,
-
FROM_DIFFERENCE,
-
FROM_IMPORT,
-
FROM_WEB_SERVICE,
-
FROM_DATA_AGGREGATOR,
-
FROM_AUTOMATION
API operations
Reading the supervision history record data
-
Method:
GET
-
Path:
/history/{uuid}
-
Generates:
application/json
-
Requires:
application/json, text/plain
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parameters:
-
UUID - history entry identifier for the supervised item
The returned data is a JSON object with the structure:
{
"id": 12345,
"uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"invalid":false,
"timestamp":"2021-01-01T12:00:00",
"supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"progress":100,
"addedCount":0,
"locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"mapShapeLatitude":50.0,
"mapShapeLongitude":20.0,
"mapShapeMapCode":"default",
"parameters":[
{
"id": 3456,
"parameterSettingUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"date": "2021-01-01T12:00:00",
"userUuid": "1c4066e6-cdd6-4903-803a-b6bffe689527",
"currentValue":"100.0",
"source":"FROM_WEBSERVICE"
}
]
}
Saving history to an existing supervised item
-
Method:
POST
-
Path:
/add-history/{uuid}
-
Generates:
application/json
-
Requires:
application/json
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parameters:
-
UUID - supervised element identifier
The query body should contain a JSON object with monitoring history data. The object has the following structure:
{
"invalid":false,
"timestamp":"2021-01-01T12:00:00",
"supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"progress":100,
"addedCount":0,
"locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"mapShapeLatitude":50.0,
"mapShapeLongitude":20.0,
"mapShapeMapCode":"default",
"parameters":[
{
"id": -1,
"parameterSettingUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"date": "2021-01-01T12:00:00",
"userUuid": "1c4066e6-cdd6-4903-803a-b6bffe689527",
"currentValue":"100.0",
"source":"FROM_WEBSERVICE"
}
]
}
Query
/rest/amage/v1/supervisions/add-history/1c4066e6-cdd6-4903-803a-b6bffe689527
Response
{
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Editing supervision history
-
Method:
POST
-
Path:
/edit-history/{uuid}
-
Generates:
application/json
-
Requires:
application/json
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parameters:
-
UUID - supervision history identifier
Due to operations on existing data, changes in related parameters are not included in the edit. The parameters remain unchanged. We only modify the parameters of the main object of supervision history. |
The query body should contain a JSON object with monitoring history data. The object has the following structure:
{
"invalid":false,
"timestamp":"2021-01-01T12:00:00",
"supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"progress":100,
"addedCount":0,
"locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"mapShapeLatitude":50.0,
"mapShapeLongitude":20.0,
"mapShapeMapCode":"default"
}
Query
/rest/amage/v1/supervisions/edit-history/1c4066e6-cdd6-4903-803a-b6bffe689527
Response
{
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Deletion of supervision history
-
Method:
DELETE
-
Path:
/delete-history/{uuid}
-
Generates:
application/json
-
Requires:
application/json
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parameters:
-
UUID - supervision history identifier
Query content (body) is empty.
Query
/rest/amage/v1/supervisions/delete-history/1c4066e6-cdd6-4903-803a-b6bffe689527
Response
{
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Examples
Sample Python code using the requests library to add supervision history.
#!/usr/bin/python3
import binascii
import hashlib
import requests
PARAM_SEPARATOR = ";"
def calc_api_sign(path, api_secret):
message_digest = hashlib.sha256()
message_digest.update(bytearray.fromhex(api_secret))
message_digest.update(PARAM_SEPARATOR.encode('utf-8'))
message_digest.update(path.encode('utf-8'))
return message_digest.digest()
def post_method(server_url, headers, path, json):
print(server_url + path)
url = server_url + path
response = requests.post(url, headers=headers, json=json)
print("received return code: {0}".format(response.status_code))
print("received data: {0}".format(response.text))
def get_header(path, content_type, accept):
headers = {
"Content-Type": content_type,
"Accept": accept,
"amage-device-uuid": device_uuid,
"amage-api-key": api_key,
"amage-api-sign": binascii.hexlify(calc_api_sign(path, api_secret)).decode()
}
return headers
server_url = "https://server.url/rest/amage/v1/"
device_uuid = "b0b135db-14f7-4d35-92d8-8357815185df"
api_key = "f4affb2db24b2b0903ad89ceeb622ece"
api_secret = "f4affb2db24b2b0903ad89ceeb622ede"
supervision_state_item_uuid = '1ba796f7-4a56-4ce1-ad6c-6d9c528974ad'
supervision_element_uuid = '1c4066e6-cdd6-4903-803a-b6bffe689527'
parameter_setting_uuid = '1c4066e6-cdd6-4903-803a-b6bffe689528'
request_path = "supervisions/add-history/" + supervision_element_uuid;
#ItemSource available values:
# FROM_DESKTOP,
# FROM_MOBILE,
# FROM_IDENTIFIER,
# FROM_DIFFERENCE,
# FROM_IMPORT,
# FROM_WEB_SERVICE,
# FROM_DATA_AGGREGATOR,
# FROM_AUTOMATION
1json = {
'invalid': False,
'timestamp': '2024-10-06T12:00:00',
'supervisionElementUuid': supervision_element_uuid,
'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185de',
'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
'progress': 100,
'addedCount': 1,
'mapShapeLatitude': 0,
'mapShapeLongitude': 0,
'mapShapeMapCode': 'default',
'parameters': [
{
'date': '2024-10-06T12:00:00',
'parameterSettingUuid': 'e3588070-5ccf-47fa-aa9d-e7ca0b929d90',
'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185de',
'currentValue': '99',
'source': 'FROM_WEB_SERVICE'
}
]
}
post_method(server_url, get_header(request_path, "application/json", "application/json"), request_path, json)
Example execution
Example query results for adding supervision history.
json = {
'invalid': False,
'timestamp': '2024-10-06T12:00:00',
'supervisionElementUuid': supervision_element_uuid,
'userUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
'progress': 100,
'addedCount': 1,
'locationUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
'mapShapeLatitude': 0,
'mapShapeLongitude': 0,
'mapShapeMapCode': 'default',
'parameters': [
{
'date': '2024-10-06T12:00:00',
'parameterSettingUuid': 'e3588070-5ccf-47fb-aa9d-e7ca0b929d90',
'userUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
'currentValue': '99',
'source': 'FROM_WEB_SERVICE'
}
]
}
Incorrect location UUID:
httpd://server.url/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 400
received data: {"id":null,"uuid":null,"success":false,"errorCode":400,"message":"Location not found with UUID: 75d2b25d-4698-48b9-bb62-7569ffb763fc"}
Invalid user UUID, no location:
/usr/bin/python3 example_supervision.py
http://localhost:8000/assetweb/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 400
received data: {"id":null,"uuid":null,"success":false,"errorCode":400,"message":"User not found with UUID: 75d2b25d-4698-48b9-bb62-7569ffb763fc"}
Correct data:
1json = {
'invalid': False,
'timestamp': '2024-10-06T12:00:00',
'supervisionElementUuid': supervision_element_uuid,
'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185df',
'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
'progress': 100,
'addedCount': 1,
'mapShapeLatitude': 0,
'mapShapeLongitude': 0,
'mapShapeMapCode': 'default',
'parameters': [
{
'date': '2024-10-06T12:00:00',
'parameterSettingUuid': 'e3588070-5ccf-47fb-aa9d-e7ca0b929d90',
'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185df',
'currentValue': '99',
'source': 'FROM_WEB_SERVICE'
}
]
}
/usr/bin/python3 example_supervision.py
http://server.url/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 200
received data: {"id":1000816683,"uuid":"d020d04c-756c-453e-8458-28590dc5c0fa","success":true,"errorCode":0,"message":""}
Process finished with exit code 0