Documentation

# iManage migration connector

Migrates documents from iManage Work (on-premises) to SharePoint Online matter sites provisioned by Epona ProvisioningService.

DLL: Epona.Migrate.iManage.dll

Audience

Technical consultants with SharePoint and Epona365 knowledge and basic familiarity with iManage Work. Read the migration overview before starting.

# What it does

The iManage connector connects directly to the iManage Work SQL Server database (MHGROUP schema) and migrates documents to SharePoint by matter code or folder ID. It supports:

  • Document retrieval — reads documents directly from the iManage SQL Server database and file storage
  • Metadata preservation — maps iManage custom fields and document properties to SharePoint columns
  • Permission migration — exports document-level and folder-level security from iManage and applies it in SharePoint
  • Document class routing — maps iManage document class/subclass combinations to SharePoint content types and target folders
  • Delta migration — tracks what has already been migrated; subsequent runs process only new documents, new versions, or documents changed since the last run
  • Matter-scoped import — migrates one or more matters per run, specified by client/matter code or folder ID
  • Shortcut handling — iManage allows a document to appear in multiple folders simultaneously; SharePoint does not support this. The connector uploads the document once at the first location and creates .url shortcut files in all other folders that link back to the real document in SharePoint

# How it differs from other connectors

Unlike the filesystem, OpenText, or Box connectors, the iManage connector:

  • Reads directly from the iManage SQL Server database — no vendor API required; the connector queries the MHGROUP schema tables (DOCMASTER, PROJECTS, CUSTOM1–CUSTOM31) and reads document binaries from the iManage file storage
  • Creates the tracking table in the source database — the _EDMSDocument tracking table is created directly inside the iManage SQL Server database, not in a separate file
  • Supports two import modes — Workspace mode (matter code identifies the workspace via custom tables) and Folder mode (project ID identifies the import target)

# Prerequisites

  • iManage Work on-premises deployment with SQL Server accessible from the migration workstation
  • SQL Server login with read access to the MHGROUP schema and write access to create and populate _EDMSDocument in the iManage database
  • Read access to the iManage document file storage (network share)
  • Target SharePoint matter sites provisioned by Epona ProvisioningService
  • SharepointCfg JSON file configured with the target SharePoint tenant credentials

# Deployment

  1. Copy Epona.Migrate.iManage.dll to the Epona.Migrate.exe application directory
  2. Start Epona.Migrate.exe — the iManage tab appears automatically
  3. Configure the database connection and iManage settings (see steps below)

# Step 1 — Configure the connection

  1. In the iManage tab, click the ... button next to the configuration dropdown to open the iManage Configuration editor

  2. Click Add to create a new configuration and set the connection fields:

    Field Value
    Name Required. Unique name for this configuration
    DbServer SQL Server hostname or instance (e.g., imanage-sql or imanage-sql\SQLINSTANCE)
    DbDatabase iManage database name (the one that contains the MHGROUP schema)
    DbUserName Leave blank for Windows integrated authentication, or enter a SQL Server login
    DbPassword Leave blank for Windows integrated authentication, or enter the password

  3. Click Save — the configuration appears in the iManage dropdown

  4. Select the configuration from the dropdown

TIP

The connection must reach the SQL Server database that contains the MHGROUP schema (tables such as MHGROUP.DOCMASTER, MHGROUP.PROJECTS, MHGROUP.CUSTOM1). The connector creates the _EDMSDocument tracking table in the dbo schema of this same database on the first Import run, if it does not already exist.

Pre-creating the tracking table

If the migration account should not have DDL rights, a DBA can pre-create the tracking tables in advance. The creation script is written to MigrateDb\CreateMigrationTablesSqlServer.sql in the Epona.Migrate.exe application directory each time the tool starts. Run this script against the iManage database with an account that has db_ddladmin or db_owner.

