Reference layers overview
Reference layers give your data context: boundaries from a file, imagery from a tile server, a layer from ArcGIS or a WMS service, a vector tile style, place names or the line between day and night. They are drawn as they are published and do not come from your data model.
Reference layers and data layers
A map in Icon Map Slicer is a basemap, plus data layers, plus reference layers.
| Data layers | Reference layers | |
|---|---|---|
| Where the content comes from | The rows of your report, through the field wells | A file, a link or a service that you point the map at |
| What a row does | One row draws one thing | Rows are not needed. A reference layer draws with no fields at all |
| Click and select | Selects the row and filters the report page | Not selected by a click. Polygons of a file layer can select the data inside them, see below. Hovering can show a tooltip |
| Styling from data | Conditional formatting (fx) on most settings | Fixed styling, or styling by a property inside the file or service |
A reference layer is not joined to your data, but your data can still control it. Several settings take conditional formatting (fx), so a measure or a slicer can decide what is drawn:
- Visible on file, raster and WMS layers shows or hides the layer.
- Filter Value on a file layer keeps only the features whose property matches your data. See Files and feeds.
- Filter Value on the Vector Tiles layer does the same for a vector tile style. See Vector tiles over the basemap.
- CQL Filter (optional) on a WMS layer filters the service.
- The link itself can come from a measure on most layer types.
ArcGIS layers also have Visible, and SQL WHERE Clause filters an ArcGIS feature layer.
If you want shapes that are colored by your data and that filter the report page when clicked, use a data layer instead: Shapes from files, Vector tiles or Icon Map Catalog layers.
ArcGIS feature layers can also be bound to your data: see ArcGIS layers bound to data.
Select data with a boundary file
A file layer's polygons can act as selection areas. Switch on Use Polygons for Selection for the layer, and a click on one of its polygons selects every data item inside it, which filters the report page. See Files and feeds and Select everything inside a shape.
Types of reference layer
The Reference Layers card has a group for each type. Each group has its own switch in its heading.
| Type | Group in the Format pane | What it draws | How many |
|---|---|---|---|
| Files and feeds | GeoJSON / Shape / KML | Points, lines and polygons from a link or an uploaded file | 5 |
| Raster tiles | Raster Tiles | Imagery or a tiled map from a tile template or a Cloud Optimized GeoTIFF | 5 |
| WMS | OGC WMS | Map images from a Web Map Service | 5 |
| Vector tiles | Vector Tiles | The layers of a MapLibre style, merged over the basemap | 1 |
| Icon Map Catalog | Catalog card | Ready-made boundaries and places | 20, shared with catalog layers bound to data |
| Daylight | Daylight Terminator | Shading over the part of the world that is in darkness | 1 |
| Map labels | Map Labels | Place names drawn above your data | 1 |
File layers also read KMZ, CSV and WFS links, and raster layers also read WMTS services.
| Type | Group in the Format pane | What it draws | How many |
|---|---|---|---|
| ArcGIS | ArcGIS Layer - Setup | A feature layer, a map, image or vector tile service, or a whole web map | 5 |
File layers can also carry their own text labels. See Labels on reference layers.
Add a reference layer
The quickest way is the Layer Manager.
- In the Format pane, open the Layer Manager card and switch on Open Layer Manager.
- Select Add a layer, then Reference layer.
- Pick a tile: Files & feeds, Tiles & imagery, WMS, ArcGIS, Icon Map Catalog, Map labels or Day and night. Each tile shows how many of that type are in use.
- Follow the steps. For a link, select Check to have the link read and described before the layer is added.
- Select Add to map, then Apply changes.
The full walkthrough is in Add a layer.
The Vector Tiles layer is not in the picker. Add it in the Format pane.
Every reference layer can also be set up in the Format pane, and some settings are only there: conditional formatting (fx), filters, WMS authentication and Z-Index numbers. Open Format pane > Reference Layers and switch on the group of the type you want. Its settings, and for files a configuration group per layer, appear below.
A few settings are only in the Layer Manager: the WFS feature type, the refresh interval of a file link, and the proxy for file and raster layers. The Format pane has no switch for them.
More than one layer of a type
Files, WMS and raster layers each have five slots. The Format pane shows the settings of one slot at a time.
- Files: set Number of Layers (1 to 5), then choose the layer to edit in Apply settings to.
- WMS and raster layers: the first layer is set in the group itself. Set Number of Additional Layers (0 to 4), then choose the additional layer to edit in Apply settings to.
ArcGIS layers work like files: Number of Layers and Apply settings to are in ArcGIS Layer - Setup.
Drawing order
Every layer on the map, reference or data, has a Z-Index (Z-Index or Z Index in the Format pane). A layer with a higher Z-Index is drawn nearer the viewer. Reference layers and data layers share one scale, so a reference layer can sit under your data, between two data layers, or on top of everything.
| Layer | Default Z-Index |
|---|---|
| Daylight terminator | 450 |
| Map labels | 440 |
| Labels of a file layer | 370 |
| File layers | 365 |
| Vector tiles | 355 |
| Raster layer 1 | 354 |
| Additional raster and WMS layers | 344 |
| WMS layer 1 | 255 |
ArcGIS layers default to 345.
For comparison, circles default to 405, images to 410 and data labels to 950. The defaults put imagery and boundaries under your data and place names above it.
To change the order, edit the Z-Index of a layer in its group in the Format pane. Values run from 0 to 1000.
In the Layer Manager you do not need the numbers. The list shows every layer that is switched on, top first. Drag a row, or use Move up and Move down, and the Z-Index values are rewritten for you. See Edit, reorder and remove layers.
Zoom range and visibility
File, raster and WMS layers, and map labels, each have a minimum and maximum zoom. Outside that range the layer is not drawn. Use this to show detailed boundaries only when the reader has zoomed in.
File, raster and WMS layers have a Visible setting that takes conditional formatting (fx). Return "Yes" or "No" from a measure to show a layer only for a slicer choice or a bookmark.
ArcGIS layers have both too.
Legend
File layers appear in the legend and in the layer control, under their title, their file name or "Reference layer n". Switch the entries on and name them under Format pane > Legend > Legend labels, with Reference layer {n} in legend and Reference layer {n} title.
ArcGIS reference layers appear too, each with its own ArcGIS legend, named with ArcGIS layer {n} in legend and ArcGIS layer {n} title. See Legend.
WMS, raster and vector tile reference layers have no legend entry.
Tips and limits
- A click on a reference feature does not select it or filter the report page. The exception is a file layer with Use Polygons for Selection on, which selects the data inside the polygon you click.
- Links must start with
https://. - A layer that is read from a link is read by the browser of the person viewing the report. The server must allow requests from Power BI (CORS).
- Uploaded files are stored in the report, so they work wherever the report does.
Servers that block Power BI
Some servers do not allow a Power BI visual to read them.
The Icon Map proxy can fetch some layers on the map's behalf. It needs an Icon Map license key, and proxied requests may consume additional usage credits. It is not used when Airgapped Environment is on or your license rules it out, and the Layer Manager then hides its proxy check box and switch.
| Layer | How to use the proxy |
|---|---|
| Files and feeds | In the Layer Manager. When the link check reports that the server does not allow Power BI to read it, tick Read it through the Icon Map CORS proxy (only for servers you trust). Later, change Use proxy when required in the layer's editor |
| Raster tiles and WMTS | The same check box and switch, in the Layer Manager |
| ArcGIS | Use proxy when required on the ArcGIS Authentication card |
| WMS, vector tiles | No proxy. The server must allow Power BI |
Each server is tried directly first, and only a server that blocks Power BI is read through the proxy. For what the proxy sends, see ArcGIS sign-in and the proxy.