Migrate from QField

• QField and Mergin Maps ecosystems
  • Users, organisations, workspaces
• Before we start
• Migrate QField project to Mergin Maps
  • Transfer QField project to the desktop
  • Convert QField project to QGIS project
  • Upload QGIS project to Mergin Maps
• Migrate QFieldCloud Settings
  • Organisations and permissions
  • Billing, subscriptions and plans
• Known differences between QField and Mergin Maps platforms
• Troubleshoot
• Credits

This guide is intended for current QField and QFieldCloud users considering switching to Mergin Maps as well as for Mergin Maps users looking to transfer their data from QField ecosystem.

Mergin Maps is the closest alternative to QField Ecosystem. Both QField and Mergin Maps are open-source projects powered by QGIS. Their respective mobile apps are both officially recommended for QGIS projects by QGIS.org (opens new window). Both platforms support almost the same set of supported formats via QGIS data providers and GDAL. Moreover, the mobile apps are based on the same open-source GIS stack and technology. As such their projects are almost fully interoperable.

QField and Mergin Maps ecosystems

The QField ecosystem consists of QField (mobile application), QFieldCloud (geo data collaboration server), QFieldSync (QGIS plugin) and QFieldCloud SDK (Python API client). Let's see the tools from Mergin Maps that are counterparts:

QField Ecosystem	Mergin Maps	Note
QField	Mergin Maps mobile app	Mobile application powered by QGIS
QFieldCloud	Mergin Maps	Web application (server) for sharing geo-data
QFieldSync	Mergin Maps QGIS plugin	QGIS Plugin for sync and manipulation of projects
QFieldCloud SDK and CLI	Python client (opens new window)	Interaction with REST API via Python or console

QFieldCloud is based on PostgreSQL and PostGIS database and there might be direct connection to these. Mergin Maps is fully based on a file-based system, so it is not possible to connect directly to a PostGIS database. However, you can use the DB Sync tool to map your Mergin Maps project to a PostGIS database schema or vice versa.

On top of Python client (opens new window), Mergin Maps offers also other developer tools to manage projects for larger teams, such as Media Sync and Work Packages.

You can also customise Mergin Maps mobile app and deploy your own Mergin Maps servers as the Mergin Maps Community Edition or Mergin Maps Enterprise Edition.

Users, organisations, workspaces

There are some similarities and differences in how QField and Mergin Maps manage their users and projects:

• a user is a key management unit in both platforms. Each user needs to have an account.
• a project is basically the same concept in both platforms (a .qgz file with associated files)
• organisations in QFieldCloud are similar to workspaces in Mergin Maps
• project collaborators in QFieldCloud are workspace members or guests that have access to a project in Mergin Maps
• organisation members in QFieldCloud are workspace members in Mergin Maps

Before we start

Before the start of migration, you need to have a Mergin Maps account and a workspace to manage your projects. If you are already registered, feel free to skip these steps.

• Sign up to Mergin Maps to create a Mergin Maps account and a workspace
• Install QGIS and Mergin Maps QGIS plugin
• Install Mergin Maps mobile app

We also recommend going through the Get Started tutorial to get familiar with Mergin Maps.

Migrate QField project to Mergin Maps

Both platforms are using QGIS Projects (.qgz files) and associated online or offline geo-data sources.

Therefore, if you open the project in QGIS on your desktop, you will be able to upload it to Mergin Maps.

Transfer QField project to the desktop

If you use a USB cable for synchronisation of your data, use your common workflow to transfer the project to your computer, e.g. by using the Send compressed folder to option in QField to send the compressed project to your email.

If you use QFieldCloud, use QFieldSync to synchronise the latest changes.

Convert QField project to QGIS project

Now that you have your QField project on your computer, you need to convert it to a regular QGIS project. Mergin Maps doesn't use offline editing, nor connections to QFieldCloud PostGIS databases, so we need to remove those.

1. Close QGIS

2. Find the project folder location on your computer (e.g. C:\GIS\QField_MyProject) and create a copy in a new location (e.g. C:\GIS\MyProject)

   • this folder should contain a single QGIS project file (.qgz or .qgs), local data files (such as GeoPackages .GPKG, Shapefiles .SHP or rasters) and other necessary files (such as photos .jpg or .png).
   • remove all hidden files and all files that are not strictly required by a regular plain QGIS project (such as QField configuration files, backups of the layers or offline synchronisation logs).

   TIP

   Depending on your project, it might be easier to just copy the QGIS project file (.qgz or .qgs) and other required data sources to the new folder one by one.

