DateTime@1

Node DateTime@1 performs date and time operations on pipeline data. It supports arithmetic (adding days, hours, minutes, seconds), comparison (days between dates), formatting, and extraction operations. All DateTime operations work with UTC dates.

Adapter Prerequisites

• General availability: All adapters support this node type.

Node Configuration

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

transformations:
- type: DateTime@1
  operation: AddDays                  # Date/time operation to perform
  path: $.startDate                   # Path to the source DateTime value
  targetPath: $.endDate               # Path where the result will be stored
  value: 7                            # Constant value to use in operation
  # OR use valuePath instead of value:
  # valuePath: $.daysOffset           # Path to value to use in operation

Parameters

Required Parameters

Parameter	Type	Description
operation	enum	Date/time operation to perform (see operations below)
targetPath	string	JSON path where the result will be stored

Optional Parameters

Parameter	Type	Default	Description
path	string	$	JSON path to the source DateTime value. Not required for Now operation
value	object	-	Constant value: a number for Add* operations, or a format string for Format
valuePath	string	-	JSON path to a dynamic value. Takes precedence over value when set

Operations

The node supports eleven date/time operations:

Arithmetic Operations

• Now: Returns the current UTC date and time. Ignores path, value, and valuePath.
• AddDays: Adds a specified number of days (fractional values allowed) to the source DateTime.
• AddHours: Adds a specified number of hours to the source DateTime.
• AddMinutes: Adds a specified number of minutes to the source DateTime.
• AddSeconds: Adds a specified number of seconds to the source DateTime.

Comparison Operations

• DaysBetween: Computes the whole number of days between two dates (date-only, ignoring time). The result is (valuePath date - source date) in whole days. Requires valuePath to specify the second date.

Extraction Operations

• StartOfDay: Truncates a DateTime value to midnight (00:00:00) of the same day.
• ExtractDate: Alias for StartOfDay. Truncates to midnight.
• ExtractTime: Extracts the time portion as a string in HH:mm:ss format.

Formatting Operations

• Format: Formats a DateTime using a .NET format string specified in value. Returns a string.

Combining Operations

• CombineDateTime: Takes the date part from the source (path) and the time part from another DateTime (valuePath), combining them into a single DateTime.

Value Sources

For AddDays, AddHours, AddMinutes, and AddSeconds, you can specify the operand in two ways:

1. Constant Value: Use the value parameter to specify a fixed numeric value
2. Dynamic Value: Use the valuePath parameter to reference a value from elsewhere in the data

If valuePath is provided, it takes precedence over value. Negative values are supported (e.g., -3 to subtract 3 days).

For DaysBetween and CombineDateTime, the second DateTime must be provided via valuePath.

For Format, the .NET format string must be provided via value (e.g., yyyy-MM-ddTHH:mm).

Error Handling

The node will:

• Throw an error if the data context is null
• Throw an error if no DateTime value is found at the specified path
• Throw an error if value or valuePath is required but not set
• Throw an error if an unsupported operation is specified

Examples

Example 1: Get Current Date at Midnight

Get the current UTC date truncated to midnight:

transformations:
- type: DateTime@1
  operation: Now
  targetPath: $.now
- type: DateTime@1
  operation: StartOfDay
  path: $.now
  targetPath: $.today

Output:

{
  "now": "2026-03-09T14:30:45Z",
  "today": "2026-03-09T00:00:00Z"
}

Example 2: Add Days with Constant Value

Schedule a follow-up date 7 days from a reference date:

transformations:
- type: DateTime@1
  operation: AddDays
  path: $.orderDate
  value: 7
  targetPath: $.followUpDate

Input:

{
  "orderDate": "2026-03-01T10:00:00Z"
}

Output:

{
  "orderDate": "2026-03-01T10:00:00Z",
  "followUpDate": "2026-03-08T10:00:00Z"
}

Example 3: Compute Days Between Two Dates

Calculate the number of days between a template reference date and today:

transformations:
- type: DateTime@1
  operation: DaysBetween
  path: $.templateDate
  valuePath: $.today
  targetPath: $.daysDiff

Input:

{
  "templateDate": "2025-01-01T06:00:00Z",
  "today": "2026-03-09T00:00:00Z"
}

Output:

{
  "templateDate": "2025-01-01T06:00:00Z",
  "today": "2026-03-09T00:00:00Z",
  "daysDiff": 432
}

Note: DaysBetween compares dates only (ignoring time). The result is (valuePath.Date - path.Date).TotalDays as a whole number.

Example 4: Format DateTime as String

Format a DateTime for display or naming:

transformations:
- type: DateTime@1
  operation: Format
  path: $.shiftStart
  value: "yyyy-MM-ddTHH:mm"
  targetPath: $.shiftStartFormatted

Input:

{
  "shiftStart": "2026-03-09T06:00:00Z"
}

Output:

{
  "shiftStart": "2026-03-09T06:00:00Z",
  "shiftStartFormatted": "2026-03-09T06:00"
}

Example 5: Combine Date and Time from Different Sources

Take the date from one DateTime and the time from another:

transformations:
- type: DateTime@1
  operation: CombineDateTime
  path: $.targetDay
  valuePath: $.shiftTime
  targetPath: $.shiftDateTime

Input:

{
  "targetDay": "2026-03-15T00:00:00Z",
  "shiftTime": "2025-01-01T14:30:00Z"
}

Output:

{
  "targetDay": "2026-03-15T00:00:00Z",
  "shiftTime": "2025-01-01T14:30:00Z",
  "shiftDateTime": "2026-03-15T14:30:00Z"
}

Example 6: Dynamic Day Offset with ValuePath

Add a variable number of days from elsewhere in the data:

transformations:
- type: DateTime@1
  operation: AddDays
  path: $.templateStart
  valuePath: $.daysToAdd
  targetPath: $.shiftStart

Input:

{
  "templateStart": "2025-01-01T06:00:00Z",
  "daysToAdd": 432
}

Output:

{
  "templateStart": "2025-01-01T06:00:00Z",
  "daysToAdd": 432,
  "shiftStart": "2026-03-09T06:00:00Z"
}

Example 7: Extract Time as String

Extract only the time portion from a DateTime:

transformations:
- type: DateTime@1
  operation: ExtractTime
  path: $.timestamp
  targetPath: $.timeOnly

Input:

{
  "timestamp": "2026-03-09T14:30:45Z"
}

Output:

{
  "timestamp": "2026-03-09T14:30:45Z",
  "timeOnly": "14:30:45"
}

Use Cases

• Shift Scheduling: Generate shift start/end times by offsetting template dates
• Date Arithmetic: Calculate deadlines, follow-up dates, or expiration dates
• Report Generation: Format dates for display in reports or notifications
• Data Import: Normalize date formats during ETL processing
• Time Series: Compute intervals between events or measurements
• Recurring Jobs: Calculate next execution dates for scheduled tasks

Notes

• UTC Only: All DateTime operations use UTC. Ensure input dates are in UTC format.
• Fractional Days: AddDays accepts fractional values (e.g., 0.5 for 12 hours).
• Negative Values: Add operations accept negative values to subtract time.
• DaysBetween Direction: The result is valuePath.Date - path.Date, so it's positive when the valuePath date is later.
• Format Strings: Uses standard .NET format strings with CultureInfo.InvariantCulture.

Related Nodes

• Math@1: Perform mathematical operations on numeric values
• FormatString@1: Create formatted strings using JSON path placeholders
• ConvertDataType@1: Convert between different data types