The original version of this document is located at https://docs.qfield.org/get-started/tutorials/advanced-setup-qfc

Advanced Setup Guide

Supported Vector Providers

Currently, QFieldCloud supports GeoPackage and PostGIS layers for collaborative editing.
Other formats supported by QGIS should also work but are not officially supported.

Synchronization Process

When working with QFieldCloud, it is important to understand the synchronization process to avoid data loss or overwriting files and deltas.
You can find technical details on the different job types in the technical documentation section.
In simple words, three different synchronization activities exist:

• From QGIS to QFieldCloud: Uploads a complete new project package and replaces the existing package stored in the cloud.
  When working with GeoPackages, the existing GeoPackage in the cloud is replaced with the newly uploaded file.
• From QFieldCloud to QField: Downloads the uploaded project package to your mobile device.
  QFieldCloud packages the project into a specific format saved in the internal application folder structure.
  When working with PostgreSQL databases in offline editing mode, a local GeoPackage is created in the corresponding folder (ensure your secret is configured properly).
• From QField to QFieldCloud: Applies changes as deltas after completing data collection.
  Deltas reflect only the attribute and geometry changes made in the field.
  When uploading or synchronizing with QFieldCloud, only the deltas are applied, so the entire GeoPackage is not replaced.

Working Modes

When configuring a project for QField, choose between different packaging options:

• Offline editing: Regardless of whether files are stored in a GeoPackage, database, or other formats, QFieldCloud creates a temporary GeoPackage of all project data.
  Changes made to this GeoPackage remain local until synchronized.
  Once changes are uploaded or synchronized back to QFieldCloud, only the modifications are applied to the existing cloud file.
  We recommend this option to prevent data loss during connection drops.
• Direct Data Access: Edits data directly in the PostGIS database.
  This option requires a reliable internet connection in the field.
  It allows all users to immediately view data changes and use PostGIS-specific configurations (such as triggers and generated fields).

In general, changes become visible to other users once synchronization via QFieldCloud occurs across devices.
If you are working in Offline Editing mode a local copy is created, advanced PostGIS operations (such as triggers) will not be available in QField.

Find more information in the QFieldCloud technical reference.

Working with GeoPackages

Using GeoPackages is usually the best choice for a simple setup to centralize data collected by your QField users into a single file.

If you set up a relation, add a UUID field and use it as the primary or foreign key.
Do not use the default fid field for relations as a primary or foreign key.
The fid field can be modified during synchronization with QFieldCloud and lead to errors over time.
A UUID is unique and will not cause conflicts during synchronization.

PostGIS

Using PostGIS is a good choice if your data must be visible and editable for multiple users.

It requires your database to be publicly accessible, and credentials must be saved unencrypted in the QGIS project file.
Please consider the security implications of these requirements and maintain regular backups.

Access to the database can be saved and made available for QFieldCloud in two ways:

• Direct Connection: Store all information, including credentials, directly inside the QGIS project file.
• Using a PG Service File: Use a service file saved as a secret in QFieldCloud.
  We highly recommend using a PG Service file for data security.
  Read more on PG Service and secrets in the PG Service documentation.

Find more information in the QFieldCloud technical reference.

Restriction of Project Files

To prevent modifications to the core QGIS project file, project administrators can restrict access to these files in QFieldCloud.

Once enabled, only administrators and managers can push changes to restricted files.
Other project collaborators can still upload and modify project datasets (such as GeoPackages), but cannot alter the main project file or its core components.

Restricted Files

When enabled, the following files can only be modified or uploaded by a user with an Admin or Manager role:

• The primary QGIS project file (e.g., my_project.qgz)
• The attachments zip archive associated with the project (e.g., my_project_attachments.zip)
• QGIS auxiliary data files that store information like label positions (e.g., my_project.qgd)
• QField style files (.qml) that share the same name as the project file

Handling Conflicts

When working in a collaborative environment with multiple users accessing the same project, two users might modify the same feature during fieldwork.
In your project settings page, choose whether QFieldCloud applies the last wins policy or flags conflicts for project managers to resolve manually.

Read more on how QFieldCloud handles conflicts in the technical documentation.

Activate Email Notifications for QFieldCloud Changes

To receive notifications about activity in your teams and projects, activate the email notification option in QFieldCloud.

You can receive notifications for the following events:

• User created
• Organization created
• Organization deleted
• Organization membership created
• Organization membership deleted
• Team created
• Team deleted
• Team membership created
• Team membership deleted
• Project created
• Project deleted
• Project membership created
• Project membership deleted

You only receive notifications for actions initiated by other organization members or project collaborators.

Enhance Your Project with the “Optimized Packager”

We recommend using the Optimized Packager over the deprecated QGIS Core Offline Editing packager for all projects.

Consider this example configuration:

• Layer 1.1:
• Data Source: layers.gpkg
• Table: layer1
• Filter: id % 2 = 1
• Layer 1.2:
• Data Source: layers.gpkg
• Table: layer1
• Filter: id % 2 = 0

Result:

• Optimized Packager: Generates a single layer in the offline GeoPackage, combining data from layer1 with specified filters applied.
• QGIS Core Offline Editing Packager: Creates two separate layers representing the filtered datasets:
• Layer 1: Filtered with id % 2 = 1
• Layer 2: Filtered with id % 2 = 0

Configuration of Attachment Folders

If your project contains photos, documents, or other attachments, configure your QGIS project to ensure files download to your QField device.

Connect to a Custom QFieldCloud Server in QField and QFieldSync

QField and QFieldSync connect to the default QFieldCloud service at app.qfield.cloud.

Modify the default server address in QField and QFieldSync if using a custom deployment: