Templates are essential components in GelatoConnect that handle both incoming and outgoing data flows. They transform incoming customer data into formats your workflow can process, and they format outgoing data from GelatoConnect to meet your customers' system requirements. This guide will walk you through creating, testing, and implementing templates for both directions of data exchange in your order management workflows.
Understanding Templates in GelatoConnect
Templates in GelatoConnect serve as blueprints that define how data should be structured, processed, and presented. They handle two critical data flows:
Incoming Data Templates
These templates transform data coming from your customers' systems into formats that GelatoConnect can process:
Order Submit Request: Converts customer order data into GelatoConnect's internal format
Cancel Request: Formats cancellation requests to be understood by GelatoConnect
Outgoing Data Templates
These templates format data being sent from GelatoConnect back to your customers or their systems:
Response Formatting: Structures API responses to order submissions or cancellations
Event Notifications: Creates standardized messages for order status updates
Postbacks: Formats data sent to external systems when order statuses change
All templates use the Jinja2 templating language, which provides powerful features for data transformation, conditional logic, and dynamic content generation.
Types of Templates You Can Create
GelatoConnect supports several template types for different data flow directions:
Incoming Data Templates (Customer → GelatoConnect)
Order Submit Request: Transforms customer order data into GelatoConnect's format
Cancel Request: Transforms customer cancellation requests into GelatoConnect's format
Outgoing Data Templates (GelatoConnect → Customer)
Submit Response: Formats responses sent back after order submission
Cancel Response: Formats responses sent back after cancellation requests
Webhook: Creates JSON payloads for external system notifications on order status changes
Email: Formats email notifications for various order events
The direction of data flow is critical to understand when creating templates, as it determines what data is available and how it should be structured.
Step-by-Step Guide to Creating a Template
1. Navigate to the Templates Section
Log in to your GelatoConnect account
Go to Workflow > Order Intake > Templates
Click the Add Template button to start creating a new template
2. Choose Your Template Type
Select the type of template you want to create:
For API integrations, you'll typically need Order Submit Request, Submit Response, and Cancel Response templates
For notifications, select Webhook or Email
3. Define the Template Format
Choose the format for your template:
JSON: Most common for API integrations and webhooks
XML: Used for some legacy systems
Plain Text: Typically used for email templates
4. Generate a Sample Input Payload
To create an effective template, you need to understand what data will be available:
Click the Generate Template button
Select Add Sample Input Payload to provide test data
Choose the appropriate event type from the dropdown:
Order Received
Order Failed
Order Canceled
Order Returned
Order Produced
Order Delivered
Order Shipped
Order In Transit
The system will populate a sample payload with typical data for that event, which you can use as a reference when creating your template.
5. Create Your Template Mapper
The Template Mapper is where you define how data is transformed between formats:
In the Template Mapper section, write your template using Jinja2 syntax
Reference data from the input payload using double curly braces:
{{ variable }}Add formatting filters with the pipe symbol:
{{ variable|js }}(thejsfilter escapes strings for JSON)Use control structures like
{% if %},{% for %}, and{% set %}for conditional logic and loops
Template Direction Considerations
The content of your template will differ based on whether you're handling incoming or outgoing data:
For Incoming Data Templates (Customer → GelatoConnect):
Focus on extracting data from customer-specific formats
Map custom field names to GelatoConnect's standard field names
Validate and transform data to meet GelatoConnect's requirements
Handle any special formatting or data conversion needs
For Outgoing Data Templates (GelatoConnect → Customer):
Structure data according to what the customer's system expects
Include all required fields for the customer's integration
Format dates, currency values, and other data according to customer preferences
Add any customer-specific identifiers or references
Example: Order Received Webhook Template
Here's an example template for an "Order Received" webhook:
{
"event": "Order Received",
"orderId": "{{ orderId }}",
"orderReferenceId": "{{ orderReferenceId }}",
"timestamp": "{{ created }}",
"status": "{{ fulfillmentStatus }}",
"items": [
{% for item in items %}
{
"itemReferenceId": "{{ item.itemReferenceId }}",
"status": "{{ item.fulfillmentStatus }}"
}{% if not loop.last %},{% endif %}
{% endfor %}
],
"message": "The order has been received."
}This template creates a JSON structure with order details and iterates through all items in the order.
6. Render and Verify the Template
After creating your template:
Click the Render button to compile the template
Review the output in the preview pane
Verify that all data is properly formatted and that there are no syntax errors
Check for missing or improperly formatted fields
7. Test Your Template
Testing is crucial to ensure your template works correctly:
Assign a name to your test in the Test Template section
Click Run Test to execute the template against the sample data
Verify that the Status shows as Passed
Review the output to ensure it matches your expectations
8. Save Your Template
Once you're satisfied with the template:
Give your template a descriptive name
Click Add Template or Save Changes to save it
The template will now be available for use in triggers and workflow configurations
Using Templates with Triggers
Templates are most often used with triggers to automate notifications when specific events occur:
1. Create a Trigger
Go to Workflow > Order Intake > Triggers
Click Add Trigger
Select the customer this trigger applies to
Name your trigger (e.g., "Order Received Notification")
Select the event that will activate the trigger (e.g., "Order received")
2. Configure Delivery Method
Choose how notifications should be delivered:
URL: Send a webhook to an external system
Specify the destination URL
Select POST or GET method
Choose JSON or XML format
Configure retry options if desired
Email: Send an email notification
Enter recipient email addresses
Add a subject line
Specify sender name and address
3. Select Your Template
From the Template dropdown, select the template you created earlier
If no template exists, you can create one directly in the trigger configuration using the same interface described above
Creating Templates Directly from Triggers
For convenience, you can also create templates while setting up triggers:
When creating a trigger, instead of selecting an existing template, click Create Template
Define the template format (JSON, XML, or Plain Text)
Use the template editor to create your template as described above
Save the template, and it will be automatically selected for this trigger
This approach is useful for quick template creation when you're already configuring a trigger.
Linking Templates to API Endpoints
When submitting orders via API, you'll often need to transform data between your format and GelatoConnect's format. Templates handle this transformation, but you must explicitly link your template to the API endpoint for it to be applied.
How to link a template to an order submit endpoint:
Navigate to your connector list and click the Edit hyperlink next to the submit order endpoint.
On the endpoint configuration page, locate the Endpoint template section
Select your order submit template from the dropdown menu
Click the Set endpoint button in the top right of the page
Click Save changes in the top right to apply your configuration
After completing these steps, all order submissions sent to this endpoint will use your template to transform the data before processing. This ensures your system's format is correctly converted to GelatoConnect's expected format.
Without this configuration, your template will not be applied even if it exists and is correctly designed, which can lead to order validation failures if your data format doesn't exactly match GelatoConnect's requirements.
Advanced Template Techniques
Using Lookups
Lookups are especially valuable for bidirectional data mapping between systems. They work differently depending on the template direction:
For Incoming Templates (Customer → GelatoConnect):
Map customer-specific values to GelatoConnect's standardized values:
{% set shipMethod = lookups({"shipping_code": order.shipping.method}, strict=False, default="normal") %} "shipmentMethodUid": {{ shipMethod|js }},For Outgoing Templates (GelatoConnect → Customer):
Transform GelatoConnect's internal values to customer-expected formats:
{% set customerShippingCode = lookups({"gelatoShipMethod": shipment.shipmentMethodUid}, strict=False, default=shipment.shipmentMethodUid) %} "shipping_method": {{ customerShippingCode|js }},Conditional Logic
Use conditions to include or format data differently based on circumstances:
{% if item.fulfillmentStatus == "shipped" %}
"trackingNumber": "{{ item.trackingCode }}",
"trackingUrl": "{{ item.trackingUrl }}",
{% endif %}Variable Assignment
Create variables to simplify complex expressions:
{% set fullName = customer.firstName + " " + customer.lastName %} "recipientName": "{{ fullName }}",Loops with Complex Objects
Navigate nested data structures:
"items": [
{% for item in items %}
{
"sku": "{{ item.sku }}",
"quantity": {{ item.quantity }},
"options": [
{% for option in item.options %}
{
"name": "{{ option.name }}",
"value": "{{ option.value }}"
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
Template Best Practices
Direction-Based Naming Conventions
Use clear, descriptive names that indicate both purpose and data flow direction
For incoming templates: Include prefixes like "IN_" or suffixes like "_Request"
For outgoing templates: Use prefixes like "OUT_" or suffixes like "_Response" or "_Notification"
Include the customer name for customer-specific templates
Use consistent naming patterns to make templates easy to find
Error Handling
Set default values to prevent null references
Use the
defaultfilter for missing values:{{ variable|default('N/A') }}Use
try/exceptblocks for potentially problematic code sections
Maintenance
Add comments to explain complex logic:
{# This handles special case for international orders #}Keep templates modular and focused on specific purposes
Update templates when data structures or requirements change
Testing
Test with various data scenarios, including edge cases
Verify templates with real production data when possible
Create comprehensive tests for critical templates
Troubleshooting Template Issues
Common Problems and Solutions
Problem | Possible Cause | Solution |
Syntax error | Mismatched brackets or quotes | Check template syntax carefully; ensure all opening tags have corresponding closing tags |
Missing data | Referencing fields that don't exist | Verify field names against input payload; add default values for optional fields |
Formatting issues | Incorrect filter usage | Confirm proper usage of filters like |
Template not applied | Template not linked to trigger | Verify trigger configuration and template selection |
Nested data access errors | Incorrect path to nested properties | Check data structure and adjust property paths accordingly |
Field mapping errors | Incorrect field names for incoming/outgoing data | For incoming templates, verify customer field names; for outgoing templates, check expected response format |
Data transformation issues | Incompatible data formats | Ensure proper data type conversion between systems (dates, numbers, etc.) |
Debugging Tips
Use the Render button frequently during development to catch errors early
Add temporary debug output to examine variable values
Check for typos in field names, which are a common source of errors
Remember that Jinja2 is case-sensitive when referencing variables
Next Steps
After creating your templates, consider:
Setting up triggers for automatic notifications
Exploring advanced Jinja2 techniques
Creating lookup tables to enhance template flexibility
Establishing comprehensive testing procedures for your templates
For examples of common template patterns, refer to our Jinja2 Template Mapper Examples article.
Need help with your templates? Contact our support team at [email protected].