Widgets/Logic

Expression Eval Widget

Expression Eval Widget

A Logic type widget. Expression Eval Widget allows you to execute JavaScript-like expressions. It takes an input value, evaluates an expression using this value, and outputs the result.

 

Inputs

  • data (DataType: Anything) The input value to be used in the expression. Can be accessed as data within the expression.
  • Property access: You can access object properties using dot notation (data.propertyName) or bracket notation:
    • data['key with spaces'] - Access properties with spaces using single quotes
    • data["key with spaces"] - Access properties with spaces using double quotes
    • data[0] - Access array elements by numeric index

Outputs

  • result (DataType: Anything) The result of the evaluated expression.

Configuration

  • expression (string): The JavaScript expression to evaluate. The expression has access to the input value through the data variable.

Expression Eval Settings



Available Global Objects

The expression has access to the following global objects:

  • Math, Date, JSON
  • Array, Object, String, Number, Boolean, RegExp, Symbol
  • Map, Set, Promise

Global Variables Access

You can access global variables in your expressions using the $vars object:

  • Dot notation: $vars.variableName - Access any global variable by name
  • Bracket notation (static): $vars["variableName"] - Access using string literal
  • Bracket notation (dynamic): $vars[data.fieldName] - Access using dynamic key from context

Note: Nested bracket notation like $vars[$vars["key"]] is not currently supported.

Example:

// Use a global variable as a threshold
$vars.threshold * data.value

// Access with bracket notation
$vars["apiKey"] + $vars["apiSecret"]

// Dynamic access using input data
$vars[data.configKey]

// Access a global username
$capitalize($vars.username)

Secrets Access

You can access secrets mapped to the recipe using the $secrets object:

  • Dot notation: $secrets.secretName - Access a secret by name
  • Returns the decrypted secret value if it exists and is mapped to the recipe
  • Returns an empty string if the secret doesn't exist or is not mapped
  • Security note: Bracket notation ($secrets["key"]) is not supported

Example:

// Use a secret API key
$secrets.apiKey

// Combine secret with input data
$secrets.apiEndpoint + "/users/" + data.userId

// Use secret in conditional logic
$secrets.environment === "production" ? "live" : "test"

Date Helpers

The date object provides access to current date and time information:

Year/Month/Day:

  • date.year - Full year (e.g., 2024)
  • date.month - Month (1-12)
  • date.day - Day of month (1-31)
  • date.fullYear - Alias for year
  • date.date - Alias for day

Time:

  • date.hours - Hours (0-23)
  • date.minutes - Minutes (0-59)
  • date.seconds - Seconds (0-59)
  • date.milliseconds - Milliseconds (0-999)
  • date.time - Timestamp in milliseconds

Day of Week:

  • date.dayOfWeek - Day index (0=Sunday, 6=Saturday)
  • date.dayName - Full day name (e.g., "Monday")
  • date.shortDayName - Short day name (e.g., "Mon")

Timezone & UTC:

  • date.timezoneOffset - Timezone offset in minutes
  • date.UTCDate, date.UTCDay, date.UTCFullYear, date.UTCHours, date.UTCMilliseconds, date.UTCMonth, date.UTCMinutes, date.UTCSeconds

String Representations:

  • date.isoString - ISO string format
  • date.localeString - Locale string format

Example:

// Check if timestamp is in the future
data.timestamp > date.time ? "future" : "past"

// Format current date
date.year + "-" + date.month + "-" + date.day

Helper Functions

The Expression Eval Widget provides various helper functions for common operations:

String Helpers

  • $capitalize(value) - Capitalizes the first letter of a string
  • $uppercase(value) - Converts string to uppercase
  • $lowercase(value) - Converts string to lowercase

Example:

$capitalize(data.name)  // "john" → "John"
$uppercase(data.text)    // "hello" → "HELLO"
$lowercase(data.TEXT)    // "WORLD" → "world"

JSON Helpers

  • $json(string) - Parses a JSON string into an object
  • $stringify(value) - Converts a value to JSON string

Example:

$json(data.jsonString).name
$stringify(data.obj)

Array Helpers

  • $length(value) - Gets the length of a string or array
  • $isEmpty(value) - Checks if array/string is empty
  • $isNotEmpty(value) - Checks if array/string is not empty
  • $first(value) - Gets first item/character
  • $last(value) - Gets last item/character
  • $compact(value) - Removes empty values from array

Example:

$length(data.items)         // Returns array length
$isEmpty(data.items)        // Returns true if empty
$isNotEmpty(data.items)     // Returns true if not empty
$first(data.items)          // Returns first item
$last(data.items)           // Returns last item
$compact(data.items)        // Returns filtered array

Encoding/Decoding Helpers

  • $base64Encode(value) - Encodes a string as base64
  • $base64Decode(value) - Decodes a base64 string
  • $urlEncode(value) - URL-encodes a string
  • $urlDecode(value) - URL-decodes a string

Example:

$base64Encode(data.secret)    // Encodes to base64
$base64Decode(data.encoded)   // Decodes from base64
$urlEncode(data.query)        // URL-encodes string
$urlDecode(data.encodedUrl)   // URL-decodes string

Extraction Helpers

  • $domain(value) - Extracts domain from URL
  • $email(value) - Extracts email from string
  • $url(value) - Extracts URL from string
  • $urlPath(value) - Extracts path from URL

Example:

$domain(data.url)              // Extracts domain
$email(data.text)              // Extracts email address
$url(data.text)                // Extracts URL from string
$urlPath(data.url)             // Extracts path from URL


📌 Important Notes

  • Access to global objects like window, document, eval, Function, process, require is restricted or removed
  • Allowed global objects include: Math, Date, JSON, Array, Object, String, Number, Boolean, RegExp, Symbol, Map, Set, Promise
  • If an expression evaluates to exactly true (and the expression string itself is not just 'true'), the original input data is passed to the output. Otherwise, the direct result of the expression is outputted
  • If the expression returns undefined or null, no output is transmitted
  • If the expression results in NaN (Not a Number), an error will be thrown
  • The special symbol abort can be returned by an expression to prevent any output (e.g., data < 0 ? abort : data * 2)

 

Example Expressions

Basic Number Transformation

This example demonstrates how to use the Expression Eval Widget to transform a number input by applying a mathematical operation.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Slider Widget provides input values ranging from 0 to 5
  2. The Expression Eval Widget performs a simple mathematical operation by multiplying the provided input by 3
  3. The result of the evaluated expression is then displayed in the Display Widget

 

Array Filter Operation

This example demonstrates how to use the Expression Eval Widget to filter an array of objects based on a condition.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Text Widget provides an array of objects, where each object includes an age property with a different value
  2. The Expression Eval Widget applies a filter using data.filter((x) => x.age >= 18), returning only the objects where the age is 18 or above
  3. The result of the filter operation is then produced as output

 

Conditional Logic with Object Validation

This example demonstrates how to use the Expression Eval Widget to validate an object and either pass it through or abort the flow based on a condition.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Slider Widget controls the age value (15-20) of a person object
  2. The Object Widget creates a person object with age and name properties
  3. The Expression Eval Widget validates the age using data.age >= 18 ? data : abort:
    • If the age is 18 or above, the full person object (with both age and name) is passed through
    • If the age is below 18, the flow is aborted and no output is produced
  4. The result (if any) is then stringified and displayed in the Text Widget

This demonstrates how abort can be used to implement validation logic, where only valid objects are allowed to continue through the flow.

 

String Transformation with Helper Functions

This example demonstrates how to use the Expression Eval Widget with helper functions to transform and format strings, combining global variables and input data.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Button Widget triggers the flow
  2. The Text Widget provides a JSON string containing firstName and surname properties: {"firstName": "karla", "surname": "gomez"}
  3. A Global Variable status is created in the Global Variables Panel with DataType: Text and Value: "Pending"
  4. The Text to Object Widget parses the JSON string into an object
  5. The Expression Eval Widget uses $capitalize(data.firstName) and $capitalize(data.surname) to capitalize the name fields, and $uppercase($vars.status) to convert the global status variable to uppercase, formatting them with labels and line breaks
  6. The formatted result is displayed in the Text Widget: "User Name: Karla Gomez\nStatus: PENDING"

This demonstrates how helper functions can transform strings and combine data from multiple sources (input data and global variables).

 

Building URLs with Global Variables and Secrets

This example demonstrates how to use the Expression Eval Widget to construct a URL by combining a global variable, input data, and a secret key.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Button Widget triggers the flow
  2. The Text Widget provides a JSON string containing firstName and userId properties: {"firstName": "Karla", "userId": "1a2b3c"}
  3. A Global Variable apiUrl is created in the Global Variables Panel with DataType: Text and Value: "https://my.api.io"
  4. A Secret Widget is added to the workflow with the name API_KEY, declaring that a secret with this name is required.
  5. The API_KEY secret is mapped to a Context and an Environment Variable, enabling the Secret Widget to retrieve the secret value from the Hub at runtime
  6. The Text to Object Widget parses the JSON string into an object
  7. The Expression Eval Widget uses $vars["apiUrl"] to access the global variable, data.userId to extract the user ID from the input, and $secrets.API_KEY to access the mapped secret value, combining them to construct a complete URL
  8. The constructed URL is displayed in the Text Widget: "https://my.api.io/users/1a2b3c?key=demo_token_123"

This demonstrates how to combine global variables, input data, and secrets to build dynamic URLs for API requests.

 

Comparing Timestamps with Date Helpers

This example demonstrates how to use the Expression Eval Widget with the date object to compare a timestamp with the current time and format the result accordingly.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Button Widget triggers the flow
  2. The Text Widget provides a JSON string containing a timestamp property: {"timestamp": 2524608000000} (representing January 1, 2050 in milliseconds)
  3. The Text to Object Widget parses the JSON string into an object
  4. The Expression Eval Widget uses date.time to access the current timestamp and compares it with data.timestamp using the expression: data.timestamp > date.time ? "Future at: " + new Date(data.timestamp).toISOString(): "Past"
    • If the input timestamp is greater than the current time (date.time), it returns "Future at: " followed by the ISO string representation of the timestamp
    • If the input timestamp is less than or equal to the current time, it returns "Past"
  5. The result is displayed in the Text Widget: "Future at: 2050-01-01T00:00:00.000Z" (since the timestamp represents a future date)

This demonstrates how to use date.time to compare timestamps with the current time and format dates using JavaScript's Date object and toISOString() method.

 

Extracting Array Elements with Helper Functions

This example demonstrates how to use the Expression Eval Widget with array helper functions to check if an array has elements and extract the last item.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Button Widget triggers the flow
  2. The Text Widget provides a JSON array string: ["Apple", "Lemon", "Watermelon"]
  3. The Text to Object Widget parses the JSON string into an array (with outputIsArray set to true)
  4. The Expression Eval Widget uses $isNotEmpty(data) to check if the array has elements, and $last(data) to extract the last item using the expression: $isNotEmpty(data) ? $last(data) : "Empty array"
    • If the array is not empty, it returns the last element using $last(data)
    • If the array is empty, it returns "Empty array"
  5. The result is displayed in the Text Widget: "Watermelon" (the last element of the array)

This demonstrates how to use array helper functions $isNotEmpty and $last to safely check array contents and extract specific elements.

 

Parsing JSON Strings with Helper Functions

This example demonstrates how to use the Expression Eval Widget with the $json helper function to parse a JSON string directly within the expression and extract properties, including nested ones.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Button Widget triggers the flow
  2. The Text Widget provides a JSON string with nested structure: {"orderId": "ord_7781", "customer": { "firstName": "John" }, "total": 49.9}
  3. The Expression Eval Widget uses the $json helper function to parse the JSON string directly within the expression and extract the nested firstName property from the customer object using: $json(data).customer.firstName
  4. The extracted value is displayed in the Text Widget: "John"

This demonstrates how to use the $json helper function to parse JSON strings directly in expressions without requiring a separate Text to Object Widget, allowing for more concise workflows when you only need to extract specific properties from JSON data, including nested properties.

 

Extracting Email and URL from Text

This example demonstrates how to use the Expression Eval Widget with extraction helper functions to extract email addresses and URLs from text content.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Button Widget triggers the flow
  2. The Text Widget provides a text message containing an email address and a URL: "Your account has been successfully created. You can access the platform using your email johndoe@myemail.com. Login URL: https://my.app/login/"
  3. The Expression Eval Widget uses the $email and $url helper functions to extract the email address and URL from the text using: "User Email: " + $email(data) + "\nURL: " + $url(data)
  4. The extracted values are displayed in the Text Widget: "User Email: johndoe@myemail.com URL: https://my.app/login/"

This demonstrates how to use extraction helper functions $email and $url to automatically extract email addresses and URLs from text content, making it easy to parse and format structured information from unstructured text.

 

Quick Examples

Here are some common expressions and their results:

  • data * 10 (If data is 5, result is 50)
  • data.name (If data is { "name": "Kemu" }, result is "Kemu")
  • data['key with spaces'] (If data is { "key with spaces": "value" }, result is "value")
  • data[0] (If data is ["apple", "banana"], result is "apple")
  • data > 10 ? 'big' : 'small' (If data is 20, result is "big")
  • data.toUpperCase() (If data is "hello", result is "HELLO")
  • data.length (If data is [1, 2, 3], result is 3)
  • data.map(x => x.name) (If data is [{name: "John"}, {name: "Jane"}], result is ["John", "Jane"])
  • data.reduce((sum, x) => sum + x.value, 0) (If data is [{value: 1}, {value: 2}, {value: 3}], result is 6)
  • data.age >= 18 ? data : abort (If data is {age: 20}, result is {age: 20}; if data is {age: 15}, the expression returns abort and the next widget is not called)
  • true (If the expression is literally the string "true", it will output true. Otherwise, if an expression evaluates to true, the original data input is passed through.)

 

📌 Additional Notes

  • The widget supports both primitive values and complex objects as input
  • Array operations like filter, map, and reduce are available for data transformation
  • The widget automatically detects the output type and updates its port accordingly
  • Error handling is provided for invalid expressions or runtime errors

 

Glossary

  • Global Variables Panel

A centralized interface component in Kemu that provides a single location to create, configure, and manage Global Variables used throughout recipes. Global Variables are values that persist during recipe execution and can be accessed and modified from any widget in the workflow or directly from the panel interface. The panel enables centralized variable management, runtime control, configuration sharing across workflows, and hierarchical organization of related variables. Variables created in the panel are immediately available to widgets, expressions, and services throughout the recipe. Users can open the Platform Help from the left sidebar (question mark icon) to find more information about the Global Variables Panel