Skip to main content

Time Span

Calculates the time difference between two date/time values and returns the result in milliseconds. This node is essential for measuring durations, calculating elapsed time, and time-based analytics in automation workflows.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Start Date - The starting date/time value. Must be formatted according to the Layout option.
  • End Date - The ending date/time value. Must be formatted according to the Layout option.

Output​

  • Time Span (ms) - The time difference in milliseconds. Positive if End Date is after Start Date, negative if End Date is before Start Date.

Options​

  • Layout - The date/time format of both input times. Options include:
    • ANSIC - Mon Jan 2 15:04:05 2006
    • UnixDate - Mon Jan 2 15:04:05 MST 2006
    • RubyDate - Mon Jan 02 15:04:05 -0700 2006
    • RFC822 - 02 Jan 06 15:04 MST
    • RFC822Z - 02 Jan 06 15:04 -0700
    • RFC850 - Monday, 02-Jan-06 15:04:05 MST
    • RFC1123 - Mon, 02 Jan 2006 15:04:05 MST
    • RFC1123Z - Mon, 02 Jan 2006 15:04:05 -0700
    • RFC3339 - 2006-01-02T15:04:05-07:00 (default, ISO 8601)
    • RFC3339Nano - 2006-01-02T15:04:05.000000000-07:00
    • Custom - Define a custom format

How It Works​

The Time Span node calculates the duration between two date/time values by:

  1. Parsing the Start Date according to the specified Layout
  2. Parsing the End Date according to the specified Layout
  3. Calculating the difference (End Date - Start Date)
  4. Converting the difference to milliseconds
  5. Outputting the result as a number

Important: The result is End Date - Start Date:

  • Positive value: End Date is after Start Date
  • Negative value: End Date is before Start Date
  • Zero: Both dates are the same

Use Cases​

Performance Monitoring

  • Measure execution time of automation tasks
  • Track response times from APIs
  • Monitor processing durations

Deadline Management

  • Calculate time remaining until deadlines
  • Check if tasks are overdue
  • Determine urgency of pending items

Time Tracking

  • Calculate work session durations
  • Track time spent on activities
  • Measure billable hours

Analytics and Reporting

  • Calculate average processing times
  • Measure time between events
  • Generate time-based statistics

Age Calculations

  • Determine age of records
  • Check data freshness
  • Identify stale items

Examples​

Example 1: Calculate Duration (1 hour)

Start Date: 2024-03-15T10:00:00Z
End Date: 2024-03-15T11:00:00Z
Layout: RFC3339
Output: 3600000 (ms)

Conversion: 1 hour = 60 minutes = 3,600 seconds = 3,600,000 milliseconds

Example 2: Calculate Duration (30 minutes)

Start Date: 2024-03-15T10:00:00Z
End Date: 2024-03-15T10:30:00Z
Layout: RFC3339
Output: 1800000 (ms)

Conversion: 30 minutes = 1,800 seconds = 1,800,000 milliseconds

Example 3: Negative Duration (End Before Start)

Start Date: 2024-03-15T14:00:00Z
End Date: 2024-03-15T10:00:00Z
Layout: RFC3339
Output: -14400000 (ms)

Conversion: -4 hours = -14,400,000 milliseconds

Example 4: Calculate Days (7 days)

Start Date: 2024-03-15T00:00:00Z
End Date: 2024-03-22T00:00:00Z
Layout: RFC3339
Output: 604800000 (ms)

Conversion: 7 days × 24 hours × 60 minutes × 60 seconds × 1000 ms = 604,800,000 milliseconds

Example 5: Precise Timing with Nanoseconds

Start Date: 2024-03-15T10:00:00.000000000Z
End Date: 2024-03-15T10:00:00.500000000Z
Layout: RFC3339Nano
Output: 500 (ms)

Conversion: 500 milliseconds

Example 6: Cross-Day Duration

Start Date: 2024-03-15T23:00:00Z
End Date: 2024-03-16T02:00:00Z
Layout: RFC3339
Output: 10800000 (ms)

Conversion: 3 hours = 10,800,000 milliseconds

Converting Milliseconds​

To convert the millisecond output to other units:

UnitFormulaExample (3,600,000 ms)
Secondsms ÷ 1,0003,600 seconds
Minutesms ÷ 60,00060 minutes
Hoursms ÷ 3,600,0001 hour
Daysms ÷ 86,400,0000.0417 days

You can use the Calculator node or JavaScript to perform these conversions:

// Convert milliseconds to hours
var milliseconds = msg.span; // Output from Time Span node
var hours = milliseconds / 3600000;
msg.hours = hours;

Workflow Example​

Measure Automation Task Duration

  1. Use Now node to capture start time → save to msg.startTime
  2. Execute automation tasks
  3. Use Now node again to capture end time → save to msg.endTime
  4. Use Time Span node:
    • Start Date: msg.startTime
    • End Date: msg.endTime
  5. Log duration: Task completed in {{span}}ms

Check if Deadline is Approaching

  1. Get current time using Now node → msg.currentTime
  2. Get deadline from database → msg.deadline
  3. Use Time Span node:
    • Start Date: msg.currentTime
    • End Date: msg.deadline
  4. Check if result < 86400000 (1 day in ms)
  5. If true, send reminder notification

Calculate Age of Record

  1. Get record creation timestamp → msg.createdAt
  2. Get current time using Now node → msg.now
  3. Use Time Span node:
    • Start Date: msg.createdAt
    • End Date: msg.now
  4. Convert milliseconds to days: msg.span ÷ 86,400,000
  5. Check if age exceeds threshold

Tips for Effective Use​

  • Consistent Formats - Both Start Date and End Date must use the same Layout
  • Mind the Order - Remember: Result = End Date - Start Date
  • Negative Values - Use negative values to identify past-due items or reversed time sequences
  • Precision - Use RFC3339Nano for sub-second precision measurements
  • Timezone Awareness - Ensure both times are in the same timezone or use UTC to avoid confusion
  • Convert Units - Use Calculator node to convert milliseconds to more readable units
  • Large Durations - Be aware that JavaScript's number precision may affect very large duration values
  • Zero Checks - Test for zero to detect identical timestamps

Common Errors and Solutions​

Error: "failed to parse start date"

  • Cause: Start Date format doesn't match the Layout specification
  • Solution: Ensure Start Date is formatted according to the selected Layout

Error: "failed to parse end date"

  • Cause: End Date format doesn't match the Layout specification
  • Solution: Ensure End Date is formatted according to the selected Layout

Error: "start_time is required"

  • Cause: No value provided for Start Date input
  • Solution: Provide a valid date/time string in the Start Date field

Error: "end_time is required"

  • Cause: No value provided for End Date input
  • Solution: Provide a valid date/time string in the End Date field

Unexpected negative result

  • Cause: End Date is before Start Date (this may be intentional)
  • Solution: Verify the order is correct; swap dates if needed, or use absolute value if only magnitude matters

Incorrect duration calculation

  • Cause: Start and End dates are in different timezones
  • Solution: Convert both dates to the same timezone (preferably UTC) before calculating the span

Important Notes​

  • The calculation is precise to the millisecond level
  • The result accounts for all date/time components (years, months, days, hours, minutes, seconds, milliseconds)
  • Leap years and varying month lengths are automatically handled correctly
  • Timezone information in the dates is respected in the calculation
  • For very long durations (years), consider potential precision limitations with large numbers
  • The maximum safe integer in JavaScript is 2^53 - 1; very large time spans may lose precision

Practical Examples with Conversions​

Example: Measure API Response Time

Start: 2024-03-15T10:00:00.000Z
End: 2024-03-15T10:00:00.234Z
Output: 234ms (API responded in 234 milliseconds)

Example: Calculate Working Hours

Start: 2024-03-15T09:00:00Z (Clock in)
End: 2024-03-15T17:30:00Z (Clock out)
Output: 30600000ms = 8.5 hours

Example: Check Payment Overdue

Start: 2024-03-15T00:00:00Z (Due date)
End: 2024-03-20T00:00:00Z (Current date)
Output: 432000000ms = 5 days overdue
  • Now - Get current time for span calculations
  • Add Time - Add duration to a date instead of calculating it
  • Split Date - Extract components from dates for comparison
  • Format Time - Ensure dates are in the correct format for calculation