Script and Validation Nodes

Script & Validation Nodes

Article Type: Node Reference Audience: Developers, App Admins Module: Data Flows / Node Designer Applies to Versions: Platform 3.0+ Prerequisites: Basic understanding of Data Flow concepts, familiarity with JSONata or JavaScript

1. Overview

What are Script & Validation Nodes?

Script and Validation nodes provide custom logic capabilities within your data flows. When no other node can accomplish a specific task, script nodes allow you to write custom JSONata or JavaScript code. Validation nodes ensure data integrity by validating payloads against JSON schemas before processing continues.

Why are they important?

While Fuuz provides specialized nodes for common operations, enterprise integrations often require custom business logic, complex data transformations, or validation rules that can't be expressed with standard nodes. Script nodes bridge this gap, while validation nodes prevent bad data from propagating through your flows.

Note: JSONata is the most "core" language to the Fuuz platform. It is used throughout screens, transforms, and data flows. JavaScript is available when you need features like loops, accumulators, or are more comfortable with traditional programming constructs.

The 4 Node Types

Node Type	Language	Best For
JSONata Script	JSONata	Data transformation, filtering, mapping, aggregation — declarative functional style
JavaScript	JavaScript	Complex logic with loops, accumulators, or when JavaScript familiarity is preferred
Saved Script	JSONata or JavaScript	Reusable scripts with versioning, deployment management, input/output schemas
Validate	JSON Schema	Validating incoming payloads meet requirements before processing

2. JSONata Script Node

Purpose & Use Cases

The JSONata Script Node allows you to write free-form JSONata scripts to accomplish tasks when no other node can meet your needs. JSONata is a declarative functional language designed specifically for querying and transforming JSON data.

Key Features:

• Use CTRL+SPACE in the editor to see snippets of accessible functions with sample executions and descriptions
• Access to standard JSONata functions plus Fuuz custom bindings
• Implicit return — the result of the expression is automatically returned
• Access payload via $ and context via $$

Configuration Parameters

Parameter	Description
Script	Free-form JSONata script editor

JSONata Basics

Path Expressions: Navigate JSON objects using dot notation.

Address.City              /* Returns "Winchester" */
Phone[0].number           /* First phone number */
Account.Order.Product     /* Navigate nested structures */

String Concatenation:

FirstName & ' ' & Surname  /* "Fred Smith" */

Numeric Operations:

Price * Quantity          /* Multiplication */
Total / Count             /* Division */
Value % 10                /* Modulo */

Array/Object Transformations:

Orders[status = 'open']                     /* Filter array */
Products.(name & ': $' & price)             /* Map transformation */
$sum(LineItems.amount)                      /* Aggregation */

3. JavaScript Node

Purpose & Use Cases

The JavaScript Node allows you to write free-form JavaScript. JavaScript is helpful when you need better accumulator management, for/while loops, or when you're more comfortable with JavaScript than JSONata.

Configuration Parameters

Parameter	Description
Script	Free-form JavaScript editor. Use CTRL+SPACE to see available functions.

Important: Critical Difference — Unlike JSONata, you must explicitly return data in JavaScript for it to be passed to the next nodes. Otherwise, the output will be null.

Return Statement Examples

With Return (Correct):

if(true === true) {
  return true
}
/* Results in: true */

Without Return (Incorrect):

if(true === true) {
}
/* Results in: null */

4. Saved Script Node

Purpose & Use Cases

The Saved Script Node allows you to reference reusable scripts written in JavaScript or JSONata. Saved scripts support versioning, deployment management, and input/output schema definitions — making them ideal for shared logic used across multiple flows.

Configuration Parameters

Parameter	Description
Script Language	JSONata or JavaScript
Saved Script	The saved script you are executing (select from available scripts)
Request Transform	Format the payload to match the saved script's expected input
Response Transform	Format the script output before passing to next nodes

Saved Script Management

Saved Scripts (also called Saved Transforms) provide enterprise-grade script management:

• Versioning: Create multiple versions of a script while maintaining history
• Deployments: Deploy specific versions with labels (SCRIPT NAME: VERSION: timestamp)
• Input Schema: Define expected input structure with JSON Schema validation
• Output Schema: Define expected output structure for documentation and validation
• Active Status: Enable/disable scripts without deleting them
• Substitution: Configure one script to substitute for another

5. Validate Node

Purpose & Use Cases

The Validate Node allows you to provide a JSON schema to validate the payload at any point in your flow. It ensures the data meets minimum requirements before processing continues.

The Validate Node is especially useful for Request/Response flows where you need to validate incoming payloads from another Data Flow or an external client. If validation fails, it provides details about which part of the schema was not met, reducing unnecessary debugging.

Configuration Parameters

Parameter	Description
Schema	A JSON schema your input payload will be validated against

Example Schema

{
  "exampleSchema": {
    "childProperty": "ChildText"
  }
}

Tip: You can build a JSON schema from a JSON payload through the "Convert Json to Json Schema" screen within the platform.

6. Fuuz Custom JSONata Bindings

Fuuz extends standard JSONata with custom bindings/functions developed specifically for the platform. These are available in addition to all standard JSONata functions.

Core Functions

Function	Description
$cuid()	Generate a collision-resistant unique identifier
$uuid()	Generate a UUID
$throw(string)	Throw an error with message
$coalesce(a, b, ...)	Return first non-null value
$tryCatch(fn)	Execute function with error handling
$nullIf(any, any)	Return null if values are equal

Data Operations (Shared)

Function	Description
$query(object)	Execute GraphQL query against Fuuz API
$mutate(object)	Execute GraphQL mutation against Fuuz API
`$integrate(object	array)`
$executeFlow(string, object)	Execute a deployed data flow
$executeTransform(string, object)	Execute a saved transform
$document(object[, options])	Render a document
$getCalendar(object)	Retrieve calendar data

Frontend Functions (Web Flows Only)

Function	Description
$navigateTo(pathname, options)	Navigate to a screen
$navigateBack()	Navigate to previous screen
$addNotificationMessage(title, options)	Display a notification message
$writeToClipboard()	Write to system clipboard
$readFromClipboard()	Read from system clipboard

Additional Function Categories

• Calendar Functions: $eventsBetween(), $getEventEnd(), $getEventsAt(), $getAvailabilityBetween(), $availableAt()
• File Functions: $pdfToJson(), $mergePDFs(), $rotatePDF()
• Moment/Time Functions: $momentTz(), $momentTzTimezones(), $momentTzGuess(), $momentMax(), $momentMin()
• XML Functions: $jsonToXml()
• Logging: $log(message, meta, level)

7. Best Practices

When to Use Which Language

Use JSONata when:

• Transforming JSON data structures
• Filtering and mapping arrays
• Aggregating data ($sum, $average, $count)
• Simple conditional logic
• Working with Fuuz platform bindings

Use JavaScript when:

• You need for/while loops with complex iteration
• You need better accumulator/state management
• You're more comfortable with JavaScript
• Complex business logic with many branches

Validation Patterns

Pattern: Validate External Input

Request Node → Validate Node → Process Data

Pattern: Validate with Error Handling

Try Catch → Validate Node → Process (or Catch → Return Error)

Important: Data Mappings also validate against their schemas and will throw errors if input or output validation fails. Treat Data Mapping nodes the same as Validate nodes — place a Try/Catch before them if graceful failure is important.

8. Troubleshooting

Symptom	Likely Cause	Resolution
JavaScript returns null	Missing return statement	Add explicit return statement
JSONata syntax error	Invalid expression structure	Check brackets, quotes, and operators
Validation fails unexpectedly	Schema doesn't match actual data structure	Use "Convert Json to Json Schema" tool to regenerate
Cannot access context	Using wrong binding	Use $$ for context, $ for payload
Saved script not found	Script not deployed or inactive	Deploy the script and ensure active status is true
Function not available	Using frontend function in backend flow	Check function scope (Frontend vs Shared)

9. Related Resources

• Custom Fuuz Only JSONata Library — Complete reference of platform-specific bindings
• JSONata Tutorial — Learn JSONata basics and advanced features
• Transform Nodes — Data format conversion nodes
• Flow Control Nodes — Error handling with Try Catch
• Data Mapping — Visual data mapping with schema validation
• Platform Website: fuuz.com

10. Revision History

Version	Date	Author	Description
1.0	2025-01-01	Fuuz Documentation Team	Initial release - Complete guide covering JSONata Script, JavaScript, Saved Script, and Validate nodes.

See Also

• Data-Flow-Nodes-Reference
• Custom-Fuuz-Only-JSONata-Library
• Transform-Nodes-Data-Flows
• Flow-Control-Nodes
• Data-Mapping
• Script-Editor

---

Source: support.fuuz.com