QGIS Integration

The QGIS integration lets Pro and Max users take a saved planting plan into a desktop GIS as a GeoPackage and, with the official AgroForestDesigner Sync plugin, synchronize supported spatial changes back to the plan.

Use the integration when you need GIS inspection, spatial editing, overlays, or a controlled round trip between AgroForest Designer and QGIS. The browser plan remains the authoritative application record. A downloaded file is a versioned snapshot, not a live connection.

QGIS and the GeoPackage improve spatial interoperability, but they do not turn map imagery or design coordinates into survey-grade data. Verify critical boundaries, positions, levels, dimensions, and coordinate reference systems against an appropriate field survey.

Choose the right workflow

The integration supports two related workflows:

Workflow	What it does	Connection token required
GeoPackage export	Downloads the current saved plan as a multi-layer .gpkg file for inspection or offline work in QGIS	No token for a download started while signed in to AgroForest Designer
Connected synchronization	Lets the official QGIS plugin discover your projects, download plan data, preview supported changes, and push an approved batch back	Yes; write access is required for a push

Opening and styling an exported GeoPackage does not change the server plan. Changes return to AgroForest Designer only through the validated synchronization workflow.

Before you start

Prepare the following:

• an active subscription that includes QGIS interoperability;
• a project and planting plan owned by your account;
• a current saved plan version;
• a maintained QGIS installation with GeoPackage support; and
• the official AgroForestDesigner Sync plugin when you need connected synchronization.

Plugin downloads require the same Pro or Max access as connected synchronization. AgroForest Designer discovers validated releases from the deployment's download directory, so the QGIS plugin download page always marks the newest available version and also lists older releases.

Save the plan immediately before export. The GeoPackage and API read the latest server-side plan; unsaved changes that exist only in the browser are not included.

Install the QGIS plugin

1. Sign in to AgroForest Designer and open the QGIS plugin download page.
2. Download the release marked Latest. Keep the .zip archive intact; do not extract it.
3. In QGIS, open Plugins > Manage and Install Plugins.
4. Select Install from ZIP, choose the downloaded archive, and select Install Plugin.
5. Acknowledge the experimental-plugin warning when QGIS shows it. The release page reads this status directly from the plugin metadata.
6. Open Web > AgroForestDesigner > AgroForestDesigner Sync, or select its toolbar button.

The release page shows the supported QGIS range, archive size, and SHA-256 checksum for every validated ZIP. If QGIS rejects an archive, download it again from the page and compare its checksum before retrying. Never install an archive received through an untrusted message or unrelated website.

Download a GeoPackage

1. Open the required saved plan in the Digital Planting Plan.
2. Select Save version and wait for the success confirmation.
3. Open Execution > Output.
4. Select Download GeoPackage.
5. Store the downloaded .gpkg file in a project folder with a clear date or revision reference.
6. In QGIS, add the GeoPackage through the data-source manager or drag the file into the project.

The filename is derived from the project and plan name. The package uses GeoPackage 1.3 and WGS 84 (EPSG:4326) with coordinates stored as longitude, latitude. QGIS can display the layers in another project coordinate reference system, but do not redefine the source layer CRS merely to make it match the canvas.

Every export contains identifiers for the project, plan, package, base revision, and base content. It also contains the server URL and synchronization metadata used to detect later conflicts. Keep one untouched copy of an important export before doing extensive editing, and do not move internal afd_ tables between unrelated packages or plans.

Treat the GeoPackage as confidential project data because its visible features can describe a real site and design. Synchronization tables contain feature baselines, identifiers, revision fingerprints, and the server address, but new exports do not embed the raw plan, raw annotations, backend-only metadata, credentials, or an API token. Removing one visible layer is still not a reliable anonymization method.

Understand the exported layers

Every GeoPackage contains the complete layer structure, including layers that are empty in the selected plan.

Layers that support synchronization

Layer	Geometry	Supported use
plantings	Point	Move, add, or remove individual plants and update supported planting or implementation fields
plant_zones	Polygon	Edit planting-zone geometry, colour, and notes
paths	Line	Edit path centre lines and supported name, width, colour, opacity, or smoothing values
design_polygons	Polygon	Edit polygon or rectangle drawings and supported display properties
design_circles	Point plus radius_m	Move or resize circular drawings and edit supported display properties
ground_control	Point	Move, add, or remove ground-control markers and edit their labels

Work with individual plants

plantings is one QGIS layer for performance and practical editing, but every row is one individual placed plant. Plants are never grouped into one aggregate feature. Open the attribute table or the plugin's Plant inspector to inspect, search, select, and zoom to an individual. The inspector also reports the feature count so a pulled plan can be checked against the number expected in the browser.

Each individual has two complementary identifiers:

• afd_id is the stable technical identity used for synchronization. Never edit, copy between plans, or use it as a display number.
• plant_number is the positive planner inventory number and plant_code is its readable form, such as P12. The number is persisted with the plant. New plants receive a number after the plan's high-water mark, so gaps left by removed plants are not silently recycled. afd_src_idx is only an internal source position and is never a plant number.

GeoPackage schema 1.2 exposes the following plant-source and display context in addition to editable planting fields. This context is read-only on an existing feature; source_type and source_id may be supplied only to identify the source while creating a new plant or planting zone:

Fields	Meaning
display_name, scientific_name	A useful display fallback and the botanical name
common_name_en, common_name_nl, common_name_fr	English, Dutch, and French common names when present in the catalogue or saved marker
cultivar_id, cultivar_name	Cultivar identity and label where applicable
plant_layer	Food-forest or vegetation layer
generation_layer_id, generation_layer_name, generation_sequence, generated_instance_id	Context for algorithm-generated placements
source_type, source_id, catalog_id	Typed origin and stable source identifier. source_type plus source_id is canonical; catalog_id remains available for compatible older clients

The same localized/display and cultivar fields are available on plant_zones where meaningful, but zones do not consume P-numbers.

In the plugin, choose the preferred common-name language under Settings. Auto (QGIS language) starts with the QGIS interface language; English, Dutch, and French prefer the matching field and fall back to another available common name and then the scientific name. Scientific name forces the botanical name. Label modes are None, Plant code, Preferred name, and Code + preferred name. Labels are scale-limited to keep dense plans readable. The selected language affects presentation only and is never pushed as a catalogue change.

The server accepts geometry plus only the following properties during synchronization:

Layer	Accepted properties
plantings	source_type, source_id, catalog_id, radius_m, color, stem_type, planted, planted_date, planted_notes, planted_nursery_id, planted_nursery, existing_plant
plant_zones	source_type, source_id, catalog_id, color, notes
paths	name, description, width_m, color, opacity, smoothing
design_polygons	name, description, height_m, fill_color, fill_opacity, stroke_color, stroke_opacity, stroke_weight, visible
design_circles	name, description, height_m, radius_m, fill_color, fill_opacity, stroke_color, stroke_opacity, stroke_weight, visible
ground_control	label

An editable layer is not an unrestricted database table. In particular:

• a new plant or planting zone needs either an existing AgroForest Designer catalogue plant or an active personal plant owned by the plan owner;
• the plant-source identity of an existing plant or zone cannot be changed in place;
• afd_id is the stable feature identity and must never be edited;
• fields such as afd_locked, source indexes, plant codes, localized or derived plant names, cultivar/generation context, diameter_m, plant height_m, and template references are transport or reference data; and
• invalid, unknown, or out-of-range values cause validation to reject the batch.

The current plugin does not include a plant-library browser. For a catalogue plant, use source_type = catalog and its numeric source_id, or the compatible catalog:<id> reference. For an entry in My Plants, use source_type = user and its UUID source_id, or the canonical user:<uuid> reference. Older packages may still contain preset:<pk>; this form is accepted only for backward compatibility.

Personal references are always resolved for the plan owner. A missing, foreign, archived, or guessed entry cannot create a new placement, and a personal plant that is read-only under the current plan allowance also cannot be newly placed from QGIS. Existing placements keep their embedded display snapshot, so they remain visible and can receive ordinary geometry or implementation updates even if the library entry is later archived or unavailable. The snapshot, not a later library lookup, is authoritative for an unchanged placement.

A GeoPackage includes only the placement fields needed to render and synchronize a personal plant. It does not export private library notes, owner identity, moderation or review state, submission data, or administrator metadata.

Reference-only layers

Layer	Geometry	Meaning
project_boundary	Polygon	The project boundary controlled by AgroForest Designer
measurements_lines	Line	Saved distance measurements and derived distance values
measurements_areas	Polygon	Saved area measurements and derived area or perimeter values
structures	Point	Placed structure templates and their anchor information
annotations	Point	Plan comments and replies
orthomap_extents	Polygon	Reserved for orthomap coverage metadata; the current export leaves this layer empty and never embeds raster pixels

These layers are reference-only. The GeoPackage enforces that restriction with database triggers, so QGIS should report an error if an insert, update, or delete is attempted. Make boundary, measurement, structure, annotation, or orthomap changes in AgroForest Designer and then create a fresh export.

Create a connection token

Open Execution > Output > QGIS connection, or open the QGIS integration page directly.

