Prepare data in QGIS

Groundwork reads a standard QGIS project file (.qgs or .qgz). It shows your layer, its symbology and its labels in the browser. This page is for a map connected to a cloud folder or to QGIS Server. If your data is on a WFS server or in a STAC catalogue, you do not need this page.

Where you set each part in QGIS

Part	Where you set it in QGIS	What it decides in Groundwork
Data source	Layer Properties → Source	The file that each layer reads
Read-only layers	Layer Properties → Data Sources and QGIS Server and QField	Whether your team can edit each layer, and which edits
Measurements	Project Properties → General	The units of `$area`, `$length` and `$perimeter`
Map colour	Project Properties → Colors	The colour of the map’s buttons and other controls
Map logo	Project Properties → Variables	The logo at the start of the panel header
Feature title	Layer Properties → Display	The title of each feature
Styling	Layer Properties → Symbology and Labels and Legend	How the layer draws, its legend and the values that users can filter by
Edit form	Layer Properties → Attributes Form and Variables	What each field shows and accepts while your team edits
Related records	Project Properties → Relations	The records linked to each feature, such as the inspections of a tree
Expressions	Expression Builder	Which calculations Groundwork reads in labels, style rules and the edit form
Private tables	Project Properties → Data Sources	Which tables stay off the map and out of the layer list
Opening view and layer order	Project Properties → The layers panel and the map canvas and QField	The layer that opens active, the hidden layers and the view that the map opens on
Filters	Project Properties → Mergin Maps	The filters ready in each layer’s filter row

Set each layer’s data source

In the QGIS User Guide: Source Properties, Creating new layers from an existing layer for Save Features As, and Introducing QGIS projects.

Save the project as .qgs, the XML format. Groundwork also opens the zipped .qgz format. Groundwork does not support database sources such as PostGIS. A GeoParquet, FlatGeobuf or GeoPackage layer is read-only, and so is a CSV that is not a child layer. Groundwork draws a .tif or .tiff file as an image, with no features to list or edit.

GeoJSON

Set the source of your vector layer to a GeoJSON, GeoParquet, FlatGeobuf or GeoPackage file. Put the file next to the project file, or in a subfolder with a relative path. Groundwork downloads a GeoPackage whole, so the whole file must be 25 MB or less.

If your team must edit the layer, or your data is in another format such as Shapefile, first export it to GeoJSON in QGIS:

Right-click the layer.
Choose Export → Save Features As….
Choose the format GeoJSON.
Save the file beside the project file.

CSV

A table with no geometry can also be a CSV file. Examples are the list of choices that a field reads, or the inspections linked to each tree. Add the file to QGIS by dragging it into the project, or from the Delimited Text tab of the Data Source Manager. A list of choices needs only two columns: the code that the field stores and the name to show. Groundwork reads every value as text, and reads a CSV only through the project that uses it. Your team can add and change records in a CSV child layer that you dragged in, as Link records to a feature describes.

WFS

You can also put WFS layers in a project. Groundwork loads these layers live from the server.

When a WFS layer loads whole

Groundwork ignores the QGIS setting Only request features overlapping the view extent on a WFS layer. Whether or not the box is ticked, Groundwork loads a layer of 2,000 features or fewer whole. It loads a larger layer only in the current map view.

Set the display field

Set the layer’s display field (Layer Properties → Display) to the attribute that best names a feature. Groundwork uses it as the feature title in lists, tooltips and headings. So users see “Lemon-scented Gum” instead of an ID number. If there is no display field, Groundwork chooses a suitable field itself.

In the QGIS User Guide: Display Properties.

Make a layer read-only

For a layer that your team must see but not edit, tick its Read-only box in Project Properties → Data Sources, under Layer Capabilities. Examples are a cadastre, a catchment boundary, or last year’s survey. When that layer is active, Groundwork does not show the Add, Edit and Delete tools, and a padlock marks the layer in the layer picker.

You set this for each layer. So one project can have an editable capture layer and any number of read-only context layers.

On a map connected to QGIS Server, Groundwork cannot read this tick, because QGIS Server does not publish it. There, your team can edit every layer, and Groundwork saves an edit only if the server accepts WFS-T.

To lock one field and leave the rest of the layer editable, use the Attributes Form instead: Lock a field.

In the QGIS User Guide: Data Sources Properties.

Lock some edits

You can lock some edits of a layer and leave the others open. For example, your team can add inspections but not delete them, or update the details of a tree but not move it. Set the locks in either of two places. If either place locks an edit, Groundwork locks it.

QGIS Server. In Project Properties → QGIS Server → WFS capabilities, tick Published for the layer. Then tick Insert, Update and Delete for the edits that your team can make. Update covers both the details and the shape of a feature. Groundwork reads these ticks from the project file, so you do not need to run QGIS Server.
QField. Install the QFieldSync plugin. In Layer Properties → QField, under Permissions, tick Disable feature addition, Disable attribute editing, Disable geometry editing or Disable feature deletion. To lock only some features, use the button beside the box and enter an expression, such as "status" = 'surveyed'.

When adding is locked, Groundwork does not show the add button. When deleting is locked, Groundwork does not show Delete. When the details are locked, the form shows them as plain text. When the shape is locked, Groundwork does not show the handles that move it. A padlock marks the layer in the layer picker.

How Groundwork reads an expression

Groundwork works out the expression for each feature from its saved values. If Groundwork cannot read an expression, it locks the edit. A new feature has no values yet, so an expression on adding locks every new feature. On a map connected to QGIS Server, Groundwork cannot read either setting.

Set the view and the layer order

View

Groundwork opens the map on the view that you last saved with the project. So before you save, move the QGIS canvas to where your team must start. A map connected to QGIS Server opens on the area of its layers instead. For both kinds of map, you can also set an opening view in Groundwork and send it in your share link.

Layer order

Put the layer that your team works in at the top of your project. When the map opens, Groundwork makes the first layer active. Its features fill the Data panel, and users edit it.

To make another layer open active, install the QFieldSync plugin in QGIS. In Project Properties → QField, choose the layer in Initial active layer, and save the project. Groundwork makes that layer active the first time a user opens the map, even if the layer is unticked. After that, the map opens on the layer that the user last worked in. On a map connected to QGIS Server, Groundwork cannot read this setting.

In the QGIS layers panel, untick any context layers that you include. Groundwork loads an unticked layer as a hidden layer, and users can show it.

In the QGIS User Guide: Layers Panel.

Private

To keep a table off the map, tick Private for it in Project Properties → Data Sources, under Layer Capabilities. QGIS describes the box as “Layers which are not shown in the legend”. Groundwork leaves a Private layer out of the layer list and does not draw it. Use this for a table that your team never needs to see on the map, such as one that feeds a field’s list. Use it also for the records of a relation that your team opens only from a tab.

When a Private layer still shows

A Private layer that holds the records of a relation still shows them in a tab on the feature that they belong to. On a map connected to QGIS Server, Groundwork cannot read this tick, so the layer stays in the layer list.

Set up filters

You can give your team the filters that they use most, ready in the row above the feature list. For example, a Condition filter on the trees layer. Set them up with the Mergin Maps plugin, so that the same filters show in the Mergin Maps app.

Install the Mergin Maps plugin in QGIS, from Plugins → Manage and Install Plugins.
Open Project → Properties, and choose the Mergin Maps tab.
Under Filtering, tick Enable filtering.
Press Add filter. Choose its Type, Layer and Field, and type a Title, such as Condition.
Save the project.

When the map opens, each filter is a button in its layer’s filter row, in the order of the plugin’s list. The button and the list of fields show the title in place of the field’s name. A filter narrows nothing until a user ticks values, or chooses a period or a range. The list of fields still holds every field. A user who removes a filter gets it back the next time they open Groundwork.

