Decidim migration from participation platforms

What a Decidim migration involves

A Decidim migration starts from one of two triggers. The first is moving participants, proposals, comments, votes and process history from another engagement platform into Decidim. The second is moving an existing Decidim instance to new hosting or infrastructure, which is mostly a database, file storage and configuration exercise. The two need different plans, so confirm early which one you are doing, or whether both are happening in the same window.

Three things must survive either move: user accounts, public permalinks and the record of who said what. Accounts matter because participants expect to log in with the credentials or social login they already use, and because verified status may depend on them. Permalinks matter because links to proposals and processes are already cited in press, council papers and social posts. The record of authorship matters because votes, comments and proposal authorship are public accountability records. Ask who owns the decision on how each of these is preserved and who signs off on the result.

The content model differs between source and target, and that gap drives most of the work. A proposal in one platform may carry a status, category, supports and a voting result that have no direct equivalent in Decidim's spaces and components. Votes may be recorded differently, comments may be threaded differently, and user identifiers rarely match. Build a field-by-field mapping from the source export before any import script is written, and agree in writing how each unmapped field will be handled, archived or dropped.

What the work includes

The work runs as six packages in sequence, with reconciliation evidence gathered before cutover. The engagement ends with a mapping specification, import scripts, reconciliation reports, and runbook and handover documentation.

Source inventory and data mapping

List every space, component, user record, proposal, comment, vote and attachment in the source platform, with its volume, owner and status. Map each item to a Decidim space (process, assembly or initiative), component and user type, and record those decisions in a mapping specification. Confirm which source fields have no Decidim equivalent before any import code is written.

Account and identity migration

Accounts determine whether participants can sign in after cutover. Check how the source stores passwords, since existing hashes may not transfer without the original algorithm and parameters. Decide which users reset passwords, which keep social or external login, and how Decidim's OmniAuth providers and verification records link to migrated accounts.

Import tooling, test loads and attachments

Import scripts run first against a non-production copy of the target instance, using representative extracts and then full-volume test loads. Each run should be repeatable from a clean database and log every rejected record. Attachments need a separate transfer path, with checksums compared between source and target before cutover.

Redirects, cutover and rollback

Map every old public URL for processes, proposals and pages to its new Decidim address, and test the redirects before DNS changes. Decidim v0.32.0 introduced locale-prefixed URLs, so redirect rules must match the release being deployed. Define the cutover sequence, the write freeze window and a rollback point that restores the source platform.

Reconciliation and post-migration verification

Reconciliation reports compare record counts, relationships and status values between source and target for each space, component and user group, and list every exception with its reason. Post-migration checks confirm that public pages load, sign-in works for each login method and attachments open. Sign-off should be recorded against these reports, not against a verbal confirmation.

Moving an existing Decidim instance

For an instance already running Decidim, the work covers a database dump and restore, transfer of the file storage used by ActiveStorage, and environment configuration for mail, background jobs, maps and social login. Align the Decidim, Ruby and Node versions on both sides before the restore. Upgrades move one minor version at a time, with the database backed up first.

What drives cost and duration

The table lists the factors that change the effort of a Decidim migration, why each one matters, and what to do to keep it under control before a quote is written.

Driver	Why it matters	How to reduce it
Number of accounts and identity linking	Each account must be mapped to a Decidim user, and participants who voted or commented under one identity need that link preserved. Matching by email alone often leaves duplicates or orphaned activity.	Export a clean user list with verified emails and a stable external ID. Decide early which duplicates to merge and who approves those decisions.
Volume and format of proposals, comments and votes	Record counts drive import time, validation work and the number of exceptions to review. Proposals with rich text or unusual status values need mapping rules, not just bulk loading.	Export proposals as structured data with clear status fields. Archive or exclude records that are out of scope and agree that list in writing.
Attachments and storage size	Files must be copied, checked and re-linked to their records. Large or missing files extend transfer time and create broken links on public pages.	Inventory attachments by size and type before the build. Confirm whether the source keeps original files and whether checksums are available.
Number of spaces and components needing a target	Each process, assembly or initiative and each component type (for example proposals, meetings or surveys) needs a target in Decidim. Components without a match require configuration or a decision to drop them.	Map every source space and feature to a Decidim equivalent in a short table. Mark gaps and get sign-off on each one.
Process history depth	Versions, state changes and timestamps are costly to reproduce. Whether they are kept as history or flattened into a current state changes both the mapping and the review effort.	Decide what history must remain visible to the public. Request a limited export of versions and state changes for the records that need it.
Languages and translated content	Each language adds content to map, check and proofread. Machine-translated fields from the source may not match Decidim's locale structure.	List languages per space and content type. Confirm which translations are authoritative and which can be left in the original language.
Custom fields or components with no direct equivalent	Source-specific fields, voting rules or workflows may need custom Decidim modules or a documented loss of data. Custom work is often the largest single variable.	Find these items during discovery. Decide per item whether to rebuild, store as static content, or retire it, and record the decision.
Integrations that feed or read the platform	Connected tools such as CRMs, email lists, data feeds or reporting jobs must be re-pointed or rebuilt. Each one adds design, testing and cutover steps.	List every integration with its direction, owner and data format. Confirm which ones must run on day one and which can wait.
Public URL redirect requirements	Links from other sites, emails and archives break if old addresses are not redirected. Redirect coverage is checked URL by URL for high-traffic pages.	Export the source URL list with traffic data where available. Agree on a redirect scope, such as top pages only or every record.
Whether the source can export complete data	Incomplete or proprietary exports force screen scraping, manual re-entry or direct database access. Each workaround adds time and risk to the migration.	Ask the current vendor for a full export in a documented format before scoping. Test the export on a copy and check record counts against the live system.

