Lesson 1. Maps & Entity Tables

In this lesson, you will model a smart-building scenario — two buildings, two offices, and four IoT devices — then build a Buildings dashboard with an OpenStreet Map widget and an Entities table widget.

Assets represent real-world objects such as buildings and office spaces.

In this step, create four assets: Building A, Building B, Office A, and Office B.
Each asset should also include attributes such as building coordinates, address, floor information, office phone number, and other relevant details that will be used in the next step.

You can create each asset manually or import multiple assets at once using bulk provisioning feature. After import, all buildings and offices will have the required attribute data.

1. Download building-assets.csv
2. Go to Entities ⇾ Assets.
3. Click + Add asset ⇾ Import asset.
4. Drag the building-assets.csv file into the import window and click Continue.
5. Verify the delimiter ,, then click Continue.
6. Map the data between the uploaded file columns and the ThingsBoard data types using the table below.
7. Click Continue, then OK.

Go to Entities ⇾ Assets and click "+ Add asset ⇾ Import assets Upload the CSV file (e.g., "building-assets.csv") and click Continue Configure import settings (CSV delimiter must be ",") and click Continue Map CSV columns to Name, Type, and server attributes (e.g., latitude, longitude, address) Complete attribute mapping (email, phone, contactPerson) and click Continue Import completed — new assets were successfully created

Check the import result.

Open "Building A" and verify imported server attributes Open "Building B" and verify imported server attributes

1. Download office-assets.csv
2. Click + Add asset ⇾ Import asset.
3. Drag the office-assets.csv file into the import window and click Continue.
4. Verify the delimiter ,, then click Continue.
5. Map the data between the uploaded file columns and the ThingsBoard data types using the table below.
6. Click Continue, then OK.

Click "+ Add asset" ⇾ "Import assets" Upload the CSV file (e.g., "office-assets.csv") and click Continue Configure import settings (CSV delimiter must be ",") and click Continue Map CSV columns to Name, Type, and server attributes (e.g., floor, email, phone, officeManager) and click "Continue" Import completed — two new assets were successfully created

Check the import result.

Open "Office A" and verify imported server attributes Open "Office B" and verify imported server attributes

Devices are IoT entities that collect data from their environment, send it to ThingsBoard, and respond to RPC commands.

Create four devices—an indoor air quality sensor, an energy meter, a water flow meter, and another indoor air quality sensor—using the bulk provisioning feature as well. Each sensor has its own type and location coordinates, which will be used later to display them on the office map.

Save the following content as devices.csv:

name,type,label,xPos,yPos
SD-001,air-sensor,Indoor Air Quality Sensor,0.51,0.68
EM-002,energy-sensor,Energy Meter,0.14,0.95
WM-003,water-sensor,Water Flow Meter,0.14,0.32
AM-307,air-sensor,IAQ Sensor,0.49,0.38

Or download a pre-made one.

1. Go to Entities ⇾ Devices.
2. Click + Add device ⇾ Import device.
3. Drag the devices.csv file into the import window and click Continue.
4. Verify the delimiter, then click Continue.
5. Map columns: name ⇾ Name, type ⇾ Device Profile, label ⇾ Label.
6. Click Continue, then OK.

Navigate to Entities ⇾ Devices, click "+ Add device", and select "Import device" Step 1. Upload a CSV file by dragging it into the upload area or clicking "Browse file", then click Continue Configure import settings: verify the CSV delimiter and options such as "First line contains column names" and "Update attributes/telemetry", then click Continue Map CSV columns to entity fields (e.g., Name, Type, Label) and assign attribute or telemetry keys (e.g., xPos, yPos), then click Continue Verify that the import process completed successfully and click OK Imported devices are displayed in the Devices table

The Attributes tab for each device displays server attributes, including active, xPos, and yPos.

The “Attributes” tab for device “SD-001” displays server attributes, including active, xPos, and yPos The “Attributes” tab for device “EM-002” displays server attributes, including active, xPos, and yPos The “Attributes” tab for device “WM-003” displays server attributes, including active, xPos, and yPos The “Attributes” tab for device “AM-307” displays server attributes, including active, xPos, and yPos

Feature Relations define directed connections between entities.

Link each building to its offices, and each office to its devices.

Buildings
├── Building A
│   ├── Office A
│   │   ├── SD-001
│   │   ├── EM-002
│   │   └── WM-003
│   └── Office B
│       └── AM-307
└── Building B

Link offices to Building A:

1. Open Building A details and go to the Relations tab.
2. Set direction to From, then click +.
3. Set relation type to Contains and entity type to Asset.
4. Select Office A and Office B, then click Add.

Open Building A ⇾ go to Relations tab ⇾ click "+" to add a relation Set relation type to "Contains", choose entity type "Asset", and select Office A and Office B Relations created — Building A now contains Office A and Office B

Link devices to Office A:

1. Open Office A details, go to Relations ⇾ From, and click +.
2. Set relation type to Contains and entity type to Device.
3. Select SD-001, EM-002, and WM-003, then click Add.

Repeat the same steps for Office B, selecting only AM-307.

Open Office A ⇾ go to Relations tab ⇾ click "+" to add a relation Set relation type to "Contains", choose entity type "Device", and select SD-001, EM-002, and WM-003 Relations created — Office A now contains SD-001, EM-002, and WM-003 Repeat for Office B — link device AM-307

A Dashboard is where you visualize and interact with your assets and devices.

Create a dashboard in a separate group for the buildings scenario.

1. Go to Dashboards.
2. Click + Add dashboard ⇾ Create new dashboard.
3. Enter dashboard title (e.g., Buildings).
4. Add dashboard to the group:
   • Enter Buildings in the “Groups” field
   • Click Create a new one!.
   • Confirm creating dashboard group by clicking Add.
5. Click Add to confirm creating dashboard.
6. Save the dashboard by clicking the Save button in the upper-right corner of the screen.

Go to Dashboards and click "+ Add dashboard" ⇾ Create new dashboard Enter dashboard title (e.g., "Buildings") Enter "Buildings" in the "Groups" field, and click "Create a new one!" Confirm creating group by clicking Add "Buildings" group created. Click Add The dashboard is created — you can now add widgets. Save the dashboard by clicking the Save button in the upper-right corner of the screen.

Add a Map widget to display Building A and Building B.
Each building must have latitude and longitude attributes to place markers correctly. Additional info—address, contact details, and image—will be shown in a popup when a marker is clicked.

Start with the preparatory work below.

Building images need to be uploaded to the Image gallery, which serves as a centralized repository for storing and managing images. They will be used in the tooltip of the map widget. You can use the Building A and Building B images from this guide or upload your own images.

Download the sample images:

• Building A photo
• Building B photo

1. Go to Resources ⇾ Image gallery.
2. Click Upload image and upload the photo for Building A, then for Building B.
3. Click the Embed image icon next to each uploaded image, copy and save the generated links. You will need these links in the next step.

Go to Resources ⇾ Image gallery and click "Upload image" Select or drag & drop an image, optionally rename it, then click Upload Verify both building images are uploaded Click the Embed image icon for the required image Copy the generated image URL — use it as the buildingImage attribute value

Add the appropriate image URL for Building A and Building B as the buildingImage server attribute.

1. Go to the Assets, open the Building A details and navigate to the Attributes tab.
2. Click + and add an attribute with the image URL corresponding to this building.
3. Repeat the same for Building B, using its corresponding image URL.

Open "Building A" ⇾ "Attributes" tab ⇾ click the "+" button Enter key "buildingImage", set type to String, and provide the image URL (e.g., "/api/images/public/..."), then click Add Verify that the "buildingImage" attribute has been added to Building A Repeat the same steps for "Building B" and verify the attribute

With images uploaded and attributes set, add the OpenStreet Map widget to the dashboard.

1. Navigate to Dashboards ⇾ Buildings.
2. Click + Add widget.
3. Open the Buildings dashboard, enter edit mode, and click Add widget.
4. Select Maps ⇾ Map.
5. Open the widget configuration and switch to the Advanced tab.
6. Select Positron layer for OpenStreet map type.
7. Scroll to the Overlays section and click Add marker on the Markers tab.
8. Set Source to Entity, enter building as entity alias name, and click Create a new one!.
9. Create alias:
   • Set filter type to Asset type
   • Specify asset type to building
   • Click Add

Navigate to Dashboards. Click to open the Buildings dashboard from the dashboards list. Open the dashboard in edit mode and click Add new widget. In the Widgets bundles dialog, select the Maps bundle. Select the Map widget. Open the widget configuration and switch to the Advanced tab. Select Positron layer for OpenStreet map type. Scroll to the Overlays section and open the Markers tab. Click Add marker, set Source to Entity, enter building, and click Create a new one. Create alias building, set Filter type to Asset type, select building, and click Add.

10. Open marker configuration and verify that the marker uses the building alias and latitude/longitude keys are set.
11. Configure data keys, including latitude, longitude, and add additional data keys: address, email, phone, and buildingImage.
12. In the Appearance section, use an image as the marker:
    • Download the image from the provided link
    • Upload it to Image gallery and use
    • Set the marker size to 60 pixels
    • Click Apply

Open marker configuration. Verify that the marker uses the building alias and latitude/longitude keys are set. Add an additional data keys: address, email, phone, and buildingImage. In the Appearance section, select Image as the marker type. Open the marker image settings. Click Browse from gallery to select or upload an image. In the image gallery, click Upload image. Upload the building-icon.svg file. Select the uploaded image, set the size (for example, 60 px), and click Apply.

13. Verify that the custom marker image is applied.

14. Configure the marker label to display the entity name.

    <div style="position: relative; white-space: nowrap; text-align: center; font-size: 12px; top: -5px;">
      <span style="border-radius: 10px; background-color: #fff; padding: 4px 12px;">${entityName}</span>
    </div>

    

