SetPrimitiveValue@1

Node SetPrimitiveValue@1 sets primitive values at specified paths in the data context. It converts a configured value to a specified primitive type and assigns it to a target path, making it essential for data enrichment, default value assignment, and metadata injection.

Adapter Prerequisites

• General availability: All adapters support this node type.

Node Configuration

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

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.status                 # Path where the value will be stored
  value: "pending"                     # The value to set (static)
  valueType: String                    # Target primitive type for conversion
  # OR use valuePath for dynamic values:
  # valuePath: $.config.defaultStatus  # Path to retrieve value from data context

Parameters

Required Parameters

Parameter	Type	Description
targetPath	string	JSONPath where the converted value will be stored
valueType	enum	Target primitive type for value conversion

Value Source Parameters

Either value or valuePath must be specified, but not both.

Parameter	Type	Required	Description
value	any	No*	Static source value to be converted and assigned
valuePath	string	No*	JSONPath to retrieve value dynamically from data context

Supported Value Types

Value Type	Description	Example Values
String	Text values	"hello", "123", "true"
Int	32-bit integers	42, "123"
Int64	64-bit integers (long)	9223372036854775807, "123456789"
Double	Double-precision floating-point	3.14159, "3.14"
Boolean	Boolean true/false values	true, "false", "True"
DateTime	Date and time values	"2023-12-25T00:00:00Z"
TimeSpan	Time duration values	"01:30:00", "1.12:00:00"
Binary	Byte values	255, "128"
StringArray	Arrays of strings	["item1", "item2"]
IntArray	Arrays of integers	[1, 2, 3]

Unsupported Types

The following complex types are not supported and will result in errors:

• Record
• RecordArray
• Enum
• DateTimeOffset
• GeospatialPoint
• BinaryLinked

Value Sources

You can specify the source value in two ways:

1. Static Value: Use the value parameter to specify a fixed value
2. Dynamic Value: Use the valuePath parameter to retrieve a value from the data context

Value Source Priority

• If valuePath is specified, it takes precedence over value
• If valuePath is specified but no value is found at that path, an error is thrown
• Only one of value or valuePath should be specified

Value Conversion

• Automatic Type Conversion: Values are automatically converted to the specified target type
• Culture-Invariant Parsing: Double values are parsed using invariant culture for consistency
• String Representations: Most primitive types can be converted from string representations
• Array Support: StringArray and IntArray types support array input values

Examples

Example 1: Setting a String Status

Add a default status to records:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.status
  value: "pending"
  valueType: String

Input:

{
  "orderId": "12345",
  "customerName": "John Doe"
}

Output:

{
  "orderId": "12345",
  "customerName": "John Doe",
  "status": "pending"
}

Example 2: Setting a Numeric Value

Add a tax rate as a double:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.pricing.taxRate
  value: "0.0875"
  valueType: Double

Input:

{
  "productId": "WIDGET-001",
  "price": 100.0
}

Output:

{
  "productId": "WIDGET-001",
  "price": 100.0,
  "pricing": {
    "taxRate": 0.0875
  }
}

Example 3: Setting a Boolean Flag

Add a feature flag:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.features.premiumEnabled
  value: true
  valueType: Boolean

Input:

{
  "userId": "user123"
}

Output:

{
  "userId": "user123",
  "features": {
    "premiumEnabled": true
  }
}

Example 4: Setting a DateTime Timestamp

Add a processing timestamp:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.metadata.processedAt
  value: "2023-10-15T14:30:00Z"
  valueType: DateTime

Input:

{
  "data": "sample content"
}

Output:

{
  "data": "sample content",
  "metadata": {
    "processedAt": "2023-10-15T14:30:00Z"
  }
}

Example 5: Setting an Integer Counter

Initialize a counter:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.metrics.processCount
  value: 0
  valueType: Int

Input:

{
  "jobId": "job-456"
}

Output:

{
  "jobId": "job-456",
  "metrics": {
    "processCount": 0
  }
}

Example 6: Setting an Array Value

Add tags as a string array:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.tags
  value: ["important", "urgent", "customer-facing"]
  valueType: StringArray

Input:

{
  "ticketId": "TICKET-789"
}

Output:

{
  "ticketId": "TICKET-789",
  "tags": ["important", "urgent", "customer-facing"]
}

Example 7: Setting with String-to-Number Conversion

Convert string input to numeric value:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.quantity
  value: "42"
  valueType: Int

Input:

{
  "productCode": "ABC123"
}

Output:

{
  "productCode": "ABC123",
  "quantity": 42
}

Example 8: Setting Multiple Values

Use multiple nodes to set several primitive values:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.metadata.version
  value: "1.0"
  valueType: String
- type: SetPrimitiveValue@1
  targetPath: $.metadata.created
  value: "2023-10-15T10:00:00Z"
  valueType: DateTime
- type: SetPrimitiveValue@1
  targetPath: $.metadata.priority
  value: "5"
  valueType: Int

Input:

{
  "title": "Sample Document"
}

Output:

{
  "title": "Sample Document",
  "metadata": {
    "version": "1.0",
    "created": "2023-10-15T10:00:00Z",
    "priority": 5
  }
}

Example 9: Dynamic Value with ValuePath

Copy a value from one location to another using ValuePath:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.customer.displayName
  valuePath: $.customer.fullName
  valueType: String

Input:

{
  "customer": {
    "id": "CUST123",
    "fullName": "John Smith",
    "email": "john@example.com"
  }
}

Output:

{
  "customer": {
    "id": "CUST123",
    "fullName": "John Smith",
    "email": "john@example.com",
    "displayName": "John Smith"
  }
}

Example 10: Configuration-Based Values

Use configuration values stored in the data context:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.order.taxRate
  valuePath: $.config.defaultTaxRate
  valueType: Double
- type: SetPrimitiveValue@1
  targetPath: $.order.currency
  valuePath: $.config.baseCurrency
  valueType: String

Input:

{
  "config": {
    "defaultTaxRate": 0.19,
    "baseCurrency": "EUR"
  },
  "order": {
    "id": "ORD-001",
    "amount": 100.0
  }
}

Output:

{
  "config": {
    "defaultTaxRate": 0.19,
    "baseCurrency": "EUR"
  },
  "order": {
    "id": "ORD-001",
    "amount": 100.0,
    "taxRate": 0.19,
    "currency": "EUR"
  }
}

Example 11: Computed Value Copy

Copy a computed value to a standardized location:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.summary.totalItems
  valuePath: $.analytics.calculatedTotals.itemCount
  valueType: Int

Input:

{
  "analytics": {
    "calculatedTotals": {
      "itemCount": 42,
      "totalValue": 1250.00
    }
  },
  "items": ["item1", "item2", "..."]
}

Output:

{
  "analytics": {
    "calculatedTotals": {
      "itemCount": 42,
      "totalValue": 1250.00
    }
  },
  "items": ["item1", "item2", "..."],
  "summary": {
    "totalItems": 42
  }
}

Use Cases

• Default Values: Set default values for optional fields in records
• Metadata Injection: Add processing timestamps, version numbers, or system identifiers
• Data Enrichment: Inject configuration constants or computed base values
• Status Initialization: Set initial status flags or state indicators
• Constants Addition: Add system-wide constants or configuration values
• Field Initialization: Initialize computed fields with starting values
• Audit Information: Add audit trails with user IDs, timestamps, or source system identifiers
• Feature Flags: Set boolean flags for feature toggles or conditional processing
• Value Copying: Copy values from one location to another within the same data context
• Configuration Management: Use centralized configuration values stored in the data context
• Computed Field Standardization: Move calculated values to standardized output locations

Error Handling

The node will throw errors when:

• The specified valueType is not supported (complex types)
• Value conversion fails due to incompatible types or invalid format
• Invalid JSONPath expressions are used for targetPath or valuePath
• valuePath is specified but no value is found at that path
• Neither value nor valuePath is specified

Conversion Examples

String to Numeric Conversion

value: "123.45"
valueType: Double
# Result: 123.45 (double)

Boolean String Conversion

value: "true"
valueType: Boolean
# Result: true (boolean)

Culture-Invariant Double Parsing

value: "3.14159"  # Always uses dot as decimal separator
valueType: Double
# Result: 3.14159 (consistent regardless of system locale)

Dynamic Value from JSONPath

valuePath: "$.metadata.userId"  # Extract value from data context
valueType: String
# Result: Value at $.metadata.userId converted to string

Notes

• Culture-Invariant: Double values are parsed using invariant culture to prevent regional formatting issues
• Type Safety: Values are converted to exact primitive types for type safety
• Path Creation: Target paths are created if they don't exist (respects targetValueWriteMode)
• Overwrite Behavior: Existing values can be overwritten or preserved based on targetValueWriteMode
• Array Support: Both string and integer arrays are supported for list-based data
• Null Handling: Null values are processed according to the target type's null handling rules
• ValuePath Priority: When both value and valuePath are specified, valuePath takes precedence
• Dynamic Resolution: ValuePath is evaluated against the current data context at runtime
• Error on Missing Path: If valuePath is specified but no value exists at that path, an error is thrown

Related Nodes

• WriteJson@1: Write complex JSON structures to the data pipeline
• Math@1: Perform mathematical operations on numeric values
• If@1: Conditionally set values based on data conditions