After pre-creation, the migration account requires:

  • db_datareader on the database — to read MHGROUP.* tables
  • INSERT, UPDATE on dbo._EDMSDocument — to record migration progress
  • ALTER on dbo._EDMSDocument — to truncate the table when using Remove; if not granted, the connector falls back to DELETE
  • CREATE TABLE on the database — to create timestamped backup copies (_EDMSDocument_{yyyyMMddTHHmmss}) during the delta backup prompt and Remove; if not granted, decline the backup prompt during Import (import proceeds), but Remove will fail
  • EXECUTE on dbo.ufn_FolderPath and dbo.ufn_RemoveInvalidFolderCharacters — to resolve folder paths during Dump and Import; these functions can also be pre-created using sql\CreateSqlFunctions.sql

# Step 2 — Configure settings

In the configuration editor, settings are grouped into four categories.

# Global

Setting Type Default Description
Name string — Required. Unique name — saved as Config\iManage\{Name}.json
Debug bool false Enable verbose debug logging

# Migrate

Setting Type Default Description
CustomClientTableNumber int? 1 Custom table number (1–12 or 29–31) used for client lookups. Default maps to MHGROUP.CUSTOM1.
CustomMatterTableNumber int? 2 Custom table number (1–12 or 29–31) used for matter lookups. Default maps to MHGROUP.CUSTOM2. For table 2, 30, or 31, the join also filters on the parent client alias.
ClientMatterSeparator char? — Character to split the value in the Workspace(s) box into client and matter codes. Only needed when matter codes are not unique across clients. For example, entering ABC@001 with separator @ yields client ABC and matter 001.
CombineClientAndMatterCodeToMatterCode string — If set, combines client code and matter code using this character when looking up the matter site in SharePoint (e.g., _ produces ABC_001). Use when the SharePoint matter site is identified by a combined code.
ImportOnlyLatestVersion bool false Import only the latest version of each document, skipping all previous versions.
CreateEmptyDirectories bool false Create empty folders in SharePoint for iManage folders that contain no documents.
ImportDocumentIgnoreProfileChanges bool false During delta migration, ignore metadata-only changes (profile updates) when checking whether a document has been modified since the last run.
ImportDocumentUseFileEditWhenColumn bool true Include the FILEDITWHEN column in addition to the profile modification date when determining the latest document modification date for delta checks.
DocumentClassToContentTypes string — Maps iManage document class/subclass combinations to SharePoint content type names. Format: CLASS_ALIAS.SUBCLASS_ALIAS=ContentType or CLASS_ALIAS=ContentType, semicolon-separated or one per line. Resolution order: exact class+subclass match → subclass only → class only → library default. If empty, the document library's default content type is used.
DocumentPropertyToFolder DocumentPropertyName? — Selects which iManage document property is used as the target subfolder name for documents not in a workspace folder. Supported values: AUTHOR, OPERATOR, C1ALIAS–C16ALIAS, C29ALIAS–C31ALIAS, T_ALIAS, C_ALIAS, SUBCLASS_ALIAS, C_ALIAS_SUBCLASS_ALIAS, C1ALIAS_C2ALIAS, C29ALIAS_C30ALIAS, C29ALIAS_C30ALIAS_C31ALIAS.
DocumentPropertyToFolders string — Maps values of the property selected by DocumentPropertyToFolder to target subfolder paths. Format: PropertyValue=SubfolderPath or CLASS.SUBCLASS=SubfolderPath (semicolon-separated or one per line). Resolution order: exact class+subclass → subclass only → class only → raw property value as folder name.
ReplaceGroupNames string — Maps iManage group names to SharePoint group names for permission migration. Format: iManageGroupName=SharePointGroupName (semicolon-separated or one per line).
ReplaceUserNames string — Maps iManage user names to SharePoint login names (UPNs). Format: iManageUserName=user@domain.com (semicolon-separated or one per line).
ReplaceFolders string — Transforms source folder paths before creating them in SharePoint. Supports renaming, stripping prefixes, skipping folders (__SKIP__), catch-all defaults, and root mapping (__ROOT__). See Folder path mapping for full syntax and examples.

