FormatString@1

Node FormatString@1 creates formatted strings by replacing JSON path placeholders with actual values from the data context.

Adapter Prerequisites

• General availability: All adapters support this node type.

Node Configuration

For fields targetPath, targetValueWriteMode, and targetValueKind, see Overview.

transformations:
- type: FormatString@1
  targetPath: $.formattedMessage  # Path where the formatted string will be stored
  format: "Invoice {$.InvoiceNumber} from {$.Customer.Name} - Total: {$.Total} EUR"  # Format string with placeholders
  nullValue: "N/A"  # String to use for null values (default: "NULL")

Parameters

Required Parameters

Parameter	Type	Description
format	string	The format string containing placeholders. Placeholders are defined as {$.json.path} where the JSON path points to values in the current data context
targetPath	string	The JSON path where the formatted result will be stored

Optional Parameters

Parameter	Type	Default	Description
nullValue	string	"NULL"	The string to use when a JSON path resolves to a null value
targetValueWriteMode	enum	-	How to write the value (see Overview)
targetValueKind	enum	-	The kind of target value (see Overview)
documentMode	enum	-	Document mode for the operation (see Overview)

How It Works

1. Placeholder Detection: The node scans the format string for placeholders in the pattern {$.path.to.value}
2. Value Resolution: For each placeholder, it evaluates the JSON path against the current data context
3. Value Replacement: Replaces each placeholder with the resolved value (or nullValue if null)
4. Result Storage: Stores the formatted string at the specified targetPath

Placeholder Syntax

Placeholders must follow this pattern:

• Start with {
• Contain a valid JSON path starting with $
• End with }

Examples:

• {$.name} - Simple property access
• {$.customer.address.city} - Nested property access
• {$.items[0].price} - Array element access
• {$.metadata['special-key']} - Bracket notation for special characters

Error Handling

The node will throw an error if:

• A JSON path in a placeholder doesn't exist in the data
• A JSON path resolves to a complex type (object or array) instead of a simple value
• The JSON path syntax is invalid

Examples

Example 1: Simple Message Formatting

transformations:
- type: FormatString@1
  targetPath: $.message
  format: "Hello {$.firstName} {$.lastName}, welcome to {$.company}!"

Input:

{
  "firstName": "John",
  "lastName": "Doe",
  "company": "MeshMakers"
}

Output:

{
  "firstName": "John",
  "lastName": "Doe",
  "company": "MeshMakers",
  "message": "Hello John Doe, welcome to MeshMakers!"
}

Example 2: Invoice Summary with Null Handling

transformations:
- type: FormatString@1
  targetPath: $.summary
  format: "Invoice #{$.invoiceNumber} | Customer: {$.customer.name} | PO: {$.purchaseOrder} | Total: {$.total} {$.currency}"
  nullValue: "N/A"

Input:

{
  "invoiceNumber": "INV-2024-001",
  "customer": {
    "name": "Acme Corp"
  },
  "purchaseOrder": null,
  "total": 1250.50,
  "currency": "EUR"
}

Output:

{
  "invoiceNumber": "INV-2024-001",
  "customer": {
    "name": "Acme Corp"
  },
  "purchaseOrder": null,
  "total": 1250.50,
  "currency": "EUR",
  "summary": "Invoice #INV-2024-001 | Customer: Acme Corp | PO: N/A | Total: 1250.5 EUR"
}

Example 3: Creating URLs from Data

transformations:
- type: FormatString@1
  targetPath: $.dashboardUrl
  format: "https://dashboard.example.com/projects/{$.projectId}/tasks/{$.taskId}?user={$.assignee.email}"

Input:

{
  "projectId": "PROJ-123",
  "taskId": "TASK-456",
  "assignee": {
    "name": "Jane Smith",
    "email": "jane.smith@example.com"
  }
}

Output:

{
  "projectId": "PROJ-123",
  "taskId": "TASK-456",
  "assignee": {
    "name": "Jane Smith",
    "email": "jane.smith@example.com"
  },
  "dashboardUrl": "https://dashboard.example.com/projects/PROJ-123/tasks/TASK-456?user=jane.smith@example.com"
}

Example 4: Log Message Generation

transformations:
- type: FormatString@1
  targetPath: $.logEntry
  format: "[{$.timestamp}] {$.level}: {$.service} - {$.message} (Duration: {$.duration}ms)"

Input:

{
  "timestamp": "2024-01-15T10:30:45Z",
  "level": "ERROR",
  "service": "PaymentService",
  "message": "Payment processing failed",
  "duration": 1234
}

Output:

{
  "timestamp": "2024-01-15T10:30:45Z",
  "level": "ERROR",
  "service": "PaymentService",
  "message": "Payment processing failed",
  "duration": 1234,
  "logEntry": "[2024-01-15T10:30:45Z] ERROR: PaymentService - Payment processing failed (Duration: 1234ms)"
}

Example 5: SQL Query Generation

transformations:
- type: FormatString@1
  targetPath: $.sqlQuery
  format: "SELECT * FROM {$.table} WHERE status = '{$.filter.status}' AND created_date >= '{$.filter.startDate}' ORDER BY {$.sortField} {$.sortOrder}"

Input:

{
  "table": "orders",
  "filter": {
    "status": "pending",
    "startDate": "2024-01-01"
  },
  "sortField": "created_date",
  "sortOrder": "DESC"
}

Output:

{
  "table": "orders",
  "filter": {
    "status": "pending",
    "startDate": "2024-01-01"
  },
  "sortField": "created_date",
  "sortOrder": "DESC",
  "sqlQuery": "SELECT * FROM orders WHERE status = 'pending' AND created_date >= '2024-01-01' ORDER BY created_date DESC"
}

Use Cases

• Message Generation: Create user-friendly messages from structured data
• URL Construction: Build dynamic URLs for APIs or web applications
• Log Formatting: Generate standardized log entries
• Report Generation: Create formatted text summaries from data
• Query Building: Construct database queries or search strings
• Notification Templates: Format email subjects or SMS messages
• File Naming: Generate dynamic file names based on data attributes

Notes

• Simple Values Only: Placeholders must resolve to simple values (string, number, boolean, null). Objects and arrays are not supported
• Path Validation: All JSON paths in placeholders must exist in the data, otherwise the node will fail
• Null Handling: Use the nullValue parameter to control how null values are displayed
• No Escaping: The node doesn't provide escape mechanisms for literal braces. If you need literal { or } in your output, consider using a different approach
• Performance: The node uses compiled regular expressions for efficient placeholder detection
• Type Conversion: All values are converted to strings using their default string representation