InDesign Data Merge Skill

Orchestrates the complete InDesign data merge pipeline. The naive path — calling document_merge_data_layout directly — often fails because the template must have its data-merge fields linked to the correct data columns before merging. This skill ensures that linkage is in place first, including automatic placeholder creation when the template has none, and PDF-to-INDD conversion when the user only has a PDF layout.

Pipeline at a glance:

Phase	What happens	Gate
0	Adobe init	—
1a	Convert PDF template → .indd (skip if already .indd)	⛔ GATE 1
1b	Confirm .indd URL and data file are available	—
2	Export IDML; detect existing merge placeholders	—
3	Create placeholders via LLM mapping (only if Phase 2 found none)	⛔ GATE 2
4	Run document_merge_data_layout	—

---

Tool Reference

Step	Tool	Notes
Initialize Adobe tools	adobe_mandatory_init	Always call first
Inspect PDF pages	asset_inline_preview	Returns rendered preview per page
Preview PDF pages (fallback)	asset_preview_file	Use if asset_inline_preview unavailable
Upload condensed template PDF	asset_initialize_file_upload + asset_finalize_file_upload	Required before convert_pdf_to_indd
Convert PDF → INDD	convert_pdf_to_indd	Use extractedDocumentPresignedUrls as inddUrl
Export IDML	export_idml	Outputs presigned IDML URL for inspection
Generate mapping prompt	generate_indd_mapping_prompt	Read-only; returns prompt — you run it through an LLM
Create placeholders in INDD	prepare_indd_merge_template	Only after user approves mapping
Run data merge	document_merge_data_layout	Template + data → merged PDF

---

⛔ MANDATORY GATES

Two rules are non-negotiable and override all efficiency instincts.

Gate 1 — PDF template: analyse layout before converting

Never call convert_pdf_to_indd on a user-supplied PDF without first inspecting its page layout structure. A multi-page PDF (e.g. a prior merged output) produces a multi-page INDD which breaks the merge. Always distil it to a single-layout condensed PDF first.

Gate 2 — Mapping: show and wait before creating placeholders

Never call prepare_indd_merge_template in the same turn you generate or display the mapping JSON. Show the mapping summary + raw JSON, ask for approval, and end the turn. Only call prepare_indd_merge_template after the user explicitly approves in a later turn.

---

Workflow

Step 0 — Initialize Adobe Tools

{ "skill_name": "adobe-create-pdfs-from-data", "skill_version": "1.0.1" }

Call adobe_mandatory_init once, before any other Adobe tool.

---

Step 1a — Convert PDF Template to INDD (skip if already .indd)

When to run: The user's template is a PDF (or any non-INDD layout). If you already have a usable .indd URL, skip directly to Step 1b.

Sub-step 1 — Inspect all pages

Record the user-supplied PDF URL as originalPdfUrl.

Call asset_inline_preview on the PDF (or asset_preview_file as fallback). Record totalPages.

If totalPages == 1: set templatePdfUrl = originalPdfUrl and skip to Sub-step 5.

Sub-step 2 — Compare page layouts visually

Look at each preview image. Ask: "If I removed all text and image content and compared only the skeleton — frame positions, structural regions — would this page match another page?"

Group pages by layout skeleton into layoutGroups:

layoutGroups = {
  "layout-A": [1, 2, 3, ...],   // pages sharing layout A
  "layout-B": [N+1, ...],        // pages with a distinct layout B
}

Pick templatePages as a single representative page:

• If layoutGroups has exactly 1 entry: templatePages = [first page in that group].
• If layoutGroups has >1 entry: ask the user which layout group to use (or default to the group with the most pages) and set templatePages to one page from that group.

Tell the user:

"Your PDF has {totalPages} pages. I found {N} unique layout(s). I'll use page {templatePages[0]} as the template. (If you need multiple layouts, we can run separate merges per layout.)"

Sub-step 3 — Extract only the template pages

Download the PDF from {originalPdfUrl} and extract only page(s) {templatePages} (1-indexed) to template-condensed.pdf using PyMuPDF (fitz). Report the absolute file path as intermediatePdfLocalPath.

Record the path as intermediatePdfLocalPath.

Sub-step 4 — Upload the condensed PDF