# Permissions

Setting Type Default Description
ImportDocumentPermissions bool false Migrate document-level permissions from iManage to SharePoint. Before enabling, check the proportion of uniquely secured documents using the Dump output — a high number significantly degrades SharePoint performance.
PermissionReadToRoleDefinition string Read SharePoint role definition assigned for iManage Read permission.
PermissionReadWriteToRoleDefinition string Contribute SharePoint role definition assigned for iManage Read/Write permission.
PermissionFullAccessToRoleDefinition string Full Control SharePoint role definition assigned for iManage Full Access permission.
PermissionNoneToRoleDefinition string — SharePoint role definition for iManage No Access. If empty, no-access entries are skipped.
PermissionsFolderOwnerToFullAccess bool true Automatically grant the folder owner Full Control in SharePoint.
PermissionsDocumentAuthorToFullAccess bool true Automatically grant the document author Full Control in SharePoint.
PermissionsDocumentOperatorToFullAccess bool true Automatically grant the document operator Full Control in SharePoint.
FolderDefaultSecurityViewGroupName string — SharePoint group granted Read permission on all folders (added alongside migrated permissions).
FolderDefaultSecurityPublicGroupName string — SharePoint group granted Contribute permission on all folders.
DocumentDefaultSecurityViewGroupName string — SharePoint group granted Read permission on all documents that have custom security.
DocumentDefaultSecurityPublicGroupName string — SharePoint group granted Contribute permission on all documents that have custom security.

# Metadata

These settings map iManage document fields to SharePoint column names (internal names). Leave empty to skip writing the corresponding column.

Setting Description
AUTHOR Document author (MHGROUP.DOCMASTER.AUTHOR)
OPERATOR Last operator — user who last modified the document
C1ALIAS / C1DESCRIPTION Custom table 1: alias / description
C2ALIAS / C2DESCRIPTION Custom table 2: alias / description
C3ALIAS / C3DESCRIPTION – C12ALIAS / C12DESCRIPTION Custom tables 3–12: alias / description
C13ALIAS – C16ALIAS Custom fields 13–16 (alias only)
C29ALIAS / C29DESCRIPTION Custom table 29: alias / description
C30ALIAS / C30DESCRIPTION Custom table 30: alias / description
C31ALIAS / C31DESCRIPTION Custom table 31: alias / description
CDBL1 – CDBL4 Numeric (double) custom fields 1–4
CBOOL1 – CBOOL4 Boolean custom fields 1–4
CDATE1 – CDATE4 Date custom fields 1–4
DocumentNumber Original iManage document number (without version). Can be mapped to a SharePoint column for search and cross-reference.
DocumentNumberVersion Document number and version combined (e.g., 12345.1)
DocumentClass Document class alias (C_ALIAS)
DocumentClassAndSubClass Document class and subclass combined
DocumentClassSub Document subclass alias (SUBCLASS_ALIAS)
WorkspaceName Workspace name

# Step 3 — Dump (explore content and map users/groups)

Click Dump to scan the iManage database and produce an overview Excel file. No documents are migrated. The file is saved to the Migrate\ subdirectory as iManage_{ConfigName}_{timestamp}.xlsx.

The Excel file contains the following sheets:

Sheet Contents Typical use
Workspaces All workspaces with client/matter codes and document counts Identify which matters are in scope
Duplicate Workspaces Workspaces with the same client/matter combination Investigate duplicates before starting — see Duplicate Workspaces in Troubleshooting
My Favorites / My Matters iManage favourites and personal matters Import into Epona365 using the My Favorites and My Matters file handlers
Workspace Folder Security Folder-level permission entries per workspace Import workspace permissions into Epona365 using the Permission Set file handler
Folders Folder structure with document counts and migration progress Verify folder hierarchy and track migration per folder
Documents (no folder) Documents not in any folder, grouped by document property Identify documents that need DocumentPropertyToFolder routing
List Documents (no folder) Individual documents not in any folder Review specific documents for routing decisions
Captions iManage field captions (custom field labels) Identify custom field names for metadata mapping
Document Types Document type codes and names Build DocumentClassToContentTypes mappings
Document Classes Document class and subclass codes Build class-to-content-type mappings
Users iManage user accounts Map iManage usernames to Azure AD UPNs for ReplaceUserNames
Groups iManage security groups Map iManage group names to SharePoint groups for ReplaceGroupNames
Custom Fields All custom field definitions Identify which C1–C31 fields contain relevant metadata

User and group mapping

Run Dump before the first Import to get the full user and group lists. Configure ReplaceUserNames and ReplaceGroupNames in the iManage configuration before enabling ImportDocumentPermissions.

# Step 4 — Initial migration by workspace

  1. Select the iManage configuration from the iManage dropdown

  2. Select the SharePoint environment from the main window SharePoint Environment dropdown

  3. Select the import mode from the Type of Import dropdown:

    • Workspace — standard mode: matter codes identify iManage workspaces via the client/matter custom tables
    • Folder — matter codes are treated as iManage project IDs (PRJ_ID); use when migrating by folder ID rather than by matter code

  4. Optionally check Shortcuts only to run shortcut migration only — see Step 7 for when to use this

  5. In the Workspace(s) text box, enter the matter codes to migrate — one per line or semicolon-separated

    Syntax per entry:

    Form Example When to use
    Matter code only 001234 Matter codes are unique across all clients
    Client + matter code ABC@001234 Same matter code exists under different clients; requires ClientMatterSeparator

  6. Click Import

The import dialog shows how many matters will be processed. Confirm to start.

What happens during Import:

  1. The connector creates the _EDMSDocument tracking table in the iManage database if it does not already exist
  2. If _EDMSDocument already contains rows, a dialog asks: Make a backup of the current delta/log table (existing records will not be deleted)?
    • Yes — copies the current table to _EDMSDocument_{yyyyMMddTHHmmss} before continuing
    • No — continues without a backup; existing records remain untouched
    • Cancel — aborts the import
  3. For each matter code, the connector queries MHGROUP.DOCMASTER for documents belonging to that matter. Documents already successfully migrated and unchanged since are skipped
  4. Each document binary is read from the iManage file storage and uploaded to the SharePoint document library with metadata applied
  5. If ImportDocumentPermissions is enabled, document-level permissions are read from iManage and applied in SharePoint
  6. Each processed document version is recorded in _EDMSDocument

Matter site must exist

The SharePoint matter site and document libraries must already exist before running Import. If the matter is not found in the SharePoint MatterList, the import for that matter fails with "Matter not found in MatterList".

Azure Blob Storage

When UseAzureBlobStorage is enabled in the SharepointCfg, document permissions are not imported even if ImportDocumentPermissions is true. A warning is shown in the confirmation dialog. Use UseAzureBlobStorageErrorAction to control what happens to documents that fail Azure Blob processing (None, RecycleBin, or Delete). See Azure migration jobs and monitor for job lifecycle, monitor window, and retry workflow.

# Step 5 — Migration of documents not in folders

Some iManage documents exist directly in a workspace without being placed in any folder (PROJECT_ITEMS has no entry for them). These are not picked up by the standard Workspace or Folder import modes.

Use the Documents (no folder) and List Documents (no folder) sheets from the Dump output (Step 3) to identify whether such documents exist and how many there are before running this step. Alternatively, run DocumentsNoFolder.sql or ListDocumentsNoFolder.sql from sql/Dump/ manually against the iManage database.