How the project runs

The sequence moves data from the source platform into a tested Decidim instance in stages, so each cutover decision rests on reconciled records and signed-off mappings.

Audit the source platform and data
We inventory the source platform's participants, accounts, proposals, comments, votes, attachments, process history and public URLs, and identify what needs to be kept, archived or dropped. The output is a source audit report listing data volumes, export methods, known data quality issues and the public records that must keep resolving after the move.
Agree the mapping specification
We write a field-by-field mapping from each source object to its Decidim equivalent, covering spaces, components, statuses, authors, identifiers and locales. Content owners review and approve it in writing. The output is a signed mapping specification that lists every transformation rule and each decision that content owners made about records that do not map cleanly.
Build the target environment
We build the Decidim instance on the supported release line, with Ruby, Node and PostgreSQL versions taken from the installation documentation for that release, and configure background jobs, file storage, SMTP and social login as the target design requires. The output is a documented environment that passes a clean install and a smoke test, with versions recorded in the handover pack.
Run trial imports on copies of real data
We run the import scripts repeatedly against copies of the source data, never the live system, and log every rejected or altered record. Each trial produces an import log and an exception list that content owners review. The step closes when trial runs produce stable results and the exception list has a documented owner and decision for each item.
Reconcile counts and sign off
We compare record counts, identifiers, attachments, timestamps and sampled content between source and target, and check that accounts and public links resolve as the mapping specification requires. The output is a reconciliation report with the differences explained, followed by written sign-off from the named content and business owners.
Rehearse the cutover
We run the full cutover sequence on a staging copy, timing each step against the freeze window agreed in the written scope, and record every deviation with its fix. The output is a dress rehearsal log and a final runbook with named owners, rollback points and go or no-go criteria for the live event.
Cut over live and monitor hypercare
During the agreed freeze window we make the source read-only, run the final import, run the reconciliation checks again and switch public traffic. Afterward we monitor errors, account issues and redirect behavior through the hypercare period set in the scope, and close with a redirect check report and handover of operations documentation.

What to keep in-house and what to outsource

This table compares each migration work area by who usually does it, which skills it needs, and where the organization must keep decision rights even when a partner does the engineering.

Work area	Usually kept in-house	Usually outsourced	Skills required
Data ownership and mapping decisions	Deciding which records are public, which are restricted, how proposals and votes are presented, and which legacy fields map to which Decidim components	Drafting the field-by-field mapping document and listing the options each source field can take	Public administration policy, records management, and familiarity with the source platform's data model
Legal review of accounts and personal data	Approving the lawful basis for moving accounts, email addresses and participant content, and signing off the transfer plan	Preparing data inventories, flagging personal fields and documenting how transferred data is minimized	Data protection law, records retention rules, and data processing agreement terms
Source system export	Granting access to the old platform, confirming export scope and approving the extract	Writing export scripts or API crawlers, running test extracts and producing checksums and row counts	Knowledge of the source platform's API or database, plus scripting in a language the team can support
Import engineering	Reviewing sample imported records and signing off mapping exceptions	Building the importer into Decidim components, handling attachments, author links and process history, and running rehearsal loads	Ruby on Rails, Decidim module development, and experience with large idempotent data loads
PostgreSQL and Rails operations	Owning the production database, backup policy and change approvals for the target environment	Tuning the import, running migrations, configuring ActiveJob and ActiveStorage, and rehearsing restores	PostgreSQL administration, Rails deployment, and backup and restore testing
Redirect and DNS work	Approving old-to-new URL mapping, the domain cutover date and the retirement plan for the old site	Building redirect rules, preparing DNS changes and testing that old links resolve to the matching Decidim pages	Web server and DNS administration, with a clear view of how search engines and bookmarked links are used
Content verification by staff	Checking that processes, proposals, comments and results read correctly, and signing off each phase	Providing sampling scripts and a defect log so staff can compare source and target records quickly	Editorial knowledge of the participatory process and the language versions the site publishes
Post-cutover monitoring	Watching participant reports, moderation queues and public communications during the first weeks	Watching error logs, job queues, email delivery and performance, then fixing defects found	Application monitoring, log analysis, and Decidim incident handling under the security patch grace periods

