What Are Template Mappers?

Template mappers in GelatoConnect are powerful tools that transform data between your system's format and GelatoConnect's format. They act as translators, ensuring that information flows seamlessly between different systems, regardless of how each system structures its data.

Whether you're submitting orders to GelatoConnect or receiving updates about order status changes, template mappers make it possible to convert data formats without requiring changes to your existing systems.

Why Use Template Mappers?

Template mappers solve several common integration challenges:

Different Data Structures: Your system and GelatoConnect may organize the same information differently.
Field Naming Differences: Your system might call a shipping address "delivery_address" while GelatoConnect uses "shippingAddress".
Format Conversions: You might need to convert data formats, such as changing date formats or transforming measurement units.
Selective Field Mapping: You might want to include only specific fields from your data when sending to GelatoConnect.
Conditional Logic: You might need to apply different mapping rules based on certain conditions, such as order type or destination country.

How Template Mappers Work

GelatoConnect uses the Jinja2 templating language for its template mappers. This powerful and flexible language allows you to:

Extract Values: Pull data from your input format
Transform Data: Apply functions and logic to modify the data
Build Output: Construct the final output in GelatoConnect's expected format

A template mapper takes an input (your data) and produces an output (GelatoConnect-compatible data) based on a set of transformation rules you define.

Template Mapper Components

A typical template mapper in GelatoConnect consists of these components:

1. Input Data

This is the source data you want to transform. It could be:

Order data from your e-commerce system
Customer information from your CRM
Product details from your catalog

2. Template Definition

This is where you define how to transform the input data. Using Jinja2 syntax, you specify:

Which fields to extract from the input
Any transformations to apply
The structure of the output

3. Output Format

The result of the template processing, typically in JSON format that conforms to GelatoConnect's API requirements.

Basic Template Mapper Example

Let's look at a simple example that converts an order from your system's format to GelatoConnect's format:

Your System's Order Data:

{
  "order_id": "ORD-12345",
  "customer": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "delivery": {
    "street": "123 Main St",
    "city": "New York",
    "zip": "10001",
    "country": "US"
  },
  "products": [
    {
      "sku": "POSTER-A4-MATTE",
      "qty": 2,
      "image_url": "https://example.com/images/poster1.jpg"
    }
  ]
}

Template Mapper:

{
  "orderReferenceId": "{{ order_id }}",
  "orderType": "order",
  "currency": "USD",
  "shippingAddress": {
    "firstName": "{{ customer.name.split(' ')[0] }}",
    "lastName": "{{ customer.name.split(' ')[1] }}",
    "addressLine1": "{{ delivery.street }}",
    "city": "{{ delivery.city }}",
    "postCode": "{{ delivery.zip }}",
    "country": "{{ delivery.country }}",
    "email": "{{ customer.email }}",
    "phone": "+1234567890"
  },
  "items": [
    {% for product in products %}
    {
      "itemReferenceId": "{{ order_id }}-{{ loop.index }}",
      "productUid": "{{ lookups({'sku': product.sku}, strict=False, default='') }}",
      "quantity": {{ product.qty }},
      "files": [
        {
          "type": "default",
          "url": "{{ product.image_url }}"
        }
      ]
    }{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}

Resulting GelatoConnect-Compatible Order:

{
  "orderReferenceId": "ORD-12345",
  "orderType": "order",
  "currency": "USD",
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "city": "New York",
    "postCode": "10001",
    "country": "US",
    "email": "[email protected]",
    "phone": "+1234567890"
  },
  "items": [
    {
      "itemReferenceId": "ORD-12345-1",
      "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
      "quantity": 2,
      "files": [
        {
          "type": "default",
          "url": "https://example.com/images/poster1.jpg"
        }
      ]
    }
  ]
}

Key Template Mapper Features

Variable Interpolation

Use double curly braces to insert values from the input data:

jinja"orderReferenceId": "{{ order_id }}"

Filters

Apply transformations to values with filters (indicated by the pipe symbol):

jinja"firstName": "{{ customer.name | title }}"

Common filters include:

upper: Convert to uppercase
lower: Convert to lowercase
title: Capitalize the first letter of each word
trim: Remove whitespace from start and end
default: Provide a default value if the variable is undefined
js: Ensure the value is properly formatted for JSON

Control Structures

Use logic to conditionally include content or iterate over arrays:

{% for product in products %}
  // Process each product
{% endfor %}

{% if customer.type == "business" %}
  // Include business-specific fields
{% else %}
  // Include individual customer fields
{% endif %}

Lookups

Use the lookups() function to map values between systems, such as converting your product SKUs to GelatoConnect product UIDs:

jinja"productUid": "{{ lookups({'sku': product.sku}, strict=False, default='') }}"

The lookup functionality requires setting up lookup tables in GelatoConnect, which map your system's values to GelatoConnect's values.

Creating and Testing Template Mappers

GelatoConnect provides a user-friendly interface for creating and testing template mappers:

Create a Template: Navigate to the Templates section and create a new template.
Choose Template Type: Select the appropriate template type (e.g., Order Submit Request, Order Received notification).
Define the Template: Write your Jinja2 template in the editor.
Test with Sample Data: Provide sample input data and render the template to see the result.
Debug and Refine: Adjust your template as needed based on the rendered output.
Save and Activate: Once your template is working correctly, save it for use in your integration.

Common Use Cases for Template Mappers

1. Order Submission Mapping

Transform orders from your system's format to GelatoConnect's API format.

2. Status Update Notifications

Create templates for different order status events (received, shipped, delivered) to notify your systems.

3. Custom Webhooks

Format data to send to third-party systems when specific events occur.

4. Data Normalization

Standardize data from multiple sources before processing.

Best Practices for Template Mappers

Start Simple: Begin with a basic template and gradually add complexity.

Use Comments: Add comments to explain complex transformations.

jinja{# This extracts the first and last name from the full name #}

Handle Missing Data: Always provide defaults or checks for optional fields.
```
jinja"additionalInfo": "{{ customer.notes | default('') }}"
```
Test Edge Cases: Ensure your templates handle unexpected input formats or values.
Use Lookups for Complex Mappings: Rather than hardcoding mappings in your template, use the lookups functionality.
Keep Templates Focused: Create separate templates for different purposes rather than one complex template.
Validate Output: Always verify that your template output meets GelatoConnect's API requirements.

Advanced Template Mapper Techniques

As you become more comfortable with template mappers, you can utilize advanced features:

Macros

Define reusable blocks of template code:

{% macro format_address(address) %}
  {
    "addressLine1": "{{ address.street }}",
    "city": "{{ address.city }}",
    "postCode": "{{ address.zip }}",
    "country": "{{ address.country }}"
  }
{% endmacro %}

// Then use it like this:
"shippingAddress": {{ format_address(delivery) }}

Set Statements

Create variables within your template:

{% set full_name = customer.firstName + ' ' + customer.lastName %}
"recipientName": "{{ full_name }}"

Custom Filters and Functions

GelatoConnect supports several custom filters and functions beyond standard Jinja2:

lookups(): For mapping between value systems
js: For proper JSON escaping
Various date formatting functions

Next Steps

Now that you understand the basics of template mappers in GelatoConnect, you're ready to:

Learn more about creating templates for order intake
Explore Jinja2 template examples
Set up postback triggers that use your templates
Understand how to test and troubleshoot your templates

If you need assistance with template mappers, contact our support team at [email protected].

How to Setup Lookups

Getting Started with GelatoConnect API

Template Mapper Examples

Setting Up Lookups for API Integration

Creating Templates for Order Intake

Introduction to Template Mappers in GelatoConnect