Steps:

  1. Select the iManage configuration and the SharePoint environment

  2. In the Type of Import dropdown, select Documents not in folder

  3. In the Workspace(s) text box, enter the matter codes to migrate

  4. Configure DocumentPropertyToFolder in the iManage configuration to control how documents are routed to SharePoint folders:

    Value Target folder
    C_ALIAS_SUBCLASS_ALIAS {DocumentClass}\{DocumentSubClass}
    C1ALIAS_C2ALIAS {C1}\{C2}
    C29ALIAS_C30ALIAS {C29}\{C30}
    C29ALIAS_C30ALIAS_C31ALIAS {C29}\{C30.C31}
    Any other property name Single-level folder from that property value

    If DocumentPropertyToFolder is not set, all unfoldered documents land at the document library root (or in the NewTargetFolder if configured).

  5. Click Import and confirm

When this step is run again, delta logic applies — documents already recorded in _EDMSDocument without errors are skipped.

# Step 6 — Delta migration

Subsequent Import runs automatically use delta mode when _EDMSDocument already contains records.

How delta works:

  1. On startup, Import checks whether _EDMSDocument has any rows
  2. If rows exist, a dialog asks: Make a backup of the current delta/log table (existing records will not be deleted)?
    • Yes — copies the current table to _EDMSDocument_{yyyyMMddTHHmmss} before continuing
    • No — continues without a backup
    • Cancel — aborts the import
  3. Documents already in _EDMSDocument with a target filename and no error are skipped. A document version is re-queued if it has no entry in _EDMSDocument, has a recorded error (retry), or its modification date in iManage is newer than SourceLastModified in _EDMSDocument. New versions of previously migrated documents are picked up automatically.

Starting fresh:

Click Remove to reset the migration state. A confirmation dialog is shown: "Clean the previous import? The current content is copied to a new table. Continue?" On confirm, the current _EDMSDocument contents are copied to a timestamped backup table (_EDMSDocument_{yyyyMMddTHHmmss}), then the table is truncated. The next Import treats all matters as a fresh migration.

When to use Remove

Use this when re-migrating all documents from scratch — for example, after a test migration before going live, or when the SharePoint target has been recreated.

Do not use SELECT INTO to copy the tracking table

If you need to manually copy _EDMSDocument to another database or instance, do not use SELECT INTO — it creates a table without the primary key, unique index, or other indexes, which will break delta logic and cause duplicate entries. Always create the table structure first using MigrateDb\CreateMigrationTablesSqlServer.sql, then copy the rows with INSERT INTO ... SELECT.

# Step 7 — Shortcut migration

iManage allows a single document to appear in multiple folders simultaneously. SharePoint does not support this — a file can only exist in one location in a document library.

The connector resolves this as follows:

  • During normal Import, each document is uploaded once to its primary folder location
  • Any additional folder entries for the same document (shortcuts in iManage) are recorded but not yet created in SharePoint
  • After all documents are fully migrated, run a second Import with Shortcuts only checked — the connector creates a .url shortcut file in each additional folder that links to the real document's SharePoint URL

When to run:

Run the shortcut migration after all documents have been migrated and verified, including any delta runs. The shortcut creation reads TargetDocLib, TargetFolder, and TargetFileName from _EDMSDocument to build the link — if a document has not yet been migrated (no target URL), its shortcut entry is skipped with a logged warning.

Steps:

  1. Confirm all documents are migrated — use the Report to verify zero errors outstanding
  2. In the iManage tab, enter the same matter codes in Workspace(s)
  3. Check Shortcuts only
  4. Click Import and confirm

The connector creates one .url file per duplicate folder entry. The shortcut file uses the Windows Internet Shortcut format:

[InternetShortcut]
URL=https://<tenant>.sharepoint.com/<path-to-real-document>

To identify documents that appear in multiple folders before running this step, check the Duplicate Documents sheet from the Report (Step 9) or run DocumentShortcuts.sql from sql/ manually against the iManage database.

TIP

The Duplicate Documents sheet in the Report (Step 9) shows which documents have shortcuts and whether their real document has already been migrated, making it easy to verify coverage after the shortcut run.

# Step 8 — Document and folder security

Two separate security export buttons are available on the iManage tab:

Dump Doc Security — exports document-level permission assignments from iManage to a file. Requires documents to already be migrated (the export cross-references _EDMSDocument). Only documents with non-inherited (explicit) security are included.

