paulh
/
adobe-to-docusign-migrator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
adobe-to-docusign-migrator/field-mapping.md

138 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Field Mapping: Adobe Sign → DocuSign
This doc tracks direct mappings and required transforms between Adobe Sign library document (template) properties and DocuSign template properties.
## Field Type Mapping (inputType + contentType + validation → DocuSign tab)
Adobe Sign requires `inputType`, `contentType`, and sometimes `validation` to determine the correct DocuSign tab.
Source: Adobe Sign UI "Change field type" dropdown (all 15 types) + API field data.
| Adobe UI Label | inputType | contentType | validation | DocuSign Tab | Notes |
|---------------------|-------------------|------------------|------------|----------------------|--------------------------------------------|
| Signature | SIGNATURE | SIGNATURE | — | signHereTabs | |
| Initials | SIGNATURE | SIGNER_INITIALS | — | initialHereTabs | NOT a full signature |
| Recipient name | TEXT_FIELD | SIGNER_NAME | — | fullNameTabs | Auto-populated from signer profile |
| Recipient email | TEXT_FIELD | SIGNER_EMAIL | — | emailAddressTabs | Auto-populated from signer profile |
| Date of signing | TEXT_FIELD | SIGNATURE_DATE | — | dateSignedTabs | Auto-populated on signing |
| Text | TEXT_FIELD | DATA | STRING | textTabs | |
| Date | TEXT_FIELD | DATA | DATE | dateTabs | User-entered date (not auto-signed date) |
| Number | TEXT_FIELD | DATA | NUMBER | numberTabs | |
| Drop-down menu | DROP_DOWN | DATA | — | listTabs | Options from hiddenOptions array |
| Attachments | FILE_CHOOSER | DATA | — | signerAttachmentTabs | Manual review recommended |
| Participation stamp | PARTICIPATION_STAMP | — | — | (skipped) | No DocuSign equivalent |
| Image | INLINE_IMAGE | DATA | — | (skipped) | No DocuSign equivalent |
| Company | TEXT_FIELD | COMPANY or SIGNER_COMPANY | — | companyTabs | Auto-populated from signer profile. API returns `SIGNER_COMPANY` when set via UI. |
| Title | TEXT_FIELD | TITLE or SIGNER_TITLE | — | titleTabs | Auto-populated from signer profile. API returns `SIGNER_TITLE` when set via UI. |
| Stamp | STAMP | — | — | stampTabs | DocuSign stampTabs — signer uploads/selects a stamp image (hanko/seal). Requires stamp feature enabled on account. |
| Signature block | BLOCK | SIGNATURE_BLOCK | — | signHereTabs | Composite block — mapped to sign-here |
## Role/Recipient Mapping
| Adobe Field | DocuSign Field | Notes |
|-----------------------|---------------------|-------|
| recipientSetRole | role (signer, etc.) | Matching by role name |
| recipientSetMemberInfos.email | role.email | |
## Known Edge Cases & Decision Log
- [2026-04-14] DocuSign checkboxes must be uniquely tab-labeled and mapped to a recipient; Adobe Sign sometimes groups these differently.
- [2026-04-14] Date fields on Adobe may include validation Adobe-only, which needs stripping or custom mapping for DocuSign’s `dateSigned`.
- [2026-04-14] Conditional logic for showing/hiding fields in Adobe is not always supported in DocuSign (needs review for each case).
- [2026-04-15] `numberTabs` API bug: DocuSign API accepts `numberTabs` in the template JSON, but the created template displays as a Text field with "Numbers" validation in the editor. Functionally equivalent at signing time; visual/semantic discrepancy only. No API workaround known.
- [2026-04-15] Multi-location fields: Adobe Sign fields can have multiple `locations` (cloned/synced instances). DocuSign equivalent is tab merging — multiple tabs with the same `tabLabel` sync their value. Our compose script now emits one tab per location for all data-entry types. See `PLATFORM-QUIRKS.md` for full details.
- [2026-04-15] Tab width required: DocuSign text-entry tabs render as a vertical line if `width` is omitted. Always pass `width` (and `height`) from the Adobe Sign location. Minimum 120pt enforced.
## Workflow Feature Mapping (Rough)
- Sequential routing → Recipient order
- Parallel routing → Recipient routing order logic (sequential/parallel in DocuSign)
- Conditional logic → Needs review, possible via DocuSign conditional tabs/logic
## Coordinate System
Both Adobe Sign and DocuSign measure field positions from the **top-left corner** of the
page with y increasing downward — no coordinate inversion is needed. The conversion is
a direct pass-through:
```
docusign_xPosition = adobe_location.left
docusign_yPosition = adobe_location.top
docusign_width = max(adobe_location.width, MIN_TEXT_WIDTH) # 120pt floor
docusign_height = adobe_location.height
```
`MIN_TEXT_WIDTH = 120` is enforced on all text-entry tabs so they render as visible
input boxes rather than vertical lines (DocuSign renders zero-width tabs as a thin line).
## Multi-location (Cloned) Fields
Adobe Sign allows a single field definition to have multiple `locations` — the field
appears in several places on the document and all instances stay in sync.
DocuSign replicates this via **tab merging**: multiple tabs that share the same
`tabLabel` automatically sync their value at signing time. The compose script emits
one tab per location for all data-entry tab types. Radio groups are handled differently
— each location is a separate radio button within the same group, not a clone.
Tab types that support merging (one tab emitted per location):
`textTabs`, `numberTabs`, `dateTabs`, `dateSignedTabs`, `fullNameTabs`,
`emailAddressTabs`, `companyTabs`, `titleTabs`, `listTabs`, `checkboxTabs`
Tab types that do not merge (only first location used or handled specially):
`signHereTabs`, `initialHereTabs`, `stampTabs` — each location is an independent signing/stamping action
`radioGroupTabs` — each location is one radio button within the group
`signerAttachmentTabs` — each location is an independent attachment request
## Conditional Logic Mapping
Adobe Sign `conditionalAction` → DocuSign `conditionalParentLabel` + `conditionalParentValue` on the dependent tab.
| Adobe Sign | DocuSign | Outcome | Notes |
|-----------------------------------|---------------------------------|---------|-------|
| `predicates[].fieldName` | `conditionalParentLabel` | Mapped | For radio groups, matches the group name |
| `predicates[].value` | `conditionalParentValue` | Mapped | The value the trigger must equal to reveal the tab |
| `action: SHOW` | Supported | Mapped | Tab is hidden until condition is met |
| `action: HIDE` | **Not supported** | Dropped | No DocuSign equivalent — field always shown. `HIDE_ACTION` issue emitted. |
| `operator: EQUALS` | Supported | Mapped | Only operator DocuSign supports |
| Other operators (NOT_EQUALS, etc.)| **Not supported** | Dropped | Condition skipped. `UNSUPPORTED_OPERATOR` issue emitted. |
| Multiple predicates (ANY/ALL) | **Partial** — first EQUALS only | Partial | `MULTI_PREDICATE` issue emitted; remaining predicates ignored |
| Trigger field on a different recipient | **Not supported** | Dropped | DocuSign `conditionalParentLabel` only works within the same recipient's tab set. `CROSS_RECIPIENT_CONDITIONAL` issue emitted. |
| Parent is signature/auto-fill tab | **Not supported** | Stripped | DocuSign forbids signature, initial, dateSign, fullName, email, title tabs as conditional parents. `INVALID_PARENT_TAB` issue emitted. |
## Known Gaps
- **Conditional HIDE**: Adobe Sign can conditionally hide a field. DocuSign only supports
revealing hidden fields — there is no native way to hide a visible field conditionally.
Templates with HIDE conditions will have those fields always visible after migration.
Emits a `HIDE_ACTION` field issue.
- **Cross-recipient conditionals**: Adobe Sign allows field B to appear/hide based on
the value of field A even when A and B belong to different recipients. DocuSign's
`conditionalParentLabel` only works within a single recipient's tab set.
Emits a `CROSS_RECIPIENT_CONDITIONAL` field issue; the condition is dropped.
- **Invalid or forbidden conditional parents**: If the trigger field maps to a signature,
initial, dateSign, fullName, email, or title tab — DocuSign forbids these as conditional
parents and returns `CONDITIONALTAB_HAS_INVALID_PARENT` (400). The compose pipeline
strips these conditions in a post-processing pass and emits an `INVALID_PARENT_TAB`
field issue.
- **Multi-predicate conditions**: Adobe Sign supports ANY/ALL of multiple predicates.
DocuSign only supports a single parent condition per tab. Only the first EQUALS
predicate is mapped; complex conditions require manual rework.
Emits a `MULTI_PREDICATE` field issue.
- **Unsupported operators**: NOT_EQUALS, GT, LT etc. have no DocuSign equivalent.
The condition is dropped. Emits an `UNSUPPORTED_OPERATOR` field issue.
- **DocuSign formula fields**: No Adobe Sign equivalent — flag for manual rewrite.
- **Advanced field validation**: Adobe regex/custom script validation is not mapped;
best-effort via standard DocuSign validation types only.
- **Radio group flattening**: Adobe radios with `radioGroup` are merged into a single
DocuSign `radioGroupTabs` entry with per-location radio button coordinates.
- **Stamp tab account feature**: `stampTabs` requires the stamp/hanko feature to be
enabled on the DocuSign account. Verify before migrating templates that contain
Adobe Sign STAMP fields. Emits a `PARTIAL_FIELD_TYPE` field issue.
- **FILE_CHOOSER → signerAttachmentTabs**: Docusign attachment tabs behave differently
from Adobe file upload fields (different UX, no file type restrictions).
Emits a `PARTIAL_FIELD_TYPE` field issue recommending manual review.
## Field Issue Codes
All dropped or approximated features are surfaced as structured `FieldIssue` objects
alongside human-readable warning strings. See `src/models/field_issue.py` for the full
list. The UI groups these by code in collapsed sections within migration result rows,
history rows, and the template detail Issues tab.
Reference in New Issue View Git Blame Copy Permalink