Prepare data in QGIS

Groundwork reads a standard QGIS project file (.qgs). 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.

Set each layer’s data source

Set the source of your vector layer to a GeoJSON, GeoParquet or FlatGeobuf file next to the project file, or in a subfolder with a relative path.

If your data is in a different format, such as Shapefile or GeoPackage, first export it to GeoJSON in QGIS:

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

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

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.

Make a layer read-only

For a layer that your team must see but not edit, tick Read-only in Layer Properties → Source. 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.

Attach records to a feature

To attach records to a feature, such as the inspections of each tree or the maintenance done on it, use a relation in your QGIS project. A relation joins two of its layers. The referenced layer holds the features. The referencing layer holds the records that belong to them. Groundwork reads the relation, and uses the second layer as records, not as a separate layer.

Your team sees these records on a tab in the details of each parent feature, with the name of the relation. Groundwork never draws them on the map, and the child layer is not in the layer picker or the legend. The records do not need a geometry, so a table of records is enough. Save it as a GeoJSON file beside the project, as you do with the data of other layers.

The field pairs of the relation connect a record to its feature, and every pair must match. Groundwork compares the values as text, without the spaces at the start or end. So 2001 on one side and "2001" on the other still match. A feature with an empty matching field has no records.

Give every record in the child layer its own id in the GeoJSON file, and make sure that no two are the same. Then your team can change records in Groundwork, and also add them. This is the id of each feature in the GeoJSON file, not one of its fields. A field called id does not let Groundwork tell the records apart.

If a record has no id, or two records have the same id, your team can still add records, but cannot change existing ones. If the layer accepts new records, an open record shows a message about this.

To show a symbol beside each record in the panel, style the child layer in QGIS as you style other layers. For example, a style categorised on a condition field gives each condition its own symbol. If Groundwork cannot read a style for the layer, its records show no symbol.

Put both layers in the project. Groundwork ignores a relation that refers to a layer that is not in the project. A layer can be the child of more than one relation. A child layer can also be the parent of another relation.

Set the view and the layer order

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.

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.

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

What your styling looks like in the browser

When the map loads, Groundwork converts your QGIS styling automatically. You do not need separate style files. Groundwork fully reproduces a single-symbol, categorised or graduated style made from simple markers, lines and fills. It also reproduces labels from a single field.

A categorised style also gives the layer its legend and the values that users can filter by. For example, trees coloured by a species field get a species legend and a species filter.

Set every size, width and dash length in millimetres. Groundwork reads a value in points, inches or map units as a number of screen pixels, and the result is wrong.

If Groundwork cannot read the style of a layer, it uses a colour from a fixed palette for that layer. The layer still loads, shows in the list and accepts edits as usual. Do not use these items:

• Complex marker types. If a layer has a font, filled, raster-image or ellipse marker, Groundwork draws the full layer in a palette colour. Groundwork draws an SVG marker from your own file as a plain marker in the same colour. It reproduces icons from the built-in QGIS library.
• Line decorations. Groundwork draws marker, arrow, hashed and the other decorated line types as a plain line. For a dash pattern that is correct at any width, tick Use custom dash pattern and set a pattern in millimetres. Groundwork draws the preset Dash and Dot styles as a small, fixed pattern on the screen.
• Hatched fills. On a simple fill, Groundwork draws any Fill style other than Solid or No brush as solid black. If the Stroke style is No pen, it draws nothing. Use a solid fill, or No brush for polygons with only an outline. Groundwork always draws fills at half opacity, so you can see the basemap below them.
• Symbology types that draw nothing. With No symbols, Heatmap, Point displacement, Point cluster, Merged features, Inverted polygons or 2.5D, the layer is blank on the map. Its features still show in the list, and users can still edit them.
• Rule-based expressions. Groundwork reads a rule’s condition if it compares a field with a value: =, !=, <, <=, >, >=, IS NULL, IS NOT NULL, and AND/OR/NOT combinations. If a rule uses an expression function or a variable, Groundwork ignores its condition and draws that rule’s symbol on every feature. Write not-equal as !=, not <>.
• Complex labels. Groundwork reproduces a label’s field, font, colour, text buffer, a simple offset and Prevent overlap. It does not reproduce expressions, rule-based labels, callouts or other placement settings. Anywhere in the style, it also ignores data-defined overrides, symbol opacity, symbol levels and blend modes. On points and lines, set the opacity in the symbol’s colour instead.

Before you share the map, open it in Groundwork. The map loads but looks different from QGIS tells you the cause of each problem. Fix the problem in QGIS: change the style, and save the project over the published one. The next person who opens the map gets the new version.

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 or FlatGeobuf file in the project folder.
• Make sure that the project is saved as .qgs. For a cloud folder, make sure that the canvas shows the view that the map must open on before you save.
• Make sure that each layer that your team must not change has Read-only ticked.

Next: Publish to a cloud folder.