Folder Security — exports folder-level permission assignments from iManage to a file. Useful for reviewing workspace and folder security before or after migration.

Performance impact of document-level permissions

A large number of uniquely secured documents significantly degrades SharePoint performance. Before enabling ImportDocumentPermissions, check the Workspace Folder Security sheet from the Dump output to understand how much custom security exists. In many cases, applying permissions at the document library or folder level provides adequate control with much better performance.

# Step 9 — Migration report

Click Report to export migration statistics from _EDMSDocument to Excel. The file is saved to the Migrate\ subdirectory.

The report is intended as a delivery document for the customer — it provides a clear overview of what was migrated, how many documents were processed per folder and matter, and whether any errors remain. Use it at the end of each migration phase and as sign-off evidence when the migration is complete.

Sheets:

Sheet Contents
Total Overall document and version counts, migrated counts, and error counts; filtered per matter if matters are entered
Folders Folder structure with per-folder document counts, migrated counts, and error counts
No Folders Documents not in any folder, grouped by document property, with migration progress
Duplicate Documents Documents that appear in multiple folders (shortcuts) with their migration target URLs
MigrateSource Errors Error counts per matter — only present when errors exist
Unique Errors Distinct error messages across all matters — only present when errors exist

Run the Report after each migration session to track progress and identify outstanding errors before sign-off.

# The _EDMSDocument tracking table

The connector creates and maintains this table directly in the iManage SQL Server database (dbo._EDMSDocument).

Column Type Description
ID int (identity) Primary key
SharepointFileId varchar(50) SharePoint file GUID after upload
MigrateSource nvarchar(800) Source matter code (used to scope queries per matter)
Source nvarchar(800) iManage document number
SourceVersion varchar(50) iManage document version
SourceLastModified datetime Modification date at time of migration (used for delta checks)
TargetDocLib nvarchar(425) Target SharePoint document library URL
TargetFolder nvarchar(425) Target folder path within the document library
TargetFileName nvarchar(255) Target file name in SharePoint
TargetDocumentNumber varchar(50) SharePoint document ID after upload
TargetDocumentVersion varchar(25) SharePoint version after upload
Error varchar(800) Error message if the document failed; empty string if successful
Modified datetime When the row was last updated
Created datetime When the row was first created

A trigger (EDMSDocumentAfterUpdate) writes the previous state to _EDMSDocumentLog on every update or delete, providing a full audit trail of all migration changes.

Backup tables are named _EDMSDocument_{yyyyMMddTHHmmss} and are created by the Yes option at the delta backup prompt and always by Remove.

# Configuration file location

iManage configurations are saved as JSON files in:

[Epona.Migrate.exe directory]\Config\iManage\{Name}.json

Each named configuration is a separate file. Renaming a configuration (changing the Name field) renames the file and deletes the old one.

# General migration settings (SharepointCfg)

The SettingsCfg.Migrate section of the SharepointCfg controls migration behaviour shared across all connectors. The settings below are relevant to iManage migrations.

Setting Description
UseAzureBlobStorage When true, uploads use the Azure Blob Storage pipeline instead of CSOM. Document permissions are not migrated when this is enabled, even if ImportDocumentPermissions is true.
UseAzureBlobStorageErrorAction What to do with documents that fail Azure Blob processing: None (leave as-is), RecycleBin (move to SharePoint recycle bin), Delete (permanently delete). Confirm with the client before setting a destructive action.
CleanupOffice2003Documents Strip doc properties from .doc/.xls/.ppt/.msg files before upload
CleanupOffice2007Documents Strip doc properties from .docx/.xlsx/.pptx files before upload
ForceEmailInAutoFilingFolder Always route emails to the AutoFiling folder
ForceEmailContentType Override content type for all email documents

See the migration overview for the full settings reference.

# SQL scripts

The project includes SQL scripts in two locations. Run them directly in SQL Server Management Studio against the iManage database for diagnostics or pre-migration analysis.

