Transform JSON with Custom Scripts

Sometimes your transformation needs go beyond simple renaming or type casting. The Transform Builder includes a powerful Custom Script operator that lets you write JavaScript to handle any edge case.

🚩 The Scenario

You have an API response where permissions is a comma-separated string, and you need to convert it to a proper array:

{
  "userId": 42,
  "permissions": "read,write,admin",
  "metadata": "{\"theme\":\"dark\",\"lang\":\"en\"}"
}

You need:

{
  "userId": 42,
  "permissions": ["read", "write", "admin"],
  "metadata": {"theme": "dark", "lang": "en"}
}

🛠️ Step-by-Step

1. Open the Transform Builder.
2. Load your JSON data.
3. Use Magic Map to auto-detect all fields, or drag fields manually.
4. For the permissions field, click the ⚡ icon to add an operation.
5. Select Custom Script from the operations list.
6. Enter your transformation logic:

// The current field value is available as `value`
// The entire source record is available as `record`
return value.split(',').map(p => p.trim());

7. For the metadata field, add another Custom Script:

return JSON.parse(value);

🔒 Security Sandbox

Custom scripts run in a sandboxed environment. The following globals are blocked for security:

• window, document, fetch, XMLHttpRequest
• localStorage, sessionStorage, indexedDB
• process, require, Worker

This ensures that transformation logic cannot make network requests or access browser storage.

💡 Available Variables

Variable	Description
value	The current value of the field being transformed
record	The entire source record (root object)

🧮 More Examples

Extract domain from email:

return value.split('@')[1];

Calculate age from birthdate:

const birth = new Date(value);
const today = new Date();
return Math.floor((today - birth) / (365.25 * 24 * 60 * 60 * 1000));

Conditional complex logic:

if (record.country === 'US') {
  return value.replace(/(\d{3})(\d{3})(\d{4})/, '($1) $2-$3');
}
return value;

⛓️ Chaining with Other Operations

Custom scripts can be combined with built-in operations. For example:

1. Trim → removes whitespace
2. Custom Script → splits into array
3. The operations execute in order, left to right.

---

🚀 Try it now

Open the Transform Builder and add a Custom Script operation to any field mapping.