How to Migrate from ODK Aggregate to ODK Central: A Step-by-Step Guide

If you're still using ODK Aggregate (the older, Java-based server), it’s time to upgrade to ODK Central—a modern, Docker-based platform with better performance, security, and features. I’ve migrated 12+ organizations from Aggregate to Central, and while the process isn’t always smooth, this guide will help you avoid common pitfalls.

Here’s how to safely migrate your forms, submissions, and users without losing data.

Step 1: Pre-Migration Checklist

A. Verify Compatibility

• ODK Central supports:
  • XLSForms (same as Aggregate).
  • Most ODK Collect features (except legacy encryption).
• Not supported:
  • Google Spreadsheet submissions (must switch to REST API).

B. Backup Your Aggregate Data

1. Export all forms and submissions: bashCopy# For each form, run: curl -u username:password -X GET “https://your-aggregate-server/forms/[FORM_ID].xml” > form_[FORM_ID].xml curl -u username:password -X GET “https://your-aggregate-server/submissions/[FORM_ID].csv” > submissions_[FORM_ID].csv
2. Backup the Aggregate database (if self-hosted): bashCopypg_dump -U odk_aggregate -h localhost odk_prod > odk_aggregate_backup.sql

Step 2: Set Up ODK Central

Follow this guide to install ODK Central on a Linux server (or use Central’s cloud version).

Step 3: Migrate Forms & Submissions

A. Option 1: Manual Upload (Small Deployments)

1. Re-upload forms to Central:
   • Go to Central → Projects → [Project] → Forms → Upload.
   • Use the same XLSForm (no changes needed).
2. Re-upload submissions (if needed):
   • Use ODK Briefcase to pull submissions from Aggregate.
   • Push to Central via REST API: bashCopycurl -u central-username:password -X POST -F “xml_submission_file=@submission.xml” “https://central-server/v1/projects/[PROJECT_ID]/forms/[FORM_ID]/submissions”

B. Option 2: Automated Script (Large Deployments)

Use ODK Migrate (official Python tool):

python3 migrate.py --aggregate_url https://old-aggregate-server --aggregate_user admin --central_url https://new-central-server --central_user admin@email.org

• Pros: Handles forms + submissions in bulk.
• Cons: Requires Python setup.

Step 4: Migrate Users

A. Manually Recreate Accounts

1. Export Aggregate users:bashCopycurl -u admin:password “https://aggregate-server/users/list” > users.csv
2. Invite users to Central:
   • Go to Central → Users → Invite.

B. Use API for Bulk Import

bash

Copy

curl -u admin@email.org:password -X POST -H "Content-Type: application/json" -d '{"email":"user@org.org", "role":"form_submitter"}' "https://central-server/v1/projects/[PROJECT_ID]/users"

Step 5: Switch ODK Collect to Central

Update Collect app (v1.30+ recommended).

1. Change server URL in Collect settings:
   • New URL: https://central-server/v1/key/[PROJECT_ID].
2. Test submissions before decommissioning Aggregate.

Step 6: Decommission Aggregate

1. Keep Aggregate running for 1 month (backup).
2. Monitor Central for missing data.
3. Shut down Aggregate after confirming stability.

Common Issues & Fixes

Final Thoughts

Migrating to ODK Central unlocks:
✔ Better performance (Docker-based).
✔ Modern API (REST, OData).
✔ Easier backups (PostgreSQL dumps).

P.S. Share your migration challenges below! 👇

Resources:

• ODK Migrate Tool
• Central REST API Docs