Preparing data in QGIS

Groundwork reads a standard QGIS project file (.qgs) and reproduces your layer, its symbology, and its labels in the browser. This page applies to a map connected to a cloud folder or to QGIS Server; if your data is on a WFS server or in a STAC catalogue instead, you can skip it.

Layer data sources

Point your vector layer at a GeoJSON or GeoParquet file stored next to the project file, or in a subfolder referenced by relative path. If your data is currently in another format (Shapefile, GeoPackage), export it to GeoJSON in QGIS first: right-click the layer → Export → Save Features As… → format GeoJSON, and save it beside the project file. A project can also contain WFS layers, which Groundwork loads live from the server.

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” where an ID number would otherwise sit. Without one, Groundwork guesses a sensible field.

Layers your team can’t edit

Tick Read-only in Layer Properties → Source for any layer your team should see but not edit: a cadastre, a catchment boundary, last year’s survey. With that layer active, the Add, Edit and Delete tools do not appear, and a padlock marks the layer in the layer picker. It is set per layer, so one project can hold an editable capture layer and any number of read-only context layers.

Records that hang off a feature

A relation declared in your QGIS project joins two of its layers: the referenced layer holds the features, and the referencing layer holds records belonging to them — the inspections on each tree, the maintenance done to it. Groundwork reads the relation and treats that second layer as records rather than as a layer of its own.

Those records never reach the map. The child layer is not drawn, is not in the layer picker or the legend, and cannot be shown or hidden. Its records appear as a tab on a parent feature’s details instead, labelled with the relation’s name. That holds whether or not the records have a shape, so a table of records with no geometry works — save it as a GeoJSON file beside the project, the same as any other layer’s data.

The relation’s field pairs are what matches a record to its feature, and every pair has to match. Values are compared as text with surrounding spaces trimmed, so 2001 on one side and "2001" on the other still line up. A feature whose matching field is empty holds no records.

Every record in the child layer needs its own id in the GeoJSON file, and no two the same. Its records can then be changed in Groundwork as well as added to. A field named id is a different thing: a layer can show one in its attributes and still be a layer whose records Groundwork cannot tell apart.

Where a record has no id, or two share one, records can still be added and existing ones cannot be changed. An opened record says so, where the layer takes new records at all.

Style the child layer in QGIS as you would any other, and each record carries its own symbol beside it in the panel: a style categorised on a condition field gives each condition its own symbol on the record. A layer with no style Groundwork can read shows no symbol on its records.

Both layers have to be in the project — a relation naming a layer the project does not hold is dropped. A layer can be the child of more than one relation, and a child layer can itself be the parent of another.

The view and the layer order

Groundwork opens the map on the view you last saved the project with, so position the QGIS canvas where your team should start before saving. A map connected to QGIS Server opens framed on its layers instead; an opening view set in Groundwork and sent out with your share link covers both cases. The first layer in your project is the one Groundwork makes active when the map opens, the one whose features fill the Data panel and the one users edit, so put the layer your team works in at the top. Layers unticked in the QGIS layers panel load hidden, ready for users to show, which suits context layers.

What your styling looks like in the browser

Groundwork converts your QGIS styling automatically when the map loads, with no separate style files needed. A single-symbol, categorised or graduated style built from simple markers, lines and fills is reproduced in full, along with labels drawn from a single field. A categorised style also gives the layer its legend and the values users can filter by: trees coloured by a species field get a species legend and a species filter.

Set every size, width and dash length in millimetres. A value in points, inches or map units is read as a number of screen pixels and comes out wrong.

A layer whose style Groundwork can’t read falls back to a colour from a fixed palette; it still loads, lists and edits normally. What to keep clear of:

• Elaborate marker types. A font, filled, raster-image or ellipse marker drops the whole layer’s style to a palette colour. An SVG marker from a file of your own draws as a plain marker in the same colour; icons from QGIS’s built-in library are reproduced.
• Line decorations. Marker, arrow, hashed and the other decorated line types draw as a plain line. For a dash pattern that holds up at any width, tick Use custom dash pattern and set a pattern in millimetres; the preset Dash and Dot styles draw as a fixed, small on-screen pattern.
• Hatched fills. Any Fill style other than Solid or No brush on a simple fill draws as solid black, or draws nothing at all when its Stroke style is No pen. Use a solid fill, or No brush for outline-only polygons. Fills always draw at half opacity, so the basemap stays visible underneath.
• Symbology types that draw nothing. No symbols, Heatmap, Point displacement, Point cluster, Merged features, Inverted polygons and 2.5D leave the layer blank on the map, with its features still listed and still editable.
• Rule-based expressions. A rule carries across where it tests a field against a value: =, !=, <, <=, >, >=, IS NULL, IS NOT NULL, and AND/OR/NOT combinations. An expression function, a variable or the Else catch-all loses its condition, and that rule’s symbol is then drawn on every feature. Write not-equal as !=, never <>.
• Elaborate labelling. Labels keep their field, font, colour, text buffer, a simple offset and Prevent overlap. Expressions, rule-based labelling, callouts and further placement are left behind, and so are data-defined overrides, symbol opacity, symbol levels and blend modes everywhere in the style; set opacity in the symbol’s colour instead, on points and lines.

Open the map in Groundwork before you share it. The map loads but looks different from QGIS matches what you see to its cause. The fix is in QGIS: restyle and save the project over the published one, and the next person to open the map gets the new version.

Before you publish

• Open the project fresh in QGIS and check your layer draws (no broken file paths).
• Confirm each file-backed layer points at a GeoJSON or GeoParquet file inside the project folder.
• Check the project is saved as .qgs. For a cloud folder, check the canvas is on the view the map should open on before saving.
• Check any layer your team must not change is ticked read-only.

Next: Publishing to a cloud folder.