Documentation

# OpenText / eDocs migration connector

Migrates documents from OpenText eDocs Document Management (formerly PC DOCS) into SharePoint Online matter sites provisioned by Epona ProvisioningService.

DLL: Epona.Migrate.OpenText.dll

Audience

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

# What it does

The OpenText connector connects directly to the OpenText eDocs SQL Server database (the DOCSADM schema) and migrates documents to SharePoint by matter code. It supports:

  • Document retrieval — reads documents directly from the eDocs database and file storage
  • Metadata preservation — maps eDocs document properties to SharePoint columns
  • Permission migration — exports document- and folder-level security from eDocs and applies it in SharePoint
  • Document type routing — maps eDocs document types to SharePoint content types and target folders
  • Delta migration — tracks what has already been migrated; subsequent runs process only new or changed documents
  • Flexible selection — import by a PROFILE field value (Field mode), or recreate a whole eDocs folder or workspace subtree (Folder/Workspace mode)
  • Upload method — direct CSOM upload (default), or the Azure Blob upload pipeline when UseAzureBlobStorage is enabled in the SharepointCfg

Upload method

By default the connector uploads documents directly to SharePoint with CSOM. When SettingsCfg.Migrate.UseAzureBlobStorage is enabled in the SharepointCfg, the connector instead uses the Azure Blob upload pipeline (the same mechanism the iManage connector uses): documents are encrypted, uploaded to an Azure Blob container and queued for SharePoint's migration import. CSOM is used to overwrite a version that was already imported in a previous run.

# How it differs from other connectors

Unlike the filesystem or Box connectors, the OpenText connector:

  • Connects directly to the eDocs SQL Server database — no vendor API required; the connector reads the eDocs SQL Server database directly and reads document binaries from the eDocs file storage (network share)
  • Creates the tracking tables next to the source data — the _EDMSDocument (and other _EDMS*) tables are created automatically inside the eDocs SQL Server database on the first run. Set MigrationDatabase on the database connection to place them in a separate database on the same SQL Server instead, leaving the eDocs database untouched.

# Prerequisites

  • OpenText eDocs deployed and accessible via SQL Server
  • SQL Server login with read access to the DOCSADM schema and write access to create and populate the _EDMS* tracking tables (in the eDocs database, or in the separate MigrationDatabase if configured)
  • Read access to the eDocs file storage (network share where document binaries are stored)
  • Target SharePoint matter sites provisioned by Epona ProvisioningService
  • SharepointCfg JSON file configured with the target SharePoint tenant credentials

# Deployment

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

# Step 1 — Configure the connection

The OpenText connector connects to the eDocs SQL Server database using the Database dropdown in the main window.

  1. In the main window, click Create/Edit Database

  2. Add a new connection and set the following fields:

    Field Value
    Name Descriptive identifier (e.g., ClientName-eDocs)
    Server SQL Server hostname or instance (e.g., edocs-sql or edocs-sql\SQLINSTANCE)
    Database eDocs database name (typically DOCSADM)
    UserName Leave blank for Windows integrated authentication, or enter a SQL Server login
    Password Leave blank for Windows integrated authentication, or enter the password
    MigrationDatabase (Optional) Name of a separate database on the same SQL Server to hold the migration tracking tables (_EDMS*). Leave blank to create them in the eDocs database itself. See Separate migration database.

  3. Click Save — the connection appears in the main Database dropdown

  4. Select the connection from the Database dropdown

TIP

The connection must reach the SQL Server database that contains the DOCSADM schema (tables such as DOCSADM.PROFILE, DOCSADM.MATTER, DOCSADM.CLIENT). The connector creates the _EDMSDocument (and other _EDMS*) tracking tables in the dbo schema on the first run, if they don't exist yet — in the eDocs database, or in MigrationDatabase if configured.

# Separate migration database

By default the _EDMS* tracking tables are created in the eDocs database. To keep that database untouched, set MigrationDatabase to the name of another database on the same SQL Server. The connector then creates and reads the tracking tables there, addressing them via three-part names ([MigrationDatabase].dbo._EDMSDocument) over the single connection — so delta queries can still join the tracking data to the eDocs source tables.

The migration account then needs, on MigrationDatabase:

  • CREATE TABLE — to create the _EDMS* tables on the first run (and timestamped backup copies on Remove)
  • db_datareader, INSERT, UPDATE — to read and record migration progress
  • ALTER — to truncate the tracking table when using Remove; if not granted, the connector falls back to DELETE

The MigrationDatabase must already exist on the server; the connector creates only the tables, not the database. Read access to the DOCSADM.* tables in the eDocs database is still required.

# Step 2 — Configure settings

In the OpenText tab, click the ... button next to the configuration dropdown to open the OpenText Configuration editor. Settings are grouped into three categories.

# Global

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

# Migrate

