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-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
  • Matter-scoped import — migrates one or more matters per run, specified by client/matter code

Azure Blob Storage not supported

The OpenText connector uses direct CSOM upload only. If UseAzureBlobStorage is enabled in the SharepointCfg, the Import button will show a warning and refuse to start. Disable this option in the SharePoint configuration before migrating from OpenText.

# How it differs from other connectors

Unlike the filesystem, iManage, 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 table in the source database — the _ToDMSforLegal table is created directly inside the eDocs SQL Server database, not in a separate migration database. It can also be created manually in advance using CreateDeltaTable.sql, included in the deployment zip file.

# 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 _ToDMSforLegal table in the eDocs database
  • 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
  • UseAzureBlobStorage must be disabled in the SharepointCfg SettingsCfg.Migrate section

# 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

  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 _ToDMSforLegal tracking table in the dbo schema of this same database on the first Import run, if it doesn't exist yet.

Pre-creating the tracking table

If the migration account should not have DDL rights, a DBA can pre-create the _ToDMSforLegal table using CreateDeltaTable.sql, included in the deployment zip. Run this script against the eDocs database with an account that has db_ddladmin or db_owner on the database.

After pre-creation, the migration account requires:

  • db_datareader on the database — for read access to DOCSADM.* tables and _ToDMSforLegal
  • INSERT, UPDATE on dbo._ToDMSforLegal — to record migration progress
  • ALTER on dbo._ToDMSforLegal — to truncate the table when using Remove; if not granted, the connector falls back to DELETE
  • CREATE TABLE on the database — required to create timestamped backup copies (_ToDMSforLegal_{timestamp}). These backups are created when the user chooses Yes at the delta backup prompt during Import, and always when using Remove. If CREATE TABLE is not granted, declining the backup prompt during Import allows the import to proceed, but Remove will always crash with a SQL exception.

# 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.
ImportViaDocumentMetaData bool true Import documents using metadata-based lookup. Setting this to false is not yet implemented — the Import button will show an error if disabled.
ImportDocumentPermissions bool true 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.
CreateEmptyDirectories bool false Create empty folders in SharePoint for eDocs folders that contain no documents. Not yet implemented — this setting has no effect in the current version.
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.

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

# 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 five sheets:

Sheet Contents Typical use
Clients CLIENT_ID, CLIENT_NAME, DISABLED Verify which clients are in scope
Matters ClientCode, ClientName, MatterCode, MatterName, SecureDocumentCount, TotalDocumentCount Identify which matters to migrate and how many documents have custom security
DocumentTypes TYPE_ID, DESCRIPTION, DISABLED, DocumentCount Build the DocumentTypeToContentTypes and DocumentTypeToFolders mappings
Users USER_ID, FULL_NAME, EMAIL_ADDRESS, ALLOW_LOGIN, DISABLED, NETWORK_ID, LAST_LOGIN_DATE Map eDocs users to Azure AD/Microsoft 365 accounts for permission migration
Groups GROUP_ID, GROUP_NAME, DISABLED Map eDocs security groups to SharePoint or Microsoft 365 groups for permission migration

User and group mapping

Run Dump before the first Import to get the full user and group list. Permission assignments use the USER_ID and GROUP_ID values directly. Because these eDocs identifiers typically do not match SharePoint login names or group names, you must map them in the Replace User/Group names setting (SettingsCfg.ReplaceUserGroupNames) in the SharepointCfg. Format: eDocs_USER_ID=sharepoint@domain.com;EDOCS_GROUP=SharePoint Group Name;. Disabled users and groups are excluded from the security query.

# Step 4 — Initial migration by matter code

  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 _ToDMSforLegal tracking table in the eDocs database if it does not already exist
  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 _ToDMSforLegal, has an error (retry), or its LASTEDITDATE in eDocs is newer than the VersionModified recorded in _ToDMSforLegal (modified since last run)
  3. Each document is uploaded to the corresponding SharePoint document library using CSOM, 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
  5. Each processed document version is recorded in _ToDMSforLegal with its SharePoint target URL and any error

The progress bar in the main window shows per-matter progress. Errors are logged and recorded in _ToDMSforLegal.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 5 — Delta migration

Subsequent Import runs automatically use delta mode when the _ToDMSforLegal table already contains records.

