Vai al contenuto

Lavori

I lavori su QFieldCloud eseguono operazioni pesanti con i file di progetto e i layer all'interno di QGIS. I lavori vengono creati in risposta a determinate azioni dell'utente.

Once a job is created, it is added to the project's job queue and waits for available QFieldCloud resources to run. At any given moment only one job can run per project. The rest of the queued jobs will perform in the same order as in they entered the queue.

Each job consists of one or more steps and each step is responsible for one self contained task on the project. QFieldCloud supports three predefined job workflows: process_projectfile, package and delta_apply.

Durante l'esecuzione, i lavori scrivono messaggi di log che sono disponibili nella pagina dei lavori del progetto per i lavori che hanno raggiunto lo stato finale FINISHED o FAILED.

I lavori hanno accesso ai segreti del progetto.

Note

Tutti i lavori possono essere lanciati utilizzando l'API di QFieldCloud.

Attenzione

  • Le condizioni di attivazione descritte in questa pagina possono cambiare senza preavviso.
  • Tutti i lavori devono terminare entro 10 minuti, altrimenti si verificherà un errore di timeout e verranno interrotti.

Info

If you are looking for technical details how Jobs work, check the Job Queue documentation.

Tipi di lavoro

Elaborazione del file di progetto (process_projectfile)

The process project file job is used to extract details about the project configuration and project layers including QGIS version used, project CRS, layer CRS, layer names, layer validity etc. QFieldCloud validates the uploaded QGIS project file (.qgs/.qgz), as well as the supporting GeoPackages, TIFFs and other data source files. It also validates remote connections to PostGIS, WFS, WMS and other online data sources. QFieldCloud will open the project file in a QGIS instance on the server to extract all the necessary information.

Triggers and Possible Errors

This job is triggered every time a file is uploaded to QFieldCloud.

The following conditions may result in an error while uploading to QFieldCloud:

  • Non è stato ancora caricato alcun file di progetto QGIS (.qgs/.qgz).
  • The uploaded file is within the DCIM directory. Those files are assumed to be irrelevant to project validity.
  • C'è già un lavoro process_projectfile in stato PENDING.

Troubleshoot and fix

A process_projectfile job might result in a FAILED status, due to several reasons. Below is a list (non-exhaustive) with the most common causes:

  • The uploaded QGIS project file (.qgs/.qgz) is unreadable, incomplete, broken or wrong. Try to reupload the QGIS project file.
  • QGIS is crashing after opening the project file.
  • Try to identify the layer that is causing the crash by removing one layer at a time from the project and reuploading the QGIS project file.

Note

Even if a process_projectfile job results in a SUCCESS status, it does not mean the project is properly configured. The SUCCESS status just states the project has been successfully opened and all the needed information has been extracted.

Creazione pacchetto (package)

The package job converts a QGIS project to a QField project, the same way it is done on QGIS via QFieldSync. The package job will prepare all layers marked as "Offline editing" to a single GeoPackage.

Triggers and Possible Errors

This job is triggered every time the Download or Synchronize buttons are pressed on QField. Unless at least one of the following condition are valid:

  • Il progetto non ha mai eseguito un lavoro process_projectfile che abbia avuto come risultato lo stato SUCCESS.
  • Esiste già un lavoro package in stato PENDING.
  • Il progetto non contiene layer vettoriali online (PostGIS, WFS ecc.), l'ultimo risultato del lavoro package è stato SUCCESS e non sono stati caricati file o modifiche.

Risoluzione dei problemi

A package job might result in FAILED status , due to several reasons. Below is a list (non-exhaustive) with the most common causes:

  • Il progetto non ha mai eseguito un lavoro process_projectfile che abbia avuto come risultato lo stato SUCCESS.
  • Some of the project layers are inaccessible from QFieldCloud.
  • Make sure all files are uploaded and all credentials to online layers (PostGIS, WFS etc) are stored within the QGIS project file.

Applicazione delta (delta_apply)

Delta apply è responsabile di rendere permanenti tutte le modifiche apportate a QField.

Triggers and Possible Errors

This job is triggered every time a Synchronize or Push changes button is pressed on QField, or Apply pending changes button is pressed on the Changes project page in QFieldCloud.

Issues may arise if any of the following condition are valid:

  • The project never ran a process_projectfile job that resulted in SUCCESS status.
  • C'è già un lavoro delta_apply in stato PENDING.

Risoluzione dei problemi

A delta_apply job may result in a FAILED status, due to several reasons. Below is a list (non-exhaustive) with the most common causes:

  • Database connection issues: The online database (PostgreSQL/PostGIS) used in the QGIS project reset the connection, timed out, or is currently unavailable.
  • Feature missing: The feature being updated has been deleted from the source data (e.g., by another user or process) before the delta change could be applied.
  • Layer missing: The layer corresponding to the changes was removed from the QGIS project.
  • Source changed: The structure of the layer source was changed (e.g., columns were renamed or removed), making the delta incompatible.
  • Project size: The project is too big and the job has failed to run within the resource limits.
  • Hidden files: There are hidden files and directories within the project that are preventing the normal work of QFieldCloud. Hidden files and directories are those starting with a leading dot (.).
