Reading and updating the power at a client

In OZmap, a client and their residence are represented by distinct elements. The person who subscribed to an internet service is represented by the "Client" element, and the residence where this client lives and where the internet service is installed is represented by the "Property" element. Therefore, the power level related to a client is read and edited in the "Property" element in OZmap.

Initial Scenario

As an example, consider a scenario where a monitoring or provisioning software wants to read and update the power levels of clients in OZmap.

Example

A client monitored by the integrator software experiences a change in power level, and the software needs to verify if the new power level in its monitoring system differs from the client’s power level in OZmap. If they are different, it needs to update the power level to the new value in OZmap. The client in this software is identified in OZmap by the 'Code' (code) attribute in this example, but other attributes can be used, such as the MAC address (mac_address).

API

The next step is to figure out how the requests for reading and updating the client’s power level should be made. Below is an example:

Given the information of the code that identifies the client in OZmap, for this example, let’s assume the client’s code is: power-test

First, we will request OZmap to find the current power level.

With the client’s code being power-test, the search in OZmap would be done as follows:

curl --location --request 
GET 'https://sandbox.ozmap.com.br:9994/api/v2/properties/client/power-test' \
--header 'authorization: AUTHORIZATION_TOKEN' \
--header 'Accept: application/json' \

Attention! The authorization token must be created in the OZmap interface. For more information, click here.

The expected return for this search is:

[
    {
        "_id": "64399b0a7112800014c374bb",
        "observation": "",
        "drop": "64399b0a7112800014c374bd",
        "tags": [],
        "cables": [],
        "kind": "Property",
        "coords": [
            -48.528035581111915,
            -27.576536156030667
        ],
        "address": "",
        "box": "5da728dd11450e0006947cbb",
        "pole": "5da728dd11450e0006947cbd",
        "client": {
            "_id": "64399b0a7112800014c374b8",
            "certified": false,
            "status": 0,
            "observation": "",
            "tags": [],
            "implanted": true,
            "onu": {
                "user_PPPoE": "",
                "serial_number": "",
                "mac_address": ""
            },
            "kind": "ftth",
            "code": "power-test",
            "name": "Cliente Teste Potências",
            "creatorData": {
                "id": "5d9f3fb8200141000647f768",
                "name": "Support OZmap",
                "username": "devoz"
            },
            "createdAt": "2023-04-14T18:27:22.741Z",
            "updatedAt": "2023-04-14T19:43:49.595Z",
            "__v": 0
        },
        "project": "5d9f3ff9200141000647f814",
        "creatorData": {
            "id": "5d9f3fb8200141000647f768",
            "name": "Support OZmap",
            "username": "devoz"
        },
        "history": {
            "clients": [
                {
                    "id": "64399b0a7112800014c374b8",
                    "code": "power-test",
                    "enter_date": "2023-04-14T18:27:22.747Z",
                    "exit_date": null
                }
            ]
        },
        "createdAt": "2023-04-14T18:27:22.751Z",
        "updatedAt": "2023-04-14T19:43:49.965Z",
        "__v": 0,
        "potencyRead": -20.05,
        "connections": [
            {
                "id": "5da728dd11450e0006947cbf",
                "kind": "Splitter",
                "port": 5,
                "name": "Splitter 1",
                "implanted": true,
                "fiber": "64399b0a7112800014c374be"
            }
        ]
    }
]

The current power level recorded for the client’s property is indicated by the potencyRead attribute, which returned the value of -20.05. This attribute is only present in the response if a value for the power level is defined in OZmap. Therefore, if potencyRead is not included in the response, it indicates that the client does not have a power value set for their property in OZmap.

Assuming that the new power level in the monitoring software is -23.47, the power update for this client’s property should be done using the _id attribute, which in this example has the value 64399b0a7112800014c374bb.

With the id 64399b0a7112800014c374bb, the power update in OZmap would be done as follows:

curl --location --request 
PATCH 'https://sandbox.ozmap.com.br:9994/api/v2/properties/64399b0a7112800014c374bb' \
--header 'authorization: AUTHORIZATION_TOKEN' \
--header 'Content-Type: application/json \
--data-raw '{
    "potencyRead": -23.47
}'

Attention! The authorization token must be created in the OZmap interface. For more information, click here.

The expected response for this operation is an empty message with a "204 No Content" status, indicating that the client’s power level was successfully updated.