Setting Type Default Description
ClientMatterSeparator char @ Character used to split the value entered in the Workspace(s) text box into a client code and a matter code. Only needed when matter codes are not unique in the source — i.e., the same matter code can exist under different clients. For example, entering ABC@001 with separator @ yields client ABC and matter 001. If the entered value does not contain the separator, it is treated as a matter code only. If set to null, splitting is disabled and the entire input is treated as a matter code.
CombineClientAndMatterCodeToMatterCode string — If set, combines the client code and matter code into a single matter code using this character as the separator (e.g., _ produces ABC_001). Use this when the target matter site in SharePoint is identified by a combined client-matter code rather than the matter code alone. If empty, the matter code from the source is used as-is for the SharePoint target lookup.
ImportDocumentPermissions bool false Migrate document-level permissions from eDocs to SharePoint. Before enabling, read the performance impact warning in Step 6 — a high number of uniquely secured documents can significantly degrade SharePoint performance. If false, no document permissions are migrated. On an environment using Azure Blob upload, enabling this together with UseAzureBlobStorage is blocked at import time (the Blob manifest does not carry permissions) — apply permissions from the Step 6 export instead.
ImportFolderPermissions bool false Migrate folder-level permissions during Folder and Workspace import (see Step 4b). When enabled, each created SharePoint folder receives the eDocs folder's ACLs, mapped through the same Permission…ToRoleDefinition settings as documents; when disabled, folders inherit permissions from their parent. The import start prompt states whether folder-permission import is on. No effect in Field import mode.
CreateEmptyDirectories bool false Create empty folders in SharePoint for eDocs folders that contain no documents. Applies to Folder and Workspace import.
TrackChangesInDocumentProfile bool false By default a document is re-imported only when a version's content changed (its DOCSADM.VERSIONS.LASTEDITDATE). Enable this to also re-import when the document's profile/metadata changed — the delta check then additionally compares DOCSADM.PROFILE.LAST_PRF_EDIT_DATE, so a metadata-only edit (for example a renamed document or a changed custom field) re-uploads the latest version to push the updated columns to SharePoint. Ignored on older schemas that lack LAST_PRF_EDIT_DATE. Side effect: SharePoint's Modified date then reflects the later of the content edit and the metadata edit.
TimeZone integer 93 (UTC) Time zone of the date columns in the source eDocs database. The connector converts document Created/Modified dates from this time zone to UTC before writing them to SharePoint. eDocs stores these dates in UTC, so the default 93 (UTC = no conversion) is correct for virtually all databases — leave it at UTC. Only change it if you have verified the source values are not UTC; a wrong setting shifts every Created/Modified date in SharePoint by the offset. To confirm, compare a document's date in the eDocs client against the raw CREATION_DATE/CREATION_TIME in the database; if those stored values are genuinely not UTC, set this to the time zone the values are in (see the SharePoint time zone IDs (opens new window)).
PermissionReadToRoleDefinition string Read SharePoint role definition name assigned for eDocs Read permission. If empty, eDocs Read grants are not mapped to any SharePoint role.
PermissionReadWriteToRoleDefinition string Contribute SharePoint role definition name assigned for eDocs Read/Write permission. If empty, eDocs Read/Write grants are not mapped.
PermissionFullAccessToRoleDefinition string Full Control SharePoint role definition name assigned for eDocs Full Access permission. If empty, eDocs Full Access grants are not mapped.
PermissionNoneToRoleDefinition string — SharePoint role definition name assigned for eDocs No Access permission. If empty, eDocs No Access entries are skipped and no permission is written.
DocumentTypeToContentTypes string — Maps eDocs document type IDs to SharePoint content type names. Format: DOCTYPE1=ContentTypeName1;DOCTYPE2=ContentTypeName2; (semicolon-separated) or one mapping per line. Both formats are equivalent — newlines are converted to semicolons internally. If empty, all documents fall through to DefaultDocumentContentType or DefaultEmailContentType.
DefaultDocumentContentType string — Default SharePoint content type for documents whose type is not in DocumentTypeToContentTypes. If empty, the document library's default content type is used.
DefaultEmailContentType string — Fallback content type for email documents not matched by DocumentTypeToContentTypes. If empty, the email content type from the DMS Configuration list is used. Content type resolution order for emails: (1) ForceEmailContentType in SharepointCfg wins if set; (2) DocumentTypeToContentTypes if the email's document type is mapped; (3) this setting; (4) DMS Configuration list.
DocumentTypeToFolders string — Maps eDocs document type IDs to target subfolder paths within the document library. Format: DOCTYPE1=Correspondence;DOCTYPE2=Contracts; (semicolon-separated) or one mapping per line. Applied per document based on its document type. If a workspace redirect with a subfolder is specified (e.g., 001234=NEWCODE/Correspondence), that subfolder takes precedence and DocumentTypeToFolders is not applied for that run. If empty (and no redirect subfolder), documents are uploaded to the document library root.
ReplaceFolders string — Renames source folder paths before they are created in SharePoint. Format: OldPath=NewPath;OldPath2=NewPath2; Not yet implemented — this setting has no effect in the current version.
MatterField string — DOCSADM.PROFILE column name used to select documents for import. Documents are filtered by comparing this column to the value entered in the Workspace(s) field, matched on the stored value (i.e. the SYSTEM_ID for lookup and user columns). Usually a matter custom field (for example, FRB_LGLFILE), but any PROFILE column works — including user columns such as AUTHOR or TYPIST to import by a user's SYSTEM_ID (see Choosing the field to import by). When a database connection is selected, the configured column is validated against DOCSADM.PROFILE on save. Leave empty if the database does not use a field for matter identification.
ReplaceUserNames string — Maps eDocs user IDs (USER_ID) to SharePoint/Microsoft 365 login names. Applied to the document Author, CreatedBy and ModifiedBy fields and to user permission entries. Format: USER_ID=user@domain.com; (semicolon-separated) or one mapping per line. Fill the _M365UserName column on the Users dump sheet and copy the _UserMapping column here. Unmapped users are written through unchanged. This is OpenText-specific — it does not use the shared SettingsCfg.ReplaceUserGroupNames.
ReplaceGroupNames string — Maps eDocs group IDs (GROUP_ID) to SharePoint/Microsoft 365 group names. Applied to group permission entries. Format: GROUP_ID=SharePoint Group Name; (semicolon-separated) or one mapping per line. Fill the _M365GroupName column on the Groups dump sheet and copy the _GroupMapping column here. Unmapped groups are written through unchanged. OpenText-specific.

