# Map

Cx Assistant help · platform: web · module: maps · updated 2026-09-19
Canonical: https://cx-assistant.com/en/help/web/maps

## What is the Map and how to open it

The Map shows your project on a live map: every site and building that has an address or coordinates, and every asset that has its own position or route. Pins take the colour of the asset status, so you can read the state of the whole project at a glance. Hover a pin for a summary, click it for the details.

To open it, click Map in the sidebar (it carries a Beta chip). You can also press Ctrl+K (⌘K on a Mac) and type "map".

The Map entry only appears when two things are true: the Map module is switched on for the project, and your role has the `maps.read` permission. See the permissions section if you cannot find it.

The map fills the whole page. The toolbar floats at the top left, the details panel opens on the right, the basemap switch and the Legend sit at the bottom left, and the zoom buttons sit at the bottom right.

## What the pins, lines and colours mean

- A rounded square pin is a site or a building. Its colour is the most common status among the assets inside it. Its name is always shown under the pin.
- A round pin is an asset with its own position (a turbine, a pole, a tower). Its colour is the asset's status, and the icon inside comes from the asset type. Asset IDs appear under the pins once you zoom in close.
- A coloured line is an asset with a route (an overhead line, a cable route, a pipeline). It has a round pin at its midpoint so you can always click it.
- A red ring with a number means open issues. For an asset, the number counts open issues linked to it and to its sub-assets. For a site or building, it counts open issues linked to the assets inside it.
- A donut with a number is a group of nearby pins. The donut's colours show the mix of pins inside. Click it to zoom in.
- A grey-blue pin has no status information.

Equipment inside a building does not need its own pin. It is counted in the building's pin instead.

Open the Legend at the bottom left for a reminder: Site / building, Asset, Line / route, the colours in use, and Open issues. The Legend is hidden on small screens.

## How to move around: basemap, zoom, Fit all and pin grouping

- Drag the map to pan. Use the mouse wheel or the + and − buttons at the bottom right to zoom.
- Fit all (the frame icon at the bottom right) zooms out to show every pin that matches your filters.
- The group icon above it turns pin grouping on or off. When grouping is on, nearby pins merge into a donut until you zoom in. When it is off, every pin is drawn on its own.
- At the bottom left, switch the basemap between Streets and Satellite. The switch only appears when the server offers both.

Your basemap, your grouping choice and whether the Legend is open are remembered in this browser.

When you open the map, it frames all your pins. If you arrive from a Show on map link, it flies straight to that pin instead.

## How to search and filter the map

Everything is in the toolbar at the top left.

- Search: type in the box labelled "Search sites, buildings & assets…" and pick a result. The map flies to that pin and opens its details. Search looks only at pins that match the current filters.
- Status: show only one asset status. A site or building stays visible when at least one asset inside it has that status. An asset also stays visible when one of its sub-assets has it.
- Type: the same, by asset type.
- Sites & buildings and Assets: two chips that show or hide each kind of pin. At least one always stays on.
- With open issues: show only the pins that have open issues.

Your filters, the Colour by choice and the selected pin are kept in the page address. Copy the link from the browser to share exactly the view you are looking at.

## How to change what the colours mean (Colour by)

Use the Colour by menu in the toolbar:

- Status (the default): pins and lines use your project's asset status colours. A site or building takes the most common status of its assets.
- Asset type: each asset type gets its own colour. Everyone in the project sees the same colour for the same type. A site or building takes the most common type inside it.
- Open issues: red for pins with open issues, green for pins with none.

The Legend follows your choice. The red ring with the issue count is shown in every mode.

## The details panel: what a pin tells you

Hover a pin to see a small summary card. Click the pin to open the details panel on the right. Press Esc or the ✕ to close it.

For a site or building the panel shows:
- Its name, code and place in the locations tree, and its Address.
- Assets by status: how many assets are inside, split by status.
- Asset types: a chip per type with its count.
- Floor plans: layouts anchored to this building. Click one to open it (you need access to Layouts).
- Buttons: Add building (sites only), Add asset, Create issue and View assets, which opens the Assets page.

For an asset the panel shows:
- Its ID, type and Status. Click the ID, press Open asset, or double-click the pin to open the full asset dialog.
- Part of (the parent asset, clickable) and Location.
- Category, model, vendor and description when they are filled in.
- Sub-assets: how many, split by status and type.
- For a line: Length and Chainage.

