Adding images as posts in boxes and clients

Adding images as posts in OZmap is performed in two main steps:

Creating the post on the element (such as a Box or a Client).
Adding the image to the newly created post.

Below, we detail these steps with two practical examples of API calls in OZmap: one demonstrates how to perform this procedure for Boxes, and the other for Clients.

At the end of this documentation, you'll also find instructions on how to search for posts by element or by post ID.

Example 1

Below is an example of how to create a post with an image in a Box in OZmap.

1. Create a Post in a Box

We will use the following Box data as an example:

{
  ...
  "kind": "Box",
  "project": "5d9f3ff9200141000647f814",
  "name": "CTO - Example",
  "pole": "5da61d8e493d9c000666541d",
  "boxType": "589ddcf07dfe452f10d7c274",
  "hierarchyLevel": 2,
  "implanted": false,
  "observation": "",
  "history": [],
  "createdAt": "2019-10-15T19:29:23.366Z",
  "updatedAt": "2024-12-07T21:25:17.110Z",
  "tags": [],
  "id": "5da61e13493d9c0006665474",
  "lng": -48.52691441774369,
  "lat": -27.57763947862014
  ...
}

Using the Box ID (5da61e13493d9c0006665474), we can create the "Example" post linked to this Box. Use the following API call:

curl --location 'http://example.ozmap.com.br:9090/api/v2/posts' \
--header 'Authorization: <API Key>' \
--form 'title="Example"' \
--form 'observation="Created as an example"' \
--form 'element.id="5da61e13493d9c0006665474"' \
--form 'element.kind="box"'

If the post is successfully created, the API will return the status 201 Created and the following response:

{
    "element": {
        "id": "6679af75a6f60e0014e5e5e5",
        "kind": "box"
    },
    "owner": "64de32ae14ce55033e8b1f63",
    "tags": [],
    "title": "Example",
    "observation": "Created as an example",
    "files": [],
    "creatorData": {
        "id": "64de32ae14ce55033e8b1f63",
        "name": "example",
        "username": "example"
    },
    "_id": "67573d571cd4d097fa52d5fd",
    "createdAt": "2024-12-09T18:56:23.189Z",
    "updatedAt": "2024-12-09T18:56:23.189Z",
    "__v": 0,
    "id": "67573d571cd4d097fa52d5fd"
}

2. Add an Image to the Created Post

With the post created, identify the Post ID (67573d571cd4d097fa52d5fd). Now, add an image to the post by specifying the element type (post), the Post ID, and the image file path.

Use the following API call:

curl --location 'https://example.ozmap.com.br:9994/api/v2/files' \
--header 'Authorization: <API Key>' \
--form 'element.kind="post"' \
--form 'element.id="67573d571cd4d097fa52d5fd"' \
--form 'files=@"/example/example.png"'

If the image is successfully added, the API will return the status 201 Created and the following response:

[
    {
        "name": "example.png",
        "contentType": "image/png",
        "_id": "675739df7aa07efbe653da82",
        "createdAt": "2024-12-09T18:41:35.348Z",
        "updatedAt": "2024-12-09T18:41:35.348Z",
        "__v": 0,
        "id": "675739df7aa07efbe653da82"
    }
]

Example 2

Below is an example of creating a post with an image in a Client in OZmap.

1. Create a Post in a Client

We will use the following OZmap Property data as an example:

{
    "drop": "6400e9c18a21020d261e7df6",
    "tags": [],
    "cables": [],
    "kind": "Property",
    "box": "5da7581911450e000694802f",
    "client": {
        "certified": false,
        "status": 0,
        "observation": "",
        "tags": [],
        "implanted": false,
        "onu": {
            "user_PPPoE": "",
            "serial_number": "ZTEGC8FBF102",
            "mac_address": "",
            "id": "6757442b7aa07efbe653f352"
        },
        "kind": "ftth",
        "code": "login3627",
        "createdAt": "2023-03-02T18:24:01.315Z",
        "updatedAt": "2024-10-15T18:29:15.351Z",
        "id": "6400e9c18a21020d261e7df1"
    },
    "id": "6400e9c18a21020d261e7df4",
    "lng": -48.589592553843374,
    "lat": -27.577004146565635,
    ...
}

