How to upgrade a project from version 2 to version 3

[TonyFMCMC]

Can anyone please advise as to a process for upgrading projects from version 2 to version 3?

[TonyFMCMC]

So far, with no published guidance that I could find, and through trial and error:

1. Rename your old Roam installation folder [edit: Not needed; v2 installs to c:\Intramaps Roam and v3 to c:\Roam]
2. Install Intramaps Roam version 3 (currently 3.0.6) from the source on github (https://github.com/roam-qgis/Roam/releases)
3. Install QGIS 3.10 using https://download.qgis.org/downloads/QGIS-OSGeo4W-3.10.14-1-Setup-x86_64.exe (the latest version 3.10 release). (Roam 3.0.6 requires "c:\Program Files\QGIS 3.10" or "C:\Program Files (x86)" in the installation path... Maybe there is a workaround for this but I didn't find it. Best I can think of is to install the latest LTR but specifying "c:\Program Files\QGIS 3.10" as the directory for the installation, but I didn't try this) .
4. Copy your Roam 2 projects directory contents into the Roam 3 projects directory.
5. If you had a custom shared files directory in Roam2 as I did, move the files into the projects/_data directory, and update their locations in the project.qgs file using a text editor. This allows you to manage these files using the data tab on the left in Roam Config Manager 3.
6. Open the new Roam Config Manager. The old projects should appear (but annotated with "Requires upgrade")
7. For each project click on the project, open the project in QGIS (using the button at the top right of Roam) and save the project (to update the project.qgs file to version 3), then upgrade the project to Roam v 3 using the Upgrade Project button at the top right of Roam.
8. Click on the map menu item under the project in Config Manager, and scroll down to the bottom of the right hand column to check that all files have loaded.
9. At the moment I am stuck because the Azure sql databases I linked to in Roam 2 are not loading in Config Manager when I click on Map. Its funny because they load fine in QGIS.

[TonyFMCMC]

Continuing:

9. SQL was failing because I had tried to manually set up an environment variable QGIS_PREFIX_PATH=c:\Program Files\QGIS 3.22.5 when I was trying to use the latest LTR. Removing this allowed config manager to load a heap more providers, including MSSQL spatial data provider, and to open my Azure SQL geographic tables.

[TonyFMCMC]

Note that the format of the Roam.txt file on the roam server has changed, with an extra line ("id={project_id}") under each project. I'm not clear whether this would upset Roam; there is no feedback that Roam can't find the roam project server or that there is an error in the Roam.txt file. I considered it prudent to delete the version 2 Roam.txt file and the version 2 project files, and have Config Manager v3 upload new ones. Note that in Roam settings the project server needs to be set to the url of the folder containing the Roam.txt file and the projects folder. It must include the "http://" prefix.

Thinking about it now, because the old project server was defunct I established a new project server for Roam 3; and I think for others it would be wise to at least set up a different folder in your web server for Roam 3 projects, so that when installing Roam 3 on your clients (which might not happen all at once) there is no confusion between Roam 3 project files and Roam 2 project files. Leave the new folder empty for Config Manager v3 to populate [I initially copied the old project folder and Roam.txt files across to the v3 project server, but then ended up deleting them so Config Manager v3 could populate it with the correct format.]

[TonyFMCMC]

Another little tidbit. In Roam 2 to get something under the Sync heading (in my case a .bat file to download copies of sql data to a local gpkg file (faster)) you had to manually add a section on a new line in the project.config file after project_version called providers: e.g.:

providers:
  Download SQL data (requires MCMC vpn):
    cmd: sync_data.bat
    type: replication
    variables:
      LOCALDATABASE: Roam

I had several entries under providers. But the new functionality in Roam 3 of having the c:\Roam\projects_data directory, and the facility to update this in Roam meant I no longer needed them. I fell into the trap of deleting the subsections under providers, but not deleting the providers heading. As a result Roam crashed with a message in [user]_roam.log file as follows:
ERROR - 2022-05-23 15:25:50,548 - environ-excepthook:79 - Uncaught exception Traceback (most recent call last): File "C:\Users\Nathan\dev\Roam\ext_libs\cx_Freeze\initscripts\__startup__.py", line 40, in run File "C:\Users\Nathan\dev\Roam\ext_libs\cx_Freeze\initscripts\Console.py", line 23, in run File "src\roam\__main__.py", line 73, in <module> File "C:\Users\Nathan\dev\Roam\src\roam\mainwindow.py", line 503, in load_projects File "C:\Users\Nathan\dev\Roam\src\roam\syncwidget.py", line 47, in loadprojects File "C:\Users\Nathan\dev\Roam\src\roam\project.py", line 341, in syncprovders AttributeError: 'NoneType' object has no attribute 'items'
LESSON: Don't leave the providers: section with nothing under it. Not even 'null' or '[]'.