A JavaScript transformation runs your own function on each record that leaves an export or lookup, or on an import's result data, so you can apply logic that rules can't express: conditions, calculations across lists, and restructuring based on what a record contains. This article explains how to set up a JavaScript transformation, what your function receives and must return, and gives code samples for common tasks. It's for builders who are comfortable writing JavaScript.
Prerequisites:
- Open the Define transformation editor on an export, lookup, or import step. For steps, see Add a transformation to a flow step.
- Saving a JavaScript transformation erases any Rules 1.0 or Rules 2.0 rules on the same step. For details, see Add a transformation to a flow step.
- A script can be used by more than one step. Changes you make to a script affect every step that uses it.
Set up a JavaScript transformation
- At the top of the editor, select JavaScript.
- In Script, select an existing script, or select Add to create a new one.
- In Function, enter the name of the function to run, for example
transform. - If the script has no transform function, select Insert transform stub. The stub adds a commented
transform(options)function that returns the record unchanged. - Write your logic in the function.
- Select Preview. The Function input pane shows the record your function receives, and the Function output pane shows what it returns.
- Save the transformation. For the steps, see Preview and save.
To get help with your code, select a block of code and select Explain selection, or open Celigo Ora in the editor. To discard your unsaved changes, select Reset script. The editor returns to the step's last saved state, including the selected script.
Function reference
Your function receives one argument, options, and must return the transformed record.
| Property | Type | Description |
|---|---|---|
options.record |
object or array | The record to transform. Whether it's an object or an array depends on the data source. |
options.settings |
object | All custom settings in scope for the transformation. |
options.testMode |
Boolean |
true when the transformation runs in test mode or a preview. |
options.job |
object | The job that's running. |
options.pageIndex |
number | The index of the page of records being processed. |
options.headers |
object | On HTTP exports, the response headers, with lowercase names. |
options.context |
object | Metadata about the Model Context Protocol (MCP) caller: token, byUser, client, and source. Present only on tool runs. |
- Return value — Return the transformed record. Whatever the function returns replaces the record for the rest of the flow.
- Errors — If the function throws an exception, integrator.io returns an error for that record.
function transform(options) {
// Change options.record here.
return options.record;
}Code samples
Each sample is a complete function that you can paste into a script and adapt. The samples assume options.record is an object.
Copy a body field to list items
Adds the order ID to every line so each line can be processed on its own.
function transform(options) {
const record = options.record;
(record.lines || []).forEach(function (line) {
line.orderId = record.orderId;
});
return record;
}Copy a list field to the body
Copies the SKU of the first line to a top-level field.
function transform(options) {
const record = options.record;
if (record.lines && record.lines.length > 0) {
record.firstSku = record.lines[0].sku;
}
return record;
}Change fields based on a condition
Renames cust_email to email and removes internal notes for wholesale customers.
function transform(options) {
const record = options.record;
if (record.cust_email !== undefined) {
record.email = record.cust_email;
delete record.cust_email;
}
if (record.customerType === 'wholesale') {
delete record.internalNotes;
record.priceList = 'WHOLESALE';
}
return record;
}Inspect and change an entire record
Trims spaces from every top-level string value, whatever fields the record contains.
function transform(options) {
const record = options.record;
Object.keys(record).forEach(function (key) {
if (typeof record[key] === 'string') {
record[key] = record[key].trim();
}
});
return record;
}Calculate a value from a list
Adds the order total, calculated from each line's quantity and price.
function transform(options) {
const record = options.record;
record.orderTotal = (record.lines || []).reduce(function (total, line) {
return total + (line.qty || 0) * (line.price || 0);
}, 0);
return record;
}Flatten nested lists into one list
Builds one list of components from every line's components list.
function transform(options) {
const record = options.record;
const allComponents = [];
(record.lines || []).forEach(function (line) {
(line.components || []).forEach(function (component) {
allComponents.push({
lineSku: line.sku,
componentSku: component.sku,
qty: component.qty
});
});
});
record.allComponents = allComponents;
return record;
}Fail a record that's missing required data
Throws an error so the record fails with a clear message instead of reaching the next step.
function transform(options) {
const record = options.record;
if (!record.customerId) {
throw new Error('customerId is missing for order ' + record.orderId);
}
return record;
}