paulh
/
adobe-to-docusign-migrator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
adobe-to-docusign-migrator/docs/agent-harness/EXECUTION-BOARD.md

15 KiB
Raw Permalink Blame History

Execution Board (Living Kanban)

Last updated: 2026-04-21 (post-redesign bug fixes + Phase 23)

Completed (v1 — CLI Pipeline)

  • Adobe Sign OAuth setup + token auto-refresh (src/auth_adobe.py, src/adobe_api.py) ✅
  • Template download pipeline — metadata, fields, docs, PDF (src/download_templates.py) ✅
  • Field type mapping — all major Adobe field types → DocuSign tabs ✅ (see field-mapping.md)
  • Coordinate system fix — y passthrough (top-origin, no conversion needed) ✅
  • Conditional logic mapping → conditionalParentLabel/Value ✅ (see validation/conditional-logic-eval.md)
  • DocuSign template JSON composition (src/compose_docusign_template.py) ✅
  • DocuSign JWT upload (src/upload_docusign_template.py) ✅
  • Regression checklist for all field types ✅ (see tests/FIELD-TYPE-REGRESSION.md)
  • End-to-end round-trip test (3 real Adobe templates → DocuSign) ✅

Phase 1 — Idempotent Upload ✅ (2026-04-17)

  • Add find_existing_template(name) to upload_docusign_template.py — lists DS templates by name, returns most-recently-modified match
  • Change upload_template() to upsert: PUT if match found, POST if not
  • Add --force-create CLI flag to bypass upsert
  • Write tests/test_upload_upsert.py — 4 tests passing

Phase 2 — FastAPI Backend Foundation ✅ (2026-04-17)

  • Add new dependencies to requirements.txt
  • Create web/ directory structure (app.py, config.py, session.py, routers/, static/)
  • Implement GET /health endpoint
  • Write tests/test_api_health.py — 2 tests passing

Phase 3 — Auth Endpoints ✅ (2026-04-17)

  • Implement Adobe Sign OAuth start + callback + disconnect in web/routers/auth.py
  • Implement DocuSign OAuth start + callback + disconnect
  • Implement GET /api/auth/status
  • Write tests/test_api_auth.py — 4 tests passing

Phase 4 — Template Listing API ✅ (2026-04-17)

  • Implement GET /api/templates/adobe in web/routers/templates.py
  • Implement GET /api/templates/docusign
  • Implement GET /api/templates/status — computes not_migrated / migrated / needs_update
  • Write tests/test_api_templates.py — 7 tests passing

Phase 5 — Migration API ✅ (2026-04-17)

  • Implement POST /api/migrate in web/routers/migrate.py — download → compose → upsert pipeline
  • Implement GET /api/migrate/history — reads/writes migration-output/.history.json
  • Write tests/test_api_migrate.py — 7 tests passing

Phase 6 — Frontend ✅ (2026-04-17)

  • Create web/static/index.html — side-by-side template browser layout
  • Create web/static/app.js — auth status check, template listing, migrate flow, history
  • Create web/static/style.css — status badges, layout

Phase 7 — End-to-End & Regression ✅ (2026-04-17)

  • Write tests/test_e2e.py — 7-step full pipeline test, 1 test passing
  • Write tests/test_regression.py — compose pipeline vs snapshots, 4 tests passing
  • Create tests/fixtures/expected/ — snapshot JSONs for David Tag Demo, NDA, Rob Test
  • Full suite: 29/29 passing

Phase 8 — Normalized Intermediate Schema ✅ (2026-04-21)

  • Create src/models/ package with __init__.py
  • Implement src/models/normalized_template.py — pydantic model with NormalizedTemplate, NormalizedField, NormalizedRole, NormalizedDocument
  • Implement src/services/ package with __init__.py
  • Implement src/services/mapping_service.py — Adobe Sign folder → NormalizedTemplate converter with checksums
  • Write tests/test_normalized_schema.py — 13 tests passing (model construction, serialization, real fixture round-trips)
  • Update README

Phase 9 — Validation Service ✅ (2026-04-21)

  • Implement src/services/validation_service.py — ValidationResult(blockers, warnings), checks for no recipients, no documents, no fields, missing roles, unsupported features
  • Implement src/reports/report_builder.py — MigrationReport, TemplateReport, MigrationStatus enum, factory functions
  • Integrate validation into migration pipeline (_run_validation in web/routers/migrate.py) — blocks on blockers
  • Implement compare_field_counts(normalized, ds_template) post-migration check
  • Write tests/test_validation_service.py — 20 tests passing
  • Update README

