DocEx Migration Guide — PTE to AppSource
This guide covers upgrading from the old Per-Tenant Extension (PTE) version of DocEx to the new AppSource version.
The migration is handled automatically by the DocEx Migration app — a Per-Tenant Extension (PTE) that you install alongside both the old and new DocEx apps. When installed, it copies all data from the old PTE tables to the new tables.
What Gets Migrated
The migration app transfers the following data automatically:
| Data | Details |
|---|---|
| DocEx Setup | License keys, document number series, custom processing codeunit IDs |
| Gateways | All gateway configurations including codes, directions, connectors, processing objects, and automation flags |
| Document Automation | Automation rules per document type and direction |
| Document Headers | All document records with type mapping to new enum values |
| Document Lines | All document line items |
| Document Auxiliary Data | All key-value data including blob fields |
| Messages | All messages including file content (blob and media fields) |
| Message Channels | All channel queue entries with status mapping |
| Message Channel Archive | Historical processed message records |
| Message Channel Errors | Error logs with error messages and call stacks |
| Azure Blob V2 Accounts | Storage account names, container names, URLs |
| Azure Blob V2 Settings | Per-gateway settings (prefix, file mask, import action, archive config) |
| Azure File Share V2 Accounts | Storage account names, file share names, auth type, URLs |
| Azure File Share V2 Settings | Per-gateway settings (prefix, import action, archive config) |
Enum Mapping
Gateway connector enum values are re-mapped from old PTE ordinals to new AppSource ordinals:
| Connector | Old Value | New Value |
|---|---|---|
| File Connector | 1 | 72310775 |
| Azure Blob V2 | 65171 | 72310827 |
| Azure File Share V2 | 65191 | 72310878 |
Document types and message statuses are similarly re-mapped to their new ordinal values.
What Does NOT Migrate
Credentials stored in Isolated Storage cannot be migrated. This is a platform limitation — Isolated Storage is scoped to the app that created it, so secrets from the old PTE apps are not accessible to the new AppSource apps.
You must manually re-enter the following after migration:
| Connector | Credentials to Re-enter |
|---|---|
| Azure Blob Storage | Access Key |
| Azure File Share | Access Key or SAS Token |
The migration log will include a warning entry reminding you of this requirement.
Migration Process
Step 1: Install the Migration App
Install the DocEx Migration PTE app. The migration runs automatically on installation (per company).
- If migration data already exists (i.e. migration was previously run), the process is skipped.
- Existing records in the new tables are skipped (not overwritten).
Step 2: Review the Migration Log
Open the DocEx Migration Log page to review the results:
| Column | Description |
|---|---|
| Table Name | Which table was migrated |
| Records Migrated | Number of records successfully copied |
| Records Skipped | Number of records that already existed in the new tables |
| Status | Success, Warning, or Error |
| Message | Details (e.g. credential warnings) |
| Migration Date | Timestamp of the migration |
Look for any Warning or Error entries and address them before proceeding.
Step 3: Re-enter Connector Credentials
This is the most critical step. Open each connector's account settings in the new DocEx app and re-enter all credentials:
- Azure Blob Storage: Go to Azure Blob V2 account settings → enter the Access Key
- Azure File Share: Go to AFS V2 account settings → enter the Access Key or SAS Token
Step 4: Test Connectivity
Use the Test Connection action (available on Azure Blob and other connector account pages) to verify that all connectors can reach their external storage. For gateways without a test action, try a manual Receive or Send operation.
Step 5: Uninstall Old PTE Apps
Uninstall the old PTE apps in the correct order:
- Uninstall old PTE connector apps (Azure Blob, AFS, File)
- Uninstall old PTE DocEx main app
Step 6: Uninstall Migration App
Once everything is verified and working, uninstall the DocEx Migration app. It is no longer needed.
Retry Migration
If something went wrong, you can retry the migration:
- Open the DocEx Migration Log page.
- Use the Retry Migration action.
- This clears the existing log and re-runs the full migration process.
Note that existing records in the new tables will be skipped (not duplicated), so retrying is safe.
Troubleshooting
| Issue | Resolution |
|---|---|
| Migration log shows 0 records for all tables | The old PTE app may not be installed, or it has no data in this company |
| Connector shows "connection failed" after migration | Re-enter credentials (Step 3) — they cannot be migrated |
| Some records show as "Skipped" | Records already exist in the new tables — this is normal if migration was run before |
| Gateway connector shows wrong type | Verify the enum mapping is correct; check if the old connector used a custom/non-standard ordinal value |