Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update system.en.md #452

Closed
wants to merge 1 commit into from
Closed

Update system.en.md #452

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 68 additions & 57 deletions documentation/reference/qfieldcloud/system.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,70 +13,46 @@ tx_slug: documentation_reference_qfieldcloud_system
A QGIS project is a *.qgs* or *.qgz* file. A Project is created on
QGIS Desktop and uploaded to QFieldCloud using the QGIS's plugin
QFieldSync. Before the uploading of the QGIS project, it is necessary
for each layer of the QGIS project an "action" that determines how
for each layer of the QGIS project to set an "action" that determines how
QFieldSync and QField should treat the layer. There are the two types
of actions that can be setup - one for QFieldCloud and one for the
traditional cable export.

This information is saved within the QGS project as layer's
*customProperty*, with the *QFieldSync/action* key.

The available actions are:
The following actions are available and will be explained in more detail below:

| Action internal name | Name showed in the UI |
|----------------------|-----------------------|
| OFFLINE | Consolidate |
| NO_ACTION | Live layer |
| REMOVE | Ignore layer |
| COPY | Copy |
| KEEP_EXISTING | Keep Existing |
| Name showed in the UI | Work mode |
|---------------------------------|---------------------|
| Offline editing | QFieldCloud & cable |
| Directly access data source | QFieldCloud & cable |
| Remove from project | QFieldCloud & cable |
| Copy | only cable |
| Keep existing (Copy if missing) | only cable |

This would be the behavior of QFieldSync with the different
layer actions:
#### QFieldSync > QFieldCloud configuration
When synchronising a project with QFieldCloud, all layers in the QGIS project are sent to QFieldCloud. The configuration set in QFieldSync is applied by QFieldCloud only at the moment of packaging a project for QField.

This is the behavior of QFieldCloud (`libqfieldsync`) with the layers:

| Action | File based layer | Service-based layer (e.g. WMS) | Database layers (Postgres) |
|-----------------------------|------------------------------------------------------------------------------------------------|-----------------------------------|--------------------------------------------------------------------------------------------------|
| Offline editing | Create consolidated copy of the data on pull, apply delta file on push to original data source | N/A | Create a consolidated copy of the data on pull, apply delta file on push to original data source |
| Directly access data source | Create a read-only copy in an individual geopackage | No action on the layer | No action on the layer |
| Remove from project | Remove the layer from the project | Remove the layer from the project | Remove the layer from the project |

| Action | File based layer | Not file based layer |
|---------------|------------------------------------------------------------------|----------------------------------------|
| OFFLINE | Create a consolidated copy of the data | Create a consolidated copy of the data |
| NO_ACTION | N/A | No action on the layer |
| REMOVE | Remove the layer from the project | Remove the layer from the project |
| COPY | Make source path relative and copy the file | N/A |
| KEEP_EXISTING | Make source path relative and copy the file if it does not exist | N/A |

This is the behavior of QFieldCloud (`libqfieldsync`) with the
layers:

| Action | File based layer | Not file based |
|---------------|-----------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| OFFLINE | Create consolidated copy of the data on pull, apply delta file on push to original data source | Create consolidated copy of the data on pull, apply delta file on push to original data source |
| NO_ACTION | N/A | No action on the layer |
| REMOVE | Remove the layer from the project | Remove the layer from the project |
| COPY | Make source path relative and create copy of the data on pull, apply delta file on push to original data source | N/A |
| KEEP_EXISTING | Make source path relative and create copy of the data on pull, apply delta file on push to original data source | N/A |

This is the behavior of QField with the layers:

| Action | File based layer | Not file based layer |
|---------------|------------------------------------|--------------------------------------------|
| OFFLINE | Create and push deltafile | N/A (it's always file based at this point) |
| NO_ACTION | N/A | Edit the online (live) database |
| REMOVE | N/A (the layer is no longer there) | N/A (the layer is no longer there) |
| COPY | Create and push deltafile | N/A |
| KEEP_EXISTING | Create and push deltafile | N/A |

In summary, for with QFieldCloud:

- *NO_ACTION* is used for online layers that are located on a server
accessible via the Internet and that are modified directly by
QField.
- *HYBRID* means that a geopackage will be generated on the
In summary, with QFieldCloud:

- *Offline editing* means that a geopackage will be generated on the
server (or directly on the desktop for file-based layers) and
downloaded by clients. The client will generate deltafiles of the changes.
- *OFFLINE* is used for example to work with local databases not
visible by QFieldCloud which are consolidated before being
loaded from the desktop to the server and are not synchronized
with the original data by QFieldCloud.
- *REMOVE* will simply remove the layer from the project.
- *KEEP_EXISTENT* will not be used for QFieldCloud syncronizations.
downloaded by clients. *Offline editing*-layers will all be combined in a single `data.gpkg`.
The client will generate deltafiles of the changes. On push, the original data source will be updated, including the database for database layers.
- *Directly access data source* is mainly used for service-based layers that are located on a server
accessible via the Internet and that are modified directly by QField.
Examples are WMS, WMTS-layers or layers coming from a database.
If the layer is file-based, a read-only copy will be generated in an individual geopackage per layer.
- *Remove from project* will simply remove the layer from the project (not package it for QField).

From QFieldSync it will be possible to update a project already
loaded on QFieldCloud. In the event that the changes concern only
Expand All @@ -87,19 +63,54 @@ reset on the server (delta files will be deleted) and for each
client it will be necessary to download the updated version of the
project before being able to push new changes.

#### QFieldSync > Cable export configuration
When using the traditional cable export, the configuration in QFieldSync > Cable export will be applied by QFieldSync at the moment of clicking on "Package for QField".
This is the behavior of QFieldSync for cable export with the different
layer actions:

| Action | File based layer | Web-service layers (e.g. WMS) | Database layers (Postgres) |
|---------------------------------|------------------------------------------------------------------|-----------------------------------|------------------------------------------------|
| Offline editing | Create a consolidated copy of the data | N/A | Create a consolidated copy of the data (.gpkg) |
| Directly access data source | N/A | Directly access the web service | Edit the online (live) database |
| Remove from project | Remove the layer from the project | Remove the layer from the project | Remove the layer from the project |
| Copy | Make source path relative and copy the file | N/A | N/A |
| Keep existing (Copy if missing) | Make source path relative and copy the file if it does not exist | N/A | N/A |

#### Behaviour of QField
Depending on the actions set for each layer in QFieldSync for QFieldCloud or Cable export, QField will act as follows:

| Action | File based layer | Service-based layer (e.g. WMS, database) |
|---------------------------------|------------------------------------|--------------------------------------------|
| Offline editing | Create and push deltafile | N/A (it's always file based at this point) |
| Directly access data source | N/A | Edit the online (live) database |
| Remove from project | N/A (the layer is no longer there) | N/A (the layer is no longer there) |
| Copy | Create and push deltafile | N/A |
| Keep existing (Copy if missing) | Create and push deltafile | N/A |


### QFieldCloud Project
Is composed of one and only one QGIS project and the possible
related files (e.g. geopackages, images, ...) included the offline
or hybrid data package.
related files (e.g. geopackages, images, ...).

### Technical names for actions
The technical names for the available actions in QFieldSync are:

| Name showed in the UI | Action internal name |
|---------------------------------|----------------------|
| Offline editing | OFFLINE |
| Directly access data source | NO_ACTION |
| Remove from project | REMOVE |
| Copy | COPY |
| Keep existing (Copy if missing) | KEEP_EXISTING |

## Use Cases

### Hybrid
### Offline editing in the field, QFieldCloud connected to the database
Hybrid editing mode with synchronization on the server

!![Hybrid editing mode](../../assets/images/hybrid-schema.png)

### Offline database
### Offline editing in the field, QFieldCloud not connected to the database
Offline editing mode with desktop synchronization

!![Offline editing mode](../../assets/images/offline-schema.png)
Loading