What usually goes wrong

Most Decidim migrations fail in the same few places, and most of those failures are visible only after cutover. Each card below names a failure point and the check that would have caught it before users did.

Accounts without a working login path

Users are imported, but none can sign in because password hashes did not carry over or the login method changed. Test a sample of accounts from each source group (admins, moderators, citizens with social logins) against the staging instance before any user receives a notice. Confirm which login methods each account needs, such as email and password, Decidim's OAuth login, or a configured social provider.

Duplicate users for one person

The same participant appears as two accounts when email case, whitespace or a changed address does not match during import. Duplicates split proposal support, notifications and authorship history. Run a matching report on normalized email addresses before import, and have a content owner review the flagged pairs and decide which account survives.

Proposal authorship and status lost

Proposals arrive with the wrong author, with no author at all, or with a status that does not map to Decidim's workflow. Officials then see records that differ from what the public saw. Build an explicit status mapping table with the program owner, and reconcile a set of proposals per status and per author against the source export.

Comments detached from proposals

Comment threads import as orphaned records, or attach to the wrong resource after identifiers change. Readers then see proposals with no discussion, which removes the context that justified decisions. Compare comment counts per proposal between source and target, and open a sample of long threads to confirm order, replies and authors.

Broken public links

Citizens, journalists and search engines already link to old proposal and process URLs, and Decidim's URL structure will differ from the source platform. Without redirects, those links return errors and the public record appears removed. Map every legacy URL pattern to its new route, add redirects, and check a sample of indexed URLs after launch.

Attachments missing or renamed

Files fail to download, arrive without their original names, or are attached to the wrong record. Documents that support a decision then become unavailable. Compare file counts and checksums between the source storage and Decidim's file storage, and open a sample of attachments from several processes to confirm they download and display correctly.

Timestamps shifted by time zone

Publication, closing and voting dates move by hours when a source system stores local time and the import treats it as UTC, or the reverse. Deadlines then appear to have passed early or late, which matters for consultations with fixed close dates. Set the time zone assumption in writing before import, and check the dates of closing events against the source record.

Personal data in unapproved environments

Production exports containing names, emails and proposal content are copied to developer laptops, shared drives or test servers that lack the approved controls. This can create a breach that is harder to explain than the migration itself. Agree in advance which environments may hold personal data, mask data in lower environments, and record where every copy was made and deleted.

Incomplete source exports

The export omits hidden or archived processes, deleted-but-retained records, votes, or attachments beyond a size limit, and nobody notices until the source is switched off. Ask the source vendor or administrator for a documented list of exported entities, and reconcile record counts by type against the source database or API before accepting the export as complete.

Cutover without a tested rollback

The migration runs once on the day of launch, and the team has no proven way back if counts, logins or links fail. Rehearse the full cutover on a production-sized copy of the data, time each step, and write down the rollback trigger and the steps to restore the source. Keep the source platform read-only and available until the agreed acceptance checks pass.

How the work changes by starting point

Commercial engagement platforms often offer partial exports, so the first task is finding out what the vendor will release before the scope is fixed. The work leans toward reconstruction and reconciliation.

Scope: Inventory every process, proposal, comment and participant record the platform holds, then map each one to a Decidim space or component. Some history may need to be rebuilt as static records.
Export path: Confirm in writing which formats, fields and attachments the vendor will supply, and whether account data can leave the platform at all.
Risks: Authorship, dates, vote or support counts and status history can be lost, and participant accounts may need password resets or new sign-up.
Verification: Reconcile record counts per space against the source, spot-check a sample of proposals for author, date and status, and confirm that attachments open.

What you need to provide

The migration moves participants, proposals and process history, so the work depends on decisions only your organization can make. Name one accountable owner each for accounts, content and public records, and give them authority to approve what goes live. Without named owners, mapping questions sit unanswered and cutover slips.

Provide access to the source platform with export rights sufficient for a full extract, plus a sample export early in the project. The sample lets the team test how users, proposals, comments, attachments and vote or support counts map into Decidim spaces and components before any production data moves. Decide which historical records stay public on the new site, which are archived read-only, and which are not carried over. Those choices shape the mapping more than any technical setting.

