This guide provides practical examples of Jinja2 template mappers in GelatoConnect to help you implement common data transformation scenarios. Whether you're mapping order data, transforming notifications, or implementing lookups, these examples will give you a solid foundation.
Basic Order Submission Example
This example shows how to map a standard order submission:
Input Data:
{
"order": {
"id": "12345",
"customer_email": "[email protected]",
"items": [
{
"id": "item-1",
"product_code": "POSTER-A3",
"quantity": 2,
"file_url": "https://example.com/files/poster.pdf"
}
],
"shipping": {
"recipient": {
"first_name": "John",
"last_name": "Smith"
},
"address": {
"line1": "123 Main St",
"line2": "Apt 4B",
"city": "New York",
"postal_code": "10001",
"country": "US",
"state": "NY"
},
"phone": "212-555-1234"
}
}
}Template Mapper:
{
"orderReferenceId": "{{ order.id }}",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
"firstName": "{{ order.shipping.recipient.first_name }}",
"lastName": "{{ order.shipping.recipient.last_name }}",
"addressLine1": "{{ order.shipping.address.line1 }}",
"addressLine2": "{{ order.shipping.address.line2 }}",
"city": "{{ order.shipping.address.city }}",
"postCode": "{{ order.shipping.address.postal_code }}",
"country": "{{ order.shipping.address.country }}",
"state": "{{ order.shipping.address.state }}",
"email": "{{ order.customer_email }}",
"phone": "{{ order.shipping.phone }}"
},
"items": [
{% for item in order.items %}
{
"itemReferenceId": "{{ item.id }}",
"productUid": "{{ lookups({'product_code': item.product_code}, strict=False, default='') }}",
"quantity": {{ item.quantity }},
"files": [
{
"type": "default",
"url": "{{ item.file_url }}"
}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}Working with Multiple Product Files
This example handles products with multiple files (front and back):
Input Data:
{
"orderReferenceId": "{{ order.id }}",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
"firstName": "{{ order.shipping.recipient.first_name }}",
"lastName": "{{ order.shipping.recipient.last_name }}",
"addressLine1": "{{ order.shipping.address.line1 }}",
"addressLine2": "{{ order.shipping.address.line2 }}",
"city": "{{ order.shipping.address.city }}",
"postCode": "{{ order.shipping.address.postal_code }}",
"country": "{{ order.shipping.address.country }}",
"state": "{{ order.shipping.address.state }}",
"email": "{{ order.customer_email }}",
"phone": "{{ order.shipping.phone }}"
},
"items": [
{% for item in order.items %}
{
"itemReferenceId": "{{ item.id }}",
"productUid": "{{ lookups({'product_code': item.product_code}, strict=False, default='') }}",
"quantity": {{ item.quantity }},
"files": [
{
"type": "default",
"url": "{{ item.file_url }}"
}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}Template Mapper:
{
"orderReferenceId": "{{ orderNumber }}",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
{% set nameParts = deliveryDetails.contactName.split(' ') %}
"firstName": "{{ nameParts[0] }}",
"lastName": "{{ nameParts[1:] | join(' ') }}",
"addressLine1": "{{ deliveryDetails.address.street }}",
"city": "{{ deliveryDetails.address.city }}",
"state": "{{ deliveryDetails.address.state }}",
"postCode": "{{ deliveryDetails.address.zip }}",
"country": "{{ deliveryDetails.address.country }}",
"email": "{{ deliveryDetails.email }}",
"phone": "{{ deliveryDetails.phone }}"
},
"items": [
{% for product in products %}
{
"itemReferenceId": "{{ product.productId }}",
"productUid": "{{ lookups({'sku': product.sku}, strict=False, default='') }}",
"quantity": {{ product.qty }},
"files": [
{
"type": "front",
"url": "{{ product.files.front }}"
},
{
"type": "back",
"url": "{{ product.files.back }}"
}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}Conditional Logic Example
This example demonstrates conditional logic to handle different product types:
Input Data:
{
"orderId": "ORD-5555",
"customer": {
"name": "Alice Johnson",
"email": "[email protected]",
"phone": "555-123-4567"
},
"shipping": {
"address": "789 Pine St",
"apartment": "",
"city": "Boston",
"state": "MA",
"zipCode": "02108",
"country": "US"
},
"items": [
{
"id": "ITEM-A",
"type": "poster",
"sku": "POSTER-LG",
"quantity": 1,
"image": "https://example.com/files/poster.jpg"
},
{
"id": "ITEM-B",
"type": "card",
"sku": "CARD-SM",
"quantity": 100,
"frontImage": "https://example.com/files/card-front.jpg",
"backImage": "https://example.com/files/card-back.jpg"
}
]
}Template Mapper:
{
"orderReferenceId": "{{ orderId }}",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
{% set nameParts = customer.name.split(' ') %}
"firstName": "{{ nameParts[0] }}",
"lastName": "{{ nameParts[1:] | join(' ') }}",
"addressLine1": "{{ shipping.address }}",
{% if shipping.apartment %}
"addressLine2": "{{ shipping.apartment }}",
{% endif %}
"city": "{{ shipping.city }}",
"state": "{{ shipping.state }}",
"postCode": "{{ shipping.zipCode }}",
"country": "{{ shipping.country }}",
"email": "{{ customer.email }}",
"phone": "{{ customer.phone }}"
},
"items": [
{% for item in items %}
{
"itemReferenceId": "{{ item.id }}",
"productUid": "{{ lookups({'sku': item.sku}, strict=False, default='') }}",
"quantity": {{ item.quantity }},
"files": [
{% if item.type == 'poster' %}
{
"type": "default",
"url": "{{ item.image }}"
}
{% elif item.type == 'card' %}
{
"type": "front",
"url": "{{ item.frontImage }}"
},
{
"type": "back",
"url": "{{ item.backImage }}"
}
{% endif %}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}Order Status Update Postback Example
This example formats a postback notification for order status changes:
Input Data:
{
"orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",
"orderReferenceId": "J123X456",
"customerReferenceId": "CUST-789",
"fulfillmentStatus": "shipped",
"created": "2023-04-12T10:26:52+00:00",
"items": [
{
"itemReferenceId": "123",
"fulfillmentStatus": "shipped",
"fulfillments": [
{
"trackingCode": "TRK123456789",
"trackingUrl": "https://example.com/tracking?code=TRK123456789",
"carrierName": "FedEx",
"carrierUid": "fed_ex_ground",
"fulfillmentCountry": "US",
"fulfillmentStateProvince": "NY"
}
]
}
]
}Template Mapper:
{
"event": "ORDER_SHIPPED",
"timestamp": "{{ created }}",
"order": {
"id": "{{ orderReferenceId }}",
"customer_id": "{{ customerReferenceId }}",
"status": "{{ fulfillmentStatus | upper }}",
"shipped_items": [
{% for item in items %}
{% if item.fulfillmentStatus == 'shipped' %}
{
"item_id": "{{ item.itemReferenceId }}",
"tracking": {
{% for fulfillment in item.fulfillments %}
"carrier": "{{ fulfillment.carrierName }}",
"tracking_number": "{{ fulfillment.trackingCode }}",
"tracking_url": "{{ fulfillment.trackingUrl }}",
"shipped_from": {
"country": "{{ fulfillment.fulfillmentCountry }}",
"state": "{{ fulfillment.fulfillmentStateProvince }}"
}
{% endfor %}
}
}{% if not loop.last %},{% endif %}
{% endif %}
{% endfor %}
]
}
}Advanced Lookups Example
This example demonstrates complex lookups for product mapping and carrier selection:
Input Data:
{
"reference": "ORDER-8888",
"recipient": {
"fullName": "Robert Brown",
"emailAddress": "[email protected]",
"phoneNumber": "888-555-1212",
"shippingInformation": {
"streetAddress": "321 Oak Ave",
"city": "Chicago",
"state": "IL",
"postalCode": "60601",
"countryCode": "US"
}
},
"orderItems": [
{
"lineItemId": "LI-001",
"productReference": {
"code": "BK-HCVR-A5",
"type": "hardcover_book",
"size": "A5"
},
"quantity": 1,
"assetUrls": {
"coverFile": "https://example.com/files/book-cover.pdf",
"interiorFile": "https://example.com/files/book-interior.pdf"
},
"additionalAttributes": {
"pageCount": 120,
"paperType": "premium"
}
}
],
"shippingPreference": "standard",
"region": "north_america"
}Template Mapper:
{% set shipping_lookup = {
"express_north_america": "fed_ex_2_day",
"express_europe": "dhl_express_eu",
"standard_north_america": "ups_ground",
"standard_europe": "dhl_parcel_eu"
} %}
{% set product_lookup = {} %}
{% set product_lookup = product_lookup.update({
"BK-HCVR-A5-premium": "book_product_pf_a5_pt_premium_cl_4-4_hcvr",
"BK-HCVR-A5-standard": "book_product_pf_a5_pt_standard_cl_4-4_hcvr",
"BK-SCVR-A5-premium": "book_product_pf_a5_pt_premium_cl_4-4_scvr",
"BK-SCVR-A5-standard": "book_product_pf_a5_pt_standard_cl_4-4_scvr"
}) %}
{
"orderReferenceId": "{{ reference }}",
"orderType": "order",
"currency": "USD",
{% set shipping_key = shippingPreference + '_' + region %}
"shipmentMethodUid": "{{ shipping_lookup.get(shipping_key, 'normal') }}",
"shippingAddress": {
{% set name_parts = recipient.fullName.split(' ') %}
"firstName": "{{ name_parts[0] }}",
"lastName": "{{ name_parts[1:] | join(' ') }}",
"addressLine1": "{{ recipient.shippingInformation.streetAddress }}",
"city": "{{ recipient.shippingInformation.city }}",
"state": "{{ recipient.shippingInformation.state }}",
"postCode": "{{ recipient.shippingInformation.postalCode }}",
"country": "{{ recipient.shippingInformation.countryCode }}",
"email": "{{ recipient.emailAddress }}",
"phone": "{{ recipient.phoneNumber }}"
},
"items": [
{% for item in orderItems %}
{
"itemReferenceId": "{{ item.lineItemId }}",
{% set product_key = item.productReference.code + '-' + item.additionalAttributes.paperType %}
"productUid": "{{ product_lookup.get(product_key, lookups({'code': item.productReference.code, 'paper': item.additionalAttributes.paperType}, strict=False, default='')) }}",
"quantity": {{ item.quantity }},
"pageCount": {{ item.additionalAttributes.pageCount }},
"files": [
{
"type": "cover",
"url": "{{ item.assetUrls.coverFile }}"
},
{
"type": "inside",
"url": "{{ item.assetUrls.interiorFile }}"
}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}Working with Dates and Formatting
This example shows date formatting and string manipulation:
Input Data:
{
"orderNum": "INV-20230412-001",
"datePlaced": "2023-04-12T14:30:00Z",
"clientDetails": {
"id": "CLIENT001",
"contactInfo": {
"name": "SARAH WILLIAMS",
"email": "[email protected]",
"telephone": "1.212.555.7890"
},
"deliveryAddress": {
"line1": "555 Broadway",
"line2": "Floor 10",
"city": "New York",
"region": "New York",
"code": "10012",
"country": "United States"
}
},
"lineItems": [
{
"refCode": "LI-001-A",
"productIdentifier": "BROCHURE-A4-GLOSSY",
"amount": 250,
"artwork": "https://example.com/files/brochure.pdf"
}
]
}Template Mapper:
{% set country_codes = {
"United States": "US",
"United Kingdom": "GB",
"Canada": "CA",
"Australia": "AU",
"Germany": "DE",
"France": "FR"
} %}
{% set date_parts = datePlaced.split('T')[0].split('-') %}
{% set formatted_date = date_parts[1] + '/' + date_parts[2] + '/' + date_parts[0] %}
{
"orderReferenceId": "{{ orderNum }}",
"orderType": "order",
"currency": "USD",
"metadata": [
{
"key": "clientId",
"value": "{{ clientDetails.id }}"
},
{
"key": "orderDate",
"value": "{{ formatted_date }}"
}
],
"shippingAddress": {
{% set name_parts = clientDetails.contactInfo.name | lower | title | split(' ') %}
"firstName": "{{ name_parts[0] }}",
"lastName": "{{ name_parts[1:] | join(' ') }}",
"addressLine1": "{{ clientDetails.deliveryAddress.line1 }}",
"addressLine2": "{{ clientDetails.deliveryAddress.line2 }}",
"city": "{{ clientDetails.deliveryAddress.city }}",
"state": "{{ clientDetails.deliveryAddress.region }}",
"postCode": "{{ clientDetails.deliveryAddress.code }}",
"country": "{{ country_codes.get(clientDetails.deliveryAddress.country, 'US') }}",
"email": "{{ clientDetails.contactInfo.email }}",
"phone": "{{ clientDetails.contactInfo.telephone | replace('.', '-') }}"
},
"items": [
{% for item in lineItems %}
{
"itemReferenceId": "{{ item.refCode }}",
"productUid": "{{ lookups({'product_id': item.productIdentifier}, strict=False, default='') }}",
"quantity": {{ item.amount }},
"files": [
{
"type": "default",
"url": "{{ item.artwork }}"
}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}Error Handling and Default Values
This example demonstrates robust error handling with default values:
Input Data:
{
"id": "ORD-91011",
"buyer": {
"name": "Michael Johnson"
// Missing email field
},
"shipping": {
"name": "Michael Johnson",
"address": "111 River Rd",
// Missing city
"province": "Ontario",
"postal": "M5V 2H1",
"country": "CA"
},
"items": [
{
"id": "ITEM-001",
"sku": "CALENDAR-WALL",
"quantity": 1,
"assets": {
"main": "https://example.com/files/calendar.pdf"
}
},
{
// Incomplete item
"id": "ITEM-002"
}
]
}Template Mapper:
{
"orderReferenceId": "{{ id }}",
"orderType": "order",
"currency": "CAD",
"shippingAddress": {
{% set recipient = shipping.name | default('') %}
{% set name_parts = recipient.split(' ') if recipient else ['', ''] %}
"firstName": "{{ name_parts[0] | default('Unknown') }}",
"lastName": "{{ name_parts[1:] | join(' ') | default('Customer') }}",
"addressLine1": "{{ shipping.address | default('Address Missing') }}",
"city": "{{ shipping.city | default('Toronto') }}",
"state": "{{ shipping.province | default('ON') }}",
"postCode": "{{ shipping.postal | default('') }}",
"country": "{{ shipping.country | default('CA') }}",
"email": "{{ buyer.email | default('[email protected]') }}",
"phone": "{{ buyer.phone | default('000-000-0000') }}"
},
"items": [
{% for item in items %}
{% if item.id and item.sku and item.quantity %}
{
"itemReferenceId": "{{ item.id }}",
"productUid": "{{ lookups({'sku': item.sku}, strict=False, default='') }}",
"quantity": {{ item.quantity }},
"files": [
{
"type": "default",
"url": "{{ item.assets.main | default('') }}"
}
]
}{% if not loop.last %},{% endif %}
{% endif %}
{% endfor %}
]
}Combining Multiple Sources
This example combines data from multiple sources:
Input Data:
{
"order": {
"id": "PO-12345",
"type": "standard"
},
"customer": {
"id": "CUST-789",
"segment": "business"
},
"recipient": {
"first": "David",
"last": "Miller",
"email": "[email protected]",
"phone": "303-555-1212",
"delivery": {
"address": "987 State St",
"suite": "Suite 500",
"city": "Denver",
"state": "CO",
"zip": "80202",
"country": "US"
}
},
"products": [
{
"id": "PROD-A1",
"code": "FLYER-A4-FULL",
"count": 500,
"artwork": "https://example.com/files/flyer.pdf"
}
],
"shipping": {
"method": "ground",
"expectedDays": 3
},
"promotional": {
"campaign": "SPRING2023",
"source": "email"
}
}Template Mapper:
{% set shipping_method_map = {
"overnight": "fed_ex_priority_overnight",
"express": "fed_ex_2_day",
"ground": "fed_ex_ground"
} %}
{
"orderReferenceId": "{{ order.id }}",
"orderType": "{{ 'draft' if order.type == 'preorder' else 'order' }}",
"currency": "USD",
"customerReferenceId": "{{ customer.id }}",
"shipmentMethodUid": "{{ shipping_method_map.get(shipping.method, 'normal') }}",
"metadata": [
{
"key": "campaign",
"value": "{{ promotional.campaign }}"
},
{
"key": "source",
"value": "{{ promotional.source }}"
},
{
"key": "segment",
"value": "{{ customer.segment }}"
},
{
"key": "expectedDelivery",
"value": "{{ shipping.expectedDays }}"
}
],
"shippingAddress": {
"firstName": "{{ recipient.first }}",
"lastName": "{{ recipient.last }}",
"addressLine1": "{{ recipient.delivery.address }}",
"addressLine2": "{{ recipient.delivery.suite }}",
"city": "{{ recipient.delivery.city }}",
"state": "{{ recipient.delivery.state }}",
"postCode": "{{ recipient.delivery.zip }}",
"country": "{{ recipient.delivery.country }}",
"email": "{{ recipient.email }}",
"phone": "{{ recipient.phone }}"
},
"items": [
{% for product in products %}
{
"itemReferenceId": "{{ product.id }}",
"productUid": "{{ lookups({'product_code': product.code}, strict=False, default='') }}",
"quantity": {{ product.count }},
"files": [
{
"type": "default",
"url": "{{ product.artwork }}"
}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}Working with Complex Nested Structures
This example shows how to handle deeply nested data structures:
Input Data:
{
"data": {
"transaction": {
"identifiers": {
"internalRef": "TX-44556",
"customerRef": "CUST-ABC123"
},
"metadata": {
"createdAt": "2023-04-12T09:15:00Z",
"source": "web",
"tags": ["priority", "corporate"]
}
},
"parties": {
"sender": {
"organization": "Acme Corp",
"contact": {
"person": {
"givenName": "Thomas",
"familyName": "Anderson"
},
"details": {
"email": {
"address": "[email protected]"
},
"phone": {
"number": "415-555-9876",
"extension": "123"
}
}
}
},
"recipient": {
"person": {
"givenName": "Sarah",
"familyName": "Connor"
},
"contactDetails": {
"emailAddress": "[email protected]",
"phoneNumber": "213-555-4321"
},
"location": {
"address": {
"street": "1984 Tech Blvd",
"unit": "#42",
"locality": "Los Angeles",
"region": "California",
"postalCode": "90210",
"country": "USA"
}
}
}
},
"contents": {
"items": [
{
"descriptor": {
"id": "ITM-X789",
"type": "brochure",
"specifications": {
"format": "A4",
"paperType": "Glossy",
"colorProfile": "CMYK"
}
},
"quantity": {
"value": 1000,
"unit": "pcs"
},
"digitalAssets": {
"printable": {
"fileLocation": "https://example.com/files/brochure-complex.pdf"
}
}
}
]
}
}
}Template Mapper:
{% set country_map = {
"USA": "US",
"United States": "US",
"United States of America": "US",
"UK": "GB",
"United Kingdom": "GB",
"England": "GB"
} %}
{
"orderReferenceId": "{{ data.transaction.identifiers.internalRef }}",
"orderType": "order",
"currency": "USD",
"customerReferenceId": "{{ data.transaction.identifiers.customerRef }}",
"metadata": [
{
"key": "createdAt",
"value": "{{ data.transaction.metadata.createdAt }}"
},
{
"key": "source",
"value": "{{ data.transaction.metadata.source }}"
},
{% for tag in data.transaction.metadata.tags %}
{
"key": "tag_{{ loop.index }}",
"value": "{{ tag }}"
}{% if not loop.last %},{% endif %}
{% endfor %}
],
"shippingAddress": {
"firstName": "{{ data.parties.recipient.person.givenName }}",
"lastName": "{{ data.parties.recipient.person.familyName }}",
"addressLine1": "{{ data.parties.recipient.location.address.street }}",
"addressLine2": "{{ data.parties.recipient.location.address.unit }}",
"city": "{{ data.parties.recipient.location.address.locality }}",
"state": "{{ data.parties.recipient.location.address.region }}",
"postCode": "{{ data.parties.recipient.location.address.postalCode }}",
"country": "{{ country_map.get(data.parties.recipient.location.address.country, data.parties.recipient.location.address.country) }}",
"email": "{{ data.parties.recipient.contactDetails.emailAddress }}",
"phone": "{{ data.parties.recipient.contactDetails.phoneNumber }}"
},
"items": [
{% for item in data.contents.items %}
{
"itemReferenceId": "{{ item.descriptor.id }}",
"productUid": "{{ lookups({
'type': item.descriptor.type,
'format': item.descriptor.specifications.format,
'paper': item.descriptor.specifications.paperType
}, strict=False, default='') }}",
"quantity": {{ item.quantity.value }},
"files": [
{
"type": "default",
"url": "{{ item.digitalAssets.printable.fileLocation }}"
}
]
}{% if not loop.last %},{% endif %}
{% endfor %}
]
}Tips for Effective Template Mappers
When working with Jinja2 Template Mappers in GelatoConnect, consider these practical tips:
Use Debugging Techniques:
Add temporary fields to show intermediate values
Use the {% raw %}{{ variable | tojson }}{% endraw %} filter to debug complex objects
Combine Set Statements with Conditionals:
jinja{% set shipping_type = 'express' if order.priority == 'high' else 'standard' %}Handle Missing or Nested Data:
jinja{{ data.get('nested', {}).get('deeply', {}).get('property', 'default_value') }}Create Map Dictionaries for Common Mappings:
{% set status_map = {'NEW': 'received', 'SHIPPED': 'shipped', 'DELIVERED': 'delivered'} %}
"status": "{{ status_map.get(input_status, 'unknown') }}"Encapsulate Re-usable Logic in Macros:
{% macro format_phone(phone) %}
{{ phone | replace(' ', '') | replace('.', '-') }}
{% endmacro %}Use Filters to Transform Data:
trim: Remove whitespacereplace: Substitute textupper/lower/title: Change casedefault: Provide fallback valuestojson: Format as JSON string
Consider Performance for Large Data Sets:
Pre-compute values before loops
Use set statements outside loops
Keep templates focused and specific
Next Steps
Now that you've seen these practical examples, you can:
Adapt these templates to your specific integration needs
Create more complex transformations by combining techniques
Test your templates thoroughly with real data
Set up postback triggers using these templates
Implement lookups for efficient value mapping
For more assistance with Template Mappers, contact our support team at [email protected].