How to Map Source Data Fields to Luminous
When integrating your data (like Shopify orders) into Luminous, you'll need to define how fields from your source system map to fields in Luminous. You can do this through simple paths or JSONPath expressions.
Understanding Field Mapping
Field mapping tells Luminous exactly which piece of data from your incoming source should go into a specific Luminous field.
There are two ways to map data:
Simple Path Mapping (e.g.,
order_number)JSONPath Mapping (complex queries using JSONPath)
Simple Path Mapping
Use simple paths for direct field mappings where the field is easily accessible.
Example:
Raw JSON Example:
{ "order_number": 12345 }Source Field:
order_numberLuminous Field:
orderNumber
This maps directly, pulling the order_number value (12345) from the source data into the orderNumber field in Luminous.
JSONPath Mapping
For more complex mappings, particularly involving arrays or nested data, JSONPath is powerful.
You can test and validate JSONPaths easily using online tools such as JSONPath Evaluator.
Examples of JSONPath Mapping:
Example 1: Mapping Custom Properties
Raw JSON Example:
{ "line_items": [ { "properties": [{"name": "Color", "value": "Red"}] }, { "properties": [{"name": "Size", "value": "Medium"}] } ] }Incoming Field:
line_items[*].propertiesLuminous Field:
orderItems[*].custom['Customization Json']
This expression tells Luminous to take all properties from each line_item and store them as a custom field called Customization Json for each corresponding line item in Luminous.
Example 2: Mapping Specific Property URL
Raw JSON Example:
{ "line_items": [ { "properties": [ {"name": "_imageLayers", "value": [{"Sequence": "1", "Url": "https://cdn.filestackcontent.com/image1"}]} ] } ] }Incoming Field:
$.line_items[*].properties[?(@.name=="_imageLayers")].value[0].UrlLuminous Field:
orderItems[*].custom['PrintFileURL']
This expression tells Luminous to extract the URL (https://cdn.filestackcontent.com/image1) from the _imageLayers property from each line item and store it as a custom field called PrintFileURL.
Practical Shopify Example
Here's how you'd map common fields from a Shopify order:
Order Level Fields:
{ "name": "#1110279", "order_number": 1110279 }Shopify
name→ LuminousorderNameShopify
order_number→ LuminousorderNumber
Line Item Fields:
{ "line_items": [ {"sku": "PROD-001", "price": "59.99", "properties": [{"name": "Color", "value": "Red"}]}, {"sku": "PROD-002", "price": "49.99", "properties": [{"name": "Size", "value": "Medium"}]} ] }Shopify
line_items[*].sku→ LuminousorderItems[*].skuShopify
line_items[*].price→ LuminousorderItems[*].priceShopify
line_items[*].properties→ LuminousorderItems[*].custom['Customization Json']Shopify URL from
_imageLayers:{ "line_items": [ { "properties": [ {"name": "_imageLayers", "value": [{"Sequence": "1", "Url": "https://cdn.filestackcontent.com/image1"}]} ] } ] }Incoming Field:
$.line_items[*].properties[?(@.name=="_imageLayers")].value[0].UrlLuminous Field:
orderItems[*].custom['PrintFileURL']
Tips for Success:
Always test complex mappings using the JSONPath Evaluator tool.
Make sure your paths match your data exactly, including capitalization and punctuation.
This guide will ensure you map fields correctly, making your data integration seamless and error-free!