How delta works:

  1. On startup, Import checks whether _ToDMSforLegal 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 _ToDMSforLegal_{yyyyMMdd_HHmmss} before continuing
    • No — continues without backup
    • Cancel — aborts the import
  3. Documents already in _ToDMSforLegal with a TargetUrl and no error are skipped — only new or changed documents are uploaded. The delta check is done at the SQL level: a document is re-queued only if it has no entry in _ToDMSforLegal, has a recorded error (retry), or its LASTEDITDATE in eDocs is newer than the VersionModified recorded in _ToDMSforLegal

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 (_ToDMSforLegal_{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 — File permissions

Click File Permissions to export document-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 Matters sheet from the Dump output: it shows SecureDocumentCount (documents with custom permissions) and TotalDocumentCount per matter. 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 File Permissions after migration to get the full per-document permission export for import into SharePoint.

Prerequisites:

  • Documents must already have been migrated (the export cross-references _ToDMSforLegal.TargetUrl)
  • Only documents with non-inherited (explicit) security in eDocs are included

Output file: Migrate\OpenTextFilePermissionSet{ConfigName}_{timestamp}.xlsx

Columns:

Column Description
__ClientCode eDocs client code
__MatterCode eDocs matter code
__DocumentNumber eDocs document number
Url Target SharePoint URL (from _ToDMSforLegal)
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.).

# Step 7 — Migration report

Click Report to export the contents of the _ToDMSforLegal tracking table to Excel. The file is saved to the Migrate\ subdirectory.

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

Sheets:

Sheet Contents
Migration All matters with total document version count, migrated count, and error count
Error Matters Matters that have at least one document with an error
Error Documents Individual document records with error messages

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

# The _ToDMSforLegal tracking table

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

Column Type Description
ID int (identity) Primary key
VersionID int eDocs VERSIONS.VERSION_ID
DocNum int eDocs document number
Version varchar(50) eDocs version string
VersionModified datetime Modified date at time of migration
TargetUrl nvarchar(500) SharePoint URL where the document was uploaded
TargetDocumentNumber nvarchar(50) SharePoint document ID after upload
TargetDocumentVersion nvarchar(50) SharePoint version after upload
Error nvarchar(500) Error message if the document failed; NULL if successful
createDate datetime When the row was first created
modifyDate datetime When the row was last updated

# 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 Must be false — Azure Blob Storage is not supported by the OpenText connector
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.

# Initial migration

  1. Restore the production eDocs database to a separate SQL Server instance
  2. Run CreateDeltaTable.sql against the restored copy to create _ToDMSforLegal with its primary key and indexes
  3. Configure the migration tool connection to point to the restored copy
  4. Run the migration as normal (see Steps 1–7)

# 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 _ToDMSforLegal tracking data that records what was already migrated.

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

  2. Run CreateDeltaTable.sql on the new database to create _ToDMSforLegal 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 first with CreateDeltaTable.sql, then copy the rows.

  3. Copy the tracking rows from the previous copy into the new database:

    INSERT INTO [dbo].[_ToDMSforLegal]
    (VersionID, DocNum, Version, VersionModified, TargetUrl,
     TargetDocumentNumber, TargetDocumentVersion, Error, createDate, modifyDate)
SELECT
    VersionID, DocNum, Version, VersionModified, TargetUrl,
    TargetDocumentNumber, TargetDocumentVersion, Error, createDate, modifyDate
FROM [PreviousCopyDatabaseName].[dbo].[_ToDMSforLegal];

    Replace PreviousCopyDatabaseName with the actual name of the previous database copy. The ID column is an identity and is intentionally excluded — the delta logic uses VersionID and DocNum for lookups, not ID.

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

  5. Run the delta migration as normal — the connector will skip documents already recorded in _ToDMSforLegal 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.

Script Purpose
CreateDeltaTable.sql Creates the _ToDMSforLegal tracking table and its indexes. Idempotent — skipped if the table already exists. Run with a DBA account (db_ddladmin or db_owner) before the first Import if the migration account lacks CREATE TABLE rights.
DumpContent.sql Runs the same queries the Dump button executes: clients, matters with document counts, matters with secure documents, document types, users, and groups. Use this to inspect source data directly in SSMS before running a Dump.
DumpDocuments.sql Returns the top 1,000 documents with full metadata — client, matter, document name, type, version info, author, and typist. Useful for verifying document content and column mappings before starting a migration.
docs.sql Parameterized query (@Client, @Matter) showing exactly which document versions the Import will process for a given matter, including the delta filter against _ToDMSforLegal. Use this to verify which documents will be picked up (or skipped) before running Import.
ufnFolderPath.sql User-defined function dbo.ufn_FolderPath(@profileID) that resolves a document's folder path by traversing the DOCSADM.FOLDER_ITEM parent chain. Returns a /-separated path string. Install with a DBA account if folder-path diagnostics are needed.

# 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 db_ddladmin or db_datawriter on the dbo schema (to create and write _ToDMSforLegal)

# Import shows "Azure migration not yet supported"

  • Cause: UseAzureBlobStorage is set to true in the SharepointCfg
  • Resolution: Open the SharepointCfg editor, navigate to Settings → Migrate, and set UseAzureBlobStorage to false

# "Import documents without MetaData is not yet supported"

  • Cause: ImportViaDocumentMetaData is set to false in the OpenText configuration
  • Resolution: Open the OpenText configuration and set ImportViaDocumentMetaData to true

# "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 (Matters 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 Matters sheet. The TotalDocumentCount column shows how many documents each matter has. Matters with TotalDocumentCount = 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 Matters sheet from the Dump — verify TotalDocumentCount > 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 ReplaceUserGroupNames mapping in the SharepointCfg (SettingsCfg.ReplaceUserGroupNames). The connector uses USER_ID and GROUP_ID directly — each must be mapped to the corresponding SharePoint login name (UPN) or group name. Format: USER_ID=user@domain.com;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
Last Updated: 5/11/2026, 2:44:29 PM