# Configure the topology

## Key concepts

**Canvas** - the interactive workspace on the topology editing page where all blocks and their cells are displayed visually.

**Block** - a logical unit of the structure. A block can be any element of the topology (warehouse, container, section, line, rack, shelf, etc.) placed on the canvas.

**Cell** - a slot for a single device. Cells are added inside a block.

**Index** - a unique address of a cell, automatically generated from the names of the facility and its blocks. Example: `TEX-Cont-Rack-10`.

## How to generate a topology

When a new facility is created, the system automatically generates an empty topology for it. It immediately appears on the Topology page - no additional steps are required.

<figure><img src="/files/2cE4F88kWiSl1slTTXAM" alt=""><figcaption></figcaption></figure>

To build out the structure, open the topology and add blocks (see "How to create a block").

> ⚠️ Each facility is linked to exactly one topology. It is not possible to create a second topology for the same facility.

## How to edit a topology

1. Go to  **Settings → Topology**
2. Click the **Edit topology** icon next to the topology you want to edit - the editing page will open.
3. Make your changes: add, edit, or delete blocks.
4. Click **Save** to apply the changes.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fay3wuqHdkAAEzg5N1LTo%2Fuploads%2FPcAAciFFffpuZjWKNn8o%2FEdit%20topology.mp4?alt=media&token=48b792fe-8153-45c0-ad17-5d587c8544d9>" %}

## How to create a block

Blocks are the main elements of a topology. They are created on the canvas and displayed as cards.

#### Parent block

1. Go to the **Topology** page.
2. Click the **Edit topology** icon next to the needed topology - the editing page will open.
3. On the canvas, click **Add block**, or click the **⋮** icon on any existing block card and select **Add** - the block creation wizard will open.
4. Fill in the parameters across three steps:

**Step 1 - Details**

* **Block title** - the only required field.
* **Cells per row** and **Levels** - define the number of cells horizontally and vertically.
* A live preview updates on the right as you change values.

**Step 2 - Index settings**

* **Starting number** - the starting value for cell numbering inside the block.
* **Numbering method** - defines whether cell numbering restarts for each level or continues incrementally.
* **Numbering direction** - the direction in which indexes are assigned (left to right, top to bottom, etc.).
* A live preview updates on the right as you change values.

**Step 3 - Inner blocks grid**

* **Blocks per row** - defines how many child blocks will be displayed per row if nested blocks are added inside this block later.
* A live preview updates on the right as you change values.

5. Click **Add** - the block will appear on the canvas.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fay3wuqHdkAAEzg5N1LTo%2Fuploads%2FQLbhjTDBH3q3XikN8UDh%2FCreate%20block_EN.mp4?alt=media&token=89bf90a1-ba83-49f1-bd78-e3abff162755>" %}

#### Inner block

An inner block is created inside an existing block to add more detail to the structure.

1. On the canvas, find the needed block and click the **⋮** icon on its card.
2. Select **Add** - the **Add block** wizard will open.
3. Fill in the parameters the same way as for a parent block.
4. Click **Add** - the block will appear on the canvas.

**Example structure:** Cont → Rack → cells.

> ⚠️ The maximum nesting depth is 6 levels.&#x20;

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fay3wuqHdkAAEzg5N1LTo%2Fuploads%2FeKpv9ilOFvKs8us0xXXg%2FInner%20block_EN.mp4?alt=media&token=e62e3247-d746-4e1e-a1e3-c5b7fc4a7a54>" %}

## How to duplicate a block

1. Go to the **Topology** page.
2. Click the **Edit topology** icon next to the needed topology.
3. Click the **⋮** icon on the block card and select **Duplicate**.
4. In the **Duplicate block** modal, select the number of duplicates.
5. The copies will appear on the canvas next to the original block with identical parameters.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fay3wuqHdkAAEzg5N1LTo%2Fuploads%2FYeyl7uWuuNSAgCOXJbcd%2FDublicate%20block_EN.mp4?alt=media&token=46169e94-688e-4d64-bd2c-7bfd82fa353f>" %}

## How to edit a block

1. Go to the **Topology** page.
2. Click the **Edit topology** icon next to the needed topology.
3. Click the **⋮** icon on the block card and select **Edit**.
4. Make the necessary changes.
5. Click **Save**.

> ⚠️ If the block contains devices, saving the changes will:
>
> * move all devices to **Unimported**;
> * reset all cell reservations.
>
> The system will display a warning before the action is confirmed.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fay3wuqHdkAAEzg5N1LTo%2Fuploads%2FJQX34GYrSbvpbA0AaEiH%2FEdit%20block_EN.mp4?alt=media&token=7cdc5dba-fd55-4aff-872a-27cd98ef9bc3>" %}

