# iManage Web migration connector
Migrates documents from iManage Work cloud (Web API) to SharePoint Online matter sites provisioned by Epona ProvisioningService.
DLL: Epona.Migrate.iManageWeb.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 Web connector connects to iManage Work cloud via the REST API and migrates documents to SharePoint by matter code. It supports:
- Document retrieval — downloads documents and all versions from iManage Work cloud via the Web API
- Metadata preservation — maps iManage custom fields, document class, author, and operator to SharePoint columns
- Permission migration — exports workspace and folder-level security from iManage and applies it in SharePoint
- Document class routing — maps iManage document class/subclass combinations to SharePoint content types
- Delta migration — tracks what has already been migrated; subsequent runs process only new or changed documents
- Matter-scoped import — migrates one or more matters per run, identified via iManage workspace custom fields
# How it differs from other connectors
Unlike the filesystem, OpenText, or on-premises iManage connectors, the iManage Web connector:
- Uses the iManage Work REST API — connects via OAuth2 to the cloud-hosted API; no direct access to the iManage SQL Server database or file storage is required
- Uses a separate migration database — unlike the on-premises iManage connector (which creates tracking tables directly in the iManage SQL Server database), this connector uses a dedicated migration database (SQLite or SQL Server) configured separately in the main window. This database tracks all migration progress and is the source of truth for delta runs
- Derives client/matter codes from iManage custom fields — the connector reads iManage workspace custom fields to identify the client code and matter code for each workspace, rather than reading from a dedicated matter table. The custom field numbers are configurable (
CustomClientTableNumberdefaults to1,CustomMatterTableNumberdefaults to2) - Supports Azure Blob Storage migration — high-speed upload via SharePoint's Migration API is supported alongside direct CSOM upload
# Prerequisites
- iManage Work cloud deployment accessible via HTTPS
- OAuth2 credentials: client ID and client secret issued by the iManage Work administrator
- An iManage user account with read access to the library and the workspaces to be migrated
- The custom field numbers on iManage workspaces that store the client code and matter code (defaults: custom field 1 for client code, custom field 2 for matter code)
- Target SharePoint matter sites provisioned by Epona ProvisioningService
- SharepointCfg JSON file configured with the target SharePoint tenant credentials
- A migration database: a writable local folder for SQLite (file created automatically), or an existing SQL Server database (the Migrator creates the schema on first use)
# Deployment
- Copy
Epona.Migrate.iManageWeb.dllto theEpona.Migrate.exeapplication directory - Start
Epona.Migrate.exe— the iManage Web tab appears automatically - Configure the iManage connection, migration database, and settings (see steps below)
# Step 1 — Configure the iManage connection
In the iManage Web tab, click the ... button next to the iManage dropdown to open the configuration editor. Click New to create a new configuration and set the following connection fields:
| Field | Description |
|---|---|
Name | Required. Unique name for this configuration — saved as Config\iManageWeb\{Name}.json |
Url | iManage Work cloud base URL (e.g., https://company.imanagework.com) |
Library | iManage library name (e.g., ACTIVE). If left blank, the user's preferred library is auto-discovered from the API on first connect |
UserName | iManage Work user login name |
ClientId | OAuth2 client ID issued by the iManage Work administrator |
ClientSecretKey | OAuth2 client secret — stored encrypted on save |
Password | iManage user password — stored encrypted on save |
Click Save — the configuration appears in the iManage dropdown.
Authentication
The connector uses the OAuth2 password grant flow, posting ClientId, ClientSecretKey, UserName, Password, and scope=admin to {Url}/auth/oauth2/token. The access token is cached and refreshed automatically during the migration session.
# Step 2 — Configure the migration database
The iManage Web connector uses a separate migration database to track every document and its migration state. This database persists across Import runs and is the source of truth for delta detection.
In the main window, click Create/Edit Database
Choose SQLite (file-based) or SQL Server:
Option When to use SQLite Single-machine migrations; the .dbfile is created automatically if it does not existSQL Server Shared or multi-machine access; the database must already exist — the Migrator creates the tables on the first Import run Click Save and select the connection from the main window Database dropdown
TIP
Use a dedicated database per migration engagement. Mixing multiple clients or engagements in the same database makes the Report output harder to interpret.
# Step 3 — Configure settings
In the iManage Web tab, click ... to open the configuration editor. Settings are grouped into four categories.
# Global
| Setting | Type | Default | Description |
|---|---|---|---|
Name | string | — | Required. Unique configuration name — also the JSON filename |
Debug | bool | false | Enable verbose debug logging to the application log |
# iManage
| Setting | Type | Default | Description |
|---|---|---|---|
Url | string | — | iManage Work cloud base URL |
Library | string | — | iManage library name. If blank, the user's preferred library is auto-discovered |
UserName | string | — | iManage user login name |
ClientId | string | — | OAuth2 client ID |
ClientSecretKey | string (encrypted) | — | OAuth2 client secret |
Password | string (encrypted) | — | iManage user password |
# Migrate
| Setting | Type | Default | Description |
|---|---|---|---|
CustomClientTableNumber | int | 1 | iManage custom field number (1–12 or 29–31) that holds the client code on each workspace. Values 29–31 are accepted by the validator but not currently resolved at lookup time — use 1–12 in practice |
CustomMatterTableNumber | int | 2 | iManage custom field number (1–12 or 29–31) that holds the matter code on each workspace. Values 29–31 are accepted by the validator but not currently resolved at lookup time — use 1–12 in practice |
ClientMatterSeparator | char? | — | If set, splits the value entered in the Matter(s) text box into client code and matter code. Only needed when matter codes are not unique across clients. For example, with separator ., entering ABC.001234 yields client ABC and matter 001234. If the entered value does not contain the separator, it is treated as a matter code only |
CombineClientAndMatterCodeToMatterCode | string | — | If set, combines client code and matter code into a single matter code using this character as separator (e.g., _ produces ABC_001234). Use when the SharePoint matter site identifier is a combined client-matter code |
CreateEmptyDirectories | bool | false | Create empty folders in SharePoint for iManage folders that contain no documents |
DocumentClassToContentTypes | string | — | Maps iManage document class IDs to SharePoint content type names. Format: CLASS1=ContentTypeName1;CLASS2=ContentTypeName2; (semicolon-separated) or one mapping per line. If empty, the document library's default content type is used |
ReplaceUserNames | string | — | Maps iManage user IDs to SharePoint login names (UPNs). Format: iManageUserId=user@domain.com;. Build this from the Users sheet in the Dump output |
ReplaceGroupNames | string | — | Maps iManage group names or IDs to SharePoint group names. Format: iManageGroupId=SharePoint Group Name;. Build this from the Groups sheet in the Dump output |
ReplaceFolders | string | — | Renames source folder paths before creating them in SharePoint. Format: OldPath=NewPath; |
# Permissions
| Setting | Type | Default | Description |
|---|---|---|---|
ReadToRoleDefinition | string | Read | SharePoint role definition assigned for iManage Read access. If empty, Read grants are not applied |
ReadWriteToRoleDefinition | string | Contribute | SharePoint role definition assigned for iManage Read/Write access. If empty, Read/Write grants are not applied |
FullAccessToRoleDefinition | string | Full Control | SharePoint role definition assigned for iManage Full Access. If empty, Full Access grants are not applied |
NoneToRoleDefinition | string | — | SharePoint role definition assigned for iManage No Access. If empty, No Access entries are skipped |
PermissionsFolderOwnerToFullAccess | bool | true | Always grant the workspace or folder owner Full Access in SharePoint |
PermissionsDocumentAuthorToFullAccess | bool | false | Grant the document author Full Access in SharePoint |
PermissionsDocumentOperatorToFullAccess | bool | false | Grant the document operator Full Access in SharePoint |
# Metadata
These settings map iManage document properties to SharePoint column internal names. Leave empty to skip writing the corresponding column.
| Setting | Description | Example |
|---|---|---|
AUTHOR | SharePoint column for the iManage document author | "Author" |
OPERATOR | SharePoint column for the iManage document operator | "Operator" |
C1ALIAS–C12ALIAS, C29ALIAS, C30ALIAS | SharePoint column for the alias value of iManage custom fields 1–12 and 29–30 | "C1Alias" |
C1DESCRIPTION–C12DESCRIPTION, C29DESCRIPTION, C30DESCRIPTION | SharePoint column for the description value of iManage custom fields 1–12 and 29–30 | "C1Description" |
C13ALIAS–C28ALIAS | SharePoint column for the alias value of iManage custom fields 13–28 (alias only; no description mapping) | "C13Alias" |
DocumentNumber | SharePoint column for the iManage document number (without version) | "DocNumber" |
DocumentNumberVersion | SharePoint column for the document number combined with version (e.g., 12345.1) | "DocNumberVersion" |
DocumentClass | SharePoint column for the iManage document class | "DocClass" |
DocumentClassAndSubClass | SharePoint column for the combined class and subclass | "DocClassSub" |
DocumentClassSub | SharePoint column for the document subclass only | "DocSubClass" |
WorkspaceId | SharePoint column for the iManage workspace ID | "WorkspaceId" |
WorkspaceName | SharePoint column for the iManage workspace name | "WorkspaceName" |
# Step 4 — Dump (explore content and map users/groups)
Click Dump to scan iManage and produce an overview Excel file. No documents are migrated. The file is saved to the Migrate\ subdirectory as iManageWeb_{ConfigName}_{timestamp}.xlsx.
Leave the Matter(s) text box empty to dump all workspaces in the library, or enter matter codes to limit the scope.
The Excel file contains the following sheets. Sheets that depend on data (such as Duplicate Workspaces, Doc SubClasses, or Custom Fields) are included only when that data exists in iManage.
| Sheet | Contents | Typical use |
|---|---|---|
| Workspaces | All iManage workspaces: id, name, owner, default security, custom field values, file count | Verify scope; identify workspace-to-matter mappings |
| Duplicate Workspaces | Workspaces where the matter code (from CustomMatterTableNumber) is not unique | Detect naming conflicts before running Import |
| Folders | All folders with paths, file counts, client code, and matter code | Review folder structure to be recreated in SharePoint |
| Security | Workspace and folder security assignments in SharePoint-compatible permission import format; role column names reflect the PermissionXxxToRoleDefinition settings | Review permissions before Import |
| Captions | Document caption definitions from iManage | Reference for metadata mapping |
| FileTypes | Document file type definitions | Used to map document types to content types |
| Doc Classes | Document class definitions | Build DocumentClassToContentTypes mapping |
| Doc SubClasses | Document subclass definitions (included only if subclasses exist) | Build combined class/subclass content type mappings |
| Users | All library users with _TargetUserName and _TargetUserMapping helper columns | Build ReplaceUserNames from the generated mapping formulas |
| Groups | All library groups with _TargetGroupType, _TargetGroupName, and _TargetGroupMapping helper columns | Build ReplaceGroupNames from the generated mapping formulas |
| Group Members | Group membership details (included only if groups have members) | Verify group composition for permission mapping |
| MyMatters | Users' "My Matters" workspace shortcuts | Identify matter interest per user |
| Roles | All library roles with _TargetRoleName and _TargetRoleMapping helper columns | Map iManage roles to SharePoint roles |
| Role Members | Role membership details (included only if roles have members) | Verify role composition |
| Custom Field 1–12, 29–30 | Lookup values for each custom field that has data; fields 2 and 30 include a _parent_description formula column | Identify field values; used to configure CxALIAS and CxDESCRIPTION metadata settings |
User and group mapping
Run Dump before the first Import to get the full user and group list. The _TargetUserMapping column (Users sheet) and _TargetGroupMapping column (Groups sheet) contain pre-formatted mapping formulas (iManageId=SharePointName). Fill in the SharePoint side and paste the result into ReplaceUserNames and ReplaceGroupNames in the configuration.
# Step 5 — Initial migration by matter code
Select the iManage Web configuration from the iManage dropdown
Select the migration database from the main window Database dropdown
Select the SharePoint environment from the main window SharePoint Environment dropdown
In the Matter(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 001234Matter codes are unique across all clients Client + matter code ABC.001234Same matter code exists under different clients; requires ClientMatterSeparatorto be configuredRedirect: source → target 001234=NEWCODEiManage matter code differs from the SharePoint matter site identifier Redirect with subfolder 001234=NEWCODE\CorrespondenceDocuments land under the Correspondencesubfolder, preserving the original iManage folder structure beneath itClick Import
Import asks for confirmation twice. The first dialog shows how many matters will be processed — confirm to proceed. The migration database is then created or updated, after which a second confirmation dialog appears — confirm again to start the migration. If Azure Blob Storage is enabled in the SharepointCfg, the Monitor window opens automatically after the upload phase.
What happens during Import:
- The connector creates or updates the migration database schema if it does not already exist
- For each matter code, the connector locates the matching iManage workspace by reading the custom fields configured in
CustomClientTableNumberandCustomMatterTableNumber - All folders and subfolders in the workspace are traversed; each document and its versions are downloaded via the iManage API
- Each document version is checked against
_EDMSDocument— versions that are already migrated without error and have not changed since the last run are skipped (see Step 6) - New and updated documents are uploaded to the corresponding SharePoint document library with metadata applied
- The result for each 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 "Client/Matter '[code]' not found in Sharepoint".
# Step 6 — Delta migration
Subsequent Import runs automatically use delta mode — the connector reads _EDMSDocument and skips any document version that was already successfully migrated and has not been modified since.
How delta works:
For each document version, the connector checks _EDMSDocument:
- If a row exists with the same version number (
SourceVersion), no error, non-emptyTargetFileName, andSourceLastModifiednot older than the current iManageLastModifiedOn— the version is skipped - If the version is new, has a recorded error (retry), or has been modified since the previous run — the version is re-uploaded
Resetting delta (starting fresh):
There is no Remove button on the iManage Web tab. To reset migration tracking and re-migrate all documents:
- SQLite: delete the
.dbfile and create a new connection pointing to a new or empty file. The schema is recreated automatically on the next Import run - SQL Server: truncate or drop and recreate the
_EDMSDocumenttable (and_EDMSDocumentLog,_EDMSAzureDocument,_EDMSAzureMigrationJob,_EDMSAzureMigrationJobEventif needed). The schema is recreated automatically on the next Import run
When to reset
Reset the migration database when you want to re-migrate all documents from scratch — for example, after a test migration before go-live, or when the SharePoint target has been rebuilt.
# Step 7 — Document security export
Click Doc. Security to export per-document security assignments from iManage to Excel.
Not yet implemented
The Doc. Security button is present in the UI but not yet functional — clicking it shows "Not yet supported". Workspace and folder-level security is available in the Security sheet of the Dump output instead (see Step 4).
# Step 8 — Migration report
Click Report to export the contents of the _EDMSDocument tracking table to Excel. The file is saved to the Migrate\ subdirectory as Report_{timestamp}.xlsx.
The report gives a complete overview of migration progress across all matters and surfaces any outstanding errors before sign-off. Run it after each migration session.
Sheets:
| Sheet | Contents |
|---|---|
| Summary | Total sources migrated (with and without errors), total unique documents, total document versions, error counts |
| MigrateSource Totals | Per source (matter code entered at import time): document count, document version count, version error count, error flag |
| Unique Errors | Error messages grouped by text with occurrence counts — useful for triaging recurring failures |
| File Errors | Individual document records with non-empty errors — the full _EDMSDocument row for each failed version |
# The _EDMSDocument tracking table
The connector creates and maintains this table in the migration database (SQLite or SQL Server). It records every document version processed by Import.
| Column | Type | Description |
|---|---|---|
ID | integer (identity) | Primary key |
SharepointFileId | text | Unique file identifier; links this record to the Azure migration tables |
MigrateSource | text | Source identifier — the matter code value used in this import run |
Source | text | iManage document number |
SourceVersion | text | iManage document version string |
SourceLastModified | datetime | Document modification date at time of migration — used by delta to detect changes |
TargetDocLib | text | Target SharePoint document library URL |
TargetFolder | text | Target folder path within the document library |
TargetFileName | text | Target file name in SharePoint |
TargetDocumentNumber | text | SharePoint document ID after upload |
TargetDocumentVersion | text | SharePoint version after upload |
Error | text | Error message if the document version failed; empty string if successful |
Modified | datetime | When this row was last updated |
Created | datetime | When this row was first created |
# Configuration file location
iManage Web configurations are saved as JSON files in:
[Epona.Migrate.exe directory]\Config\iManageWeb\{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 Web migrations.
| Setting | Description |
|---|---|
UseAzureBlobStorage | Enable high-speed Azure Blob Storage migration. When enabled, the Monitor window opens automatically after Import to track Azure Migration API job progress |
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 regardless of matter |
ForceEmailContentType | Override content type for all email documents |
See the migration overview for the full settings reference.
# Troubleshooting
# Failed to authenticate
- Cause: Invalid
ClientId,ClientSecretKey,UserName, orPassword; orUrlpoints to the wrong iManage Work instance - Resolution: Verify all credentials with the iManage Work administrator; confirm
Urlis the correct cloud instance base URL (the connector authenticates at{Url}/auth/oauth2/token)
# Workspace not found for a matter code
- Cause: No iManage workspace has the entered matter code in the custom field configured by
CustomMatterTableNumber, or the entered code includes a client prefix that requiresClientMatterSeparatorto be set - Resolution: Run Dump and check the Workspaces sheet — identify which custom field holds the matter code and confirm
CustomMatterTableNumberis set correctly; configureClientMatterSeparatorif codes need splitting
# "Client/Matter '[code]' not found in Sharepoint"
- Cause: The matter code resolved from the iManage workspace does not match any site in the SharePoint MatterList; or
CombineClientAndMatterCodeToMatterCodeis needed to form the correct SharePoint site identifier - Resolution: Verify the matter site exists in SharePoint; confirm whether the SharePoint matter site identifier requires a combined client-matter code and configure
CombineClientAndMatterCodeToMatterCodeaccordingly
# "Specify one or more (client)mattercodes"
- Cause: The Matter(s) text box is empty when Import is clicked
- Resolution: Enter at least one matter code before clicking Import
# Zero documents migrated for a matter
- Cause: All document versions are already recorded in
_EDMSDocumentas successfully migrated and unchanged (delta mode skipped all) - Resolution: Run Report to confirm which matters have been fully migrated; if a fresh migration is required, reset the migration database (see Resetting delta)
# Duplicate matter codes in Dump
- Cause: Multiple iManage workspaces share the same custom field value in
CustomMatterTableNumber; these appear on the Duplicate Workspaces sheet in the Dump output - Resolution: Each workspace must resolve to a unique matter code for Import to work correctly. Contact the iManage administrator to correct the custom field values, or configure
ClientMatterSeparatorwithCustomClientTableNumberto disambiguate via client code
# Permissions not applied after migration
- Cause: iManage user IDs or group names are not mapped to valid SharePoint login names or group names in
ReplaceUserNames/ReplaceGroupNames - Resolution: Run Dump and use the
_TargetUserMappingcolumn (Users sheet) and_TargetGroupMappingcolumn (Groups sheet) to build the mapping strings; paste them into the corresponding configuration settings
# Content type not found
- Cause: A document class in
DocumentClassToContentTypesmaps to a content type name that does not exist on the target document library - Resolution: Verify content type names exactly (case-sensitive); ensure the content type is added to the document library on the target matter site
# No doclib(s) found for '[code]' in Sharepoint
- Cause: The matter site was found in MatterList but has no document libraries provisioned
- Resolution: Provision a document library on the matter site before running Import
# Currently only 1 target doclib is supported (N doclibs found for '[code]' in Sharepoint)
- Cause: The matter site has more than one document library; the iManage Web connector only supports a single target document library per matter
- Resolution: Ensure the matter site uses a single document library, or reconfigure the site template to remove extra libraries before running Import
# Related
- Migration overview — how the migration system works
- iManage connector — on-premises iManage Work (direct SQL Server connection)