1. Enter a Device name that identifies the computer or QGIS profile.
2. Choose whether the token expires after 7, 30, or 90 days.
3. Leave Allow validated planting-plan changes to be pushed from QGIS clear for read-only access, or select it when this device must synchronize changes.
4. Select Create token.
5. Select Copy token and store the complete token immediately. It is shown only once.
6. Store it in QGIS Authentication Manager and configure the exact Server URL shown on the integration page.

A read-only token receives gis:read. Selecting write access adds gis:write, which also retains read access. Read access is sufficient for connection checks, project and plan discovery, snapshots, and downloads. A push requires write access.

The token is not your web password. AgroForest Designer stores only a cryptographic digest plus the visible prefix, scopes, dates, and status. Do not:

• email or message the token;
• put it in a QGIS project file, GeoPackage, script, screenshot, or issue report;
• place it in a URL or query string; or
• reuse one token across several people or devices.

Create one named token per device. This makes it possible to revoke one lost or retired connection without disrupting the others.

Connect the QGIS plugin

After installing the plugin, connect it as follows:

1. In QGIS, open Settings > Options > Authentication and add a new API Header configuration. Its Resource field must exactly match the Server URL shown on the AgroForest Designer integration page. Add a Header Name of Authorization and a Header Value of Bearer followed by the complete token.
2. Open AgroForestDesigner Sync and select Settings….
3. Select the authentication entry and choose a local workspace folder for downloaded packages.
4. Save the settings and select Refresh projects. A successful connection shows Connected as followed by your name or email address.
5. Choose a project owned by the same account and one of its saved planting plans.
6. Select Pull GeoPackage before beginning a new edit session.

The API accepts the token only as an Authorization: Bearer credential. A client must not append it to a URL. Tokens cannot access projects owned by another account.

If a project exceeds the account's current project capacity, the client can still read it while GIS access remains active, but the project is reported as read-only and cannot accept a synchronized batch.

Edit and synchronize safely

Avoid editing the same plan in QGIS and the browser at the same time. A safe round trip is:

1. Save the browser plan and download a fresh package.
2. Make changes only in supported layers and fields.
3. Save all layer edits in QGIS.
4. Select Preview changes in the plugin to validate the batch.
5. Review the create, update, and delete summary and the listed layer, ID, action, and result for each preview item. Resolve any error shown by QGIS before retrying.
6. Push the exact batch that was previewed.
7. Reopen or refresh the browser plan and inspect the new saved revision.
8. Create a fresh GeoPackage before the next separate editing session.

Preview is non-mutating: it validates the entire batch without changing the plan. A successful preview is signed and remains valid for ten minutes. Push accepts only the exact content covered by that preview. If any item changes afterward, create a new preview.

A push is atomic. AgroForest Designer applies every accepted change in one transaction or applies none of them. A successful content-changing push creates a normal planting-plan revision with a QGIS source marker, so the change remains visible in plan history. A valid batch that produces no content change does not create an extra revision.

Handle concurrent changes

Every package is tied to the synchronized plan content that existed when it was exported. If the plan content changes in the browser or another QGIS session, the server detects the different plan-content ETag and returns a revision conflict instead of silently overwriting it. A save with identical plan content, or a change limited to annotations or the project boundary, does not use that plan-content conflict check.

Do not try to remove the package metadata or force the old version through. Keep your edited file, download a fresh plan, compare the changes, and deliberately reapply the required edits to the current version before previewing again. The server does not automatically merge competing spatial edits.

Respect geometry and batch limits

The synchronization contract currently enforces these limits:

• no more than 5,000 feature changes in one batch;
• keep each line or polygon at no more than 10,000 working coordinate points;
• point, single-line, and single-ring polygon geometries only;
• at least three distinct points and a real enclosed area for a polygon;
• WGS 84 coordinates in longitude, latitude order; and
• each feature identity may occur only once in a batch.

Polygons with holes, multi-geometries, non-finite coordinates, invalid plant-source references, and unsupported layers or properties are rejected. A closed polygon can contain a repeated start/end coordinate in addition to its working vertices. The server checks geometry type, coordinate ranges, point counts, distinct polygon points, and non-zero signed area, but it does not guarantee full topological validity or detect every self-intersection. Run QGIS geometry validation before previewing important polygons. Split oversized work into deliberate batches and preview each one.

Manage or revoke tokens

The integration page lists every token with its name, public prefix, creation date, expiry, scopes, and revoked status.

Select Revoke when:

• a computer, QGIS profile, or token may be lost or exposed;
• a contractor or collaborator no longer needs access;
• a token was stored outside QGIS Authentication Manager;
• write access is no longer appropriate; or
• the connection is being replaced.

