Skip to content
satware® AI OnlyOffice MCP

Template Authoring (Reference-Copy Pattern)

Overview

Section titled “Overview”

The reference-copy pattern is the recommended way to create pixel-perfect templates that exactly reproduce a customer’s corporate design. Unlike the pure DocBuilder script approach, the reference-copy pattern starts from an original reference file from the customer and injects data via OOXML post-processors.

When to Use Which Pattern?

Section titled “When to Use Which Pattern?”
Pattern When to use Example
DocBuilder script Simple layouts, no corporate design requirements Generic base templates
Reference-copy Pixel-perfect reproduction of existing documents Customer templates with logo, header, footer
docxtemplater DOCX with simple placeholders {{name}} in Word documents

Reference-Copy Workflow

Section titled “Reference-Copy Workflow”

  1. Obtain reference file from customer

    Request an original .docx/.xlsx/.pptx file from the customer. This file is the visual reference - every generated document must look exactly like it.

  2. Tokenize (insert placeholders)

    Replace fillable text in the reference file with token placeholders like {{TITLE}}, {{NAME}}, {{DATE}}. For DOCX, use FORMTEXT fields or simple {{TOKEN}} placeholders.

    Terminal-Fenster
    # Run tokenization script
    npx tsx scripts/tokenize-worms-reference-docx.ts <input.docx> <output.docx>

  3. Configure registry.json with post-processors

    Declare the post-processors in the template registry:

    {
      "templates": {
        "my_template": {
          "versions": {
            "v2.0": {
              "refDocxPath": "my_template/v2.0/reference.docx",
              "postProcessors": ["copyDOCXVisualAssets", "injectDOCXText"]
            }
          }
        }
      }
    }

  4. Create schema.json

    Define the fields the user fills in:

    {
      "type": "object",
      "properties": {
        "title": { "type": "string", "description": "Document title" },
        "date": { "type": "string", "format": "date" }
      },
      "required": ["title"]
    }

  5. Create a fixture for testing

    {
      "title": "Test Title",
      "date": "2026-08-03",
      "_postProcessorArgs": {
        "injectDOCXText": {
          "TITLE": "Test Title",
          "DATE": "03.08.2026"
        }
      }
    }

Post-Processor Reference

Section titled “Post-Processor Reference”

DOCX

Section titled “DOCX”
Post-processor Purpose Parameters
copyDOCXVisualAssets Copies theme, header, footer, logos, fonts from reference refDocxPath
injectDOCXText Injects text into {{TOKEN}} placeholders Token map in fixture
injectDOCXCheckboxes Sets SDT checkbox state from fixture booleans Token map with true/false

XLSX

Section titled “XLSX”
Post-processor Purpose Parameters
copyXLSXVisualAssets Copies formatting, sheets, column widths from reference refXlsxPath
injectXLSXText Injects text into sharedStrings and inline cells Token map in fixture

PPTX

Section titled “PPTX”
Post-processor Purpose Parameters
copyPPTXVisualAssets Copies theme, master layouts, media from reference refPptxPath
injectPPTXSlideText Injects text into slide placeholders Slot map per slide
removePPTXSlides Removes slides based on data (variable slide count) List of slide indices to remove

Token Conventions

Section titled “Token Conventions”
Token Format Usage
{{TOKEN_NAME}} DOCX/XLSX text placeholders
TITLE, SUBTITLE, SLIDE_TITLE PPTX slide titles
CONTENT, BULLET_1..3 PPTX slide content
CARD_TITLE_1..4, CONTENT_1..4 PPTX card layouts

Validate Visual Parity

Section titled “Validate Visual Parity”

Compare generated documents with the original reference:

Terminal-Fenster
# Generate visual review
npx tsx scripts/generate-worms-visual-review.ts


# Compare output with raw/worms/templates/

The FR-F1 (33 structural parity tests) and FR-F2 (3 E2E tests with 0 leftover tokens) validate structural parity automatically.

Section titled “Related”