3. Open the project from the new folder (e.g. C:\GIS\MyProject) in QGIS.

   For each layer, check its properties and verify that the sources do not point to any QFieldCloud databases.

   Some layers in the project may appear unavailable. Make sure they were copied to the folder or fix their data source.

4. If you made changes, save the project and close QGIS.

   Then, reopen the project in QGIS again to make sure that the project loads correctly.

TIP

Some Mergin Maps specific settings can be set up in the project, such as selective sync, default photo quality or custom photo names. Go to QGIS Project Preparation for inspiration.

Upload QGIS project to Mergin Maps

1. Use Mergin Maps QGIS plugin to package and upload the project to Mergin Maps as explained here
2. Log in to app.merginmaps.com to see that the project was successfully uploaded to the cloud
3. Open the project on Mergin Maps mobile app and check your project, especially feature forms and all the layers.

Migrate QFieldCloud Settings

Organisations and permissions

There is no automatic tool to extract your QFieldCloud organisations and users and migrate them to Mergin Maps.

Therefore, you will have to manually set up workspaces (if needed) and assign appropriate permissions to your team members in Mergin Maps.

For a smooth transition, it is best to read about working collaboratively in Mergin Maps.

Billing, subscriptions and plans

In Mergin Maps, each workspace has its own subscription. Read more about Mergin Maps subscription here.

• If you own Organisation plan in QFieldCloud, you will likely need Mergin Maps Professional or Team subscription.
• If you own Pro plan in QFieldCloud, you will likely need Mergin Maps Individual or Professional subscription.
• If you are Community plan in QFieldCloud, you will likely need Mergin Maps Individual subscription or deploy your own Mergin Maps Community Edition (Mergin Maps CE)

While QFieldCloud has a per-seat model, the Mergin Maps Team subscription has unlimited number of members.

Known differences between QField and Mergin Maps platforms

Here are some key differences between QField and Mergin Maps.

• Mergin Maps mobile app is fully devoted to providing a no-training mobile application, operated even for users without any prior GIS knowledge. QField interface and workflows for various tools more resembles complex GIS applications like QGIS.

  Therefore Mergin Maps mobile app is more intuitive for non-technical users, still keeping all tools for advanced workflows.

• synchronisation in Mergin Maps is conceptually based on ideas from Git. Geodiff (opens new window) creates difference files from GeoPackages that are sent over the network and applied. QFieldCloud synchronisation uses a concept of storage of differences made in SQL format and this difference log is then transmitted and applied.
  In Mergin Maps, synchronisation is an inherent part of the platform. As such, it is already set up for end-users in a smart way and there are no extra steps needed for mobile users. All synchronisation on mobile devices is done by hitting a single button.

Here is a non-definitive list of other known differences:

• QField mobile app can work without QFieldCloud (server) via USB transfer of the projects. This is not available in Mergin Maps, but you can manually download your data or upload large files to your mobile device if needed.
• Organisation teams in QFieldCloud do not have any equivalent concept in Mergin Maps. On Mergin Maps can have different workspaces for different teams.
• There is no concept of secrets in Mergin Maps. For pg_service configuration, you need to transfer it manually as described here.
• There is no concept of managing ongoing jobs or triggers in Mergin Maps accessible for users. Users see the results when jobs are finished (e.g. map rendering).
• It is not possible to connect directly to user accessible databases in Mergin Maps. Use DB Sync to map your Mergin Maps to PostGIS database schema.
• QField is built around modes. There is not such concept in Mergin Maps
• You can use the preview panel in Mergin Maps mobile app

If there is a feature missing in the Mergin Maps mobile app, check our wishlist.

Troubleshoot

Struggling to migrate your projects? We are happy to help you!

Book a short video call with our sales team or write your technical questions to our support team. You can also chat with our open-source community.

Join our community chat and ask questions!

If you are looking for a professional partner to migrate your workflow, you can ask our partners network or Lutra Consulting Ltd., the developers of Mergin Maps

Credits

QField, QFieldCloud and QFieldSync are developed by OPENGIS.ch. QField is EUIPO registered trademark 2363703 owned by OPENGIS.ch. QField is released under the GNU Public License (GPL) Version 2 or above.