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"
        }
    ]
}
W przypadku pobierania danych z systemu pole ID, UUID będą w zwracanej strukturze wypełnione danymi pochodzącymi z systemu. Pole ID to identyfikator lokalnej bazy danych. Pole UUID to identyfikator globalny w systemie AMAGE, który może służyć jako identyfikator jednoznacznie identyfikujący obiekt w systemie i w integracjach pomiędzy systemami.

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":""
}
W przypadku zapisu danych z systemu pole ID nie może być wypełnione. Zostaje ono uzupełnione podczas zapisu rekordu do bazy danych i zwrócone w strukturze odpowiedzi. Jeśli pole UUID zostanie podane, to taka wartość zostanie przypisana do rekordu. System nie sprawdza unikalności UUID w ramach struktur lub kontekstu całego systemu. Jeśli UUID nie zostanie podane, to system wygeneruje własne unikalne UUID.

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