Global Functions and Properties

Overview

The SnapLogic expression language provides a set of global functions and properties that can be used in any expression. These functions help with type conversion, data validation, URI encoding/decoding, and more. They are available without any prefix or object reference.

Type Conversion Functions

parseInt()

Converts a string to an integer value.

Syntax:

parseInt(string)
parseInt(string, radix)

Parameters:

  • string - The string to convert to an integer
  • radix (optional) - An integer between 2 and 36 representing the base of the numeral system (default: 10)

Returns: An integer parsed from the given string, or NaN if the first character cannot be converted

Examples:

parseInt("123")           // Returns: 123
parseInt("12.34")         // Returns: 12
parseInt("0x10")          // Returns: 16
parseInt("10", 2)         // Returns: 2 (binary)
parseInt(_numValue) + 2   // Convert parameter to number before arithmetic
Note: Pipeline parameters are always strings, so use parseInt() when you need to perform numeric operations.

parseFloat()

Converts a string to a floating-point number.

Syntax:

parseFloat(string)

Parameters:

  • string - The string to convert to a floating-point number

Returns: A floating-point number parsed from the given string, or NaN if the first character cannot be converted

Examples:

parseFloat("12.34")       // Returns: 12.34
parseFloat("12.34.56")    // Returns: 12.34
parseFloat("1.23e5")      // Returns: 123000
parseFloat(_priceParam)   // Convert parameter to decimal number

Type Checking Functions

typeof

Returns the type of a value as a string.

Syntax:

typeof operand

Returns: A string indicating the type of the operand. Possible values are:

  • "boolean" - For boolean values
  • "number" - For numeric values
  • "string" - For string values
  • "object" - For objects (including null)
  • "array" - For arrays

Examples:

typeof "SnapLogic"        // Returns: "string"
typeof 123                // Returns: "number"
typeof true               // Returns: "boolean"
typeof $myArray           // Returns: "array"
typeof $user              // Returns: "object"

instanceof

Tests whether an object is an instance of a specific type.

Syntax:

object instanceof type

Parameters:

  • object - The object to test
  • type - The type to test against

Supported Types:

  • Null
  • Boolean
  • String
  • Number
  • Object
  • Array
  • Date
  • LocalDate
  • DateTime
  • LocalDateTime

Returns: true if the object is an instance of the specified type, false otherwise

Examples:

$myArray instanceof Array     // Returns: true
$name instanceof String       // Returns: true
$timestamp instanceof Date    // Returns: true
$value instanceof Number      // Returns: true

isNaN()

Determines whether a value is NaN (Not a Number).

Syntax:

isNaN(value)

Parameters:

  • value - The value to test

Returns: true if the value is NaN, false otherwise

Examples:

isNaN(NaN)                // Returns: true
isNaN(123)                // Returns: false
isNaN("hello")            // Returns: false (string is not NaN)
isNaN(parseInt("abc"))    // Returns: true

URI Encoding Functions

encodeURIComponent()

Encodes a URI component by escaping special characters.

Syntax:

encodeURIComponent(string)

Parameters:

  • string - The string to encode

Returns: A new string with special characters escaped

Characters Encoded: All characters except: A-Z a-z 0-9 - _ . ! ~ * ' ( )

Examples:

encodeURIComponent("Hello World")           // Returns: "Hello%20World"
encodeURIComponent("[email protected]")      // Returns: "user%40example.com"
encodeURIComponent("value=100&type=test") // Returns: "value%3D100%26type%3Dtest"

// Building a URL with encoded query parameters
"https://api.example.com/search?q=" + encodeURIComponent($searchTerm)

decodeURIComponent()

Decodes a URI component by unescaping escape sequences.

Syntax:

decodeURIComponent(string)

Parameters:

  • string - The encoded string to decode

Returns: A new string with escape sequences replaced by the characters they represent

Examples:

decodeURIComponent("Hello%20World")           // Returns: "Hello World"
decodeURIComponent("user%40example.com")      // Returns: "[email protected]"
decodeURIComponent("value%3D100%26type%3Dtest") // Returns: "value=100&type=test"

Evaluation Functions

eval()

Evaluates an expression stored in a string or evaluates a pipeline parameter as an expression.

Syntax:

eval(expression)

Parameters:

  • expression - A string containing a SnapLogic expression or a pipeline parameter

Returns: The result of evaluating the expression

Examples:

// Evaluate a parameterized JSONPath
eval(_pathParam)   // If _pathParam = "$.age", returns the age field value

// Evaluate a dynamic expression
eval("1 + 2")      // Returns: 3

// Use in JSONPath
$.children[?(value.age > 18)].eval(value[0])

// Use in database queries
SELECT * FROM customers WHERE id = $.eval(_customerIdParam)
Note: The eval() function is particularly useful when you need to parameterize expressions or JSONPath queries using pipeline parameters.

JSONPath Function

jsonPath()

Evaluates a JSONPath expression against a document.

Syntax:

jsonPath(document, path)
jsonPath(document, path, defaultValue)

Parameters:

  • document - The document to query (typically $ for current document)
  • path - A JSONPath expression as a string
  • defaultValue (optional) - Value to return if the path is not found

Returns: The result of the JSONPath query, or the default value if specified and path not found

Examples:

// Simple field access
jsonPath($, "$.user.name")

// Array access
jsonPath($, "$user[*].screenName")

// With default value
jsonPath($, "$.store.book.author", {defaultValue: "Anonymous"})

// Complex query
jsonPath($, "$.users[?(value.age > 18)].name")
Note: For simple paths, you can use direct notation ($user.name). Use jsonPath() when you need to construct the path dynamically or use advanced features.

Expression Library Function

lib

Provides access to custom functions defined in expression libraries.

Syntax:

lib.LibraryName.functionName(arguments)

Description:

Expression libraries allow you to define reusable custom functions that can be used across multiple pipelines. The lib object provides access to these libraries.

Example:

If you have an expression library named "StringUtils" with a function "capitalize":

lib.StringUtils.capitalize($name)

// Example library function definition:
// capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1).toLowerCase()
Note: Expression libraries must be created and published in your SnapLogic organization before they can be referenced.

Boolean Literals

The expression language supports three boolean literal values:

true

Represents the boolean true value.

$isActive == true
$count > 0 ? true : false

false

Represents the boolean false value.

$isDeleted == false
$errors.length == 0 ? true : false

null

Represents a null or non-existent value.

$middleName == null
$optionalField != null ? $optionalField : "default"
Note: In conditional expressions, the following values are considered falsy: false, null, 0, "" (empty string), and NaN. All other values are truthy.

Best Practices

  • Type Conversion: Always use parseInt() or parseFloat() when performing arithmetic operations on pipeline parameters, as they are always strings.
  • URI Encoding: Use encodeURIComponent() for query parameters and path segments to ensure special characters are properly encoded.
  • Type Checking: Use typeof or instanceof to validate data types before performing operations that require specific types.
  • Error Handling: Check for NaN results after using parseInt() or parseFloat() with untrusted input using isNaN().
  • Dynamic Expressions: Use eval() sparingly and only with trusted input, as it can evaluate any expression.
  • JSONPath: For dynamic path construction, use the jsonPath() function with string concatenation or parameters.
  • Null Checks: Always check for null values before accessing nested properties to avoid errors.

Common Patterns

Safe Number Conversion:

// Convert parameter with fallback
!isNaN(parseInt(_param)) ? parseInt(_param) : 0

// Or using ternary operator
isNaN(parseFloat(_price)) ? 0.0 : parseFloat(_price)

Building URLs with Parameters:

"https://api.example.com/users/" + encodeURIComponent($userId) +
  "?search=" + encodeURIComponent($searchQuery)

Type-Safe Property Access:

($user instanceof Object && 'email' in $user) ? $user.email : null

Dynamic Path Evaluation:

// Use eval() to evaluate parameterized paths
eval(_fieldPath)   // Where _fieldPath might be "$.user.address.city"