OZloc - English ver.

OZloc is a tool integrated with OZmap that allows you to check the network feasibility for a given point on the map. It can be integrated with other systems, receiving the necessary information to perform a feasibility check through URL parameters.

To see practical examples, download the following project and follow the instructions described in its README.md.

Parameters received via URL

authorization

It is a token/API key used to authenticate with the system. This key can be generated through the OZmap user panel and must be used OZloc externally. The user must have access to the “API” module for their key to be used.

From that point on, all actions will be performed by the user to whom the key belongs, such as creating new customers in OZmap.

e.g. https://example.ozmap.com.br:9443?authorization=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtb2R1bGUiOiJhcGkiLCJ1c2VyIjoiNjIxMzlhZTMxZGNmYzcwMDE2YTc2MWY5IiwiY3JlYXRpb25EYXRlIjoiMjAyMi0wNS0wM1QxNzo0MDo0MC4xMjBaIiwiaWF0IjoxNjUxNTk5NjQwfQ.sFOkx0jZPtyPVOjWHWFAxxAzFOBZd711-up89lsJeco

lat & lng

They receive the latitude and longitude indicating the point on the map where the system will place the marker and perform the feasibility check.

e.g. https://example.ozmap.com.br:9443?lat=-27.5902598&lng=-48.6262313

address

It receives a value that will autofill the address field in the client form. Additionally, if the lat & lng parameters were not provided, the address is converted into a geographic coordinate from which the feasibility check will be performed.

e.g. https://example.ozmap.com.br:9443?address=1234 Elm Street, Springfield, IL 62704

cod_cli

It receives a value that will autofill the code field in the client form.

e.g. https://exemplo.ozmap.com.br:9443?cod_cli=2800

client_name

It receives a value that will autofill the name field in the client form.

e.g. https://exemplo.ozmap.com.br:9443?client_name=someone

integration_code

Used to indicate the address change process, it receives a value that refers to the ID of the property of the client’s old address in OZmap.

e.g. https://exemplo.ozmap.com.br:9443?integration_code=5f5a62c8043f1f0013e3ea36

disable_code

It receives the value 'true' to disable the code field in the client form (the field is enabled by default)

e.g. https://exemplo.ozmap.com.br:9443?disable_code=true

disable_name

It receives the value 'true' to disable the name field in the client form (the field is enabled by default)

e.g. https://exemplo.ozmap.com.br:9443?disable_name=true

disable_address

It receives the value 'true' to disable the address field in the client form (the field is enabled by default)

e.g. https://exemplo.ozmap.com.br:9443?disable_name=true

show_summary

It receives the value 'false' to disable the summary displayed after completing a sale in the system (the sales summary is enabled by default).

e.g. https://exemplo.ozmap.com.br:9443?show_summary=false

expand_report

It receives the value 'true' to display the expanded sales summary (occupying the entire page) after completing a sale in the system (the sales summary is presented in a pop-up window by default).

e.g. https://exemplo.ozmap.com.br:9443?expand_report=true

Feasibility Returns

If feasibility is confirmed and a reservation is made, the sales/client creation information is sent through events and can be accessed externally (more information here). The object sent by the event contains the following fields:

{ 
  action: 'client_created', 
  success: true, 
  client_data: {...}
}

The information contained in client_data varies depending on the feasibility situation. We’ll detail every scenario below:

New house

To create a client at a new property, the feasibility check searches for boxes with available ports (in network equipment, e.g., splitters) for the connection. Once created, the 'client_created' event is triggered with information about the newly created client and the feasibility.

Among the most important fields in client_data, we highlight:

new_property: Takes a boolean value indicating whether the client was created at a new property (true) or an existing one (false).
box: Contains the box data to which the client was connected (name, type, available ports, etc.).
olt_connection: A string that indicates the client’s equipment and connection port at the POP.

Complete return in JSON format:

Property

When a client is created at a property (i.e., an existing property where no client is currently allocated), the 'client_created' event is triggered with information about the newly created client and the feasibility.

Among the most important fields in client_data, we highlight:

new_property: Takes a boolean value indicating whether the client was created at a new property (true) or an existing one (false).
box: Contains the box data to which the client was connected (name, type, available ports, etc.).
olt_connection: A string that indicates the client’s equipment and connection port at the POP.

Complete return in JSON format:

Vertical building

When a feasibility request is made considering condominiums, the 'buildings' attribute provides a list of available vertical complexes in the given location. The 'availability' property indicates the number of free ports for connecting a new client, and 'connectors' is a list of network equipment available for connection in each complex.

Among the most important fields in client_data, we highlight:

building: Contains the data of the building where the client was created (name, type, available ports, etc.), including the equipment located there (connectors) and the availability of each one (availability).

olt_connection: A string that indicates the client's equipment and connection port at the POP.

Complete return in JSON format:

Gated community

A gated community represents the layout of an isolated area on the map. Therefore, with the option to consider gated communities enabled in the OZmap system settings, only elements within that area will be returned if the feasibility request was made from a point that intersects with it.

The returned data follows the same pattern as the elements in the previously mentioned topics, with the distinction of the 'horizontal_condos' attribute. Among the most important fields in client_data, we can highlight:

horizontal_condos: Contains an array of strings with the unique identifier (ID) of the horizontal condos present at the given point for feasibility (there may be multiple).

Complete return in JSON format:

No Feasibility Returns

If feasibility is denied, the event information follows the presented standard:

{ 
  action: 'viability_requested', 
  success: false, 
  viability_data: {...}
}

The information contained in viability_data varies depending on the infeasibility situation and is detailed below for each scenario:

Infeasibility due to the unavailability of ports

Infeasibility due to unavailability of ports occurs when elements are within the feasibility request area, but no ports are available for a new connection. Among the most important fields in viability_data, we highlight:

refused_boxes: Contains an array of objects with information about the rejected boxes, including the 'reason' attribute, which presents a numeric value indicating the reason for infeasibility. The value for port unavailability is 1. Example of refused_boxes:

    "refused_boxes": [
        {
            "distance": 0,
            "name": "CTO - 4",
            "id": "5da6200b493d9c0006665551",
            "project": "5d9f3ff9200141000647f814",
            "lat": -27.577986588258526,
            "lng": -48.52433681488038,
            "implanted": false,
            "reasons": [
                {
                    "reason": 1
                }
            ],
            "horizontal_condos": []
        }
    ],

refused_buildings: Follows the same structure as refused_boxes, but for vertical buildings that had their feasibility denied.

Infeasibility due to lack of nearby network

This infeasibility occurs when no network elements (boxes, condos, etc.) allow client connections within the area radius from the point checked for feasibility. We determine that the cause is a lack of network when the return indicates infeasibility but the refused_boxes and refused_buildings fields within viability_data contain empty arrays.