Data Transformation Templates

Data Transformation Templates are Handlebars templates that help you transform the data in Orderwave to another format.

This format could be text-based, like a TAB or CSV file, an XML file, or another file format, and these can be used regardless if you're pushing files to a (S)FTP server or a web service.

To start working with Data Transformation Templates, navigate to Admin > Data Transformation Templates, and click the ➕ button to create a new template. The following are the fields for the initial window:

Field	Description
Template Code	This is the unique identifier for this data transformation template across Orderwave.
Template Description	This is a description field for you to use to help describe what this template does. Be descriptive so that other team members can be sure what this is for.

After you create your template, you will be presented with a window that lets you design your template. First, choose the bucket that this template applies to. After you have chosen your bucket, the screen will change and be divided into two columns:

1. The left side, the different sections of your template
2. The right side, sample data from your Orderwave instance

On the left side (the template side), there are three sections for your template:

1. The "Header template"
2. The "Data template"
3. The "Footer template"

Header template

If your target data-type has any type of header information that should only be output once, this is the section for that information. For example, if you are generating a CSV file that should have header columns, you will place those here like this:

Shipment Number,Priority,First Name,Last Name,...

If your target data-type is XML, you can put your opening XML declarations and opening-tags in the header template:

<?xml version="1.0" encoding="UTF-8"?>
<shipments>

Even if you're producing JSON, you can use the header template to start the JSON payload output:

{
	data: [

The purpose here is that any type of boilerplate data that should precede the actual data should be placed in the header template.

TIP

The use of a header template is optional. If your target data type does not require it, leave it blank and it will not be used.

Data template

The data template is the section where most of your transformation logic will reside. While we won't go over how to use Handlebars templates completely, we can provide some guidance about how to iterate over the data from Orderwave.

Regardless of the bucket you've chosen for your template, the data passed to the template follows the same basic principles. The data is a JSON object with one key, and the key is the plural name of the bucket (without the namespace). For example, if they bucket you have chosen is oms/shipments, the data for the template is going to look like:

{
  "shipments": [
    {
      "id": "2613409379520611826",
      "shipmentNumber": "OW0002177-1",
      // shortened for readability

With this in mind, it is easy to produce a template that iterates over the data. Take for example, this XML template that works with shipments:

{{each shipments}}
	<shipment>
		<shipment-number>{{xmlFormatter shipmentNumber}}</shipment-number>
		<address>
			<first-name>{{xmlFormatter address.givenName}}</first-name>
			<last-name>{{xmlFormatter address.familyName}}</last-name>
		</address>
	</shipment>
{{/each}}

Similarly, a JSON template might look like:

{{each shipments}}
	{
		"address1": "{{jsonFormatter address.streetAddress}}",
		"address2": "{{jsonFormatter address.unitNumber}}",
		...
	}
{{/each}}

Footer template

Finally, you have a section for an optional footer. The footer should contain any closing parts of your document, such as closing XML tags, closing JSON arrays, etc.

Helpers

You may have noticed that some of the examples above included some non-standard Handlebars syntax for formatting data, like xmlFormatter and jsonFormatter. Orderwave includes many helpers that are there to help you format data for your platforms. The list of helpers are listed at the bottom of the data transformation template configuration screen.