Documentation

# Azure migration jobs and monitor

This page covers the Azure Blob migration job lifecycle, monitor window, and retry workflow. These apply to all migration connectors (FileSystem, iManage, Box, OpenText, and others) when UseAzureBlobStorage is enabled.

See Migration overview for a comparison of upload approaches.

# Error action

When a job finishes, SharePoint returns a per-file log. Files flagged with a JobError or JobWarning event have their message written to the migration database. The UseAzureBlobStorageErrorAction setting controls what happens to those files when the job completes:

Value Behaviour
None (default) File is left in SharePoint as-is; the error is recorded in the database
RecycleBin File is moved to the SharePoint recycle bin immediately after the job finishes
Delete File is permanently deleted from SharePoint immediately after the job finishes

Regardless of the setting, files with errors in the database are picked up again on the next import run and re-uploaded. The error record is what marks them for re-import — once re-uploaded successfully, the record is updated and the file is no longer retried.

A warning does not change the document's migration status — only errors mark the document as failed.

# Azure Blob job lifecycle

When Azure Blob upload is enabled, the connector batches files into migration jobs:

  1. Files are staged to an Azure Blob container with encrypted metadata
  2. The job is submitted to SharePoint's Azure migration queue
  3. SharePoint processes the job asynchronously in the background
  4. The monitor window polls the queue and updates job status in real time
  5. When the job completes, SharePoint returns a log with per-file errors and warnings
  6. For each file with a JobError or JobWarning event: the message is recorded in the database and UseAzureBlobStorageErrorAction is applied immediately — the file is recycled or deleted if configured (see Error action)

Each parallel matter task produces its own migration job. Once submitted, jobs are processed entirely by Microsoft — processing speed, queuing behaviour, and job duration are outside our control. Jobs can be slow or appear to hang with no progress for extended periods; there is nothing that can be done other than waiting or force-cancelling the job and retrying.

# Monitor window

The monitor window opens automatically after import starts. It tracks all migration jobs in the selected database.

# Job list

Each row represents one Azure migration job. Row colours indicate status:

Colour Meaning
Gray Queued — not yet submitted to SharePoint
Pale green Running — SharePoint is processing
Green Finished — no errors
Pale red Running — errors encountered so far
Red Finished — errors present

Double-click a row to open the job details window, which shows the full event log and any log files returned by SharePoint.

# Status bar

The status bar at the bottom shows: time of last refresh, number of ongoing jobs, total jobs, total errors and warnings, and total documents migrated.

# Actions

Button Action
Unfinished documents Opens a list of documents not yet fully processed (no target file set in the database)
Export all issues Exports an Excel report of all documents with errors or warnings
Retry Starts the retry workflow for failed documents (see below)
Force exit selected Cancels or removes selected jobs (see below)

# Force exit selected

Behaviour depends on the job state:

  • Not started — job and its documents are removed from the database entirely
  • Running — job is cancelled in SharePoint and marked as failed; documents can be retried
  • Finished — job record is removed from the database (documents are kept)

# Filters

Filter Effect
Hide other batches Shows only jobs from the current Epona.Migrate session
Hide finished jobs Hides completed jobs regardless of error state

# Retry failed documents

After a migration completes, use the Retry button in the monitor window to handle documents that failed.

Wait for all jobs to finish before retrying

The retry button is blocked while there are unfinished documents in the database. Wait until all jobs have completed before starting the retry process.

What happens:

  1. All documents with errors are loaded from the database
  2. Two files are exported to the Migrate\ directory next to Epona.Migrate.exe:
    • AzureMigrationRetryErrors_{source}_{timestamp}.xlsx — error report grouped by matter, listing source paths and error messages
    • AzureMigrationDeleteFile_{source}_{timestamp}.xlsx — list of target SharePoint URLs to delete before retrying
  3. A confirmation prompt asks whether to remove the errored documents from the database
  4. If confirmed, error records are cleared — the next import run will treat them as new and re-upload them (delta tracking skips only successfully migrated documents with no error)

To complete the retry:

  1. Review the error report to understand which documents failed and why
  2. Use the delete file with the Delete Documents file handler to remove incorrectly uploaded files from SharePoint
  3. Fix any source data issues if needed
  4. Re-run the import — errored documents will be picked up again
Last Updated: 5/11/2026, 2:44:29 PM