# sql/Dump/

Scripts that reproduce the queries run by the Dump button. Use these to inspect source data directly in SSMS.

Script Contents
Workspace.sql Workspaces with client/matter codes
WorkspaceDocCount.sql Workspaces with document counts
Folders.sql Folder structure with document counts
DocumentsNoFolder.sql Documents not in any folder (grouped)
ListDocumentsNoFolder.sql Individual documents not in any folder
DocumentClasses.sql Document classes and subclasses
DocumentTypes.sql Document type codes and names
CustomField.sql Custom field definitions
Users.sql iManage user accounts
Groups.sql iManage security groups
Captions.sql Field captions (labels)
MyFavoritesMyMatters.sql Personal favourites and matters

# sql/

Analysis and diagnostic scripts for monitoring migration progress.

Script Purpose
DocCountPerFolderAndMigrated.sql Document count per folder compared to migrated count
DocCountNotInFolderAndMigrated.sql Document count for documents outside folders compared to migrated
DocumentShortcuts.sql Documents appearing in multiple folders (shortcuts)
FolderStructure.sql Full folder hierarchy
FolderDocumentsSize.sql Document sizes per folder in MB (DocumentsSizeMB) — use to estimate the total storage required in SharePoint before starting the migration. Accuracy depends on the DOCSIZE field iManage stores in the database; if iManage did not record file sizes, values will be zero.
ListDocumentsWithError.sql Documents with migration errors from _EDMSDocument
ListDocumentsMovedDuringMigration.sql Documents moved between folders during migration
ListDocumentsRenamedDuringMigration.sql Documents renamed during migration
ListRemovedDocumentsDuringMigration.sql Documents removed during migration
CreateSqlFunctions.sql Creates (drop + recreate) the SQL functions and view used by the connector: ufn_FolderPath, ufn_RemoveInvalidFolderCharacters, and vwFolderWithUniqueDocuments. Use this script for DBA pre-creation; the connector also creates the functions automatically at runtime if they don't exist.
ConvertToNewStructure.sql Schema migration script for upgrading older tracking table structures

# sql/Metadata/

Scripts for pre-migration data preparation — assigning workspace numbers, filling custom fields, and updating document and folder metadata in the iManage database.

# Migrating from a database copy (production isolation)

The connector writes the _EDMSDocument tracking table directly into the iManage SQL Server database. For large migrations, this workload (reads + writes) can impact the production iManage server. When write access to production is not permitted or when production load must be avoided, run the migration against a restored copy on a separate server.

# Initial migration

  1. Restore the production iManage database to a separate SQL Server instance
  2. Run MigrateDb\CreateMigrationTablesSqlServer.sql against the restored copy to create _EDMSDocument with its primary key and indexes
  3. Configure the iManage configuration (DbServer, DbDatabase) to point to the restored copy
  4. Run the migration as normal (see Steps 1–9)

# Delta migrations

For each subsequent delta run, restore a fresh copy of the production database — do not overwrite the previous copy, as it still holds the _EDMSDocument tracking data that records what was already migrated.

  1. Restore the latest production backup to a new database name (e.g., iManage_2026_05_07)

  2. Run MigrateDb\CreateMigrationTablesSqlServer.sql on the new database (iManage_2026_05_07) to create _EDMSDocument with proper structure

    Do not use SELECT INTO to copy the table

    SELECT INTO creates a table without primary key, indexes, or constraints. Always create the table structure first with MigrateDb\CreateMigrationTablesSqlServer.sql, then copy the rows.

  3. Copy the tracking rows from the previous copy into the new database. Run this on the new database (iManage_2026_05_07), replacing iManage_2026_04_15 with the name of the previous copy:

    -- Run on: iManage_2026_05_07 (the new database)
INSERT INTO [dbo].[_EDMSDocument]
    (SharepointFileId, MigrateSource, Source, SourceVersion, SourceLastModified,
     TargetDocLib, TargetFolder, TargetFileName, TargetDocumentNumber, TargetDocumentVersion,
     Error, Modified, Created)
