Reading and updating a client status

In OZmap, a client and their residence are represented by distinct elements. The "Client" element represents the person who subscribed to an internet service, and the residence where this client lives and where the internet service is installed is represented by the "Property" element. Therefore, the status of a customer is read and edited in the "Client" element in OZmap. The color of the icon representing the customer in OZmap is defined by their status, with two statuses currently available: "OK" (green icon) and "ERROR" (red icon).

Initial Scenario

For example, consider a scenario where a monitoring or provisioning software needs to read and update client statuses in OZmap.

Example

A client monitored by the integrator software experiences an optical signal loss, and the software needs to update the client’s status in OZmap to ERROR. In this example, the client in the software is identified in OZmap by the "Code" (code) attribute, 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 Client statuses should be made. Below is an example:

For this example, let's assume the client’s code is: test-status. First, we need to identify the client ID to be updated.

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

curl --location --request 
GET 'https://sandbox.ozmap.com.br:9994/api/v2/properties/client/test-status' \
--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 is:

[
    {
        "_id": "643d32bf7112800014c38742",
        "observation": "",
        "drop": "643d32bf7112800014c38744",
        "tags": [],
        "cables": [],
        "kind": "Property",
        "coords": [
            -48.52836683392526,
            -27.576685937919645
        ],
        "address": "",
        "box": "5da728dd11450e0006947cbb",
        "pole": "5da728dd11450e0006947cbd",
        "client": {
            "_id": "643d32be7112800014c3873f",
            "certified": false,
            "status": 0,
            "observation": "",
            "tags": [],
            "implanted": true,
            "onu": {
                "user_PPPoE": "",
                "serial_number": "",
                "mac_address": ""
            },
            "kind": "ftth",
            "code": "test-status",
            "name": "Cliente Teste Status",
            "creatorData": {
                "id": "5d9f3fb8200141000647f768",
                "name": "Support OZmap",
                "username": "devoz"
            },
            "createdAt": "2023-04-17T11:51:26.981Z",
            "updatedAt": "2023-04-17T11:51:26.981Z",
            "__v": 0
        },
        "project": "5d9f3ff9200141000647f814",
        "creatorData": {
            "id": "5d9f3fb8200141000647f768",
            "name": "Support OZmap",
            "username": "devoz"
        },
        "history": {
            "clients": [
                {
                    "id": "643d32be7112800014c3873f",
                    "code": "teste-status",
                    "enter_date": "2023-04-17T11:51:27.067Z",
                    "exit_date": null
                }
            ]
        },
        "createdAt": "2023-04-17T11:51:27.072Z",
        "updatedAt": "2023-04-17T11:51:27.493Z",
        "__v": 0,
        "connections": [
            {
                "id": "5da728dd11450e0006947cbf",
                "kind": "Splitter",
                "port": 6,
                "name": "Splitter 1",
                "implanted": true,
                "fiber": "643d32bf7112800014c38745"
            }
        ]
    }
]

The current status recorded for this customer is indicated by the status attribute of the "client" object, which returned the value 0, representing the "OK" status.

To modify this client’s status, the update should be made using the _id attribute of the "client" object, which in this example has the value 643d32be7112800014c3873f. We must pass status 1, which represents the "ERROR" status.

With the id 643d32be7112800014c3873f, the status update in OZmap is done as follows:

curl --location --request 
PATCH 'https://sandbox.ozmap.com.br:9994/api/v2/ftth-clients/643d32be7112800014c3873f' \
--header 'authorization: AUTHORIZATION_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": 1
}'

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 status was successfully updated.

Batch update

Also, there is a way to update the status of multiple clients simultaneously, which can be done through a batch update. For example, we’ll use the clients with the following IDs: 643d32be7112800014c3873f, 6400e9c18a21020d261e7df1, and 6400e9e28a21020d261e7e32. Taking these IDs into account, the bulk update of those clients' status in OZmap can be performed as follows:

The expected response for this operation is an empty message with a “204 No Content” status, indicating that the clients’s status were successfully updated.