claude-skills/skills/n8n-workflow-specialist/EXPRESSIONS.md

n8n Expression Reference

This guide provides comprehensive reference for writing n8n expressions.

Table of Contents

• Basic Syntax
• Accessing Data
• String Operations
• Number Operations
• Date & Time
• Array Operations
• Object Operations
• Conditional Logic
• JSON Operations
• Common Patterns

Basic Syntax

n8n expressions are wrapped in double curly braces:

{{ expression }}

You can combine text with expressions:

Hello {{ $json.name }}, your order #{{ $json.orderId }} is ready!

Accessing Data

Current Item Data

// Access field in current item
{{ $json.fieldName }}

// Nested fields
{{ $json.user.email }}
{{ $json.data.items[0].name }}

// Access by bracket notation
{{ $json["field-with-dashes"] }}

Previous Node Data

// Access data from a specific node
{{ $node["HTTP Request"].json.data }}

// Access by node index
{{ $("HTTP Request").item.json.result }}

// First item from previous node
{{ $node["HTTP Request"].json }}

// Specific item by index
{{ $items("HTTP Request")[0].json.field }}

Input Data

// Current input item
{{ $input.item.json.field }}

// All input items
{{ $input.all() }}

// First input item
{{ $input.first().json.field }}

// Last input item
{{ $input.last().json.field }}

Binary Data

// Access binary data
{{ $binary.data }}

// Binary data from specific node
{{ $node["Read File"].binary.data }}

Workflow & Execution Data

// Workflow ID
{{ $workflow.id }}

// Workflow name
{{ $workflow.name }}

// Execution ID
{{ $execution.id }}

// Execution mode (manual, trigger, webhook)
{{ $execution.mode }}

// Current timestamp
{{ $now }}

// Today's date at midnight
{{ $today }}

String Operations

Basic Methods

// Convert to lowercase
{{ $json.email.toLowerCase() }}

// Convert to uppercase
{{ $json.name.toUpperCase() }}

// Trim whitespace
{{ $json.text.trim() }}

// Get length
{{ $json.message.length }}

Splitting & Joining

// Split string into array
{{ $json.email.split('@') }}

// Get specific part after split
{{ $json.email.split('@')[1] }}

// Join array into string
{{ $json.tags.join(', ') }}

Search & Replace

// Replace first occurrence
{{ $json.text.replace('old', 'new') }}

// Replace all occurrences
{{ $json.text.replaceAll('old', 'new') }}

// Check if string includes substring
{{ $json.text.includes('keyword') }}

// Check if string starts with
{{ $json.url.startsWith('https://') }}

// Check if string ends with
{{ $json.filename.endsWith('.pdf') }}

// Find position of substring
{{ $json.text.indexOf('word') }}

Substring & Slicing

// Get substring (start, length)
{{ $json.text.substring(0, 10) }}

// Slice string (start, end)
{{ $json.text.slice(0, 5) }}

// Get first character
{{ $json.name[0] }}

// Get last character
{{ $json.name[$json.name.length - 1] }}

Advanced String Operations

// Pad start with zeros
{{ $json.id.toString().padStart(5, '0') }}

// Pad end with spaces
{{ $json.text.padEnd(20, ' ') }}

// Repeat string
{{ '-'.repeat(10) }}

// Match regex
{{ $json.text.match(/\d+/) }}

// Test regex
{{ /^\d{5}$/.test($json.zipCode) }}

Number Operations

Basic Math

// Addition
{{ $json.price + 10 }}

// Subtraction
{{ $json.total - $json.discount }}

// Multiplication
{{ $json.quantity * $json.price }}

// Division
{{ $json.total / $json.items }}

// Modulo (remainder)
{{ $json.number % 2 }}

// Exponentiation
{{ $json.base ** $json.exponent }}

Parsing & Formatting

// Parse string to integer
{{ parseInt($json.value) }}

// Parse string to float
{{ parseFloat($json.price) }}

// Round to 2 decimal places
{{ parseFloat($json.amount).toFixed(2) }}

// Round to nearest integer
{{ Math.round($json.value) }}

// Round up
{{ Math.ceil($json.value) }}

// Round down
{{ Math.floor($json.value) }}

Math Functions

// Absolute value
{{ Math.abs($json.difference) }}

// Maximum value
{{ Math.max($json.value1, $json.value2, $json.value3) }}

// Minimum value
{{ Math.min($json.value1, $json.value2, $json.value3) }}

// Random number (0-1)
{{ Math.random() }}

// Random integer (0-99)
{{ Math.floor(Math.random() * 100) }}

// Square root
{{ Math.sqrt($json.number) }}

// Power
{{ Math.pow($json.base, $json.exponent) }}

Number Validation

// Check if number
{{ !isNaN($json.value) }}

// Check if integer
{{ Number.isInteger($json.value) }}

// Check if finite
{{ isFinite($json.value) }}

Date & Time

Current Date & Time

// Current timestamp (ISO format)
{{ $now }}

// Today at midnight
{{ $today }}

// Using DateTime (Luxon)
{{ DateTime.now().toISO() }}

