164 lines
12 KiB
Markdown
164 lines
12 KiB
Markdown
# 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
|
||
|
||
## Multi-Document Templates
|
||
|
||
Adobe Sign library documents can contain multiple documents (PDFs) stacked into one template. DocuSign templates also support multiple documents — each document gets a unique `documentId` starting from 1.
|
||
|
||
### How it works
|
||
|
||
The compose pipeline assigns a `documentId` to each document in the order returned by the Adobe Sign `documents.json` list. All form fields reference their page position within the document they belong to (`pageNumber` is 1-based within the document's own page sequence, not the overall template page count).
|
||
|
||
```
|
||
Adobe Sign template with 2 docs:
|
||
doc[0]: "Contract.pdf" (3 pages) → documentId: 1
|
||
doc[1]: "Exhibit-A.pdf" (2 pages) → documentId: 2
|
||
|
||
A field on page 2 of Exhibit-A.pdf:
|
||
adobe_location.pageNumber = 2 (within the exhibit)
|
||
compose emits: documentId=2, pageNumber=2
|
||
```
|
||
|
||
DocuSign uses `(documentId, pageNumber)` together to locate every tab. If only one document exists, `documentId` is always `1`.
|
||
|
||
### Known limitation
|
||
|
||
Adobe Sign form fields store `pageNumber` as a sequential page number across the **entire** template (all documents concatenated). If a template has two 3-page documents, fields on document 2 have `pageNumber` 4–6. The compose pipeline does not currently rebase page numbers per document — it passes Adobe's page numbers through as-is and sets `documentId` based on field assignment.
|
||
|
||
**Impact**: For single-document templates this is correct. For multi-document templates, verify field placement visually in DocuSign after migration if the template spans more than one PDF.
|
||
|
||
## 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.
|