asset_initialize_file_upload({ path: "template-condensed.pdf", media_type: "application/pdf" })
// PUT the local file bytes to the returned upload URL, then:
asset_finalize_file_upload({ filename: "template-condensed.pdf", transfer_document: <from initialize response> })

Record the resulting presigned URL as templatePdfUrl.

Sub-step 5 — Convert to INDD

convert_pdf_to_indd:
  pdfSourceUrl:                        {templatePdfUrl}
  outputFormat:                        "indd"
  embedLinks:                          false
  waitForCompletion:                   true
  includeAdobeZipDownloadLinksInResult: false

Use the first entry in extractedDocumentPresignedUrls as inddUrl. If that field is missing, re-run with embedLinks: true. Do not attempt to download or unzip the output ZIP.

---

Step 1b — Prerequisite Check

Confirm all inputs are accessible (attached files, URLs from conversation, or prior tool calls):

• .indd URL — if missing, prompt the user to upload their template
• Data file — CSV, TSV, or other delimited text; if missing, ask the user
• Image assets (optional) — any images referenced by the data file (e.g. photo columns)

If any file is a local attachment without a URL, upload it first:

asset_initialize_file_upload → asset_finalize_file_upload

Record inddUrl and dataUrl. Proceed only when both are confirmed.

Collect image assets (if the data file references images)

Parse the header row of dataUrl. If any column values look like image filenames or paths (common with @-prefixed image fields in InDesign templates), collect those images:

1. For each unique image filename referenced in the data, obtain a presigned URL — either from the user's supplied URLs, or by uploading local files via asset_initialize_file_upload + asset_finalize_file_upload.
2. Build additionalImageFiles: a map of { "filename.jpg": "<presignedUrl>", ... } covering every unique image referenced across all rows.

Record additionalImageFiles (or {} if no image columns are present).

---

Step 2 — Export IDML and Inspect for Placeholders

Export IDML

export_idml:
  assets:
    - sourceUrl: {inddUrl}  destination: "template.indd"

Record the presigned idmlUrl from the response.

If export_idml fails (missing execute URL), tell the user you cannot proceed with automatic placeholder creation and ask whether they want to continue manually.

Inspect for existing placeholders

Fetch and unzip the IDML. Build docAnalysis capturing every candidate merge target:

• Text frames: uid, bounds, current text content, any existing <<fieldName>> or <AppliedDataMergeField> tokens
• Image frames: uid, bounds, aspect ratio, any @-prefixed image field names

Extract idmlPlaceholders: string[] — unique field names stripped of <</>> wrappers.

If placeholders are found: skip Phase 3 and go directly to Step 4 using inddUrl.

If no placeholders are found: proceed to Step 3.

---

Step 3 — Create Placeholders (only if Step 2 found none)

Step 3a — Read data headers

Parse the header row of dataUrl. Treat the file as delimited text; infer the delimiter if ambiguous. Preserve exact column name strings as dataColumns: string[].

Step 3b — Generate mapping JSON

Call generate_indd_mapping_prompt — this returns a prompt string only; it does not call an LLM:

generate_indd_mapping_prompt:
  userRequest:      {user's original request}
  tier:             "standard"   (use "complex" for dense templates; "modification" for edits)
  idmlPresignedUrl: {idmlUrl}
  csvInfo:
    headers:      {dataColumns}
    data_types:   {inferred types}
    sample_data:  {first 2–3 rows}

Run the returned prompt through an LLM requiring JSON-only output. Record as mappingJson.

Step 3b.1 — Validate / filter the mapping

Call generate_indd_mapping_prompt again with the same inputs, adding:

  mappingJson: {mappingJson}

If the response includes filteredMappings (hallucinated UIDs removed), use it as the working mapping. Fix any errors and re-validate until isValid: true.

After the first successful validation, record:

• originalMappingJson — the first validated mapping (use filteredMappings if returned)
• originalIdmlUrl — the idmlUrl from Step 2 (never overwrite with a post-edit version)
• originalInddUrl — the inddUrl from Step 1b (never overwrite with mappedInddUrl)

Step 3b.2 — ⛔ Show mapping and END TURN (Gate 2)

Your response for this step must contain exactly:

1. A human-readable summary of text/image mappings (placeholder name → CSV column, frame UID)
2. The raw mapping JSON in a code block
3. This confirmation question as the final line:

   "Please confirm this mapping (or tell me what to change). I'll apply it to create placeholders in your .indd and then run the merge."

After that line — no more tool calls, no further narration. End the turn.

If the user requests changes, enter a modification loop:

• Apply only the user's requested deltas on top of originalMappingJson — never use an intermediate draft or mappedInddUrl as the base
• Re-run Step 3b.1 validation with tier: "modification", passing originalIdmlUrl and originalMappingJson in modificationContext
• Re-present the updated mapping and ask for confirmation again — do not call prepare_indd_merge_template until the user approves

Step 3c — Apply placeholder mapping to INDD

Only callable after user explicitly approves in a later turn.

prepare_indd_merge_template:
  assets:
    - sourceUrl: {originalInddUrl}  destination: "template.indd"
  params: {filteredMappings or validated mappingJson}

Record the first presigned URL from the response as mappedInddUrl.

---

Step 4 — Run the Data Merge

document_merge_data_layout:
  templateSourceUrl:    {mappedInddUrl or inddUrl}
  templateFileName:     "template.indd"
  dataSourceUrl:        {dataUrl}
  additionalImageFiles: {additionalImageFiles}   # omit or pass {} if no image columns
  outputSpecs:          [{ outputMediaType: "application/pdf" }]
  recordRange:          "All"

Return download links to the user:

"Data merge complete — {N} record(s) rendered. Here are your download links:"

---

Decision Tree

User requests data merge
        │
Phase 0: adobe_mandatory_init
        │
Already have .indd URL?
   YES → Step 1b
   NO  → Template is PDF?
           YES → Step 1a.1: inspect all pages
                   → single page? → convert_pdf_to_indd (original URL)
                   → multi-page?  → identify unique layouts → extract condensed PDF
                                  → upload → convert_pdf_to_indd → inddUrl
           NO  → Step 1b (ask for .indd upload)
        │
Step 1b: confirm inddUrl + dataUrl
        │
Step 2: export_idml → parse IDML for placeholders
        │
   Placeholders found?
   YES → Step 4: document_merge_data_layout
   NO  → Step 3a: parse data headers
         Step 3b: generate_indd_mapping_prompt → LLM → mappingJson
         Step 3b.1: validate → filteredMappings
         ⛔ STOP — show mapping + ask approval — END TURN
              │
         [Next turn] user approves?
         YES → Step 3c: prepare_indd_merge_template → mappedInddUrl
         NO  → modify against originals → re-validate → ⛔ STOP again
        │
Step 4: document_merge_data_layout → return download links

---

Error Handling

Situation	Action
export_idml fails / missing execute URL	Inform user that automatic placeholder creation is unavailable; ask if they want to continue manually
prepare_indd_merge_template fails / missing execute URL	Ask deployer to set ADOBE_CAPABILITY_SMART_MAPPING_EXECUTE_URL; stop
Data file delimiter unclear	Ask the user what delimiter is used and whether the first row is a header
Mapping JSON invalid after validation	Re-run LLM with the validation errors; require JSON-only output; retry until isValid: true
document_merge_data_layout fails	Surface the raw error; suggest checking that template variable names match CSV column headers exactly
convert_pdf_to_indd fails	Confirm the PDF URL is accessible; retry with embedLinks: true; if still failing, ask user for a native .indd
No .indd and PDF conversion unavailable	Ask user to export their template as .indd directly

---

Admin Notes (IDCS Environment)

The IDML export and smart-mapping tools require these environment variables (configure them in your deployment environment):

Variable	Used by
ADOBE_CAPABILITY_IDMLEXPORT_EXECUTE_URL	export_idml
ADOBE_CAPABILITY_SMART_MAPPING_EXECUTE_URL	prepare_indd_merge_template
ADOBE_CLIENT_ID, ADOBE_CLIENT_SECRET, ADOBE_API_KEY, ADOBE_IMS_ORG_ID, ADOBE_CLIENT_CODE, ADOBE_IMS_TOKEN_URL, ADOBE_API_BASE_URL	All Adobe tools