// Current timestamp in milliseconds
{{ Date.now() }}

Creating Dates

// From ISO string
{{ DateTime.fromISO($json.dateString) }}

// From format
{{ DateTime.fromFormat($json.date, 'yyyy-MM-dd') }}

// From timestamp
{{ DateTime.fromMillis($json.timestamp) }}

// Specific date
{{ DateTime.fromObject({ year: 2024, month: 1, day: 15 }) }}

Formatting Dates

// ISO format
{{ DateTime.now().toISO() }}

// Custom format
{{ DateTime.now().toFormat('yyyy-MM-dd') }}
{{ DateTime.now().toFormat('dd.MM.yyyy HH:mm:ss') }}
{{ DateTime.now().toFormat('MMMM dd, yyyy') }}

// Locale-specific
{{ DateTime.now().toLocaleString(DateTime.DATE_FULL) }}
{{ DateTime.now().toLocaleString(DateTime.DATETIME_MED) }}

// Relative time
{{ DateTime.now().toRelative() }}

Date Arithmetic

// Add time
{{ DateTime.now().plus({ days: 7 }) }}
{{ DateTime.now().plus({ hours: 2, minutes: 30 }) }}
{{ DateTime.now().plus({ months: 1 }) }}

// Subtract time
{{ DateTime.now().minus({ days: 30 }) }}
{{ DateTime.now().minus({ years: 1 }) }}

// Difference between dates
{{ DateTime.now().diff(DateTime.fromISO($json.startDate), 'days').days }}
{{ DateTime.now().diff(DateTime.fromISO($json.startDate), ['years', 'months', 'days']) }}

Date Components

// Get year
{{ DateTime.now().year }}

// Get month (1-12)
{{ DateTime.now().month }}

// Get day
{{ DateTime.now().day }}

// Get hour
{{ DateTime.now().hour }}

// Get minute
{{ DateTime.now().minute }}

// Get day of week (1-7, Mon-Sun)
{{ DateTime.now().weekday }}

// Get day name
{{ DateTime.now().weekdayLong }}

// Get month name
{{ DateTime.now().monthLong }}

Date Manipulation

// Start of day
{{ DateTime.now().startOf('day') }}

// End of month
{{ DateTime.now().endOf('month') }}

// Start of week
{{ DateTime.now().startOf('week') }}

// Set specific time
{{ DateTime.now().set({ hour: 9, minute: 0, second: 0 }) }}

Array Operations

Basic Array Methods

// Get array length
{{ $json.items.length }}

// Access element by index
{{ $json.items[0] }}

// Last element
{{ $json.items[$json.items.length - 1] }}

// Join array
{{ $json.tags.join(', ') }}

// Check if array includes value
{{ $json.items.includes('value') }}

Transforming Arrays

// Map: transform each element
{{ $json.users.map(user => user.email) }}
{{ $json.prices.map(p => parseFloat(p) * 1.2) }}

// Filter: keep elements matching condition
{{ $json.users.filter(user => user.active === true) }}
{{ $json.numbers.filter(n => n > 10) }}

// Find: get first matching element
{{ $json.users.find(user => user.id === 123) }}

// Find index
{{ $json.items.findIndex(item => item.name === 'Product') }}

// Some: check if any element matches
{{ $json.items.some(item => item.price > 100) }}

// Every: check if all elements match
{{ $json.items.every(item => item.inStock === true) }}

Array Aggregation

// Reduce: calculate sum
{{ $json.prices.reduce((sum, price) => sum + parseFloat(price), 0) }}

// Calculate average
{{ $json.numbers.reduce((sum, n) => sum + n, 0) / $json.numbers.length }}

// Find maximum
{{ Math.max(...$json.numbers) }}

// Find minimum
{{ Math.min(...$json.numbers) }}

// Count occurrences
{{ $json.items.filter(item => item.status === 'active').length }}

Sorting Arrays

// Sort numbers ascending
{{ $json.numbers.sort((a, b) => a - b) }}

// Sort numbers descending
{{ $json.numbers.sort((a, b) => b - a) }}

// Sort strings alphabetically
{{ $json.names.sort() }}

// Sort objects by property
{{ $json.users.sort((a, b) => a.name.localeCompare(b.name)) }}

Array Manipulation

// Slice: get portion of array
{{ $json.items.slice(0, 5) }}

// Concat: combine arrays
{{ $json.array1.concat($json.array2) }}

// Flat: flatten nested arrays
{{ $json.nestedArray.flat() }}

// Unique values (using Set)
{{ [...new Set($json.items)] }}

// Reverse array
{{ $json.items.reverse() }}

Object Operations

Accessing Properties

// Dot notation
{{ $json.user.name }}

// Bracket notation
{{ $json["property-name"] }}

// Nested access
{{ $json.data.user.addresses[0].city }}

Object Methods

// Get all keys
{{ Object.keys($json) }}

// Get all values
{{ Object.values($json) }}

// Get entries (key-value pairs)
{{ Object.entries($json) }}

// Check if property exists
{{ $json.hasOwnProperty('email') }}

// Check if object has any properties
{{ Object.keys($json).length > 0 }}

Object Transformation

// Merge objects
{{ Object.assign({}, $json.obj1, $json.obj2) }}

// Spread operator
{{ {...$json.user, role: 'admin'} }}

// Extract specific properties
{{ (({ name, email }) => ({ name, email }))($json.user) }}

// Map object to array
{{ Object.entries($json).map(([key, value]) => ({ key, value })) }}

Conditional Logic

Ternary Operator

// Basic ternary
{{ $json.status === 'active' ? 'Active' : 'Inactive' }}

// Nested ternary
{{ $json.score >= 90 ? 'A' : $json.score >= 80 ? 'B' : 'C' }}

// With numbers
{{ $json.quantity > 0 ? $json.price * $json.quantity : 0 }}

If Function

// Basic if
{{ $if($json.premium === true, 'Premium User', 'Regular User') }}

// With expressions
{{ $if($json.total > 100, $json.total * 0.9, $json.total) }}

Logical Operators

// AND
{{ $json.age >= 18 && $json.verified === true }}

// OR
{{ $json.role === 'admin' || $json.role === 'moderator' }}

// NOT
{{ !$json.deleted }}

// Nullish coalescing
{{ $json.name ?? 'Unknown' }}

// Default value
{{ $json.value || 'default' }}

Comparison

// Equality
{{ $json.status === 'completed' }}

// Inequality
{{ $json.type !== 'test' }}

// Greater than
{{ $json.score > 50 }}

// Less than or equal
{{ $json.price <= 99.99 }}

// Type checking
{{ typeof $json.value === 'string' }}

JSON Operations

Parsing & Stringifying

// Parse JSON string
{{ JSON.parse($json.jsonString) }}

// Stringify object
{{ JSON.stringify($json.data) }}

// Stringify with formatting
{{ JSON.stringify($json.data, null, 2) }}

Handling JSON Errors

// Safe JSON parse with try/catch in Code node
try {
  const data = JSON.parse(items[0].json.rawData);
  return [{json: data}];
} catch (error) {
  return [{json: {error: 'Invalid JSON', raw: items[0].json.rawData}}];
}

Common Patterns

Email Validation

// Check if valid email format
{{ /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test($json.email) }}

// Extract domain from email
{{ $json.email.split('@')[1] }}

// Normalize email
{{ $json.email.toLowerCase().trim() }}

URL Operations

// Extract domain from URL
{{ new URL($json.url).hostname }}

// Get URL parameters
{{ new URL($json.url).searchParams.get('id') }}

// Build URL with parameters
{{ `https://api.example.com/users?id=${$json.userId}&format=json` }}

Phone Number Formatting

// Remove non-digits
{{ $json.phone.replace(/\D/g, '') }}

// Format US phone
{{ $json.phone.replace(/(\d{3})(\d{3})(\d{4})/, '($1) $2-$3') }}

Price/Currency Formatting

// Format as currency
{{ parseFloat($json.price).toFixed(2) }}

// Add currency symbol
{{ `$${parseFloat($json.price).toFixed(2)}` }}

// Calculate with tax
{{ (parseFloat($json.price) * 1.19).toFixed(2) }}

Name Formatting

// Capitalize first letter
{{ $json.name.charAt(0).toUpperCase() + $json.name.slice(1).toLowerCase() }}

// Title case
{{ $json.name.split(' ').map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join(' ') }}

// Initials
{{ $json.firstName[0] + $json.lastName[0] }}

Generating IDs

// Random UUID-like string
{{ Math.random().toString(36).substring(2, 15) }}

// Timestamp-based ID
{{ Date.now().toString(36) }}

// Sequential ID with padding
{{ String($json.index).padStart(6, '0') }}

Data Validation

// Check if empty
{{ !$json.value || $json.value.trim() === '' }}

// Check if valid number
{{ !isNaN(parseFloat($json.value)) }}

// Check if array has items
{{ Array.isArray($json.items) && $json.items.length > 0 }}

// Check if date is in future
{{ DateTime.fromISO($json.date) > DateTime.now() }}

Data Cleaning

// Remove duplicates from array
{{ [...new Set($json.items)] }}

// Remove null/undefined values
{{ $json.items.filter(item => item != null) }}

// Remove empty strings
{{ $json.values.filter(v => v !== '') }}

// Trim all strings in array
{{ $json.items.map(item => item.trim()) }}

Best Practices

1. Use meaningful variable names in Code nodes
2. Test expressions with sample data before deploying
3. Handle null/undefined values with nullish coalescing (??)
4. Use Set node for simple transformations, Code node for complex logic
5. Break complex expressions into multiple steps for readability
6. Check data structure in debug panel before writing expressions
7. Use DateTime for dates, not JavaScript Date (better timezone support)
8. Validate data before processing to avoid runtime errors
9. Document complex expressions with comments in Code nodes
10. Cache frequently used values in variables to avoid repetition

Additional Resources

• Official n8n Expression docs: https://docs.n8n.io/code-examples/expressions/
• Luxon DateTime docs: https://moment.github.io/luxon/
• JavaScript reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript