Skip to main content

Create templates

Goal​

To create and manage email and document templates in the Propeller backoffice that are used for automated communications and PDF generation. Templates use Handlebars syntax for dynamic content and can be triggered by system events or used for manual operations.

Understanding Template Types​

Propeller Commerce supports two template types:

Email Templates​

  • Send automated or manual emails
  • Support dynamic subject lines and content
  • Can include PDF attachments (document templates)
  • Used for order confirmations, welcome emails, password resets, etc.

Document Templates​

  • Generate PDF documents
  • Used for orders, quotes, invoices, and custom documents
  • Can be attached to email templates
  • Support default templates for system-generated PDFs

Step 1: Navigate to Templates​

  1. From the backoffice menu, select Shops & Channels and then Templates.
  2. The Templates overview displays:
    • Template ID
    • Name
    • Type (Email or Document)
    • Created date
    • Modified date

Step 2: Create a New Template​

  1. Click New Template button in the top right corner.
  2. A dropdown appears - select either:
    • Email Template
    • Document Template

Step 3: Configure General Settings​

The General tab is available for both template types:

Template Name​

  • Name (NL): Enter a descriptive name for the template
  • Use the language dropdown to add names in multiple languages
  • Examples: "Order confirmation email", "Quote PDF", "Welcome email B2C"

Template Content​

  • Content (NL): Add the HTML template using Handlebars syntax
  • Use the language dropdown to create content in multiple languages
  • Available Handlebars variables depend on the event trigger
  • Common variables include:
    • {{data.order.id}} - Order details
    • {{data.customer.email}} - Customer information
    • {{data.contact.firstName}} - Contact details

Format Code Button​

  • Click Format Code to automatically format and indent your HTML/Handlebars code
  • Helps maintain clean, readable template code

Step 4: Advanced Data Fetching (Optional)​

For complex templates requiring additional data:

Custom Query​

  • Add a GraphQL query to fetch extra data not in the event payload
  • Example for fetching user addresses:
query userAndAddresses($userId: Int!, $orderId: Int!, $productIds: [Int!]) {
  user(id: $userId) {
    class: __typename
    firstName
    lastName
    middleName
    gender
  }
  order(orderId: $orderId) {
    reference
    total {
      taxPercentages {
        percentage
        total
      }
    }
  }
  addresses: addressesByOrderId(orderId: $orderId) {
    street
    number
    numberExtension
    country
    region
    firstName
    lastName
    middleName
    gender
    email
    company
    type
  }
}

Query Variables​

  • Define variables for the custom query using Handlebars syntax
  • Must result in valid JSON after rendering
  • Example:
{
  "userId": {{data.order.userId}},
  "orderId": {{data.order.id}},
  "productIds": [
    {{#mapValues data.order.items "productId"}}
  ]
}

Step 5: Configure Email Settings (Email Templates Only)​

Switch to the Email tab:

Email Subject​

  • Subject (NL): Enter the email subject line
  • Supports Handlebars variables for dynamic subjects
  • Example: Order {{data.order.id}} confirmation

From Settings​

  • Email: Sender's email address (e.g., info@helice.cloud)
  • Name (NL): Display name for the sender (e.g., Mozo Klantenservice)

Recipients​

Configure email recipients using:

To Recipients​

  • Add direct email addresses
  • Use Handlebars variables: {{data.customer.email}}
  • Multiple recipients supported

CC Recipients​

  • Add recipients for carbon copy
  • Click Add recipients to add CC addresses

BCC Recipients​

  • Add hidden recipients
  • Click Add recipients to add BCC addresses

Step 6: Add PDF Attachments (Email Templates Only)​

Switch to the Attachments tab:

  1. Click Add attachment
  2. Select from existing document templates
  3. Selected templates will be rendered as PDFs and attached to the email
  4. Common use case: Attach order/quote PDF to confirmation emails

Step 7: Configure Document Settings (Document Templates Only)​

Switch to the Document tab:

File Name​

  • File name (NL): Define the PDF filename
  • Supports Handlebars variables
  • Example: Order_{{data.order.id}}.pdf

Default Template Settings​

Enable checkboxes to set as system default:

  • Default order PDF: Used for order PDFs in frontend and Sales Portal
  • Default Quotation PDF: Used for quote PDFs in frontend and Sales Portal

Only one template can be marked as default for each type.

Step 8: Review Properties​

The Properties section (collapsible) shows:

  • Template id: System-generated unique identifier
  • Created at: Template creation timestamp
  • Last modified at: Most recent update timestamp

Step 9: Save the Template​

  1. Click Save in the top right corner
  2. For existing templates, you'll also see:
    • Details tab: Current configuration
    • Logs tab: Template usage history

Template Logs​

The Logs tab provides detailed execution history for each template:

Viewing Template Logs​

  1. Navigate to an existing template
  2. Click the Logs tab
  3. The log overview displays:
    • Id: Unique error log identifier
    • Error type: Type of error encountered (e.g., RENDER_ERROR, CUSTOM_QUERY_ERROR)
    • Date Created: When the error occurred

Error Types​

  • RENDER_ERROR: Template rendering failed
  • CUSTOM_QUERY_ERROR: GraphQL custom query execution failed

Analyzing Error Details​

Click on any log entry to view:

  • Error Summary: Brief error description
  • Error Message: Detailed error information
  • Created At: Exact timestamp
  • Template Information: Template ID and name
  • Event Instance: The event data that triggered the error
  • Stack Trace: Full technical details (expandable)

Common Error Scenarios​

  1. "Failed to fetch template query data"

    • Custom GraphQL query syntax error
    • Invalid query variables
    • Permission issues accessing requested data

  2. Template variable errors

    • Accessing undefined variables
    • Incorrect Handlebars syntax
    • Missing required event data

Best Practices​

  • Naming Convention: Use clear, descriptive names indicating purpose and type
  • Multi-language Support: Create content for all supported languages
  • Testing: Always test templates with real data before deploying
  • Handlebars Helpers: Utilize built-in helpers like formatDate, mapValues
  • Error Handling: Include fallbacks for optional data fields
  • Responsive Design: For emails, ensure templates work on mobile devices
  • Version Control: Document major template changes in the name or description

Integration with Event Actions​

Templates are typically triggered through Event Actions:

  1. Create the template first
  2. Create an Event Action that references the template
  3. The event payload becomes available as {{data}} in the template

For technical details on available events and payloads, see the Event and Template Configuration documentation.