# Metadata

These settings map eDocs metadata fields to SharePoint column names. Leave empty to skip writing the corresponding column.

Setting Description
Author SharePoint column (internal name) that receives the eDocs document author (USER_ID, mapped through ReplaceUserNames). If empty, the author column is not written.
DocumentNumber SharePoint column (internal name) for the eDocs document number (without version). If empty, the column is not written.
DocumentNumberVersion SharePoint column (internal name) for the eDocs document number combined with the version (e.g., 12345.1). If empty, the column is not written.
DocumentType SharePoint column (internal name) for the eDocs document type code. If empty, the column is not written.
CustomFields Maps eDocs custom field column names (as they appear on DOCSADM.PROFILE) to SharePoint column internal names. Format: OTFieldName=SharePointColumnName;OTFieldName2=SharePointColumnName2 (semicolon-separated) or one mapping per line. The CustomFields sheet in the Dump output lists available custom field names (requires DOCSADM.ATTRIBUTE). For lookup-type fields (integer foreign keys referencing a lookup table), the connector automatically resolves the integer to a display value (DESCRIPTION preferred, then NAME, then CODE). If the eDocs database is an older version without custom fields, the setting is silently ignored.

# Remapping field values

The CustomFields and DocumentType settings control which SharePoint column each value lands in. To translate the value itself — for example when eDocs stores codes or abbreviations that should become human-readable text in SharePoint — use SettingsCfg.DynamicFieldValueMapping in the SharepointCfg, scoping each mapping with the OpenText. prefix:

  • OpenText.DocumentType — remap document type codes
  • OpenText.<FieldName> — remap a custom field value, where <FieldName> is the field's DOCSADM.PROFILE column name — i.e. the value in the FieldName column of the CustomFields dump sheet (the COLNAME, which is also the left-hand side of a CustomFields entry). Use FieldName, not the Label column.

A mapping without the OpenText. prefix applies globally to that field name. The mapping supports wildcard matching and an UnknownValue fallback for unmatched values. See Dynamic Name → DynamicFieldValueMapping for the full reference, including the OpenText integration prefix.

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

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

The Excel file contains the following sheets (in order):

Sheet Contents Typical use
Overview Database-wide totals (see Overview metrics) Get a quick picture of the migration scope before drilling into the detail sheets
DocumentTypes TYPE_ID, DESCRIPTION, DISABLED, DocumentCount Build the DocumentTypeToContentTypes and DocumentTypeToFolders mappings
Users SYSTEM_ID, USER_ID, FULL_NAME, EMAIL_ADDRESS, ALLOW_LOGIN, DISABLED, NETWORK_ID, LAST_LOGIN_DATE, DocumentCount, _MatterCode, _MatterMapping, _M365UserName, _UserMapping Map eDocs users to Microsoft 365 accounts. DocumentCount shows whether a user is actually used. Fill _M365UserName and copy _UserMapping into ReplaceUserNames (CreatedBy/ModifiedBy + permissions). SYSTEM_ID + _MatterCode/_MatterMapping let you import by user — see Choosing the field to import by.
Groups GROUP_ID, GROUP_NAME, DISABLED, DocumentCount, _M365GroupName, _GroupMapping Map eDocs security groups to SharePoint/Microsoft 365 groups. DocumentCount shows whether a group is actually used. Fill _M365GroupName and copy _GroupMapping into ReplaceGroupNames (group permissions).
Workspaces WorkspaceId, WorkspaceName, DocumentCount, CreatedBy, CreateDate Plan workspace-level migration mapping (see Folders and Workspaces)
Folders FolderId, WorkspaceId, Workspace, FolderPath, FolderName, Depth, DocumentCount, CreatedBy, CreateDate, Secured Plan folder-level migration mapping (see Folders and Workspaces)
Duplicate Folders FolderId, FolderName, PlacementCount, Workspace, FolderPath Spot folders filed in more than one place (see Duplicate folders)
CustomFields FieldName, Label, FieldType, MaxLength, LookupTable from DOCSADM.DOCSCOLUMN Identify available custom field names to use in CustomFields mapping. Empty if the eDocs database is an older version without custom fields.
{LookupTableName} (one sheet per custom lookup or fixed combo field) All lookup columns + DocumentCount + _MatterCode + _MatterMapping (lookup fields), or Code + Description + _MatterCode + _MatterMapping (fixed combo fields) Lists all values for each custom field, with how many documents use each value, and the _MatterCode/_MatterMapping helper columns for mapping values to matters. Only appears when the field has a lookup table or a fixed set of values.

