8.6 KiB

Raw Blame History

Product Specification

Project: Adobe Sign to DocuSign Template Migrator

Purpose

Develop an agent/toolkit that can programmatically extract template data and field logic from Adobe Sign ("library documents"), map/transform into DocuSign's template model, and create new DocuSign templates to reduce manual migration effort.

High-Level Goals

Download all template structure (PDFs, fields/tabs, roles, routing, logic) from Adobe Sign
Generate best-approximation DocuSign templates programmatically
Handle all basic field types and recipient roles
Detect and warn on features needing special/manual handling (complex logic, custom validations, non-mappable features)
Produce a structured migration report with successes, warnings, and manual-fix items

Architecture

Components

Adobe Sign Client (src/adobe_api.py) — authenticated API calls, template listing/download
DocuSign Client (src/upload_docusign_template.py, src/docusign_auth.py) — JWT auth, template upsert
Normalized Schema Model (src/models/normalized_template.py) — platform-agnostic intermediate representation
Mapping Service (src/services/mapping_service.py) — field type, recipient role, coordinate translation
Validation Service (src/services/validation_service.py) — field count comparison, recipient checks, missing role detection
Migration Service (src/services/migration_service.py) — orchestrates download → normalize → validate → compose → upload
Report Builder (src/reports/report_builder.py) — structured success/warning/error output
Web API (web/) — FastAPI endpoints for browser-based orchestration
Frontend (web/static/) — side-by-side template browser, migration UI

Service Separation

src/
  models/
    normalized_template.py      # intermediate schema
  services/
    migration_service.py        # pipeline orchestration
    mapping_service.py          # field/role/coord transformations
    validation_service.py       # pre/post migration checks
  reports/
    report_builder.py           # structured report output
  utils/
    pdf_coords.py               # coordinate normalization helpers

High-Level Migration Flow

Authenticate to both Adobe Sign and DocuSign (OAuth)
List and select Adobe Sign templates
Extract: metadata, formFields, recipients, documents, workflows
Normalize into platform-agnostic intermediate schema
Validate normalized schema — blockers stop migration; warnings are logged
Map to DocuSign template payload
Upsert (create or update) in DocuSign
Generate migration report

Internal Normalized Schema

Use an intermediate model so the tool is not tightly coupled to either platform. This enables future support for additional eSign platforms.

Schema Structure

{
  "template": {
    "name": "Sales Agreement",
    "description": "Migrated from Adobe Sign",
    "emailSubject": "Please sign: Sales Agreement",
    "emailMessage": "",
    "documents": [],
    "roles": [
      { "name": "Customer", "order": 1, "actionType": "SIGN" },
      { "name": "Company",  "order": 2, "actionType": "SIGN" }
    ],
    "fields": [
      {
        "type": "signature",
        "page": 1,
        "x": 120, "y": 540,
        "width": 140, "height": 28,
        "required": true,
        "roleName": "Customer"
      }
    ],
    "reminderEnabled": false,
    "expirationDays": null
  }
}

Core Entities to Migrate

Entity	Adobe Sign Source	DocuSign Target
Template name	`name`	`name`
Description	`message`	`description`
Documents (PDFs)	`libraryDocumentId` → bytes	`documents[]`
Recipient roles	`participantSetsInfo`	`recipients.signers[]`
Routing order	`participantSetsInfo.order`	`routingOrder`
Form fields	`formFields`	`tabs` per recipient
Email subject	`emailSubject`	`emailSubject`
Reminders	`reminderFrequency`	`reminders`
Expiration	`daysUntilSigningDeadline`	`expirationDateTime`

Mapping Logic

1. Recipient and Role Mapping

Map Adobe Sign participant sets → DocuSign template roles
Preserve routing order
Map action types: SIGN → signer, APPROVE → approver, CC → carbonCopy

2. Field Type Mapping

{
  "SIGNATURE":   "signHere",
  "INITIALS":    "initialHere",
  "TEXT":        "text",
  "CHECKBOX":    "checkbox",
  "RADIO":       "radioGroup",
  "DROPDOWN":    "list",
  "DATE":        "dateSigned",
  "ATTACHMENT":  "signerAttachment"
}

(Full mapping table: see field-mapping.md)

3. Coordinate Mapping

Normalize to PDF points
Account for page rotation
Transform coordinate origin if needed
Validate field overlap after placement

4. DocuSign Payload Fields

The tool must populate:

Template name and description
Email subject and message defaults
Envelope/template documents (with document checksums)
Template roles with routing order
Tabs grouped by recipient
Reminder and expiration settings where supported

Unsupported / Flagged Features (Manual Review Required)

Conditional recipient routing rules
Advanced workflow branching
Calculated fields
Custom JavaScript validators
Niche authentication methods (e.g., KBA, phone auth)
Field validations with no direct DocuSign equivalent
Webhook / event associations tied to template lifecycle

Migration Options (API)

POST /api/migrate accepts:

{
  "sourceTemplateIds": ["tpl_1001", "tpl_1002"],
  "targetFolder": "Migrated Templates",
  "options": {
    "overwriteIfExists": false,
    "dryRun": true,
    "includeDocuments": true
  }
}

dryRun — validate and report without creating DocuSign templates
overwriteIfExists — when false, skip templates already migrated (default: false)
includeDocuments — embed PDFs in DocuSign template (default: true)
targetFolder — DocuSign folder for created templates

Validation Layer

Pre-migration checks (blockers and warnings):

Field count before vs. after mapping
Recipient count and routing order integrity
Fields missing role assignments
Unsupported feature detection
Document checksum comparison (before upload vs. after download confirmation)

Post-migration checks:

DocuSign template field count vs. normalized schema count
Recipient role count match
Migration report includes pass/warn/fail per template

Implementation Considerations

Authentication

OAuth for both Adobe Sign and DocuSign (with token auto-refresh)
Support admin-consent flows where required
Securely store tokens (never in logs or plaintext files)

Rate Limits

Batch API requests carefully
Retries with exponential backoff on 429/5xx
Use idempotency (upsert pattern) where possible

File Handling

Preserve original PDFs locally in downloads/
Checksum documents before and after upload
Keep document-page metadata for accurate tab placement

Security

Redact secrets and tokens from all log output
Encrypt token storage where possible
Maintain audit trail for all migration operations (template ID, timestamp, status, user)

MVP Feature Set (Phase 1)

Authenticate to both systems (CLI + Web)
List and select Adobe Sign templates
Migrate basic templates (standard roles + common fields)
Normalized intermediate schema as pipeline bridge
Validation layer (field/recipient counts, missing roles)
Migration report (success / warning / error per template)
Dry-run mode
Idempotent re-runs (overwrite prevention)

Phase 2 Features

Batch migration (multiple templates in one request)
Retry failed templates
Coordinate validation preview
Duplicate detection
Folder / category mapping
Audit logging
Rate limit handling with backoff

Phase 3 Features

UI preview for field placements
Manual correction workflow
Side-by-side template comparison (visual diff)
Webhook recreation
Advanced workflow translation

Out of Scope (MVP)

Agreement instance migration (templates only)
Custom integrations outside API surface
Real-time collaborative editing

Updated: 2026-04-21 (Blueprint alignment — added normalized schema, validation layer, migration options, security/rate-limit requirements, Phase 2/3 feature set, architecture detail)

8.6 KiB Raw Blame History