Using the Property ID (6400e9c18a21020d261e7df4), we can create a post titled "Example" linked to this Client. Use the following API call:

curl --location 'http://example.ozmap.com.br:9090/api/v2/posts' \
--header 'Authorization: <API Key>' \
--form 'title="Example"' \
--form 'observation="Created as an example"' \
--form 'element.id="6400e9c18a21020d261e7df4"' \
--form 'element.kind="property"'

If the post is successfully created, the API will return the status 201 Created and the following response:

{
    "element": {
        "id": "6400e9c18a21020d261e7df4",
        "kind": "property"
    },
    "owner": "64de32ae14ce55033e8b1f63",
    "tags": [],
    "title": "Example",
    "observation": "Created as an example",
    "files": [],
    "creatorData": {
        "id": "64de32ae14ce55033e8b1f63",
        "name": "example",
        "username": "example"
    },
    "_id": "67573d571cd4d097fa52d5fd",
    "createdAt": "2024-12-09T18:56:23.189Z",
    "updatedAt": "2024-12-09T18:56:23.189Z",
    "__v": 0,
    "id": "67573d571cd4d097fa52d5fd"
}

2. Add an Image to the Created Post

With the post created, identify the Post ID (67573d571cd4d097fa52d5fd). Add an image to the post by specifying the element type (post), the Post ID, and the image file path.

Use the following API call:

curl --location 'https://example.ozmap.com.br:9994/api/v2/files' \
--header 'Authorization: <API Key>' \
--form 'element.kind="post"' \
--form 'element.id="67573d571cd4d097fa52d5fd"' \
--form 'files=@"/example/example.png"'

If the image is successfully added, the API will return the status 201 Created and the following response:

[
    {
        "name": "example.png",
        "contentType": "image/png",
        "_id": "675739df7aa07efbe653da82",
        "createdAt": "2024-12-09T18:41:35.348Z",
        "updatedAt": "2024-12-09T18:41:35.348Z",
        "__v": 0,
        "id": "675739df7aa07efbe653da82"
    }
]

Searching for Posts in OZmap

There are three ways to search for posts in OZmap, and here is how to do each way:

Search for all posts
Serach for a specific post by ID
Search posts for a specific element

Search for all posts:

curl --location 'http://example.ozmap.com.br:9090/api/v2/posts \
--header 'Authorization: <API Key>'

Search for a specific post by ID:

curl --location 'http://example.ozmap.com.br:9090/api/v2/posts/67573d571cd4d097fa52d5fd \
--header 'Authorization: <API Key>'

Search posts for a specific element (e.g. all posts linked to a Box or Property):

In this example, we’ll demonstrate how to retrieve all posts related to a specific Box with the ID 65cfbfbc2cf4a70020d9498b. To achieve this, you simply need to add a filter query to your request. Here’s how to do it:

curl --location 'http://example.ozmap.com.br:9090/api/v2/posts?filter=[{"property":"element.id","operator":"eq","value":"65cfbfbc2cf4a70020d9498b"}] \
--header 'Authorization: <API Key>'

If there are posts for this element, the response will return a status code 201 along with all posts related to it.

{
    "total": 2,
    "count": 2,
    "rows": [
        {
            "title": "Post on Box example",
            "observation": "Post on Box example",
            "element": {
                "id": "65cfbfbc2cf4a70020d9498b",
                "kind": "box"
            },
            "createdAt": "2024-02-16T20:04:22.361Z",
            "updatedAt": "2024-02-16T20:04:22.361Z",
            "id": "65cfbfbc2cf4a70020d9498b"
            ...
        },
        {
            "title": "Post on Box example 2",
            "observation": "Post on Box example 2",
            "element": {
                "id": "65cfbfbc2cf4a70020d9498b",
                "kind": "box"
            },
            "createdAt": "2024-02-16T20:27:10.483Z",
            "updatedAt": "2024-02-16T20:27:11.795Z",
            "id": "65cfbfbc2cf4a70020d9498b"
            ...
        }
    "start": 0,
    "limit": 25
}