Alfresco → PowerFolder Migration

Technical reference for migrating Alfresco content into PowerFolder using the built-in CMIS migration tool.

Overview

The migration system connects to Alfresco over two protocols simultaneously:

Apache Chemistry OpenCMIS (CMIS 1.1 browser binding) — for the folder and file tree
Alfresco REST API v1 — for user accounts, group memberships, site roles, and tags (not available via CMIS)

The migration runs in four sequential phases per site. Multiple sites process in parallel, capped by a configurable thread limit.

Quick Start

Set the three required parameters — add cmis.url, cmis.username, and cmis.password to the
Open the Migration Dashboard — navigate to the internal admin panel and open the Alfresco Migration section.
Run analysis — click Initiate Analysis. The scan reads all Alfresco sites, users, groups, and tags in parallel (up to 15 concurrent threads). Large repositories may take several minutes.
Select sites and migrate — once analysis completes, select one or more sites and click Migrate Selected, or use Migrate All.
Send notification emails — after migration, click Send Migration Emails to notify migrated users.

Note: Analysis must complete successfully before migration can begin. The analysis report is the sole source of truth for all site and user data used during migration.

Migration Dashboard

Login as server admin and navigate to “Migration”

On the migration dashboard the data of the host system and source system is avaialble

Different actions are available on the dashboard

For reporting please use the drop-down menu

Architecture

Migration Phases

Each site runs through four phases in sequence. If a phase fails, subsequent phases for that site are automatically skipped and the site is marked Failed.

Phase	Name	Description

Phase	Name	Description
01	Structure	Recreates the Alfresco site's folder hierarchy in PowerFolder using the document library tree. When `cmis.migration.structure_via_search` is enabled, the entire tree is fetched in a single bulk search request.
02	Accounts	Creates or maps PowerFolder user accounts for all Alfresco site members. Existing accounts with matching identifiers are reused.
03	Groups	Migrates Alfresco group memberships and role assignments. Nested group hierarchies are resolved recursively.
04	Files	Downloads file content and metadata using up to 32 parallel workers shared across all in-flight sites.

Analysis Steps

Before any migration can start, the analysis pass builds a complete inventory of the Alfresco repository. These steps execute in order:

Repository info — connects over CMIS and reads the repository name, product name/version, and supported CMIS version.
Sites (parallel) — fetches all sites then scans each concurrently (up to 15 threads). Per site: member list, role-based groups (recursive), folder count, document count, tag count, and total data volume. Sites with fetch failures are automatically retried once.
Users & home folders — retrieves the full user directory, then scans each user's home folder for document and folder counts in parallel.
Groups — fetches all user-defined groups from the APP.DEFAULT zone. System groups are excluded: GROUP_ALFRESCO_*, GROUP_EMAIL_*, GROUP_EVERYONE, GROUP_SITE_ADMINISTRATORS.
Tags — retrieves all tag definitions and resolves usage counts via a single faceted search query (=cm:taggable:* with a TAG facet field).

Alfresco Roles Mapped

These four site roles are recognized and mapped to PowerFolder permissions during the Accounts and Groups phases:

SiteManager
SiteCollaborator
SiteContributor
SiteConsumer

Configuration Reference

All parameters are set in the server configuration file as key = value pairs. The three connection parameters are required; all others have working defaults.

Connection Parameters

Parameter	Default	Type	Description

Parameter	Default	Type	Description
`cmis.url`	(empty)	Required	Base URL of the Alfresco server. The CMIS browser path is appended automatically if not present: `/alfresco/api/-default-/public/cmis/versions/1.1/browser`. Example: `https://alfresco.company.com`
`cmis.username`	(empty)	Required	Username for CMIS and REST API authentication. Must have read access to all sites and the full user directory. An admin or dedicated migration service account is recommended.
`cmis.password`	(empty)	Required	Password for the configured username.
`cmis.binding`	`browser`	String	CMIS transport binding. `browser` uses JSON over HTTP (recommended). `atompub` uses XML — use only for Alfresco 4.x or earlier.

Automation Parameters

Parameter	Default	Type	Description

