Documenso Migration Deep Dive

Current State

!npm list 2>/dev/null | head -10

Overview

Comprehensive guide for migrating to Documenso from other e-signature platforms (DocuSign, HelloSign, PandaDoc, Adobe Sign). Uses the Strangler Fig pattern for zero-downtime migration with feature flags and rollback support.

Prerequisites

• Current signing platform documented (APIs, templates, webhooks)
• Documenso account configured (see documenso-install-auth)
• Feature flag infrastructure (LaunchDarkly, environment variables, etc.)
• Parallel run capability (both platforms active during migration)

Migration Strategy: Strangler Fig Pattern

Phase 1: Parallel Systems (Week 1-2)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│ Old Platform │  (100% traffic)
│          │     └─────────────┘
│          │────▶│  Documenso   │  (shadow: log only, don't send)
└──────────┘     └─────────────┘

Phase 2: Gradual Cutover (Week 3-4)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│ Old Platform │  (50% traffic via feature flag)
│          │     └─────────────┘
│          │────▶│  Documenso   │  (50% traffic)
└──────────┘     └─────────────┘

Phase 3: Full Migration (Week 5+)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│  Documenso   │  (100% traffic)
└──────────┘     └─────────────┘
                 Old platform decommissioned

Instructions

Step 1: Pre-Migration Assessment

typescript
// scripts/assess-current-system.ts
// Inventory your current signing platform usage

interface MigrationAssessment {
  platform: string;
  activeTemplates: number;
  documentsPerMonth: number;
  webhookEndpoints: string[];
  recipientRoles: string[];
  fieldTypes: string[];
  integrations: string[];  // CRM, database, etc.
}

async function assessCurrentSystem(): Promise<MigrationAssessment> {
  // Example for DocuSign
  return {
    platform: "DocuSign",
    activeTemplates: 15,
    documentsPerMonth: 200,
    webhookEndpoints: [
      "https://api.yourapp.com/webhooks/docusign",
    ],
    recipientRoles: ["Signer", "CC", "In Person Signer"],
    fieldTypes: ["Signature", "Date", "Text", "Checkbox", "Initial"],
    integrations: ["Salesforce", "PostgreSQL"],
  };
}

Step 2: Feature Mapping

| DocuSign | HelloSign | Documenso | Notes | |----------|-----------|-----------|-------| | Envelope | Signature Request | Document | Documenso v2 also has Envelopes | | Template | Template | Template | Create via UI, use via API | | Signer | Signer | SIGNER role | Same concept | | CC | CC | CC role | Same concept | | In Person | N/A | Direct Link | Use embedded signing | | Tabs/Fields | Form Fields | Fields | SIGNATURE, TEXT, DATE, etc. | | Connect (webhooks) | Callbacks | Webhooks | document.completed, etc. | | PowerForms | N/A | Direct Links | Public signing URLs |

Step 3: Template Migration

typescript
// Templates can't be migrated via API — recreate in Documenso
// Keep template definitions in code for reproducibility

interface TemplateDef {
  name: string;
  description: string;
  recipientRoles: Array<{ role: string; placeholder: string }>;
  fields: Array<{
    recipientIndex: number;
    type: string;
    page: number;
    x: number;
    y: number;
    width: number;
    height: number;
  }>;
}

const TEMPLATES: TemplateDef[] = [
  {
    name: "NDA — Standard",
    description: "Non-disclosure agreement template",
    recipientRoles: [
      { role: "SIGNER", placeholder: "Counterparty" },
      { role: "CC", placeholder: "Legal Team" },
    ],
    fields: [
      { recipientIndex: 0, type: "SIGNATURE", page: 2, x: 10, y: 80, width: 30, height: 5 },
      { recipientIndex: 0, type: "DATE", page: 2, x: 60, y: 80, width: 20, height: 3 },
      { recipientIndex: 0, type: "NAME", page: 2, x: 10, y: 75, width: 30, height: 3 },
    ],
  },
  // ... more templates
];

// Instructions: create each template in the Documenso UI using these specs
// Then record the template IDs in your config

Step 4: Webhook Migration

typescript
// Map old platform events to Documenso events
const EVENT_MAPPING: Record<string, string> = {
  // DocuSign → Documenso
  "envelope-completed": "document.completed",
  "envelope-sent": "document.sent",
  "envelope-declined": "document.rejected",
  "envelope-voided": "document.cancelled",
  "recipient-completed": "document.signed",

  // HelloSign → Documenso
  "signature_request_all_signed": "document.completed",
  "signature_request_sent": "document.sent",
  "signature_request_declined": "document.rejected",
  "signature_request_signed": "document.signed",
};

// Unified handler that works with both platforms during migration
async function handleSigningEvent(source: "old" | "documenso", event: string, payload: any) {
  const normalizedEvent = source === "old"
    ? EVENT_MAPPING[event] ?? event
    : event;

  switch (normalizedEvent) {
    case "document.completed":
      await onDocumentCompleted(payload);
      break;
    case "document.rejected":
      await onDocumentRejected(payload);
      break;
  }
}

Step 5: Dual-Write with Feature Flag

typescript
// src/signing/router.ts
const USE_DOCUMENSO = process.env.USE_DOCUMENSO === "true";

async function sendForSigning(request: SigningRequest) {
  if (USE_DOCUMENSO) {
    return sendViaDocumenso(request);
  }
  return sendViaLegacy(request);
}

// During parallel phase: send via both, compare results
async function sendForSigningParallel(request: SigningRequest) {
  const legacyResult = await sendViaLegacy(request);

  // Shadow-send to Documenso (don't actually send to recipients)
  try {
    const doc = await documensoClient.documents.createV0({ title: request.title });
    // Don't call sendV0 — just verify creation works
    await documensoClient.documents.deleteV0(doc.documentId);
    console.log("Documenso shadow test: OK");
  } catch (err) {
    console.error("Documenso shadow test: FAIL", err);
  }

  return legacyResult;
}

Step 6: Rollback Procedure

bash
# If Documenso migration causes issues:

# 1. Disable feature flag
export USE_DOCUMENSO=false
# Or toggle in LaunchDarkly/feature flag service

# 2. Deploy the change
# All new signing requests go to old platform immediately

# 3. Handle in-flight Documenso documents
# Documents already sent via Documenso will complete there
# No action needed — they just use a different platform

# 4. Investigate and fix the issue
# Review logs, fix the integration, re-enable gradually

Migration Timeline

| Week | Phase | Action | Risk | |------|-------|--------|------| | 1 | Assessment | Inventory templates, webhooks, integrations | Low | | 2 | Setup | Configure Documenso, recreate templates | Low | | 3 | Shadow | Run parallel, compare results (no live traffic) | Low | | 4 | Pilot | 10% of new documents via Documenso | Medium | | 5 | Expand | 50% of new documents via Documenso | Medium | | 6 | Cutover | 100% via Documenso, old platform read-only | Medium | | 8 | Decommission | Remove old platform code and webhooks | Low |

Error Handling

| Migration Issue | Cause | Solution | |----------------|-------|----------| | Field position different | Different coordinate systems | Map percentage-based (Documenso) from pixel-based (old) | | Webhook format change | Different payload structure | Use event normalizer/adapter | | Template missing | Not recreated in Documenso | Create from template definitions | | High error rate during cutover | Integration bug | Pause rollout, rollback, investigate |

Resources

• Strangler Fig Pattern
• Documenso Documentation
• Documenso vs DocuSign
• Feature Flags Best Practices

Next Steps

Review related skills for comprehensive coverage of your new Documenso integration.