Revocation is immediate and cannot be undone. Create a new token when access is needed again. Changing to a plan without QGIS interoperability blocks GIS data access for existing tokens; those tokens can still be revoked from the integration page.

Troubleshooting

Message or symptom	What to do
GIS access is not available or feature_unavailable	Confirm that the account has an active plan which includes QGIS interoperability. Open Subscription to review current access.
missing_token or invalid_token	Check that the client uses the complete token in QGIS Authentication Manager and sends it as a Bearer credential, not in the URL. Create a new token if the original value was not saved.
revoked_token or expired_token	Create a replacement token and update the QGIS authentication entry.
insufficient_scope	The token is read-only. Create a separate token with Allow validated planting-plan changes to be pushed from QGIS selected.
project_read_only	The project is frozen under the current capacity. Review Subscription and project usage before attempting another push.
revision_conflict	The server plan changed after the package was created. Download the current plan and reapply the required edits deliberately.
preview_expired	Preview the unchanged batch again; previews expire after ten minutes.
preview_payload_mismatch or batch_digest_mismatch	The batch changed after validation. Save the QGIS edits and create a new preview before pushing.
invalid_catalog_id or unknown_catalog_id	Use a valid catalogue plant for a new feature. Do not guess a catalogue ID.
user_plant_unavailable	The personal plant is missing, archived, or not available to this plan owner. Select an active entry from the owner's My Plants library. The same safe message is used for foreign and missing UUIDs.
user_plant_read_only	The personal plant is frozen under the current plan allowance and cannot create a new QGIS placement. Existing embedded placements remain editable.
invalid_source_reference, missing_source_reference, or source_reference_mismatch	Correct the typed source. Use a matching source_type and source_id; if catalog_id is also present, both forms must identify the same plant.
immutable_plant_source	Do not change the plant source of an existing plant or zone. Create a new feature when a different plant is required.
unsupported_layer, unsupported_property, or a read-only database error	Limit edits to the supported layers and fields listed in this guide.
invalid_geometry or number_out_of_range	Repair the feature geometry or attribute value and preview again. Check the source CRS and longitude/latitude order.
unsupported_schema_version	The plugin and server use different synchronization wire versions. Install the latest release from the plugin download page before retrying. GeoPackage 1.0 and 1.1 files remain readable after the 1.2 rollout, but push still uses the documented 1.0 wire contract.
The latest browser edits are missing from QGIS	Save a plan version in the browser, then download or fetch a fresh package.
An orthomap is not visible in QGIS	The current orthomap_extents layer is empty and the GeoPackage does not embed raster pixels. Add the original georeferenced raster separately when required.

If a repeatable problem remains, revoke any token that may have been exposed and contact support with the project and plan names, QGIS version, plugin version, package export time, action being attempted, and exact error code. Never include the raw token or confidential project data in a support message.

Connection reference for supported clients

The canonical API base is the server URL followed by /api/v1/gis/. Supported clients use these endpoints:

Endpoint	Purpose	Required scope
capabilities/	Report API/schema versions, layers, formats, limits, and current feature availability	gis:read
me/	Report the authenticated account and token metadata	gis:read
projects/	List owned projects	gis:read
projects/{project_id}/plans/	List saved plans for one owned project	gis:read
projects/{project_id}/plans/{plan_id}/snapshot/	Return current layers as GeoJSON feature collections	gis:read
projects/{project_id}/plans/{plan_id}/geopackage/	Download the current GeoPackage	gis:read
projects/{project_id}/plans/{plan_id}/sync/preview/	Validate and sign a proposed batch without saving it	gis:write
projects/{project_id}/plans/{plan_id}/sync/push/	Atomically apply the exact previewed batch	gis:write

The current public contract reports API v1, GeoPackage schema 1.2, and synchronization wire schema 1.0. Capabilities separately report the current package version, supported package versions (1.0, 1.1, and 1.2), and the sync version. This separation lets an older package complete its batch workflow while new pulls receive typed plant-source fields. A package version is not permission to send arbitrary properties: push remains a closed 1.0 allowlist. The typed source_type and source_id fields may establish the source of a newly created plant or zone, while all other identity, language, cultivar, and generation fields remain read-only.

Push clients must preserve package metadata, the base revision metadata, and the plan-content ETag, use a unique batch UUID, and send the matching conditional request information. Plan-content conflict detection uses the ETag; base_revision is validated as metadata but is not the conflict comparator. Retrying the identical batch is safe; reusing its identifier for different content is rejected.

Continue learning

Return to Digital Planting Plan for the complete browser planning workflow. Review Plans and Feature Access when an output or connection is locked, or use Projects to manage the plan and site information that remain authoritative outside the GeoPackage.