Parameter	Default	Type	Description
`cmis.auto_analysis.enabled`	`false`	Boolean	When `true`, the server automatically runs a full analysis once per day at the configured hour. A server restart is required to change the schedule.
`cmis.auto_analysis.hour`	`4`	Integer (0–23)	Hour of day (24-hour clock, server local time) for the nightly analysis run. Has no effect when auto-analysis is disabled.

Migration Behavior Parameters

Parameter	Default	Type	Description

Parameter	Default	Type	Description
`cmis.migration.owner.oid`	(empty)	String	OID of the PowerFolder user who will be set as owner of all migrated site folders. If empty, migrated folders have no assigned owner.
`cmis.migration.old_versions`	`true`	Boolean	When `true`, previous file versions are transferred alongside the current version. Set to `false` to transfer only the latest version — reduces time and storage for repositories with deep version histories.

Performance Tuning Parameters

Parameter	Default	Type	Description

Parameter	Default	Type	Description
`cmis.migration.file_workers`	`32`	Integer	Maximum concurrent file downloads during the Files phase. This pool is shared across all sites in the same job. Increase on fast networks; decrease if the Alfresco server shows saturation.
`cmis.migration.account_workers`	`16`	Integer	Maximum concurrent workers for the Accounts phase. Shared across all sites in a single run.
`cmis.migration.structure_via_search`	`true`	Boolean	When `true`, the Structure phase fetches the entire folder subtree with a single paginated search query (`ANCESTOR + TYPE:cm:folder`) instead of one request per folder. Significantly faster for deep trees. Falls back to recursive listing on failure.
`cmis.migration.files_via_search`	`true`	Boolean	When `true`, the Files phase fetches the full file inventory via paginated `ANCESTOR` search queries and feeds results directly to download workers, bypassing the recursive per-folder walk. Falls back on failure.

JVM System Property

-Dpowerfolder.cmis.migration.threads=15

Controls the number of concurrent site threads during both analysis and migration orchestration. Default: 15. Increase with care — each thread holds an open connection to the Alfresco server.

Worker Concurrency Summary

Phase / Task	Parameter	Default	Scope

Phase / Task	Parameter	Default	Scope
Site analysis	`powerfolder.cmis.migration.threads`	15	Global
Migration orchestration	`powerfolder.cmis.migration.threads`	15	Global
File downloads (Files phase)	`cmis.migration.file_workers`	32	Per run
Account creation (Accounts phase)	`cmis.migration.account_workers`	16	Per run

API Reference

All migration actions go through a single endpoint. Both GET and POST are accepted; POST is preferred for state-changing actions.

GET / POST /wapi/cmis-migration?action={action}

Authentication: All requests require an active administrator session. The endpoint is inaccessible to non-admin users.

Action	Parameters	Description

Action	Parameters	Description
`analyze`	`cancel=true` (optional)	Start a new analysis run. Pass `cancel=true` to cancel an in-progress analysis. Returns immediately — poll `getAnalysisReport` for status.
`getAnalysisReport`	—	Returns the current analysis report. Fields: `status` (RUNNING / FINISHED / FAILED / CANCELLED), `progress` (0–100%), `currentStep`, `result` (sites, users, groups, tags, summary), `finished` timestamp, `durationMs`.
`retrySite`	`siteId` (required)	Re-fetches a single site's data and replaces its entry in the report. Use to recover from `people_fetch_failed` or `groups_fetch_failed` warnings without re-running the full analysis.
`migrateSites`	`siteIds=id1,id2,…` (optional)	Starts a full 4-phase migration run. Omit `siteIds` to migrate all sites. Returns `jobId` on success. Returns HTTP 409 if another run is already active.
`migrateAccounts`	—	Runs only the Accounts phase across all sites without touching site migration status. Use as a pre-migration step to create PowerFolder accounts ahead of the full run.
`getMigrationProgress`	—	Returns live progress. Fields: `running`, `siteIds`, `inFlight[]` (phase name + % complete per site), `recentlyCompleted[]`, `totals`, `phases` (per-phase counters including `bytes` transferred).
`cancelMigration`	—	Signals a graceful cancellation. In-flight sites finish their current phase before stopping. The run transitions to Paused state.
`deleteSites`	`siteIds=id1,id2,…` (required)	Destructive. Removes the migrated PowerFolder target folders for the specified sites, resetting them to Not Migrated. User accounts and groups are not affected.
`sendMigrationEmails`	—	Queues migration notification emails for all accounts that have been migrated but not yet notified. Returns `queued` count.
`getPendingMigrationEmailCount`	—	Returns `count` — migrated accounts not yet notified. The dashboard uses this to enable or disable the Send Emails button.

