TransformString@1

Node TransformString@1 performs various string manipulation operations on text data. It can trim whitespace, convert case, extract substrings, and perform other text processing operations essential for data cleaning and formatting.

Adapter Prerequisites

General availability: All adapters support this node type.

Node Configuration

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

transformations:
- type: TransformString@1
  path: $.users[*]                    # Path to objects containing string data
  sourcePath: $.name                  # Path to string value to transform
  targetPath: $.cleanName             # Path where transformed value will be stored
  operation: Trim                     # String operation to perform
  # Optional parameters for substring operations:
  # startIndex: 0                     # Starting position for Substring operation
  # length: 10                        # Length for substring operations

Parameters

Required Parameters

Parameter	Type	Description
`path`	string	JSONPath to objects containing the string data to process
`sourcePath`	string	Relative path to the string value within each object
`targetPath`	string	Relative path where the transformed value will be stored
`operation`	enum	String operation to perform

Optional Parameters

Parameter	Type	Default	Description
`startIndex`	int	0	Starting position for `Substring` operation
`length`	int	-	Length for substring operations

String Operations

The node supports the following string manipulation operations:

Case Operations

ToUpper: Converts the string to uppercase
ToLower: Converts the string to lowercase

Trimming Operations

Trim: Removes whitespace from both ends of the string
TrimStart: Removes whitespace from the beginning (left side) of the string
TrimEnd: Removes whitespace from the end (right side) of the string

Substring Operations

SubstringFromStart: Extracts a substring from the beginning with specified length (requires length)
SubstringFromEnd: Extracts a substring from the end with specified length (requires length)
Substring: Extracts a substring starting at specific position (uses startIndex and optional length)

Operation Details

Trim Operations

Remove standard whitespace characters (spaces, tabs, newlines)
Safe for empty strings and strings with only whitespace
Preserve null values

Case Conversion

ToUpper and ToLower use culture-invariant conversion
Handle special characters and Unicode properly
Preserve null values

Substring Operations

Bounds Checking: Automatically adjust parameters to prevent out-of-bounds errors
Null Safety: Null values are preserved without processing
Empty Results: Return empty string when parameters result in no extractable content
Parameter Requirements:
- SubstringFromStart and SubstringFromEnd require length parameter
- Substring uses startIndex and optional length

Examples

Example 1: Trim Whitespace

Remove whitespace from user names:

transformations:
- type: TransformString@1
  path: $.users[*]
  sourcePath: $.name
  targetPath: $.cleanName
  operation: Trim

Input:

{
  "users": [
    { "id": 1, "name": "  John Doe  " },
    { "id": 2, "name": "\tJane Smith\n" },
    { "id": 3, "name": "Bob Wilson" }
  ]
}

Output:

{
  "users": [
    { "id": 1, "name": "  John Doe  ", "cleanName": "John Doe" },
    { "id": 2, "name": "\tJane Smith\n", "cleanName": "Jane Smith" },
    { "id": 3, "name": "Bob Wilson", "cleanName": "Bob Wilson" }
  ]
}

Example 2: Convert to Uppercase

Standardize product codes to uppercase:

transformations:
- type: TransformString@1
  path: $.products[*]
  sourcePath: $.code
  targetPath: $.standardCode
  operation: ToUpper

Input:

{
  "products": [
    { "name": "Widget A", "code": "wdg-001" },
    { "name": "Widget B", "code": "WDG-002" },
    { "name": "Gadget C", "code": "gdg-003" }
  ]
}

Output:

{
  "products": [
    { "name": "Widget A", "code": "wdg-001", "standardCode": "WDG-001" },
    { "name": "Widget B", "code": "WDG-002", "standardCode": "WDG-002" },
    { "name": "Gadget C", "code": "gdg-003", "standardCode": "GDG-003" }
  ]
}

Example 3: Extract Prefix with SubstringFromStart

Extract country code from phone numbers:

transformations:
- type: TransformString@1
  path: $.contacts[*]
  sourcePath: $.phone
  targetPath: $.countryCode
  operation: SubstringFromStart
  length: 3

Input:

{
  "contacts": [
    { "name": "Alice", "phone": "+49123456789" },
    { "name": "Bob", "phone": "+1987654321" },
    { "name": "Charlie", "phone": "+33112233445" }
  ]
}

Output:

{
  "contacts": [
    { "name": "Alice", "phone": "+49123456789", "countryCode": "+49" },
    { "name": "Bob", "phone": "+1987654321", "countryCode": "+19" },
    { "name": "Charlie", "phone": "+33112233445", "countryCode": "+33" }
  ]
}

Example 4: Extract File Extension with SubstringFromEnd

Extract file extensions from filenames:

transformations:
- type: TransformString@1
  path: $.files[*]
  sourcePath: $.filename
  targetPath: $.extension
  operation: SubstringFromEnd
  length: 4

Input:

{
  "files": [
    { "id": 1, "filename": "document.pdf" },
    { "id": 2, "filename": "image.jpeg" },
    { "id": 3, "filename": "data.xlsx" }
  ]
}

Output:

{
  "files": [
    { "id": 1, "filename": "document.pdf", "extension": ".pdf" },
    { "id": 2, "filename": "image.jpeg", "extension": "jpeg" },
    { "id": 3, "filename": "data.xlsx", "extension": "xlsx" }
  ]
}

Example 5: Extract Middle Section with Substring

Extract year from date strings:

transformations:
- type: TransformString@1
  path: $.events[*]
  sourcePath: $.date
  targetPath: $.year
  operation: Substring
  startIndex: 0
  length: 4

Input:

{
  "events": [
    { "name": "Conference", "date": "2023-10-15" },
    { "name": "Workshop", "date": "2024-03-22" },
    { "name": "Seminar", "date": "2023-12-01" }
  ]
}

Output:

{
  "events": [
    { "name": "Conference", "date": "2023-10-15", "year": "2023" },
    { "name": "Workshop", "date": "2024-03-22", "year": "2024" },
    { "name": "Seminar", "date": "2023-12-01", "year": "2023" }
  ]
}

Example 6: Extract Substring to End

Extract domain from email addresses:

transformations:
- type: TransformString@1
  path: $.users[*]
  sourcePath: $.email
  targetPath: $.domain
  operation: Substring
  startIndex: 5  # Skip "user@" part

Input:

{
  "users": [
    { "name": "John", "email": "john@example.com" },
    { "name": "Jane", "email": "jane@company.org" }
  ]
}

Output:

{
  "users": [
    { "name": "John", "email": "john@example.com", "domain": "xample.com" },
    { "name": "Jane", "email": "jane@company.org", "domain": "ompany.org" }
  ]
}

Example 7: Multiple String Operations

Apply multiple string transformations in sequence:

transformations:
- type: TransformString@1
  path: $.products[*]
  sourcePath: $.name
  targetPath: $.trimmedName
  operation: Trim
- type: TransformString@1
  path: $.products[*]
  sourcePath: $.trimmedName
  targetPath: $.upperName
  operation: ToUpper
- type: TransformString@1
  path: $.products[*]
  sourcePath: $.upperName
  targetPath: $.shortName
  operation: SubstringFromStart
  length: 10

Input:

{
  "products": [
    { "id": 1, "name": "  Premium Quality Widget  " },
    { "id": 2, "name": " Standard Gadget " }
  ]
}

Output:

{
  "products": [
    {
      "id": 1,
      "name": "  Premium Quality Widget  ",
      "trimmedName": "Premium Quality Widget",
      "upperName": "PREMIUM QUALITY WIDGET",
      "shortName": "PREMIUM QU"
    },
    {
      "id": 2,
      "name": " Standard Gadget ",
      "trimmedName": "Standard Gadget",
      "upperName": "STANDARD GADGET",
      "shortName": "STANDARD G"
    }
  ]
}

Example 8: Handle Null Values

Demonstrate null value handling:

transformations:
- type: TransformString@1
  path: $.items[*]
  sourcePath: $.description
  targetPath: $.cleanDescription
  operation: Trim

Input:

{
  "items": [
    { "id": 1, "description": "  Valid description  " },
    { "id": 2, "description": null },
    { "id": 3, "description": "" }
  ]
}

Output:

{
  "items": [
    { "id": 1, "description": "  Valid description  ", "cleanDescription": "Valid description" },
    { "id": 2, "description": null, "cleanDescription": null },
    { "id": 3, "description": "", "cleanDescription": "" }
  ]
}

Use Cases

Data Cleaning: Remove unwanted whitespace from user input
Format Standardization: Convert strings to consistent case format
Text Extraction: Extract specific parts of strings (prefixes, suffixes, codes)
Data Preparation: Clean and format strings before comparison or storage
User Input Processing: Normalize user-entered data
Code Standardization: Standardize product codes, IDs, or reference numbers
Content Processing: Extract information from structured text fields
Data Validation Preparation: Clean data before applying validation rules

Error Handling

The node will throw errors when:

The input data context is null
Required length parameter is missing for SubstringFromStart or SubstringFromEnd operations
JSONPath expressions are invalid

Behavior Notes

Null Preservation: Null values are preserved without processing
Type Conversion: Non-string values are converted to strings before processing
Bounds Safety: Substring operations automatically handle out-of-bounds parameters
Empty String Handling: Empty strings are processed according to the operation
Culture-Invariant: Case conversions use invariant culture for consistency
Whitespace: Trim operations remove standard whitespace characters (spaces, tabs, newlines)
Memory Efficient: Processing is done per object, not loading all data at once

Performance Notes

String Creation: Each operation creates a new string (strings are immutable in .NET)
Large Strings: Substring operations on very large strings may impact performance
Batch Processing: Consider the size of datasets when applying to many objects
Chaining Operations: Multiple operations can be chained but each creates intermediate strings

FormatString@1: Format strings with placeholders and templates
ConvertDataType@1: Convert between different data types
Base64Encode@1: Encode strings to Base64 format
Base64Decode@1: Decode Base64 strings back to text

Adapter Prerequisites​

Node Configuration​

Parameters​

Required Parameters​

Optional Parameters​

String Operations​

Case Operations​

Trimming Operations​

Substring Operations​

Operation Details​

Trim Operations​

Case Conversion​

Substring Operations​

Examples​

Example 1: Trim Whitespace​

Example 2: Convert to Uppercase​

Example 3: Extract Prefix with SubstringFromStart​

Example 4: Extract File Extension with SubstringFromEnd​

Example 5: Extract Middle Section with Substring​

Example 6: Extract Substring to End​

Example 7: Multiple String Operations​

Example 8: Handle Null Values​

Use Cases​

Error Handling​

Behavior Notes​

Performance Notes​

Related Nodes​

Adapter Prerequisites

Node Configuration

Parameters

Required Parameters

Optional Parameters

String Operations

Case Operations

Trimming Operations

Substring Operations

Operation Details

Trim Operations

Case Conversion

Substring Operations

Examples

Example 1: Trim Whitespace

Example 2: Convert to Uppercase

Example 3: Extract Prefix with SubstringFromStart

Example 4: Extract File Extension with SubstringFromEnd

Example 5: Extract Middle Section with Substring

Example 6: Extract Substring to End

Example 7: Multiple String Operations

Example 8: Handle Null Values

Use Cases

Error Handling

Behavior Notes

Performance Notes

Related Nodes