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:
- 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.
- 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:
- A human-readable summary of text/image mappings (placeholder name → CSV column, frame UID)
- The raw mapping JSON in a code block
- 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 |