Migration Phases (Detail)

Phase 1 — Structure

Recreates the Alfresco site's folder hierarchy in PowerFolder. When cmis.migration.structure_via_search is enabled, the entire tree is fetched in a single bulk search request. The analysis scanner imposes a maximum folder tree depth of 50 levels.

Phase 2 — Accounts

Creates PowerFolder user accounts for all Alfresco site members. Existing accounts with matching identifiers are reused. This phase can also run independently via the migrateAccounts action as a pre-migration step without affecting site migration status.

Phase 3 — Groups

Migrates Alfresco group memberships for the four site role groups. Nested group hierarchies are resolved recursively. System groups are excluded from migration.

Phase 4 — Files

Downloads file content and metadata and writes it to the structure created in Phase 1. File versions are included when cmis.migration.old_versions is true. The live transfer rate shown in the dashboard is smoothed over a 30-second sliding window.

Site Status Values

Status	Meaning

Status	Meaning
`NOT_MIGRATED`	In the analysis report but not yet migrated.
`IN_PROGRESS`	Currently running — phase name and % complete shown live in the table.
`MIGRATED`	All four phases completed successfully.
`FAILED`	A phase failed. Check the error message on the site row. Reset via `deleteSites` to re-migrate.
`SKIPPED`	A preceding phase failed — this phase did not run.

Dashboard Guide

The Migration Dashboard is a complete operational view of the analysis and migration process.

Feature	Description

Feature	Description
Repository info bar	Connected Alfresco product name, version, CMIS version, and date/time the last analysis completed with its duration.
Summary stat cards	Seven cards showing totals: Sites, Users, Groups, Folders, Documents, Tag definitions, Total data volume.
Progress bar	Weighted by data volume — a 100 GB site weighs proportionally more than a 1 GB site. Shows migrated / in-progress / failed segments.
Transfer rate & ETA	During the Files phase: download rate smoothed over 30 seconds, and estimated time remaining. ETA refreshes every 2 seconds.
Sites table	Sortable columns: Site name, Accounts, Groups, Folders, Documents, Tags, Data volume, Migration status.
Filter & search	Filter by status (All / Migrated / Not Migrated / In Progress / Failed) and free-text search by site name. Client-side, no server round-trip.
Report export	Download the analysis result as JSON (full structured data) or CSV (site list with all count columns: Site Name, # Accounts, # Groups, # Folders, # Documents, # Tags, Data Volume in bytes, Description).
Selection actions	Select rows to migrate a subset, retry their analysis, or delete migrated content. Destructive confirmations show account and group counts before proceeding.

Page reload mid-run: The dashboard automatically resumes live polling on load if a migration is already running — no manual action required.

Warnings & Troubleshooting

Analysis Warnings

Analysis warnings appear as alert indicators in the site table. They do not block migration but indicate that some site data may be incomplete.

people_fetch_failed
The API call to /sites/{siteId}/members failed. The site's account count will be zero or partial. The system retries automatically once. If the warning persists, verify that the configured Alfresco user has permission to read site memberships. Use Retry Selected to re-attempt individual sites without re-running the full analysis.

groups_fetch_failed
Could not retrieve the role-based group tree for this site. Group memberships will not be migrated. Verify that the API user can read group members for all four site role groups: GROUP_site_{id}_{SiteManager|SiteCollaborator|SiteContributor|SiteConsumer}.

Common Issues

No repositories found at the configured URL
The CMIS connection succeeded but no repository was returned. Verify that cmis.url points to a running Alfresco instance, the URL path is correct, and the configured user has access to the default repository.

Analysis returned null result
The analysis job completed but produced no data. Check server logs for connection errors during the repository or sites phase. A network timeout mid-analysis is the most common cause.

Migration already running (conflict)
Only one migration run can be active at a time. Use Stop Migration or the cancelMigration action and wait for the run to reach Paused state before starting a new one.

No analysis report available — run analysis first
A migration was requested but no completed analysis report exists. A cancelled or failed analysis does not count as completed. Run a new analysis to completion before attempting migration.