User and group mapping

Run Dump before the first Import to get the full user and group list. eDocs USER_ID/GROUP_ID values typically do not match SharePoint login names or group names, so map them in the OpenText configuration: fill the _M365UserName / _M365GroupName column on the Users / Groups sheet, then copy the generated _UserMapping / _GroupMapping column into the ReplaceUserNames / ReplaceGroupNames settings. ReplaceUserNames is applied to the document Author/CreatedBy/ModifiedBy fields and to user permission entries; ReplaceGroupNames to group permission entries. These are OpenText-specific — they replace the use of the shared SettingsCfg.ReplaceUserGroupNames. Use the DocumentCount column to skip users/groups linked to no documents — they do not need mapping.

# Overview metrics

The Overview sheet lists database-wide totals. Every count of documents follows the same rule: non-deleted, distinct documents, regardless of the number of versions (deleted documents — STORAGETYPE = 'D' — are never migrated, so they are excluded everywhere except the explicit Deleted documents metric). A metric shows n/a when its tables or columns are absent on older eDocs schemas.

Metric Meaning
Total documents All non-deleted documents
Documents with multiple versions Documents that have more than one version
Documents stored in a folder Non-deleted documents filed in at least one folder
Documents in multiple folders Documents filed in more than one folder (these are still migrated once — see Duplicate folders)
Documents not stored in a folder Non-deleted documents not filed in any folder
Secured documents Documents with explicit (non-inherited) security
Deleted documents Documents marked deleted — these are not migrated
Total workspaces Top-level containers (PROFILE.ITEM_TYPE = 'W')
Non-empty folders Folders directly containing at least one non-deleted document
Empty folders Folders containing no non-deleted documents
Duplicate folders Folders filed under more than one parent (see Duplicate folders)
Secured folders Folders with explicit (non-inherited) security — the volume migrated when ImportFolderPermissions is enabled
Max folder depth Deepest folder nesting level
Total custom fields User-added / lookup custom fields on DOCSADM.PROFILE

# Folders and Workspaces

eDocs containers nest as workspace → folder → documents. Workspaces are the top-level containers (PROFILE.ITEM_TYPE = 'W'); their name lives in PROFILE.PATH. A workspace carries no matter code, so to migrate at workspace or folder level you map its identifier to a SharePoint matter code manually (<id>=<mattercode>).

  • Folders sheet — one row per folder placement. FolderId is the folder's eDocs document number and the key you map and traverse (children link to it via their parent) — it is the value you enter to import a folder. FolderPath is the full path including the folder's own name but excluding the workspace; Workspace is shown in its own column. DocumentCount is the distinct non-deleted documents directly in that folder.
  • Workspaces sheet — one row per workspace. WorkspaceId is the value you enter to import a workspace. DocumentCount is the distinct non-deleted documents anywhere under the workspace (in any folder of its tree plus any filed directly under it).

Mapping a FolderId (or WorkspaceId) to a matter migrates that folder/workspace and recursively all of its child folders into the same folder structure in SharePoint — see Step 4b.

# Duplicate folders

A folder can be filed under more than one parent at the same time (it is "multi-filed"). Because it is one folder with one FolderId, it appears once per placement in the Folders sheet — the Duplicate Folders sheet lists exactly these folders so you can see every location at a glance. PlacementCount is how many places the folder is filed.

Documents are migrated once, not once per location

A document filed in multiple folders, or a folder filed under multiple parents, is migrated a single time — the duplicate placements are reported for transparency only, not migrated repeatedly. The Documents in multiple folders and Duplicate folders metrics on the Overview sheet exist so you understand the source structure; they do not mean documents are copied multiple times into SharePoint.

# Choosing the field to import by