Phase 10 — Migration Options API ✅ (2026-04-21)

  • Extend POST /api/migrate request body: source_template_ids[], target_folder, options.dry_run, options.overwrite_if_exists, options.include_documents
  • Implement dry-run path — validate + compose without creating DocuSign templates (status=dry_run)
  • Implement overwrite_if_exists=false — skip already-migrated templates (status=skipped)
  • Implement include_documents toggle — strips documentBase64 from payload when false
  • Keep backward compatibility with legacy adobe_template_ids field
  • Write tests/test_migration_options.py — 7 tests passing
  • Update README

Phase 11 — Rate Limiting & Retry with Backoff ✅ (2026-04-21)

  • Implement src/utils/retry.py — retry_with_backoff (sync) and async_retry_with_backoff decorators with exponential backoff + max_delay cap
  • Implement check_response_retryable(status_code) — returns True for 429/500/502/503/504
  • Write tests/test_retry.py — 14 tests passing (exponential delay, max delay, exception filtering, async)
  • Update README

Phase 12 — Security Hardening & Audit Trail ✅ (2026-04-21)

  • Implement src/utils/log_sanitizer.py — redact(), redact_dict(), SanitizingFilter, install_sanitizing_filter()
  • Redacts: Bearer tokens, JWT-style tokens, key=value secret assignments, long base64 payloads (PDF content)
  • PDF checksum (SHA-256) computed in mapping_service.adobe_folder_to_normalized() and stored in NormalizedDocument.checksum_sha256
  • Write tests/test_security.py — 15 tests passing
  • Update README

Phase 13 — Batch Migration API ✅ (2026-04-21)

  • Implement POST /api/migrate/batch — async background job, returns job_id immediately
  • Implement GET /api/migrate/batch/{job_id} — poll job status, progress, results, summary
  • Implement retry for failed templates (one retry on upload failures)
  • In-memory job store with progress tracking (_batch_jobs dict)
  • Write tests/test_batch_migration.py — 6 tests passing
  • Update README

Full Test Suite ✅ (2026-04-21)

108/108 tests passing

UI Redesign — Phases 14–22 (in progress)

Full plan: docs/UI-REDESIGN-PLAN.md

Phase 14 — App Shell & Navigation ✅ (2026-04-21)

  • Rewrite index.html as app shell (left nav, router outlet, top bar)
  • css/tokens.css — Docusign 2024 brand custom properties
  • css/base.css — reset, Inter font, utility classes
  • css/nav.css — Inkwell sidebar, logo, nav links, project footer
  • js/utils.js — escHtml, formatDate, debounce, uuid
  • js/router.js — hash-based router (#/templates default)
  • js/state.js — global state with pub/sub
  • js/api.js — fetch wrappers for all existing endpoints
  • js/auth.js — auth chips, Adobe OAuth dialog, toast notifications
  • js/app.js — entry point wiring router, auth, nav badges

Phase 15 — Project / Customer Context ✅ (2026-04-21)

  • js/project.js — project CRUD (localStorage)
  • Project switcher modal (list, create, delete, activate)
  • First-run experience (auto-open modal if no projects)
  • Active project name in nav footer

Phase 16 — Templates View with Readiness Badges ✅ (2026-04-21)

  • Backend: add blockers[] + warnings[] to GET /api/templates/status
  • 3 new backend tests (10 total in test_api_templates.py)
  • js/templates.js — filterable/sortable table with readiness badges
  • Template detail view (3 tabs: Overview, Issues, Migration History)
  • css/cards.css — badge styles, table hover, bulk toolbar

Phase 17 — Migration Workflow UI ✅ (2026-04-21)

  • Options modal (dry_run, overwrite, include_documents, target folder)
  • Progress view with batch job polling (every 2s)
  • js/migration.js — showOptionsModal, runMigration, pollJob, renderResults
  • Results view (#/results) with summary + export CSV
  • css/modals.css

Phase 18 — Issues & Warnings View ✅ (2026-04-21)

  • js/issues.js — issues view (Blockers + Warnings sections)
  • Nav badge showing blocked template count

Phase 19 — Verification View + API ✅ (2026-04-21)

  • web/routers/verify.py — POST /send, GET /status/{id}, POST /void/{id}
  • Register verify router in web/app.py
  • tests/test_api_verify.py — 7 tests passing
  • js/verification.js — send test envelope, poll status, void

Phase 20 — History & Audit View ✅ (2026-04-21)

  • js/history.js — filterable history table, expand row, export CSV
  • Checksum display (first 8 chars, full on hover)

Phase 21 — Settings View ✅ (2026-04-21)

  • js/settings.js — 3 sections (verification defaults, migration defaults, connection info)
  • css/forms.css

Phase 22 — Smoke Test Checklist & Cleanup ✅ (2026-04-21)

  • tests/UI-SMOKE-TEST.md — manual test checklist (11 sections, 55 steps)
  • Full backend test suite: 118/118 tests passing
  • Update README.md — new UI navigation guide, workflow, project context
  • Update EXECUTION-BOARD.md — all phases complete
  • Push ui-redesign branch to Gitea
  • Open PR to master

Post-Redesign Bug Fixes ✅ (2026-04-21)

Bugs discovered during live testing after Phase 22.

  • Docusign branding — replaced all "DocuSign" with "Docusign" (2024 brand) across 8 frontend files
  • Template detail routing — router.js parseHash used wrong slice indices (slice(0,3) instead of slice(0,2)), causing #/templates/:id to always fall through to the list view
  • Migration polling infinite loop — pollJob only checked 'done'/'complete' but backend emits 'completed'; migration progress spinner never resolved
  • Verification envelope role names — hardcoded roleName: "Signer" meant envelopes sent without tags; now fetches actual template role names from Docusign API before sending, falls back to "Signer" only on fetch failure
  • Verification polling rate — changed from 5 s to 30 s per Docusign rate-limit guidance; added 5-minute timeout with amber "Timed Out" badge; note: production should use Docusign Connect webhooks
  • CONDITIONALTAB_HAS_INVALID_PARENT (400) — compose was emitting conditionalParentLabel pointing to signature/auto-fill tabs (forbidden as parents) or to fields on different recipients (cross-recipient). Fixed by post-processing strip pass in _strip_invalid_conditionals
  • Migration modal failure UX — failed/blocked rows now show the error message in small red text beneath the template name; completion summary shows count + "select View Results for details" hint
  • Template detail history tab — migration history rows with errors/blockers/warnings now expand inline (matching History & Audit behaviour)

Phase 23 — Structured Field Issue Reporting ✅ (2026-04-21)

  • src/models/field_issue.py — FieldIssue dataclass with code, field_name, message, severity; 7 named codes: CROSS_RECIPIENT_CONDITIONAL, UNSUPPORTED_OPERATOR, HIDE_ACTION, MULTI_PREDICATE, INVALID_PARENT_TAB, FIELD_TYPE_SKIPPED, PARTIAL_FIELD_TYPE
  • src/compose_docusign_template.py — all warning paths now also emit structured FieldIssue; cross-recipient detection added (builds {field_name → assignee} map, checks predicate fieldName assignee before applying conditional); return signature changed to (template, warnings, issues)
  • web/routers/migrate.py — captures field_issues from compose result; all _migrate_one return paths include field_issues: []
  • web/static/js/utils.js — renderFieldIssues() groups issues by code in collapsible sections; bindFieldIssueToggles() wires expand/collapse
  • web/static/js/migration.js — results view: ⚠️ icon + amber partial badge for success-with-issues; field issue groups in expanded rows
  • web/static/js/history.js — amber partial badge + field issue groups in expanded rows
  • web/static/js/templates.js — template detail history tab shows field issues with partial badge per record
  • web/static/css/cards.css — .field-issues-block, .field-issue-group, .field-issue-row styles
  • tests/test_regression.py — updated for 3-tuple compose return
  • tests/test_api_verify.py — updated for template role-fetch + added fallback test (9 tests)
  • Full test suite: 119/119 tests passing
  • Updated README.md, field-mapping.md, EXECUTION-BOARD.md

Gitea

  • Committed and pushed all changes (2026-04-17)
  • Committed Phase 8–13 work (ui-redesign branch, 2026-04-21)
  • Committed UI mockup + Docusign 2024 brand (ui-redesign branch, 2026-04-21)
  • Committed Phases 14–22 UI implementation (ui-redesign branch, 2026-04-21)
  • Pushed ui-redesign branch to Gitea; PR #1 open against master

Results & Lessons Learned

  • (2026-04-14) NDA, David Tag Demo, Rob Test all converted cleanly
  • (2026-04-15) Coordinate bug fixed — y is top-origin in both platforms, no conversion needed
  • (2026-04-15) Paul Adobe Template created via API; Company/Title fields require manual UI fix (API limitation)
  • (2026-04-17) v2 planning complete — idempotent upload + web UI implementation begins
  • (2026-04-21) Blueprint comparison complete — added normalized schema, validation service, migration options, rate-limit/retry, security hardening, and batch migration phases (Phases 8–13)
  • (2026-04-21) Phases 8–13 fully implemented — 108/108 tests passing on ui-redesign branch
  • (2026-04-21) Enterprise UI mockup designed — 8 screens, Docusign 2024 branding, official SVG logo embedded
  • (2026-04-21) UI Redesign plan written (Phases 14–22) — frontend-only except Phase 16 (readiness data) and Phase 19 (verify API)
  • (2026-04-21) Phases 14–22 fully implemented — 118/118 tests passing, enterprise UI complete
  • (2026-04-21) Post-redesign live testing found 7 bugs — all fixed (routing, polling, branding, verification role names, conditional parent 400s)
  • (2026-04-21) Phase 23 complete — structured field issue reporting end-to-end; 119/119 tests passing; cross-recipient conditional now explicitly detected and described rather than silently producing a 400