Groundwork chooses each filter’s control from the field itself. A date or a number field gets a period or a range, and any other field a list of values to tick. So the Type you choose does not change the control. Groundwork leaves out a Text filter, because the filter row has no filter for part of a word. Use the search button for that. On a map connected to QGIS Server, Groundwork cannot read these filters.

In the Mergin Maps documentation: Filtering.

Set the map’s colour

Groundwork can show your map’s buttons in your organisation’s colour. It reads the colour from the project’s own list of colours:

Open Project → Properties, and choose the Colors tab.
Press Add under the list of project colours.
Double-click the new colour, and choose your colour.
Double-click its Label, and type Brand.
Save the project.

Groundwork uses the colour in the Light and Dark themes, for buttons, ticked boxes and the other controls that it colours. The Groundwork logo keeps its own colour. Everyone who opens your map sees your colour, because it is saved in the project.

How Groundwork adjusts the colour

Button text must read clearly: white text in the Light theme, and dark text in the Dark theme. Where your colour is too light or too dark for that, Groundwork darkens or lightens it only as far as it needs to. The map’s settings show your colour and say when Groundwork changed it.

To see your colour unchanged in the Light theme, choose a dark shade from your brand. A yellow or orange colour turns brown when Groundwork darkens it. A red colour can make every button look like a Delete button. On a map connected to QGIS Server, Groundwork does not read this colour.

In the QGIS User Guide: Colors Properties.

Show your organisation’s logo

Groundwork can show your organisation’s logo at the start of the panel header, in place of the Groundwork mark. Put the logo file in the same folder as the project, then name it in a project variable:

Open Project → Properties, and choose the Variables tab.
Press the Add variable button. QGIS adds a row to the project’s variables.
Name the variable quac_logo.
Enter the file’s name as the value, such as logo.svg.
Save the project.

Use an SVG, PNG, JPEG or WebP file of 100 KB or less. Groundwork shows the logo 28 pixels high and keeps its proportions, so a wide logo reaches further to the right, up to 160 pixels. A square emblem stays clearest at that size.

A logo made for a white background can disappear on the Dark theme. To show a different file in the Dark theme, add a second variable, quac_logo_dark, that names it. Without one, Groundwork shows your logo on a small white tile in the Dark theme.

Everyone who opens your map sees the logo, because it comes from the map’s folder. When Groundwork cannot show the logo, it shows its own mark, and the map’s settings say why. Groundwork reads the logo only for a map connected to a cloud folder. It does not read it on a map connected to QGIS Server, or from a project that you drop into Groundwork.

In the QGIS User Guide: Variables Properties.

Show an icon beside a layer

To show an icon beside a layer’s name, such as a tree beside Street trees, give the layer a variable. The icon comes from Tabler Icons, the set of icons that Groundwork uses.

Find the icon on tabler.io/icons and copy its name, such as tree.
Open Layer Properties → Variables.
Click the Add variable button. QGIS adds a row to the layer’s variables.
Name the variable quac_icon.
Enter tabler: and the icon’s name as the value, such as tabler:tree.

Where the icon shows

Groundwork shows the icon in the colour of the layer’s name. It appears before the name in the layer picker, above the feature list and in the About window. It also appears beside the name at the top of a feature’s details. For a table of related records, it appears on the table’s tab and in the filter. Groundwork loads each icon from jsDelivr, a public site that serves the Tabler files. If an icon does not load, Groundwork shows the name alone.

QGIS shows no icon in its own list of layers. Groundwork reads the variable only from the project file, so a map connected to QGIS Server does not have it.

In the QGIS User Guide: Variables properties.

Check the project before you publish

Open the project again in QGIS. Make sure that your layer draws, with no broken file paths.
Make sure that each layer from a file uses a GeoJSON, GeoParquet, FlatGeobuf, GeoPackage, .tif or .tiff file in the project folder. A table can also use a .csv file.
Make sure that the project is saved as .qgs or .qgz. For a cloud folder, make sure that the canvas shows the view that the map must open on before you save.
For a cloud folder, make sure that each layer that your team must not change has Read-only ticked.

Next: Style a layer in QGIS.