Skip to content

Date Calculation

This service task performs date and time calculations directly within a BPMN process. It supports adding or subtracting durations, computing differences between dates, formatting, and determining the start or end of a time unit — from milliseconds to years.

Benefit: Date logic can be handled natively in the process without external scripts or manual computation.

Operations

Operation Description
add Add or subtract a duration to/from a date.
difference Calculate the difference between two dates in a given unit.
format Format a date into a specific pattern or locale.
now Return the current date/time.
startOf Return the start of a given unit (e.g. start of month).
endOf Return the end of a given unit (e.g. end of year).

Input Parameters

Common Parameters

Parameter Type Required Description
operation String Yes One of: add, difference, format, now, startOf, endOf.

Operation: add

Parameter Type Required Description
date String / Number Yes ISO date string or Unix timestamp (ms).
amount Number Yes Number of units to add. Negative values subtract.
unit String Yes millisecond, second, minute, hour, day, week, month, year.

Operation: difference

Parameter Type Required Description
dateFrom String / Number Yes Start date (ISO string or timestamp).
dateTo String / Number Yes End date (ISO string or timestamp).
unit String No Unit for the result. Default: day.

Operation: format

Parameter Type Required Description
date String / Number Yes Date to format.
pattern String No Token pattern, e.g. YYYY-MM-DD HH:mm:ss. Default: YYYY-MM-DD.
timezone String No Timezone. Default: UTC.
locale String No Locale code (e.g. de-DE, en-US) for Intl-based formatting.

Operation: now

No additional parameters required.

Operations: startOf / endOf

Parameter Type Required Description
date String / Number Yes Reference date.
unit String No Time unit. Default: day.

Example: Add 30 Days

Input:

{
  "operation": "add",
  "date": "2026-02-14T00:00:00Z",
  "amount": 30,
  "unit": "day"
}

Output:

{
  "result": "2026-03-16T00:00:00.000Z",
  "timestamp": 1773878400000
}

Example: Difference Between Two Dates

Input:

{
  "operation": "difference",
  "dateFrom": "2026-01-01T00:00:00Z",
  "dateTo": "2026-12-31T23:59:59Z",
  "unit": "month"
}

Output:

{
  "difference": 11,
  "differenceExact": 11,
  "differenceMs": 31535999000
}

Example: Format a Date

Input:

{
  "operation": "format",
  "date": "2026-02-14T08:30:00Z",
  "pattern": "DD.MM.YYYY HH:mm",
  "locale": "de-DE"
}

Output:

{
  "formatted": "14.02.2026, 08:30",
  "iso": "2026-02-14T08:30:00.000Z",
  "timestamp": 1771057800000
}

Supported Units

millisecond · second · minute · hour · day · week · month · year

Use Cases

  • Calculate deadlines: Add business days or weeks to a creation date.
  • Determine overdue items: Compute the difference between now and a due date.
  • Generate formatted dates for documents, emails, or reports.
  • ISO week boundaries: Find the start and end of the current week or month.
  • Age or duration calculations: Compute years between two dates.