adobe-create-pdfs-from-data

# 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 ```json { "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 |