Date & Time

1. Overview

The Date & Time tool is a core GoInsight utility designed for robust date and time manipulation within your workflows. It provides a comprehensive set of operations to parse, format, calculate, and convert temporal data without needing external services.

With the GoInsight Date & Time node, you can seamlessly integrate time-based logic into your automations. This allows you to perform a wide range of tasks, including:

• Calculations: Add or subtract durations from a date, and calculate the precise difference between two distinct points in time.
• Conversions: Effortlessly convert dates between different timezones or switch between human-readable date strings and Unix timestamps.
• Formatting: Customize the string representation of a date to match any required format, from ISO 8601 to user-defined patterns.
• Extraction: Deconstruct a date into its individual components, such as the year, month, day, or day of the week.

2. Prerequisites

This is a built-in GoInsight tool. It is available in all workflows and does not require any special accounts or setup.

3. Credentials

This is a built-in GoInsight tool and does not require any credentials to be configured.

4. Supported Operations

This section details the operations available within the Date & Time node, categorized by their primary function.

Summary

The node's operations are centered around date calculation, conversion, and formatting. The table below provides a quick overview of the available actions.

Operation Details

Adjust Date

Adjusts the input date by a specified duration (positive to add, negative to subtract) using the specified time unit and returns the result formatted by a user-provided common format string (e.g., 'YYYY-MM-DD HH:mm:ss') or ISO 8601 by default.

Input Parameters:

• DateTime: The input date-time string, supports ISO 8601 and common formats, may include timezone.
• Duration: Amount to adjust in the specified unit. Positive for addition, negative for subtraction. Must be an integer.

Options:

• Units: Time unit for adjustment. Must be one of 'Year', 'Quarters', 'Month', 'Week', 'Day', 'Hour', 'Minute', 'Second'.
• OutputFormat: Optional common format string or strftime-compatible pattern. Supports tokens YYYY, MM, DD, HH, hh, mm, ss, MMM, MMMM, DDD, etc. If omitted or empty, returns ISO 8601.

Output:

• NewDateTime (string): Resulting date-time string.
• Success (bool): Indicates whether the adjustment succeeded.
• ErrorMessage (string): Error message if adjustment failed; otherwise empty.

Time Difference

Calculates the time difference between two input date-time strings in the specified unit.

Input Parameters:

• StartDateTime: The start date-time string, supports ISO 8601 and common formats.
• EndDateTime: The end date-time string, supports ISO 8601 and common formats.

Options:

• Units: Unit for the difference calculation. Must be one of 'Year', 'Month', 'Week', 'Day', 'Hour', 'Minute', 'Second'.

Output:

• TimeDifference (number): The time difference between ’StartDateTime‘ and ’EndDateTime‘ in the specified unit.
• Success (bool): Indicates whether the calculation was successful.
• ErrorMessage (string): Error message if calculation failed; otherwise empty.

Convert Timezone

Converts a time string from its original timezone to a specified target timezone offset.

Input Parameters:

• DateTime: Input time string in various formats, can include timezone info. If no timezone provided, treated as UTC.
• TargetTimezone: Target timezone offset in hours, format "+8", "-5", or "+5.5".

Output:

• ConvertedTime (string): Converted time string in target timezone offset. If input only contains date, returns only date.
• Date (string): Converted date portion (YYYY-MM-DD).
• Time (string): Converted time portion (HH:MM:SS), empty if input only contains date.
• Success (bool): Indicates whether the conversion succeeded.
• ErrorMessage (string): Error message if conversion fails; empty string if successful.

Convert from Timestamp

Converts a millisecond-level Unix timestamp into a formatted date string according to a specified output format or ISO 8601 if none is provided.

Input Parameters:

• Timestamp: Millisecond-level Unix timestamp.

Options:

• OutputFormat: Optional common format string or strftime-compatible pattern. Supports tokens YYYY, MM, DD, HH, hh, mm, ss, MMM, MMMM, DDD, etc. If omitted or empty, returns ISO 8601.

Output:

• Timestamp (string): Resulting date-time string formatted per 'OutputFormat' or ISO 8601 by default.
• Success (bool): Indicates whether the conversion succeeded.
• ErrorMessage (string): Error message if conversion failed; otherwise empty.

Convert to Timestamp

Converts an input date string into a millisecond-level Unix timestamp.

Input Parameters:

• DateTime: The input date-time string, supports ISO 8601 and common formats, may include timezone. If no timezone is provided, UTC is assumed.