Both kinds end with a folded Coordinates section (Route for a line). Open it to see the numbers and copy them with Copy coordinates or Copy route.

## How to see issues and create an issue from the map

When a pin has open issues, the details panel shows a red banner with the count. If your role has `issues.read`, an Open issues list follows with the most recently updated issues for that pin (up to 8). Click a row to open the issue without leaving the map.

When there are more issues than the list shows, click View all issues. The Issues page opens already filtered to that asset or that site or building.

To create an issue from the map:
1. Click the pin.
2. Click Create issue in the panel (needs `issues.create`).
3. Fill in the issue as usual. From an asset pin, the asset is already linked and its location is filled in. From a site or building pin, the location is filled in.
4. Save. The pin's issue count updates.

## How to add a site or a building from the map

You need to be the project owner, or have `projects.locations.edit` or `projects.settings.manage`.

1. Click Add in the toolbar and choose Site or Building.
2. Click on the map where it is. A pin drops there. Press Esc to cancel.
3. Drag the pin to adjust the position, or search an address in the panel on the right. Picking an address moves the pin.
4. Type a Name. Code is optional. For a building, you can choose the site it belongs to under Inside site.
5. The address is looked up from the spot you clicked. If none is found, you can type one.
6. Click Create.

The new site or building appears on the map and in the project's Locations right away.

To add a building inside an existing site, click the site's pin and then Add building. The site is already selected for you.

## How to put an asset on the map

1. Click Add in the toolbar and choose Asset.
2. In the panel, under Which asset?, search for an asset that already exists. You can search by asset ID, type or location. Assets that still have no position come first. This list needs `assets.update`.
3. Click on the map where the asset is. Drag the pin to adjust it.
4. Click Place <asset> here. The asset gets that position and becomes a pin.

If the asset is already on the map (it shows an On the map chip), placing it moves it to the new spot.

If the asset does not exist yet, skip the search, drop the pin and click Add asset details. The usual Create Asset dialog opens with the position already filled in. You complete its ID, type and category there. This needs `assets.create`.

You can also set a position from the asset itself: open the asset, find the Map position card and click Set position or route. From there, Show on map jumps to the pin.

## How to add assets to a site or building from its pin

1. Click the site or building pin.
2. Click Add asset in the panel.
3. Search for an existing asset and click Add here. The asset moves into that location. Assets that are already there are marked Already here. This needs `assets.update`.
4. If the asset does not exist yet, click New asset instead. The Create Asset dialog opens with the location filled in. This needs `assets.create`.

An asset added this way does not get a pin of its own. It is counted in the site or building pin. An asset that already had its own pin keeps it where it is.

## How to move a pin

1. Switch on Move pins in the toolbar. The switch is only shown when your role has `assets.update`.
2. Drag an asset pin to its new spot and let go.
3. The new position is saved at once, and a message confirms it. If the save fails, the pin jumps back to where it was.
4. Switch Move pins off when you are done, so you do not move a pin by accident.

Only asset pins can be dragged. Lines are not dragged: open the asset and edit its route in the Map position card. Sites and buildings are moved by editing their address or coordinates in the project's Locations.

## Lines and routes: assets that span a distance

An asset can have a route instead of a single point: an overhead line, a cable route, a pipeline. The map draws it as a line in the asset's colour, with a round pin at its midpoint.

- Click the line or its pin to select it. The map frames the whole route.
- The panel shows its Length. Under Route you see how many points it has, its Start and End, and Copy route.
- An asset that has both a position and a route is drawn as the line only.
- A route can have up to 2,000 points.

To draw or edit a route, open the asset, go to the Map position card, click Set position or route and use the Line route fields. You can also bring routes in from a KML or KMZ file.

## How to import a KML or KMZ file

Use this to bring an alignment or a site survey from Google Earth or a CAD export onto the map. You need `assets.create`.

1. Click Add in the toolbar, then Import KML.
2. In the Import KML / KMZ panel, click Choose KML / KMZ file and pick a .kml or .kmz file.
3. The file is read and drawn on the map as a dashed purple preview. Nothing is saved yet.
4. Set the Defaults: Type for lines, Type for points, Type for folders and Category. They are used wherever the file does not name a type or category. For folders you can keep "Group only — do not create folder assets".
5. Check the summary: the number of rows, lines, points and folders, any Notes, and the Rows with problems (skipped) list, which says why each row cannot be imported.
6. Click Import N assets. A message tells you how many assets were created and how many were skipped.

