261 lines
8.6 KiB
Markdown
261 lines
8.6 KiB
Markdown
# 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
|
|
|
|
1. Authenticate to both Adobe Sign and DocuSign (OAuth)
|
|
2. List and select Adobe Sign templates
|
|
3. Extract: metadata, formFields, recipients, documents, workflows
|
|
4. **Normalize** into platform-agnostic intermediate schema
|
|
5. **Validate** normalized schema — blockers stop migration; warnings are logged
|
|
6. Map to DocuSign template payload
|
|
7. Upsert (create or update) in DocuSign
|
|
8. 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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{
|
|
"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)*
|