SELECT
    SharepointFileId, MigrateSource, Source, SourceVersion, SourceLastModified,
    TargetDocLib, TargetFolder, TargetFileName, TargetDocumentNumber, TargetDocumentVersion,
    Error, Modified, Created
FROM [iManage_2026_04_15].[dbo].[_EDMSDocument];

    The ID column is an identity and is intentionally excluded — the delta logic uses Source and SourceVersion for lookups, not ID.

  4. Update the iManage configuration to point to the new database copy

  5. Run the delta migration — the connector skips documents already recorded in _EDMSDocument and processes only new or changed ones

# Troubleshooting

# Cannot connect to the iManage database

  • Cause: SQL Server connection string is incorrect, server is unreachable, or the login lacks permissions
  • Resolution: Verify DbServer and DbDatabase in the configuration; test connectivity with SQL Server Management Studio; ensure the login has db_datareader on the MHGROUP schema and db_datawriter (plus CREATE TABLE) on the dbo schema

# "Select a database and/or sharepoint configuration before importing"

  • Cause: No iManage configuration or no SharePoint environment is selected
  • Resolution: Select both from the respective dropdowns before clicking Import or Dump

# "Specify one or more (client)mattercodes"

  • Cause: The Workspace(s) text box is empty
  • Resolution: Enter at least one matter code before clicking Import

# "Matter not found in MatterList"

  • Cause: The matter code does not match any site in the SharePoint MatterList, or the ClientMatterSeparator is misconfigured
  • Resolution: Verify matter codes in the Workspaces sheet from Dump; check whether CombineClientAndMatterCodeToMatterCode is needed; confirm the target matter site exists in SharePoint

# Zero documents migrated for a matter

  • Cause: The matter has no documents in iManage matching the query, all documents were already migrated (delta), or the import mode (Workspace vs Folder) does not match the data
  • Resolution: Run Dump and check WorkspaceDocCount — verify the matter has documents; if delta is active, use Remove to reset; verify the correct Type of Import is selected

# Permissions not applied after migration

  • Cause: ImportDocumentPermissions is false, or iManage user/group names are not mapped to valid SharePoint login names
  • Resolution: Enable ImportDocumentPermissions; use the Users and Groups sheets from Dump to build ReplaceUserNames and ReplaceGroupNames mappings

# Document metadata is wrong

  • Cause: Metadata settings do not match the actual SharePoint column internal names, or the target columns do not exist on the content type
  • Resolution: Verify SharePoint column internal names match the values in the iManage configuration (Metadata section); ensure columns are added to the document library content type

# Content type not found

  • Cause: A class/subclass combination in DocumentClassToContentTypes maps to a content type name that does not exist on the target document library
  • Resolution: Verify content type names using the Document Classes sheet from Dump; ensure the content type is added to the document library

# Duplicate Workspaces

  • Cause: Two or more workspaces in iManage share the same client code and matter code combination. The connector throws InvalidOperationException: N workspaces found with clientcode '...', mattercode '...' and stops the import for that matter.
  • Resolution: Run Dump first — the Excel file includes a Duplicate Workspaces sheet that lists every matter code with a count greater than 1, along with each workspace's PRJ_ID, name, creation date, and custom field values. Use this sheet to identify which workspace is the authoritative one. The duplicate can then be resolved in iManage (rename or remove the extra workspace) before re-running the import. Alternatively, switch Type of Import to Folder and specify the PRJ_ID directly, which bypasses the client/matter lookup entirely.

# Folder paths contain invalid characters

  • Cause: iManage folder names contain characters that SharePoint does not allow (#, %, *, :, etc.)
  • Resolution: The connector automatically strips invalid characters using ufn_RemoveInvalidFolderCharacters. If this function could not be created in the database, a warning is shown during Dump — ensure the SQL Server login has permission to create functions
Last Updated: 5/13/2026, 3:25:33 PM