MatterField can point at any DOCSADM.PROFILE column — a dedicated matter code column, a lookup or fixed-combo custom field, or a user column (AUTHOR, TYPIST, LAST_EDITED_BY, etc.). Each distinct value of that column maps to a target SharePoint matter, so you can group documents by whichever attribute fits the source data.

The filter matches on the stored value. Lookup and user columns store an integer key (SYSTEM_ID), not the readable label; plain text columns store the text itself. To build the mapping:

  1. Set MatterField to the column you want to import by, e.g. AUTHOR or a custom field.
  2. Run Dump and open the value sheet for that field — the Users sheet for a user column, or the field's own value sheet for a custom field. For each value you want to migrate, type the target SharePoint matter code into the _MatterCode column.
  3. The _MatterMapping column then shows the ready-to-use entry — e.g. 1234=SmithMatter (stored value = your matter code). Copy the filled _MatterMapping cells straight into the Workspace(s) field (see Step 4 for the full redirect and subfolder syntax).

To land a value's documents in a specific subfolder, append /SubFolderPath to its target matter code — e.g. 1234=SmithMatter/Correspondence. The same _MatterCode/_MatterMapping helper columns appear on every value sheet; lookup and user fields key on the stored SYSTEM_ID, fixed-combo fields key on their Code.

# Step 4 — Initial migration by matter code

The Import mode dropdown selects how documents are selected for migration:

  • Field (default) — by a DOCSADM.PROFILE field value; covered in this step. Requires MatterField to be set.
  • Folder / Workspace — by folder or workspace; covered in Step 4b.

  1. Select the OpenText configuration from the OpenText dropdown

  2. Select the database connection from the main window Database dropdown

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

  4. 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 to be set
    Redirect: source → target 001234=NEWCODE Source matter code differs from the SharePoint matter site identifier
    Redirect with client codes ABC@001234=XYZ@NEWCODE Redirect with both source and target client codes
    Redirect with subfolder 001234=NEWCODE/Correspondence Documents land in Correspondence subfolder of the target matter's document library

    Multiple entries: ABC@001234;ABC@001235 or one per line.

    How the redirect (=) works:

    The part before = identifies the matter in eDocs (used for the SQL query). The part after = is used to look up the matter site in SharePoint. Use this when the eDocs matter code and the SharePoint matter site identifier do not match. If no = is present, the same value is used for both the eDocs query and the SharePoint lookup.

    Subfolder routing (only available with redirect): append /SubFolderPath after the target matter code to place documents in a specific subfolder within the document library. Path separators are / or \. This requires the = redirect syntax — subfolder routing is not available without it.

  5. Click Import

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

What happens during Import:

  1. The connector creates the _EDMS* tracking tables if they do not already exist (in the eDocs database, or in MigrationDatabase if configured)
  2. For each matter code, the connector queries the eDocs database for documents belonging to that matter. The query automatically excludes documents that were already successfully migrated and have not changed since — a document is included only if it has no entry in _EDMSDocument, has an error (retry), or its LASTEDITDATE in eDocs is newer than the SourceLastModified recorded in _EDMSDocument (modified since last run). When TrackChangesInDocumentProfile is enabled, a profile/metadata edit (a newer LAST_PRF_EDIT_DATE) also counts as a change
  3. Each document is uploaded to the corresponding SharePoint document library — via CSOM, or via the Azure Blob pipeline when UseAzureBlobStorage is enabled — with metadata applied according to the configured column mappings
  4. If ImportDocumentPermissions is enabled, document-level permissions are read from eDocs and applied in SharePoint on the CSOM upload path only. The Azure Blob manifest does not carry document permissions, so Import blocks when ImportDocumentPermissions and UseAzureBlobStorage are both enabled — on Azure Blob, migrate without document permissions and apply them afterwards from the Permissions export. (Folder permissions in Folder/Workspace mode are applied via CSOM and work regardless of upload method.)
  5. Each processed document version is recorded in _EDMSDocument with its SharePoint target location and any error

The progress bar in the main window shows per-matter progress. Errors are logged and recorded in _EDMSDocument.Error.

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".

# Step 4b — Folder and Workspace migration

Instead of selecting documents by a field value, you can migrate a whole eDocs folder or workspace subtree, recreating its folder structure in SharePoint. Choose Folder or Workspace in the Import mode dropdown.

  1. Run Dump and open the Folders or Workspaces sheet.
  2. In the Workspace(s) text box, enter the FolderId (Folder mode) or WorkspaceId (Workspace mode) of each item to migrate — one per line, or semicolon-separated. These are eDocs document numbers, not matter codes.
  3. Because a workspace carries no matter code, route each one to its SharePoint matter with the redirect syntax: <FolderId>=<mattercode> — and optionally a subfolder, <FolderId>=<mattercode>/<subfolder>. The same = redirect and /subfolder rules as Step 4 apply; the part before = is the folder/workspace to import, the part after = is the SharePoint target.
  4. Click Import. The start prompt states whether folder-permission import is on (see ImportFolderPermissions).