## How to move a block

1. Go to the **Topology** page.
2. Click the **Edit topology** icon next to the needed topology.
3. Click the **⋮** icon on the block card and select **Move**.
4. Specify the new location of the block within the topology structure.
5. Confirm the move.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fay3wuqHdkAAEzg5N1LTo%2Fuploads%2FEZjxIJSOmBnGZA1KEyzV%2FMove%20block_EN.mp4?alt=media&token=d749bd03-778b-4227-8b4d-b2fde8efdfd5>" %}

## How to delete a block

1. Go to the **Topology** page.
2. Click the **Edit topology** icon next to the needed topology.
3. Click the **⋮** icon on the block card and select **Delete**.
4. Confirm the deletion in the modal window.

> ⚠️ Deleting a block removes all nested blocks and cells inside it. Devices from the deleted block are moved to **Unimported** - they can be reassigned to other cells.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fay3wuqHdkAAEzg5N1LTo%2Fuploads%2FGybP9L2881CVg2vdQ05Z%2FDelete%20block_EN.mp4?alt=media&token=550f9fc5-7fad-4b40-8225-4fc870020dc5>" %}

## How to use topology in daily work

Once set up, the topology becomes a practical tool for technicians and operators.

* **Checking occupancy.** Each block card on the canvas shows the ratio of occupied to total cells in the format X / Y. For example, 48 / 60 means 12 cells are available. The same figures appear on the Topology page in the **Occupied cells** and **Total cells** columns.
* **Visual cell status.** Occupied cells appear darker, free cells appear lighter. This makes it easy to assess block occupancy at a glance without manual counting.

  <figure><img src="/files/XxnwrwS7WasqWDzYNnH7" alt=""><figcaption></figcaption></figure>
* **Viewing device details.** Clicking an occupied cell opens a popover with device information: index, serial number, IP address, and MAC address. Any value can be copied to the clipboard.

  <figure><img src="/files/oZW6HmUNNyIJyXqkYw46" alt=""><figcaption></figcaption></figure>
* **Canvas navigation.** Use the mouse scroll or touchpad to pan around the canvas. Zoom in and out using the **+** / **−** buttons in the bottom-right corner. The **Fit view** button resets the view to show the entire topology.

## FAQ

<details>

<summary><strong>What is topology for?</strong></summary>

Topology lets you visualize equipment placement within the real structure of your facility, simplifies navigation, and speeds up access to devices. It also powers the Facility map - an alternative Dashboard view with color-coded status and temperature indicators.

</details>

<details>

<summary><strong>Can I create a block without cells?</strong></summary>

Yes. Blocks can be empty - without cells. Cells can be added later by editing the block. An empty block can also serve as a container for nested blocks.

</details>

<details>

<summary><strong>What is a cell index and how is it formed?</strong></summary>

An index is a unique cell address in the system. It is generated automatically from the names of the facility and all blocks in the hierarchy. Example: TEX-Cont-Rack-10, where TEX is the facility, Cont and Rack are blocks, and 10 is the cell number.

</details>

<details>

<summary><strong>Can I change the topology structure after it has been created?</strong></summary>

Yes. You can add, edit, move, and delete blocks at any time. Changes take effect after clicking **Save.**

</details>

<details>

<summary><strong>What happens to devices when a block is edited or deleted?</strong></summary>

Devices are moved to **Unimported**. They are not removed from the system - they can be reassigned to other cells.

</details>

<details>

<summary><strong>How many topologies can be created for one facility?</strong></summary>

One. A topology is created automatically when a facility is added and is linked to it on a 1:1 basis. Creating a second topology for the same facility is not possible.

</details>

<details>

<summary><strong>Can I view the topology without edit permissions?</strong></summary>

Yes. Users with the View only role can browse the topology structure in read-only mode without making any changes.

</details>

<details>

<summary><strong>How do I find a free cell for a new device?</strong></summary>

Free cells appear lighter than occupied ones on the canvas. The number of available slots is also shown on each block card in the X / Y format, and in the Free cells column on the Topology page. To record the cell address, click it and copy the index from the popover - you will need it when importing or moving a device.

</details>

<details>

<summary><strong>How do I quickly find a device's IP or serial number?</strong></summary>

Click an occupied cell on the canvas - a popover will open with the device's serial number, IP address, and MAC address. Any value can be copied to the clipboard with a single click, without switching to the device table.

</details>

***

#### We're always available! <a href="#were-always-available" id="were-always-available"></a>

Chat with us on [Telegram](https://t.me/moondmc_bot).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.moonone.online/getting-started/configure_the_topology.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.