Deep Dive: PDF Generation

Introduction

Zudello allows users to automatically generate PDF documents based on data within the system, primarily using configured templates. This feature is commonly used for creating customer or supplier-facing documents like Purchase Orders directly from Zudello data, eliminating the need for manual creation in external tools.

This guide covers configuring PDF templates using Microsoft Word, understanding the data placeholders available, triggering PDF generation via Sentences, and troubleshooting common template issues.

Template Creation and Configuration

Zudello utilizes Microsoft Word documents (.docx) as the source for PDF templates. This allows users familiar with Word to design the layout and static content.

1. Design in Word:
   • Create a new Word document (.docx).
   • Design the layout, including headers, footers, logos, static text (e.g., terms and conditions), and tables for line items.
   • Use standard Word formatting features (fonts, colours, tables, images).
2. Insert Placeholders:
   • Identify where dynamic data from Zudello needs to appear in the template.
   • Use specific placeholder syntax (typically Jinja2-like syntax, e.g., {{ field_name }}) to mark these locations. See Understanding Placeholders below.
   • Placeholders can be used for header fields (e.g., {{ document_number }}, {{ supplier.name }}) and within table rows for line items (e.g., {{ line.sku }}, {{ line.description }}, {{ line.quantity }}, {{ line.unit_price_local }}).
3. Upload Template:
   • Navigate to Settings > PDF Templates.
   • Click New PDF Template.
   • Give the template a Name and Description.
   • Select the Module and Submodule the template applies to (e.g., Purchasing > Order).
   • Upload the designed .docx file.
   • Save the template.

Zudello converts the .docx file into its required format in the background.

Understanding Placeholders and Data Structure

Placeholders allow Zudello to insert dynamic data from the specific resource (e.g., the Purchase Order being processed) into the generated PDF.

• Syntax: Placeholders typically use double curly braces: {{ placeholder_name }}.
• Accessing Data:
  • Header Fields: Use the field's API name directly (e.g., {{ document_number }}, {{ date_issued }}, {{ total_local }}).
  • Related Fields (e.g., Supplier): Use dot notation to access fields from related records (e.g., {{ supplier.name }}, {{ supplier.tax_number }}, {{ supplier.primary_address.street }}). You need to know the relationship name (supplier, customer, employee) and the field names on the related record.
  • Line Items: Templates need a mechanism to loop through line items. This usually involves specific tags within a table row in the Word document:
    • Start Loop Tag: Often something like {% for line in lines %} placed before the table row containing line item placeholders.
    • End Loop Tag: Often something like {% endfor %} placed after the table row.
    • Inside the loop, access line fields using dot notation with the loop variable (e.g., {{ line.sku }}, {{ line.description }}, {{ line.quantity }}, {{ line.unit_price_local }}, {{ line.total_local }}).
  • Custom Fields: Access custom fields using {{ custom.your_custom_field_key }}.
• Data Availability: The data available depends on the specific resource (Module/Submodule) the template is associated with and the data present on the record when the PDF is generated. You can inspect the resource's JSON data (via API or potentially Staff tools) to confirm field names and structure.
• Formatting (Advanced): Jinja2 syntax often supports basic filters for formatting dates, numbers, or currencies (e.g., {{ date_issued | date_format }}). Refer to specific Zudello documentation or examples for supported filters.

Generating PDFs via Sentences

PDF generation is typically triggered as an action within an Automation Sentence.

1. Create/Edit Sentence: Go to Settings > Automations.
2. Set Trigger/Conditions: Define when the PDF should be generated (e.g., "When resource status has changed" to PLACED for a PO).
3. Add Action: Select the Generate PDF action.
4. Configure Action:
   • Template: Select the desired PDF Template (created in Settings > PDF Templates). Note: Currently, the specific template might be implicitly linked via Module/Submodule rather than explicitly selected in the Sentence action - verify current implementation.
   • Filename (Optional): Define a dynamic filename using placeholders (e.g., PO_{{ document_number }}_{{ supplier.name }}.pdf). If left blank, a default name is used.
5. Save Sentence.

When the Sentence trigger occurs and conditions are met, the Generate PDF action runs:

1. Zudello fetches the data for the current resource.
2. It merges the data with the selected .docx template, replacing placeholders.
3. It converts the merged document to PDF format.
4. The generated PDF is stored as a Related Attachment to the resource.

Customizing Templates for Different Document Types

• Create separate templates for different needs (e.g., Purchase Order, Sales Invoice, Expense Report).
• Associate each template with the correct Module and Submodule during configuration.
• Use appropriate placeholders relevant to the specific data structure of that Module/Submodule.
• Trigger the correct template generation using Sentences specific to the workflow of that document type.

Troubleshooting Template Issues

• PDF Generation Fails (Error in Sentence Log):
  • Cause: Often due to incorrect placeholder syntax, referencing non-existent fields, or issues in the template's structure (e.g., broken loops, invalid XML in the .docx).
  • Solution: Carefully review placeholder syntax. Verify field names against the resource's JSON data. Simplify the template to isolate the problematic section. Re-upload a clean version of the .docx.
• Placeholders Not Replaced (Appear as {{ placeholder }} in PDF):
  • Cause: Incorrect placeholder name, field is empty on the resource record, or the data wasn't available/loaded correctly during generation.
  • Solution: Double-check placeholder spelling and case sensitivity. Ensure the field exists and has data on the specific resource record being tested. Verify the relationship path (e.g., supplier.name vs. customer.name).
• Formatting Issues (Layout, Fonts, Images):
  • Cause: Complex Word features might not translate perfectly during conversion. Font embedding issues. Image compatibility problems.
  • Solution: Simplify formatting. Use standard, widely available fonts. Ensure images are in compatible formats (JPG, PNG) and reasonably sized. Test incremental changes.
• Line Items Not Appearing or Repeating Incorrectly:
  • Cause: Incorrect loop syntax ({% for ... %}, {% endfor %}) or placement relative to the table row. Incorrect line variable name used inside the loop (e.g., {{ item.sku }} instead of {{ line.sku }}).
  • Solution: Verify loop syntax and ensure tags are correctly placed outside the <w:tr> tags in the underlying Word XML (can be tricky). Confirm the correct variable name (line is common) is used for accessing line fields.

By understanding the template creation process, placeholder syntax, and Sentence integration, users can effectively leverage Zudello's PDF generation capabilities.