Agree a sign-off process for the field mapping and again for cutover, with named approvers and a deadline for each. Confirm who owns the target environment and who grants access to the hosting account, databases and mail relay. Also agree a freeze window with participating teams, during which no new proposals or edits are made on the source platform. Confirm its length with those teams, since the duration depends on your own volumes and approvals.

Arrange a legal or data protection review before personal data is transferred. Your organization decides the lawful basis for moving participant accounts and messages, and the migration team cannot make that determination for you. Also decide on translation and language handling, including which languages must be migrated and who reviews translated titles and descriptions. Confirm these inputs in writing at the start, because they change the mapping and the test plan.

Frequently asked questions

Can a Decidim migration run in stages, and what sets the schedule?

Yes. A migration can run in stages, for example moving accounts and closed historical processes first, then live processes and proposal activity at a later cutover. The schedule depends on the volume and quality of the source data, how many spaces and components must map, how many accounts and attachments move, and how many review rounds your staff need for sign-off. Test imports on a staging copy and plan a freeze window for the final run. Ask for the schedule broken into phases tied to these drivers.

What does a Decidim migration cost, and what should a quote include?

The cost follows the written scope, and DeployOpen does not publish a price list. The main components are discovery and data inventory, export and transformation work, mapping of spaces and components, account handling, test and final import runs, redirect planning, verification and cutover support. Hosting is an ongoing cost paid to your provider or your own team. Ask each quote to separate one-time work from recurring items such as hosting, upgrades and support retainers, and to list what you provide: source exports, access to the old platform and named sign-off owners. Compare quotes against the same assumptions.

Can our own team migrate to Decidim without a partner?

Yes, for small datasets, provided the team has strong Ruby on Rails and PostgreSQL skills and time to learn Decidim's data model. The team must write and test import scripts, handle file attachments and identity records, build a rollback plan and rehearse the cutover on a staging copy. Staff also need time for mapping decisions, content review and verification, usually from a product owner and a data owner. Errors in accounts or public records are visible and hard to reverse. Larger histories, several languages or tight deadlines typically justify a fixed-scope engagement, so assess your skills honestly first.

Can users keep their existing passwords and logins after migration?

They can sometimes move unchanged, but this is not guaranteed and depends on the source platform. Carrying over password hashes requires an export in a format Decidim can verify, with a compatible algorithm and parameters. If that is not available, the options include a forced reset at first login, a single sign-on bridge or a claim-your-account step. Each option affects user friction, security exposure during the transition and support volume. Confirm the hash format and the chosen method in writing before the scope is signed, and check how verified identity records will carry over.

How are public links kept working, and what happens to unmappable records?

The plan maps each old public address to its new Decidim address with permanent redirects. The map is built from a full inventory of process, proposal and comment URLs and tested before cutover. Decidim URL structures change between releases, including locale-prefixed URLs introduced in v0.32.0, so redirect rules must match the target version. Records that cannot map one-to-one, such as merged or deleted items, need agreed rules: an archive page, a redirect to the parent space or a documented exception list. Decide these rules with your records owner before the import runs, and keep the mapping log as evidence.

Does DeployOpen issue an audit report or certification for a migration?

No. DeployOpen does not issue audit reports, attestations or certifications. As part of a migration, it can prepare systems, controls and evidence, such as migration logs, access configuration and reconciliation reports, for review by an independent auditor or certification body. Ask which evidence the scope includes, who retains it and how your assessor will use it. Confirm the requirements with your assessor before work starts.

How DeployOpen delivers this service

DeployOpen scopes the migration in writing before work starts, then moves participants, proposals and process history into Decidim on infrastructure your organization controls, with accounts and public records checked at each stage. Engagements are fixed-scope, and ongoing support is available as a retainer.

How we scope

The written scope lists each source platform, the data types to move, and the Decidim spaces and components that will receive them.
We agree which participant accounts, proposal histories and public records must keep their identifiers, dates and URLs after the move.
Hosting, the Decidim version, and any identity or verification rules are confirmed in the scope before the migration plan is written.

How we build

We map source fields to Decidim models, then run test imports on a staging copy and review mismatches with your team.
Account migration is tested with sample users, including password reset paths, login providers and verification status.
Cutover is planned with a database backup taken first, a rollback point, and a checked list of redirects for old public links.

How we hand over

You receive the field mapping, import scripts, test results and a record of any data that could not be moved and why.
Runbooks cover the migration steps, the Decidim update path, backup and restore, and who approves each stage.
Your administrators are walked through the migrated spaces, moderation tools and the content checks they should repeat after launch.

How we support

Post-launch support can be agreed as a retainer covering fixes to imported content, monitoring and security patches.
Decidim releases on its supported minor branches are applied one minor version at a time, following each release's upgrade instructions.
Before any future version change, we confirm the database backup and rollback plan with your team and check the current security advisories.