What happens:

  • The folder (or workspace root) and all of its child folders are recreated under the target matter; each folder's documents are uploaded into the matching SharePoint subfolder. Document upload, metadata, delta tracking and ImportDocumentPermissions behave exactly as in Field mode.
  • The folder's own name is not prepended to the target path — its contents land under the target matter (and the /subfolder you specified, if any), with child folders nested below. Use the /subfolder redirect to place the tree under a specific folder.
  • If ImportFolderPermissions is enabled, each created folder receives the eDocs folder's ACLs (mapped through the Permission…ToRoleDefinition settings); otherwise folders inherit from their parent.
  • If CreateEmptyDirectories is enabled, folders with no documents are still created.

Each folder is migrated once

If you enter several folders/workspaces and one is already contained within another you entered (directly or as a nested subfolder), it is migrated once, under the highest selected ancestor. A folder filed under multiple parents (a duplicate folder) is likewise imported only once per run. Skipped duplicates are logged.

# Step 5 — Delta migration

Subsequent Import runs automatically use delta mode when the _EDMSDocument table 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?
    • Yes — copies the current table to _EDMSDocument_{yyyyMMdd_HHmmss} before continuing
    • No — continues without backup
    • Cancel — aborts the import
  3. Documents already migrated successfully are skipped — only new or changed documents are uploaded. The delta check is done at the SQL level: a document version is re-queued only if it has no entry in _EDMSDocument, has a recorded error (retry), or its LASTEDITDATE in eDocs is newer than the SourceLastModified recorded in _EDMSDocument. When TrackChangesInDocumentProfile is enabled, a profile/metadata edit (a newer LAST_PRF_EDIT_DATE) also re-queues the document

Starting fresh (removing delta):

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, if the table contains records, its contents are automatically copied to a timestamped backup table (_EDMSDocument_{yyyyMMdd_HHmmss}), then the table is truncated. The next Import run will treat all matters as a fresh migration.

When to use Remove

Use Remove when you want to re-migrate all documents from scratch — for example, after a test migration before going live, or when the SharePoint target has been recreated.

# Step 6 — Permissions

Click Permissions to export document- and folder-level permission assignments from eDocs to an Excel file.

Performance impact of document-level permissions

A large number of documents with unique permissions significantly degrades SharePoint performance — each uniquely secured item breaks permission inheritance and increases the load on SharePoint's security model.

Before deciding to migrate permissions, check the Overview sheet from the Dump output: it shows Secured documents (documents with custom permissions) against Total documents. If the ratio is high, discuss with the client whether document-level security needs to be migrated at all. In many cases, applying permissions at the document library or folder level (via the SharePoint provisioning configuration) provides adequate access control with much better performance. Only migrate document-level permissions when the business genuinely requires per-document security.

If you do proceed, run Permissions after migration to get the full per-document permission export for import into SharePoint.

On click, a prompt asks which objects to include:

  • Yes — only objects already migrated to SharePoint (those with a target Url in _EDMSDocument). Use this to produce a file ready to import.
  • No — every object with explicit security in eDocs, migrated or not. Migrated rows get their Url and client/matter filled; the rest are left empty (useful as a full pre-migration security overview). On a database with many secured objects this is larger and slower.

Prerequisites:

  • Only objects with non-inherited (explicit) security in eDocs are included
  • The target Url (and client/matter) is filled from _EDMSDocument for migrated objects; run the dump after migration (or re-run it) to obtain the target URLs needed for import

Output files: two workbooks in Migrate\, one per object type:

  • OpenTextFilePermissionSet{ConfigName}_{timestamp}.xlsx — document permissions (FilePermissions)
  • OpenTextFolderPermissionSet{ConfigName}_{timestamp}.xlsx — folder permissions (FolderPermissions)

They are separate files (not two sheets in one) because the Permission Set file handler imports only a workbook's first sheet — each file is therefore independently importable.

FilePermissions columns:

Column Description
__ClientCode Target SharePoint client code (derived from the matter the document was migrated under, not the eDocs PROFILE.MATTER hierarchy)
__MatterCode Target SharePoint matter code (derived from the matter the document was migrated under)
__DocumentNumber eDocs document number
Url Target SharePoint URL (from _EDMSDocument); empty when the document has not been migrated yet
DisableInheritance Always True — breaks permission inheritance on the document
RemovePermissions Always True — removes existing permissions before applying the new set
DomainMembers.{RoleName} Semicolon-separated domain accounts for this role (one column per role)
Groups.{RoleName} Semicolon-separated group names for this role (one column per role)

The role names ({RoleName}) correspond to the SharePoint role definitions configured in the migration settings (PermissionReadToRoleDefinition, etc.).

FolderPermissions columns: the same as FilePermissions, except __DocumentNumber is replaced by __FolderId (the eDocs folder document number) and Url is the target SharePoint folder URL. It lists the migrated folders that carry explicit security in eDocs. Each folder's URL is reconstructed from where its documents were migrated, so a folder appears only if at least one of its documents was migrated and the folder has explicit security. This file is useful when folder ACLs were not applied during import (ImportFolderPermissions off) and you want to apply them afterwards.

