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:

Static Value: Use the value parameter to specify a fixed value
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

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

Adapter Prerequisites​

Node Configuration​

Parameters​

Required Parameters​

Value Source Parameters​

Supported Value Types​

Unsupported Types​

Value Sources​

Value Source Priority​

Value Conversion​

Examples​

Example 1: Setting a String Status​

Example 2: Setting a Numeric Value​

Example 3: Setting a Boolean Flag​

Example 4: Setting a DateTime Timestamp​

Example 5: Setting an Integer Counter​

Example 6: Setting an Array Value​

Example 7: Setting with String-to-Number Conversion​

Example 8: Setting Multiple Values​

Example 9: Dynamic Value with ValuePath​

Example 10: Configuration-Based Values​

Example 11: Computed Value Copy​

Use Cases​

Error Handling​

Conversion Examples​

String to Numeric Conversion​

Boolean String Conversion​

Culture-Invariant Double Parsing​

Dynamic Value from JSONPath​

Notes​

Related Nodes​

Adapter Prerequisites

Node Configuration

Parameters

Required Parameters

Value Source Parameters

Supported Value Types

Unsupported Types

Value Sources

Value Source Priority

Value Conversion

Examples

Example 1: Setting a String Status

Example 2: Setting a Numeric Value

Example 3: Setting a Boolean Flag

Example 4: Setting a DateTime Timestamp

Example 5: Setting an Integer Counter

Example 6: Setting an Array Value

Example 7: Setting with String-to-Number Conversion

Example 8: Setting Multiple Values

Example 9: Dynamic Value with ValuePath

Example 10: Configuration-Based Values

Example 11: Computed Value Copy

Use Cases

Error Handling

Conversion Examples

String to Numeric Conversion

Boolean String Conversion

Culture-Invariant Double Parsing

Dynamic Value from JSONPath

Notes

Related Nodes