Migration Guide

Use this guide for Safin to Vesper, Vesper QA validation, and eventual production migration. The goal is deterministic migration with original PBSI, Ascent, Chargent, Zenventory, and carrier-enrichment records preserved for audit.

Principles

Do not delete or rewrite original managed-package records.
Run destructive metadata only for source-managed cleanup that has already been reviewed.
Use dry-runs before writes and confirm reruns are idempotent.
Keep CRM records from production-copy targets as reference-only unless a specific repair requires otherwise.
Treat settings as migration data, and treat payment terms as source-managed static configuration.

Configuration First

Run the org configuration migration before importing or repairing historical records:

node scripts/settings/migrate-org-config.mjs --source-org safin --target-org vesper --dry-run --include-secrets
node scripts/settings/migrate-org-config.mjs --source-org safin --target-org vesper --apply --include-secrets

For production, replace the aliases and run the dry-run first. The script copies branding, email configuration, operational settings, and logo files into the target org. It remaps hierarchy owners and user references where a matching target user exists. Payment terms are skipped here because the Salesforce project seeds the static catalog in code.

If a user reference cannot be mapped, the script clears that field and prints a warning instead of copying a stale sandbox username. Create or assign the intended target integration user, then rerun the script if that runtime user is required.

Payment Terms

Payment terms live in source-managed Payment_Term_Definition__c rows. PaymentTermsService seeds and repairs the canonical catalog in every org, so the settings migration no longer imports terms from Safin. Admins can turn terms on or off, but they cannot create, delete, rename, or reorder the static catalog from the UI.

Account, sales order, quote, and invoice term fields store canonical text values. Do not migrate Ascent payment-term records as the target catalog. Legacy lookup IDs from PBSI/Ascent data are invalid target values. Migration code must resolve or normalize terms into active Payment_Term_Definition__c names such as Net 15, Paid Immediately, Paid On Delivery, or Pay On Tracking.

Picklist Values

The settings migration copies configuration records. It does not mutate field metadata. If the import exposes a missing true picklist value, add that value to the source-managed field or global value set, deploy metadata to the target, and rerun the relevant migration step.

Legacy PDF Page Unblock

Before running Ascent/PBSI PDF destructive cleanup in a refreshed sandbox or production, patch the active legacy Lightning pages so they no longer reference the old custom PDF buttons:

npm run release:legacy-pdf-page-unblock -- --target-org vesper
npm run release:legacy-pdf-page-unblock -- --target-org vesper --apply
sf project deploy start --target-org vesper --manifest manifest/vesper-legacy-apex-destructive/package.xml --post-destructive-changes manifest/vesper-legacy-apex-destructive/destructiveChanges.xml --wait 30

The patch step retrieves these active pages from the target org and removes only the blocking PDF actions from the highlights panel:

Ascent_Address_SO_Page_v2
GI_ERP_AFP_Invoice_Record_Page
GI_ERP_AFP_Purchase_Order_Record_Page1
GI_ERP_AFP_Quote_Record_Page

The script is idempotent. If the pages were already patched, it reports no changes and does not deploy. Keep the active pages in place unless you manually deactivate them first in Lightning App Builder; Salesforce blocks deletion of active Lightning pages.

PBSI and Chargent Data

Use the PBSI migration runner for historical records:

python3 scripts/pbsi_migration/cli.py inspect --target-org vesper --source-dir salesforce-production-data-MAY-7-2026
python3 scripts/pbsi_migration/cli.py run --target-org vesper --source-dir salesforce-production-data-MAY-7-2026 --confirm
python3 scripts/pbsi_migration/cli.py repair --target-org vesper --source-dir salesforce-production-data-MAY-7-2026 --step fulfillment-history --confirm

Run targeted steps for BOM, finance, fulfillment, Chargent support history, and GL backfill when validating a small order dataset such as SO-011436.

Validation

After applying configuration and data migration:

Rerun the configuration migration in dry-run mode and confirm unchanged rows.
Confirm Payment_Term_Definition__c contains expected active terms.
Confirm branding and order-email settings have target-org logo file URLs.
Validate the targeted order, quote, invoice, payment, BOM, tracking, and fulfillment records.
Run python3 -m pytest scripts/pbsi_migration/tests -q.
Run npm run verify:governance after metadata or permission changes.