# Applying the export

Each file is applied through site provisioning with the Permission Set file handler, which reads every row and sets the permissions on the target object (by Url). Both file names contain PermissionSet, the name match the handler requires, so each can be run independently. Review and adjust the role columns first, then run them as part of the provisioning configuration. Rows with an empty Url (items not yet migrated) cannot be applied — migrate first, then re-export to obtain their target URLs.

# Step 7 — Migration report

Click Report to export the contents of the _EDMSDocument tracking table 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 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.

The report is grouped by the matter each document was migrated under (the value entered in the Workspace(s) field, recorded per document). The target SharePoint client/matter columns are derived from that value the same way the import resolves them — so the report is correct regardless of how the documents were selected from the source (by field, folder or workspace). It does not re-read the eDocs PROFILE.MATTER/CLIENT hierarchy. For how many documents exist in the source, use the Dump (its DocumentCount columns).

Output file: OpenTextMigrate_{ConfigName}_{timestamp}.xlsx

Sheets:

Sheet Contents
Migration One row per migrated-under matter: target ClientCode/MatterCode, the raw MigrateSource value, migrated document-version count, and error count
Error Matters Matters that have at least one document with an error
Error Documents Individual failed document versions: target client/matter, MigrateSource, source document number and version, target URL, and the error message

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 standard migration table (shared with the iManage connector) in the dbo schema — in the eDocs database, or in MigrationDatabase if configured. It replaces the older OpenText-specific _ToDMSforLegal table.

Column Type Description
ID int (identity) Primary key
SharepointFileId varchar(50) SharePoint file identifier (set by the Azure pipeline)
MigrateSource nvarchar The client/matter code entry the document was migrated under
Source nvarchar eDocs document number
SourceVersion varchar eDocs version label
SourceLastModified datetime Source modified date at time of migration (used for delta detection)
TargetDocLib nvarchar Target document library server-relative URL
TargetFolder nvarchar Target folder within the document library
TargetFileName nvarchar File name in SharePoint after upload
TargetDocumentNumber varchar SharePoint document ID after upload
TargetDocumentVersion varchar SharePoint version after upload
Error varchar Error message if the document failed; empty if successful
Modified datetime When the row was last updated
Created datetime When the row was first created

The full target URL shown in the File Permissions export and report is composed from TargetDocLib + TargetFolder + TargetFileName.

# Configuration file location

OpenText configurations are saved as JSON files in:

