adobe-to-docusign-migrator/field-mapping.md

# 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                        | Notes |
|-----------------------------------|---------------------------------|-------|
| `predicates[].fieldName`          | `conditionalParentLabel`        | For radio groups, matches the group name |
| `predicates[].value`              | `conditionalParentValue`        | The value the trigger must equal to reveal the tab |
| `action: SHOW`                    | Supported                       | Tab is hidden until condition is met |
| `action: HIDE`                    | **Not supported**               | No DocuSign equivalent — condition skipped, field always shown |
| `operator: EQUALS`                | Supported                       | Only operator DocuSign supports |
| Other operators                   | **Not supported**               | Condition skipped, warning logged |
| Multiple predicates (ANY/ALL)     | **Partial** — first EQUALS only | Warning logged; remaining predicates ignored |

## 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.
- **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.
- **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.

## To Do
- Add conditional logic/rule mapping table
- Document field mask and default value transforms