Understanding conflicts delta_apply jobs

Conflicts occur when multiple changes affect the same data in a way that QFieldCloud cannot automatically resolve without a defined policy.

What is a "CONFLICT"?

In the Changes section, a delta status is set to CONFLICT when:

  1. Concurrent Editing: Two or more users modify the same feature (identified by the same primary key) on the same layer.
  2. Primary Key Collision: A new feature is created with a primary key that already exists in the database.

What overwrites what?

QFieldCloud resolves these conflicts based on the project's conflict resolution setting.

  • Last Wins (Default): QFieldCloud compares the timestamps of the conflicting changes. The change with the most recent timestamp overwrites any previous changes to the same attributes. The older change is effectively discarded in favor of the newer one, though it remains in the history.
  • Manual: No changes are overwritten automatically. The conflict is flagged, and the project administrator must manually select which version to apply.

Preventing Conflicts

To minimize the risk of conflicts, follow these best practices:

  • Plan updates collaboratively: When updating features based on specific field conditions, assign each user a distinct set of features to edit. Clear planning reduces overlap and potential conflicts.
  • Avoid modifying primary keys: Primary keys should be treated as immutable and configured to be read-only. This ensures consistent identification of features and prevents accidental modifications.
  • Ensure unique primary keys: Use a truly unique primary key to prevent conflicts and ensure data integrity.

By implementing these practices, you can significantly reduce the likelihood of conflicts and maintain consistent data.

How to resolve conflicts?

By default, QFieldCloud overwrites conflicts using a last wins policy (the latest patch of changes to the attribute(s) involved in the conflict replaces all earlier patches of changes to these attributes). Alternatively, admins can set a project's conflict resolution policy to manual. Doing so will require the project manager to manually resolve conflicts, picking those to be applied to the project.

  1. Passa alla sezione "Modifiche".
  2. Filter the changes with the "CONFLICT" status.
  3. Per ogni modifica in conflitto, selezionarla e impostare lo stato su "Riapplica" dal menu a discesa "Azione", altrimenti se tutte le nuove modifiche sono in conflitto puoi scegliere nell'ultima modifica in conflitto e selezionare "Riapplica questa e le modifiche più recenti".
  4. Controlla i dettagli delle modifiche nel conflitto e fare clic su "Salva tutto" alla fine della pagina.

Riapplicare le modifiche in QFieldCloud
  1. Clicca sul nome del progetto sotto I miei progetti.
  2. Vai alla sezione Modifiche (Le modifiche sono ordinate dalla più recente alla più vecchia)
  3. Trova le modifiche specifiche che desideri riapplicare.
  4. Nella colonna Azione sulla destra, clicca sulla lista a discesa.

  5. Scegli l'azione desiderata per riapplicare le modifiche.

    • Riapplicare modifiche specifiche: se è necessario riapplicare modifiche specifiche, selezionare ogni modifica che si desidera applicare nuovamente e fare clic su Riapplica.
    • Riapplica le modifiche recenti: Se si preferisce riapplicare le modifiche più recenti apportate al progetto, identificare la modifica iniziale che si desidera ripristinare, quindi selezionare Riapplica questa e le modifiche più recenti.

Infine, clicca sul bottone Salva tutto.

Re-apply changes
Re-apply changes

Risoluzione dei problemi con log dei lavori

Quando si esegue un lavoro, di solito nei log si trova un passaggio chiamato "Check project layers" che stampa una tabella con tutti i layer del progetto e lo stato accanto ad essi.

Gli stati possibili sono:

  • ok - Il layer viene caricato correttamente su QFieldCloud.
  • invalid_dataprovider - Il provider di dati del layer non è valido. Di solito le informazioni aggiuntive sono mostrate nel "Riepilogo provider".
  • invalid_layer - Questo errore dovrebbe accadere molto raramente. I dati vengono caricati correttamente, ma per qualche motivo QGIS riporta il layer come non valido.

Impossibile connettersi al servizio "{SERVICE}".

QFieldCloud tries to connect to a PostgreSQL service that is not available. You should need to create a new pgservice secrets so QFieldCloud can connect to the PostgreSQL service.

Impossibile connettersi all'host "{HOST}".

QFieldCloud cannot establish a connection to the given {HOST}. Your service is not accessible from the QFieldCloud server. You might been to ask your IT department to whitelist the QFieldCloud IP.

Impossibile connettersi all'host "localhost".

You have uploaded a layer that connects to a database/service on your local machine. Either remove that layer or replace it with a layer source accessible by QFieldCloud.

File "{FILENAME}" mancante.

The file {FILENAME} (e.g. /tmp/rndstr/files/data.gpkg) is not found on the QFieldCloud server and cannot be opened. There are two things that should be checked:

  • Whether the file has been uploaded to the cloud. You can check this in Project Settings > Files page on QFieldCloud or QFieldSync.
  • Making sure the file is uploaded with the same relative path as on your PC. Please note that all project files should be within the same project directory or subdirectory as the .qgs/.qgz QGIS project file. Please also note the directory names should be preserved too, for example if a file is stored in data/data.gpkg, make sure the data directory exists on QFieldCloud too.