[Epona.Migrate.exe directory]\Config\OpenText\{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 OpenText migrations.

Setting Description
UseAzureBlobStorage When true, documents are uploaded through the Azure Blob pipeline instead of direct CSOM. Default false (direct CSOM).
CleanupOffice2003Documents Strip doc properties from .doc/.xls/.ppt/.msg files before upload. Useful when old Office files have sensitive internal properties.
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.

# Migrating from a database copy (production isolation)

When write access to the production eDocs database is not permitted, run the migration against a restored copy on a separate server. This also prevents the migration workload from impacting production performance.

Recommended: keep tracking in a separate MigrationDatabase

Set MigrationDatabase on the database connection (see Separate migration database) to a dedicated database that you do not overwrite between restores. The _EDMS* tracking tables then live outside the eDocs copy, so you can restore a fresh copy of the production database for each delta run without losing migration progress — no row-copying step is needed. The connector creates the _EDMS* tables automatically on the first run.

# Initial migration

  1. Restore the production eDocs database to a separate SQL Server instance
  2. (Optional) Create an empty MigrationDatabase on the same server and set it on the connection
  3. Configure the migration tool connection to point to the restored copy
  4. Run the migration as normal (see Steps 1–7) — the _EDMS* tracking tables are created automatically

# Delta migrations

For each subsequent delta run, restore a fresh copy of the production database. If you use a separate MigrationDatabase (recommended), just point the connection at the new copy and run — the tracking data is preserved automatically.

If instead the tracking tables live inside the eDocs copy, do not overwrite the previous copy, as it still holds the _EDMSDocument tracking data:

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

  2. Copy the tracking rows from the previous copy into the new database (the _EDMSDocument table is created automatically on the first run, or pre-create it; the ID column is an identity and is intentionally excluded):

    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 [PreviousCopyDatabaseName].[dbo].[_EDMSDocument];

    Replace PreviousCopyDatabaseName with the actual name of the previous database copy. The delta logic keys on Source (document number) and SourceVersion, not ID.

  3. Update the migration tool connection to point to the new database copy

  4. Run the delta migration as normal — the connector will skip documents already recorded in _EDMSDocument and process only new or changed ones

# SQL scripts

The deployment zip includes the following SQL scripts in the sql\ folder. Run them directly in SQL Server Management Studio against the eDocs database for diagnostics or pre-setup.

Pre-creating the tracking tables

The connector creates the _EDMS* tracking tables automatically on the first run. If the migration account lacks CREATE TABLE rights, a DBA can pre-create them: the migrator writes the exact creation script to MigrateDb\CreateMigrationTablesSqlServer.sql (next to Epona.Migrate.exe) on every startup — run that script against the database that holds the tracking tables (the eDocs database, or the separate MigrationDatabase).

Script Purpose
DumpContent.sql Generic source overview for SSMS: overview totals (documents, deleted, secured, workspaces), document types, users and groups (all with document counts and SYSTEM_ID), custom fields, and folders (with full path and per-folder document count). Uses the same counting logic as the Dump button. The folders section needs ufnFolderPath.sql installed first. The Dump button produces the full, authoritative breakdown (folder/workspace sheets and custom-field value sheets with matter-mapping helper columns); use this script only for a quick look.
PendingDocuments.sql Shows the document versions still pending migration (the delta filter against _EDMSDocument), across all documents. Add your own WHERE on the relevant DOCSADM.PROFILE column to narrow it to a matter. Use this to verify which documents will be picked up (or skipped) before running Import.
ufnFolderPath.sql Creates the dbo.ufn_FolderPath(@profileID) function (CREATE OR ALTER) that resolves a document's or folder's path by traversing the DOCSADM.FOLDER_ITEM parent chain, returning a /-separated path. Install with a DBA account against the eDocs database — required by the folders section of DumpContent.sql.

# Troubleshooting

# Cannot connect to the eDocs database

  • Cause: SQL Server connection string is incorrect, server is unreachable, or the login lacks permissions
  • Resolution: Verify the connection string in Create/Edit Database; test connectivity with SQL Server Management Studio; ensure the login has db_datareader on DOCSADM schema and rights to create and write the _EDMS* tables on the dbo schema (in the eDocs database, or in MigrationDatabase if configured)

# "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 configured incorrectly
  • Resolution: Verify the matter code format in the Dump output (the value sheet for your MatterField — e.g. its lookup-table sheet); check whether client and matter codes need to be combined using CombineClientAndMatterCodeToMatterCode; confirm the target matter site exists in SharePoint

# Import processes fewer matters than expected

  • Cause: Matters that have zero documents in eDocs are silently skipped — they consume a line in the text box but produce no import activity and are not counted in the progress.
  • Resolution: Run Dump and check the value sheet for your MatterField (its lookup-table sheet). The DocumentCount column shows how many documents each value has. Values with DocumentCount = 0 will be skipped even if their code is listed in the Workspace(s) text box.

# Zero documents migrated for a matter

  • Cause: The matter has no documents in eDocs that match the query (documents in folder workspaces are handled differently from top-level documents), or all documents were already migrated (delta mode)
  • Resolution: Check the value sheet for your MatterField from the Dump — verify DocumentCount > 0; if doing a fresh migration, use Remove to clear the delta table

# Document metadata is wrong (wrong author, date, type)

  • Cause: Author, DocumentNumber, DocumentType metadata settings do not match the actual SharePoint column names, or the target columns do not exist on the content type
  • Resolution: Verify SharePoint column internal names match the values set in the OpenText configuration (Metadata section)

# Permissions not applied after migration

  • Cause: ImportDocumentPermissions is false, or the USER_ID/GROUP_ID values from eDocs are not mapped to valid SharePoint login names or group names
  • Resolution: Enable ImportDocumentPermissions; use the Users and Groups sheets from the Dump output to build the OpenText ReplaceUserNames and ReplaceGroupNames mappings (fill _M365UserName/_M365GroupName, copy the _UserMapping/_GroupMapping columns). The connector keys on USER_ID and GROUP_ID — each must map to the corresponding SharePoint login name (UPN) or group name. Format: USER_ID=user@domain.com; and GROUP_ID=SharePoint Group Name;

# Content type not found

  • Cause: A document type in DocumentTypeToContentTypes maps to a content type name that does not exist on the target SharePoint 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

# Custom field values not written to SharePoint

  • Cause: The field name in CustomFields does not match the column name in DOCSADM.PROFILE, or the SharePoint column internal name is incorrect
  • Resolution: Run Dump and check the CustomFields sheet — use FIELD_NAME exactly as it appears there. Verify the SharePoint column internal name is correct (internal names are case-sensitive and may differ from the display name). If the CustomFields sheet is empty, the eDocs database is an older version without custom fields — the CustomFields setting has no effect.

# CustomFields sheet is empty after Dump

  • Cause: The eDocs database is an older version that does not have the DOCSADM.ATTRIBUTE table. This is expected and backwards compatible — the migration continues normally without custom fields.
  • Resolution: No action needed. If custom fields are required and the source database is old, confirm with the client whether custom fields exist.
Last Updated: 7/7/2026, 1:48:24 PM

← SharePoint migration connector →