Click Cancel or the ✕ at any time to leave without importing.

## KML import: what gets created, limits and skipped rows

What becomes what:
- Each placemark becomes one asset. Its name becomes the asset ID. A placemark with no name is imported as "Placemark 1", "Placemark 2" and so on.
- A point becomes an asset with a pin. A line becomes an asset with a route.
- A polygon is imported as its outline, as a line. A placemark made of several line parts is joined into one line. The Notes tell you when this happened.
- Folders only group the file, unless you choose a Type for folders. Then each folder becomes a parent asset, and the placemarks inside it become its sub-assets.
- If the file carries extra data fields named type, category, model, vendor, description or parent, they are used. A type or category must match one that exists in your project.
- When the same name appears twice in the file, the copies are imported as "Name (2)", "Name (3)".

Limits:
- The file can be up to 25 MB.
- A line can have up to 2,000 points.
- The file must contain at least one placemark.

A row is skipped when it has no geometry, when no type is set for it, when its type or category is not in your project, when its coordinates are out of range, or when an asset with the same ID already exists. If a parent named in the file cannot be found, the asset is still created, just without a parent, and a message tells you.

## Chainage and kilometre points (KP)

Chainage tells you how far along a line something is. It is written as KP, in kilometres + metres: KP 12+340 is 12 km and 340 m from the start.

To choose the project's reference line:
1. Click the line that everything should be measured along, for example the main pipeline.
2. Click Use as chainage reference in the panel. This button is for the project owner or people with `projects.settings.manage`.
3. To undo it, select the line again and click Stop using as reference.

Once a reference line is set:
- An asset pin shows its Chainage in the panel, for example KP 4+250 on that line. If it sits a little to the side, the panel also says how many metres off the line it is.
- Another line shows the stretch it covers, for example KP 2+000 – 3+500.
- Anything more than 250 m away from the reference line gets no KP on it.

Without a reference line, a line still shows its chainage counted from its own start.

Select a line and zoom in to see kilometre posts drawn along it: one every kilometre, and one every 100 m when you zoom in further.

## Who can see and edit the map (permissions) and how to switch the Map module on

Switching the module on: the Map is an optional module and it is off until someone turns it on for the project. The project owner, or someone with `projects.settings.manage`, opens the project from the Projects page, finds the Modules card on the project details page and turns on the Map switch. Turning it off later hides the Map but keeps all positions and routes.

Permissions:
- `maps.read`: see the Map in the sidebar and open it. The standard project roles include it.
- `assets.update`: Move pins, place an existing asset on the map, and add an existing asset to a site or building.
- `assets.create`: create a new asset from the map, and Import KML.
- Project owner, `projects.locations.edit` or `projects.settings.manage`: add a Site or a Building.
- Project owner or `projects.settings.manage`: choose the chainage reference line.
- `issues.read`: see the issues list in the panel. `issues.create`: Create issue.
- `layouts.read`: see Floor plans in a building's panel.

Buttons you have no permission for are simply not shown.

## Map troubleshooting

- I cannot see Map in the sidebar: the Map module is off for this project, or your role lacks `maps.read`. Ask a project admin to turn on Map in the Modules card of the project details page, or to give your role the permission. The Map is also not available in your personal workspace, only inside a project.
- A link to the map opens a "forbidden" page: same cause. The module is off or you lack the permission.
- "Nothing on the map yet": no site, building or asset has a position. Give your sites and buildings an address in Locations, give assets their own position, or click Add on the map.
- An asset is missing: it may have no position of its own. Equipment inside a building is counted in the building's pin. Also check the Status and Type filters, the Assets chip and With open issues.
- There is no Add button, no Move pins switch or no Import KML: your role lacks the permission. See the permissions section.
- "The basemap could not be loaded": the background map did not load. Check your connection. Pins still work.
- "The map service is not configured on this server": contact your administrator.
- KML import says "Could not read the file": the file is not a valid KML or KMZ, or it has no placemarks.
- KML import says "Nothing to import — every row has a problem": set the default types in the panel and read the Rows with problems list.
- A pin has no KP: no reference line is set, or the pin is more than 250 m away from it.
- A pin jumped back after I dragged it: the save failed. Try again.