15. Configure the tooltip function to display additional building details.

    

    const address = data.address ? data.address : 'N/A';
    const email = data.email ? data.email : 'N/A';
    const phone = data.phone ? data.phone : 'N/A';
    const buildingImage = data.buildingImage ? data.buildingImage : 'Building image not found';
    return '<div style="display:flex;flex-direction:column;font-family:\'Roboto\';font-weight:500;font-size:14px;line-height:24px;letter-spacing:0.25px;color:#29313C;margin-bottom:5px">' +
                `<img style="width: 300px; height: auto" src=${buildingImage}>` +
                '<div style="margin-top:5px;">${entityName}</div>' +
                '<div style="display:flex;flex-direction:row;align-items:center;justify-content:space-between;gap:10px">' +
                    '<div style="font-size:11px;line-height:16px;font-weight:500;color:rgba(0, 0, 0, 0.38);">Address</div>' +
                    '<div style="font-size:12px;line-height:20px;font-weight:500;color:#29313C;letter-spacing:0.25px;text-align:right;">'+ address +'</div>' +
                '</div>' +
                '<div style="display:flex;flex-direction:row;align-items:center;justify-content:space-between;gap:10px">' +
                    '<div style="font-size:11px;line-height:16px;font-weight:500;color:rgba(0, 0, 0, 0.38);">Email</div>' +
                    '<div style="font-size:12px;line-height:20px;font-weight:500;color:#29313C;letter-spacing:0.25px;text-align:right;">'+ email +'</div>' +
                '</div>' +
                '<div style="display:flex;flex-direction:row;align-items:baseline;justify-content:space-between;gap:10px">' +
                    '<div style="font-size:11px;line-height:16px;font-weight:500;color:rgba(0, 0, 0, 0.38);">Phone</div>' +
                    '<div style="font-size:12px;line-height:20px;font-weight:500;color:#29313C;letter-spacing:0.25px;text-align:right;">'+ phone +'</div>' +
                '</div>' +
           '</div>';

16. Scroll down and set card padding to 0.

17. Navigate to the Widget card tab and turn off displaying the widget title.

18. Adjust advanced widget styles and apply CSS provided below:

    .leaflet-popup-content { width: auto !important; margin: 8px; }
    a.leaflet-popup-close-button {
      font-size: 20px; color: black;
      backdrop-filter: blur(5px);
      background: rgba(255, 255, 255, 0.35);
      border-radius: 2px; top: 17px; right: 17px;
    }

    Set card padding to 0px. In the Card title section, disable the Display widget title option. Delete the values for padding. Expand the Advanced widget style section to access Widget CSS. Adjust advanced widget styles and click Add to apply the configuration.

19. Click Add to finish.

Position the widget in the top-right corner of the dashboard and resize it by dragging its edges. Once the layout is adjusted, click Save in the top-right corner to apply the changes.

Now click on any building image to display a tooltip with information about it.

The map shows building locations, but a list view makes it easy to scan building details at a glance. Add an Entities table widget to display both buildings alongside their addresses.

1. In dashboard edit mode, click Add widget.
2. Select Tables ⇾ Entities table.
3. Set datasource to the building alias.
4. Add address as a column key.
5. Set the card title to Buildings list.
6. Uncheck all Show card buttons options.
7. Click Add, resize the widget, then save the dashboard.

In dashboard edit mode, click + Add widget to add a new widget. In the Tables widget bundle, select the Entities table widget. Set the datasource to the building entity alias and configure the table columns, for example displayName and address. In the Card appearance section, set the card title to Buildings list and configure the visible card buttons. Click Add. Place and resize the Buildings list widget on the dashboard next to the map widget. Then, save the dashboard. After saving the dashboard, the Buildings list table and map widget are displayed on the dashboard.

Apply a background image and global CSS styles to give the dashboard a polished, professional look.

1. Click Settings on the dashboard toolbar.

2. In Advanced settings ⇾ Dashboard CSS, paste:

   .tb-widget-container > .tb-widget {
     border-radius: 8px;
     box-shadow: 0px 4px 10px rgba(23, 33, 90, 0.5);
   }
   .tb-dashboard-page .tb-widget-container > .tb-widget .leaflet-popup a.tb-custom-action {
     font-family: 'Roboto';
     font-weight: 500;
     font-size: 14px;
     line-height: 20px;
     letter-spacing: 0.25px;
     border-bottom: none;
     color: #00695C;
   }

   Click the "Settings" button on the dashboard toolbar Open "Advanced settings" and paste the CSS into the "Dashboard CSS" field

   This CSS snippet applies styles to elements with the .tb-widget class that are direct children of the .tb-widget-container. It specifies border-radius: 8px, which gives the element soft rounded corners, and box-shadow: 0px 4px 10px rgba(23, 33, 90, 0.5), which creates a semi-transparent shadow with a subtle blur, offset by 4 pixels downward, adding visual depth, and specifies opacity: 0.9 to make the element slightly transparent, allowing for some background visibility while maintaining the content’s visibility.

3. Download the sample background or use your own.

4. Scroll to Background image and click Browse from gallery.

5. Upload the background image if not already present, select it, and click Apply.

6. Save the layout settings, then save the dashboard.

Enter edit mode and click "Manage layouts" Click the "Layout settings" (gear) icon Scroll to the "Background image" section Click "Browse from gallery" Click "Save" to apply layout settings

As a result your dashboard should look like this: