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

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.