Output:

• Timestamp (number): Unix timestamp in milliseconds.
• Success (bool): Indicates whether the conversion succeeded.
• ErrorMessage (string): Error message if conversion failed; otherwise empty.

Extract Date Units

Extract date units (year, month, day, hour, minute, second, day of week, month name) from a date.

Input Parameters:

• DateTime: Input time string in various formats, which may include timezone info.

Output:

• Year (string): Year component.
• Month (string): Month component (1-12).
• Day (string): Day of month (1-31).
• Hour (string): Hour of day (0-23).
• Minute (string): Minute component (0-59).
• Second (string): Second component (0-59).
• DayOfWeek (string): Full English name of the weekday.
• MonthName (string): Full English name of the month.
• Success (bool): Indicates whether the conversion succeeded.
• ErrorMessage (string): Error message if conversion fails; empty string if successful.

Format Date

Formats an input date string into a specified output format.

Input Parameters:

• DateTime: The input date-time string, supports ISO 8601 and common formats, may include timezone. If no timezone is provided, UTC is assumed.

Options:

• OutputFormat: Optional common format string or strftime-compatible pattern. Supports tokens YYYY, MM, DD, HH, hh, mm, ss, MMM, MMMM, DDD, etc. If omitted or empty, returns ISO 8601.

Output:

• NewDateTime (string): Resulting date-time string.
• Success (bool): Indicates whether the formatting succeeded.
• ErrorMessage (string): Error message if formatting failed; otherwise empty.

5. Example Usage

This section will guide you through creating a simple workflow to calculate a future date, specifically determining the date 15 days from now.

The workflow will consist of: Start -> Adjust Date -> Answer.

1. Add the Tool Node

• In the workflow canvas, click the + button to add a new node.
• Select the "Tools" tab in the pop-up panel.
• Find and select "Date & Time" from the list of tools.
• From the list of supported operations for Date & Time, click on "Adjust Date". This will add the node to your canvas.

2. Configure the Node

• Click on the newly added "Adjust Date" node to open its configuration panel on the right.
• Credentials: This node does not require any credentials.
• Parameters: Fill in the input fields as follows:
  • DateTime: To use the current time as the starting point, enter the system variable {{$timestamp.now}}. This variable dynamically provides the current date and time whenever the workflow runs.
  • Duration: Enter 15. This specifies that we want to add 15 units of time.
  • Units (Options): Select Day from the dropdown list. This sets the unit for our duration.
  • OutputFormat (Options): To get a clean date format, enter YYYY-MM-DD. This will format the output as, for example, 2023-10-27.

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
• Click the "Run" button in the top-right corner of the canvas to execute the workflow.
• After a successful run, you can click the log icon (also in the top-right) to view the detailed input and output of the "Adjust Date" node, verifying that the new date is correctly calculated.

After completing these steps, your workflow is fully configured. When executed, it will take the current date, add 15 days, and output the result in a clean, readable format.

6. FAQs

Q: Why is my date string not being parsed correctly?

A: The tool works best with standard and unambiguous formats. Please ensure your input date string adheres to one of the following:

• ISO 8601: This is the most reliable format (e.g., 2023-10-26T10:00:00Z).
• Common Formats: Formats like YYYY-MM-DD HH:mm:ss are generally supported. Avoid ambiguous formats like MM/DD/YYYY vs. DD/MM/YYYY where possible.

Q: How do I handle timezones correctly?

A: If your input date string does not include timezone information (e.g., Z for UTC or an offset like +08:00), the tool will typically assume the time is in UTC. To work explicitly with timezones, use the Convert Timezone operation to shift your date to the desired offset before performing other calculations.

Q: What are some common tokens I can use in the OutputFormat parameter?

A: The formatting is highly flexible. Here are some of the most common tokens:

• YYYY: Four-digit year (e.g., 2023)
• MM: Two-digit month (e.g., 09)
• DD: Two-digit day (e.g., 05)
• HH: 24-hour format hour (e.g., 14)
• mm: Two-digit minute (e.g., 30)
• ss: Two-digit second (e.g., 05)
• MMMM: Full month name (e.g., September)
• EEE: Short day of the week name (e.g., Mon)

7. Official Documentation

As a core GoInsight utility, all relevant information is contained within this guide. For more general workflow concepts and information on using system variables, please visit the GoInsight Documentation Hub.