Modifier

Modifiers transform data on the fly within a flow. Apply a JSONata or JavaScript expression to change the structure or value of an output before it reaches the next function, a database, the frontend, or a subsequent extension node (such as another modifier or a filter).

To add a modifier:

1. Click the + icon on the right side of a function output, filter, or existing modifier.

2. Select Modifier from the list.

3. Click the new modifier node (Click to edit...) to open the code editor and write your expression.

A modifier uses either JSONata or a JavaScript expression. Switch between types by right-clicking the modifier and selecting JSONata or Expression. Adjust the default type in the App Builder settings.

Click the modifier icon on the left to evaluate the modifier manually during development. The last result appears below the expression. Right-click also lets you add a comment to the modifier or delete it.

A modifier extension node

Need help writing modifiers?

Read how to use AI for modifiers to generate JSONata or JavaScript logic with your favorite chatbot.

JSONata

JSONata is a query and transformation language designed for JSON data. It is the preferred method for structural changes, filtering, and simple math. For a complete guide, see the official JSONata documentation.

• Reference: Use the $ sign to refer to the value from the preceding output.

• Implicit arguments: JSONata modifiers automatically process the incoming data if the parentheses are left empty. For example, $uppercase() is equivalent to $uppercase($).

JSONata examples

Example 1: Path selection and math

Extracts a specific nested value from a PLC object and performs a calculation.

Data:

{
  "payload": {
    "sensors": {
      "temp_c": 25
    }
  }
}

Modifier content:

payload.sensors.temp_c * 1.8 + 32

Return of the modifier:

77

Example 2: Wrap a value in an object

Takes the incoming value ($) and wraps it inside a JSON object with a key named temp_sensor_1.

Data:

25.4

Modifier content:

{ "temp_sensor_1": $ }

Return of the modifier:

{ "temp_sensor_1": 25.4 }

Example 3: Implicit function usage

Trims whitespace and converts a raw string to uppercase without explicitly naming the input variable.

Data:

"maintenance_required"

Modifier content:

$uppercase()

Return of the modifier:

"MAINTENANCE_REQUIRED"

Example 4: Filtering an array

Returns only the objects from a list that meet a specific status condition.

Data:

[
  { "id": "A1", "status": "OK" },
  { "id": "B2", "status": "ERROR" }
]

Modifier content:

$[status="ERROR"]

Return of the modifier:

{ "id": "B2", "status": "ERROR" }

JavaScript expressions

This modifier type accepts any standard JavaScript expression that evaluates to a new value. Reference the reserved variable x to access the preceding data output. For more information, see the MDN documentation on JavaScript expressions and operators.

JavaScript expression examples

Example 1: Conditional status (ternary)

Determines a status string based on a numeric threshold.

Data:

85.5

Modifier content:

x > 80 ? "Critical" : "Normal"

Return of the modifier:

"Critical"

Example 2: Array mapping and enrichment

Iterates through an array of objects to add a new property or modify existing ones using .map().

Data:

[
  { "part": "Bolt", "qty": 10 },
  { "part": "Nut", "qty": 5 }
]

Modifier content:

x.map(item => ({
  ...item,
  available: item.qty > 0,
  lastChecked: DateTime.now().toISODate()
}))

Return of the modifier:

[
  { "part": "Bolt", "qty": 10, "available": true, "lastChecked": "2026-02-12" },
  { "part": "Nut", "qty": 5, "available": true, "lastChecked": "2026-02-12" }
]

Example 3: Multi-step logic (IIFE)

Modifiers only support expressions. For more elaborate logic involving temporary variables, use the Immediately Invoked Function Expression (IIFE) pattern.

Data:

{ "raw_value": 1024, "multiplier": 0.5 }

Modifier content:

(() => {
  const base = x.raw_value;
  const factor = x.multiplier;
  const offset = 10;
  return (base * factor) + offset;
})()

Return of the modifier:

522

Example 4: Removing and adding properties in an array

Use the spread operator (...) to reproduce existing entries while selectively removing or adding properties.

Data:

[ { "a": 1, "b": 1, "c": 1 }, { "a": 2, "b": 2, "c": 2 } ]

Modifier content:

x.map(y => ({
  ...y,         // Reproduces existing entry
  c: undefined, // Removes property c
  d: 'cool'     // Adds property d
}))

Return of the modifier:

[ { "a": 1, "b": 1, "d": "cool" }, { "a": 2, "b": 2, "d": "cool" } ]

Example 5: Processing multiple inputs (using combine)

When using the combine function, the IIFE pattern cleanly handles multiple input sources stored in the x array.

Data (combined by the combine function):

[
  [ { "name": "User1" } ], // x[0]
  [ { "asset": "CNC" } ]   // x[1]
]

Modifier content:

(() => {
  const users = x[0]
  const assets = x[1]
  return {
    assigned_users: users,
    active_assets: assets
  }
})()

Return of the modifier:

{
  "assigned_users": [ { "name": "User1" } ],
  "active_assets": [ { "asset": "CNC" } ]
}

Example 6: Date calculations (using Luxon)

Heisenware provides built-in support for the Luxon library via the DateTime, Duration, and Interval objects for complex date and time operations.

Duration and Interval are only available from version v91.

Here are some common modifier patterns:

1. Calculating future or past dates (addition and subtraction)

Data:

[
  { "startDate": "2026-01-01", "days": 5 },
  { "startDate": "2026-01-10", "days": 2 }
]

Modifier content:

x.map(y => ({
   ...y,
   dueDate: DateTime.fromISO(y.startDate).plus({ days: y.days }).toISODate()
}))

Return of the modifier:

[
  { "startDate": "2026-01-01", "days": 5, "dueDate": "2026-01-06" },
  { "startDate": "2026-01-10", "days": 2, "dueDate": "2026-01-12" }
]

2. Calculating downtime (time differences)

Find the exact duration between two timestamps, such as a machine fault start and end time.

Data:

[
  { "machine": "Press A", "faultStart": "2026-03-12T08:00:00Z", "faultEnd": "2026-03-12T10:15:00Z" }
]

Modifier content:

x.map(y => ({
   ...y,
   downtime: DateTime.fromISO(y.faultEnd)
      .diff(DateTime.fromISO(y.faultStart), ['hours', 'minutes'])
      .toFormat("h 'hrs' m 'mins'")
}))

Return of the modifier:

[
  { "machine": "Press A", "faultStart": "2026-03-12T08:00:00Z", "faultEnd": "2026-03-12T10:15:00Z", "downtime": "2 hrs 15 mins" }
]

---

3. Formatting decimal labor hours

Convert raw decimal hours from timesheets or logs into standard HH:mm timecode using the Duration object.

Data:

[
  { "worker": "Alice", "loggedDecimal": 8.75 },
  { "worker": "Bob", "loggedDecimal": 7.1 }
]

Modifier content:

x.map(y => ({
   ...y,
   standardTime: Duration.fromObject({ hours: y.loggedDecimal }).toFormat("hh:mm")
}))

Return of the modifier:

[
  { "worker": "Alice", "loggedDecimal": 8.75, "standardTime": "08:45" },
  { "worker": "Bob", "loggedDecimal": 7.1, "standardTime": "07:06" }
]

---

4. Validating events against shifts (intervals)

Check if a specific event (like a sensor trigger) occurred within a defined time window or shift using the Interval object.

Data:

[
  { "eventTime": "2026-03-12T14:30:00Z", "shiftStart": "2026-03-12T06:00:00Z", "shiftEnd": "2026-03-12T18:00:00Z" },
  { "eventTime": "2026-03-12T20:00:00Z", "shiftStart": "2026-03-12T06:00:00Z", "shiftEnd": "2026-03-12T18:00:00Z" }
]

Modifier content:

x.map(y => ({
   ...y,
   occurredDuringShift: Interval.fromDateTimes(
      DateTime.fromISO(y.shiftStart),
      DateTime.fromISO(y.shiftEnd)
   ).contains(DateTime.fromISO(y.eventTime))
}))

Return of the modifier:

[
  { "eventTime": "2026-03-12T14:30:00Z", "shiftStart": "...", "shiftEnd": "...", "occurredDuringShift": true },
  { "eventTime": "2026-03-12T20:00:00Z", "shiftStart": "...", "shiftEnd": "...", "occurredDuringShift": false }
]

---

5. Converting UTC sensor data to local time

IoT devices typically send data in UTC. Convert this to a readable local format for UI dashboards.

Data:

[
  { "sensorId": "Temp-01", "utcTimestamp": "2026-03-12T07:43:50Z" }
]

Modifier content:

x.map(y => ({
   ...y,
   localFormatted: DateTime.fromISO(y.utcTimestamp).toLocal().toFormat("dd. MMM yyyy, HH:mm:ss")
}))

Return of the modifier:

[
  { "sensorId": "Temp-01", "utcTimestamp": "2026-03-12T07:43:50Z", "localFormatted": "12. Mar 2026, 08:43:50" }
]

Example 7: Round robin (using combine)

Sometimes you want to extract items of an array in a round-robin fashion. Use a combine function in which you link the modifier's output back to the second argument:

Data:

[a, b, c]

Modifier content:

(() => {
  const [arr, prev] = x
  const last = prev ? prev : arr[0]
  const index = prev ? arr.indexOf(last) : -1
  const next = arr[(index + 1) % arr.length]
  return next
})()

Return of the modifier:

a // when triggered first time
b // second time
c // third time
a // fourth time

Using AI for modifiers

Use AI chatbots (ChatGPT, Claude, Gemini) to generate or optimize your modifiers. This helps especially with complex transformations where you need to reshape large JSON objects on the fly.

For best results, copy this article as context for the AI. Use the Copy button at the top of the page or the Open in ChatGPT / Open in Claude buttons in the top navigation bar.

Recommended AI prompt

Alternatively, copy and paste this prompt into your AI so it understands the Heisenware environment and its variable references.

I am working in Heisenware, a node-based visual programming tool for industrial applications. 
I need a "modifier" expression that transforms data on the fly between functions.

Full documentation: https://docs.heisenware.com/app-builder/build-backend/extension-nodes/modifier.md

Rules:
* A modifier is a single expression that returns the transformed value. No statements or variable declarations.
* JSONata: the input data is referenced as $. Functions with empty parentheses () automatically process the incoming data, e.g. $uppercase().
* JavaScript: the input data is referenced as x. For multi-step logic with temporary variables, use an IIFE: (() => { ... })().
* JavaScript dates: use the Luxon library via the DateTime, Duration, and Interval objects.
* Unless I say otherwise, pick the simpler of JSONata or JavaScript for the task and tell me which type to select.
* Reply with the expression only, no explanation, no markdown fences.

My input data (sample):
[Paste a sample of the data arriving at the modifier here.]

My task:
[Describe your transformation, e.g., "Extract temp_c from each object in the array and calculate the average."]