Convert Date

Overview

Convert Date transforms dates between different formats and time representations. Use this stage to convert dates from various formats, including Unix timestamps, into the required output format. It can be used to convert between human-readable dates, ISO formats, Unix timestamps, and custom date formats within a flow.

* Example flow demonstrating how Convert Date transforms a player registration date into a different date and time format and uses the converted value in the next stage.

Note: The variable names, values, criteria, and configuration used in this example are for demonstration purposes only.

Where to find it: Actions > Transformers in the stage library.

Convert Date

Where to find it: Actions > Transformers in the stage library.

Configuration

Required Fields

Using functions in these fields: Any value field above accepts @ functions, for example @NowSecond for the current time or @calc(...) for a calculation. 

See Flows Functions for the full list.

Unix Timestamp Types

System Variables

Use these system variables in the Input Date field to work with current timestamps:

System Variable Example

Input Date: @NowSecond Input Format: UNIXSECOND Output Format: yyyy-MM-dd HH:mm:ss Result: Converts current time to readable format

Exit Points

Important: this stage has only a Pass exit, no Error exit. If the input value does not match the Input Format (a text date that does not fit the pattern, or a non-numeric value set to a Unix type), the conversion cannot happen and the whole flow run stops at this stage. It does not pass through, and there is no error path to catch it. Always check or set the input into a known format before this stage (use Route Flow to validate, or Set Default to supply a fallback) so a bad value never reaches it.

How It Works

When executed, the stage:

1. Parses input date - Reads date using specified input format (Unix or pattern)
2. Converts to internal representation - Creates date object with all components
3. Formats output - Applies output format to produce result string
4. Stores result - Saves formatted date to output variable

Key behavior: All operations use UTC timezone. Time components default to 00:00:00 if not specified in pattern.

Java SimpleDateFormat Patterns

Date2 uses Java SimpleDateFormat patterns for custom date parsing and formatting. Use these pattern symbols to build custom date formats:

Pattern Letter Count Rules

The number of pattern letters changes the output. Name-based fields (month M, weekday E) switch between the full name and the short name. Number-based fields use the letter count as the minimum number of digits (zero-padded).

Month name (September shown so the length difference is clear):

• MMMM → "September" (full name)
• MMM → "Sep" (short name)
• MM → "09" (two-digit number, zero-padded)
• M → "9" (number, no leading zero)

Zero-padding on numbers: a single letter gives no leading zero, a double letter pads to two digits.

• d → "9"  ·  dd → "09" (day)
• yyyy → "1996"  ·  yy → "96" (year)

Match the input format to how the date is actually written. A value like 9-9-2026 needs input format d-M-yyyy; a zero-padded value like 09-09-2026 matches dd-MM-yyyy. There is no optional-digit wildcard, so the input pattern and the real text have to line up.

CRITICAL: Calendar Year vs ISO Week-Based Year

THIS DISTINCTION IS CRITICAL AND COMMONLY MISUNDERSTOOD

Why It Matters

ISO week-based year rules cause year boundaries to differ from calendar years:

• 29 December 2025 (Monday) belongs to ISO Week 1 of 2026
• Using YYYY on this date produces "2026" (wrong for calendar year!)
• Using yyyy on this date produces "2025" (correct for calendar year)

Critical Rule

ALWAYS use yyyy (calendar year), NOT YYYY

Only use YYYY (ISO week-based year) together with w (week in year) for ISO week date formats like YYYY-'W'ww.

Valid vs Invalid Usage

Common Safe Pattern Combinations

Use these patterns for most date/time needs:

Common Use Cases

1. ISO to US Format

Convert webhook date from ISO to US format for display.

Configuration:

• Input Date: {{webhook.timestamp}}
• Input Format: yyyy-MM-dd
• Output Name: displayDate
• Output Format: MM/dd/yyyy

Result:

Input:  "2026-01-06" Output: {{displayDate}} = "01/06/2026"

2. Unix Seconds to Readable Date

Convert API response Unix timestamp to readable format.

Configuration:

• Input Date: {{apiResponse.createdAt}}
• Input Format: UNIXSECOND
• Output Name: createdDate
• Output Format: MMMM dd, yyyy HH:mm:ss

Result:

Input:  "1735948800" Output: {{createdDate}} = "January 06, 2026 00:00:00"

3. User Date to Unix Timestamp

Convert user-entered date to Unix timestamp for API storage.

Configuration:

• Input Date: {{userInput.date}}
• Input Format: MM/dd/yyyy
• Output Name: timestamp
• Output Format: UNIXSECOND

Result:

Input:  "01/06/2026" Output: {{timestamp}} = "1735948800"

Best Practices

• ✓ Use yyyy for calendar year (99% of use cases)
• ✓ Use system variables (@NowSecond, @Now, @UnixMillis) for current timestamp
• ✓ Match pattern to input - if input has time, include time in Format pattern
• ✓ Test patterns first to verify expected output
• ✓ Use UNIXSECOND for storage (timezone-independent, standard)
• ✓ Escape special characters with quotes: yyyy-MM-dd'T'HH:mm
• ✓ Remember Y/w relationship - if using Y (ISO week year), must also use w (week in year)

Common Mistakes

Troubleshooting

Do's and Don'ts

Do:

• ✓ Use yyyy for calendar year (unless explicitly implementing ISO week dates)
• ✓ Include time components in pattern when input data includes time
• ✓ Use UNIXSECOND for internal storage
• ✓ Test patterns before deploying
• ✓ Use system variables (@NowSecond, @Now, @UnixMillis) for current time

Don't:

• ✗ Use YYYY for calendar dates (causes wrong year on week boundaries)
• ✗ Mix calendar and week-based patterns (don't use YYYY-MM-dd)
• ✗ Mix MM/mm (remember: MM = month, mm = minutes)
• ✗ Assume timezone handling (all operations are UTC)
• ✗ Use Y without w (ISO week-based year must be paired with week number)

Limitations

• UTC Only: All Unix timestamp conversions assume UTC. No timezone-aware conversions.
• English Locale: Date parsing uses English locale only. Month names must be English.
• Limited Time Precision: Supports seconds, milliseconds, and minutes only - no microseconds.

Related Stages

• Set Default Value: Set timestamp before conversion
• Change Data: Manipulate date strings before conversion
• Route Flow: Conditional routing based on dates
• Increment Number: Add time duration to timestamps