Data Mapping & Configuration

While the Layout Template defines how your PDF looks, the Mapping File defines where the data comes from and how it is processed. This separation allows you to change data logic (e.g., adding a tax calculation) without touching the visual design.

1. Basic Key Mapping

The MAPPING section connects your CSV/Excel column headers to the internal variable names used in your layout template.

# mapping.yaml
MAPPING:
  # Internal Name : CSV Column Header
  customer: "Customer Name"
  qty: "Quantity"
  price: "Unit Price"

2. Automatic Calculations

You don't need to do math in Excel before exporting. Use the CALCULATIONS section to perform logic during generation.

Row-Level Calculation (Item Scope)

Calculates values for each specific row in your data.

CALCULATIONS:
  - scope: "item"
    target: "amount"               # New variable created
    expression: "qty * price"      # Simple math using mapped keys

Group-Level Calculation (Group Scope)

Calculates totals across a group of rows (e.g., a total for one invoice).

  - scope: "group"
    target: "subtotal"
    type: "sum"                    # "sum" adds up values
    field: "amount"                # The field to sum up

3. Plugins (Advanced)

For advanced features like QR codes and Barcodes, use the PLUGINS section. (In YAML, these are simplified wrappers around the Python plugins).

PLUGINS:
  - type: "QRCode"
    source: "invoice_url"          # Column containing the URL
    target: "qr_code_path"         # Variable to use in Layout "image"
    options:
      version: 1
      box_size: 10