Migrating Data from v3 to v4¶
Upgrading your Arches installation is a complex process, as a significant backend redesign was implemented in v4. We have developed the following documentation (and the code to support it) to guide you through the process. You will be performing a combination of shell commands and basic file manipulation.
Before migrating data, you’ll need to install Arches 4 and make a new project. You can name your project whatever you want, but throughout this documentation we’ll refer to it as
my_project. You can customize the templates and images in your project any time (before or after migrating the data). We recommend adding a Mapbox key right away so you can use the map for visual checks during the migration.
Before moving on, you must be able to run the Django devserver from your v4 project, and view it in a browser at http://localhost:8000.
Once you are ready, you can begin the migration process. The overall form of the process goes like this:
- Export data from existing v3 Arches installation
- Create a v4 package (Arches-HIP users: this is already done for you)
- Place the v3 data into the Package directories
- Run commands to convert the v3 data to v4 data
- Load the package into any v4 project
We have further documented this workflow with two step-by-step guides: one for v3 users who are using Arches-HIP, and one for those who have created custom packages. You’ll find these guides below.
Exporting Your Data From v3¶
Before migrating to v4, you must export all of your data from v3. Before you begin, however, you’ll need to install some enhanced commands into your v3 app. This is a simple process:
- Download and unzip arches3-export-utils-master.zip (source)
- Copy the “management” directory into your v3 app alongside the
- In your v3 environment, run
python manage.py v3v4 --helpto make sure the new commands have been been installed.
Be sure to backup your v3 database before beginning the export process.
Now you are ready to begin exporting your data from v3. Follow these steps:
After you have all the v3 data exported, you are ready to follow the appropriate workflow for your deployment.
Migrating Your Data¶
The workflow you must use for the migration depends on the nature of your v3 deployment.
If your v3 deployment of Arches was based on Arches-HIP, and you did not modify any of the graphs (beyond perhaps changing node names) you can use the Arches-HIP Workflow. If you have changed the RDM content that’s fine, it will be preserved through the migration.
App With Custom Graphs¶
If you have a v3 deployment with custom resource graphs, you’ll need to use the following workflow. Be aware, you’ll need to remake your custom resource graphs in v4 (as “Resource Models”). This is listed as Step 6 below.
- Custom App Workflow
- 1. Create a new package
- 2. Prepare your package.
- 3. Move your exported v3 data into the package.
- 4. Move the v3 resource graph _nodes.csv files from v3 into your package.
- 5. Convert the v3 reference data.
- 6. Build the v4 Resource Models.
- 7. Generate and populate the node lookup files.
- 8. Convert the v3 JSON/JSONL business data
- 9. Write the v4 resource relations file.
- 10. Load the entire package (optional)