Skip to Content
FeaturesTasksServer smart filtering

Task Filtering and Date Logic

Explains server-side smart filtering for tasks — how dueDate, scheduledDate, showInListFrom, and withOverdue interact to determine task visibility.

This document describes how tasks are filtered by date on the server (smart filtering) and the meaning of each date field.

Parameters for smart filtering

The main parameters for smart filtering are:

  • startDate and endDate: Define the date range for the filter (e.g. today, this week).
  • withOverdue (optional): When true, overdue scheduled tasks are included; when false, they are hidden.
  • includeUndated (optional): When true, pending tasks with neither dueDateTime nor scheduledDateTime are included in date-range smart filtering. Default false.
  • currentDateTime (optional, query: currentDateTime): Client “now” as dd/MM/yyyy HH:mm. When set, showInListFrom is compared to min(currentDateTime, endDate 23:59) so same-day tasks stay hidden until their visibility window starts (e.g. show from 18:00). When omitted, behavior uses end of endDate only (legacy).

Task date fields

dueDate (dueDateTime)

  • Represents the deadline of the task.
  • The task is pending until that date (and until it is marked done).

Filter rule: If a task has a dueDate and it is on or after startDate, the task should appear in the list, even if dueDate is after endDate. Pending tasks with a future deadline are shown for any range that starts before that deadline.

  • Show when: dueDate != null AND dueDate >= startDate

showInListFrom (formerly startDueDate)

  • Meaning: “Show this task in the list only from this date onwards.”
  • Used to avoid showing a task that has a future dueDate until we are within a chosen time window before the deadline (e.g. show only 3 days before due).

Filter rule: A task is shown in a range [startDate, endDate] only if:

  • showInListFrom is null, OR
  • The “show from” instant is on or before the visibility upper bound for the range:
    • If currentDateTime is sent: showInListFrom <= min(currentDateTime, endDate at 23:59).
    • If currentDateTime is omitted: showInListFrom <= endDate at 23:59 (end of last day in range).

So: do not show the task if showInListFrom is after that upper bound (e.g. later the same day when currentDateTime is morning).

scheduledDate (scheduledDateTime)

  • Represents a specific date (e.g. “do this on 15th March”).
  • The task should appear only on that date (in the UI / filters for that day).

Filter rule:

  1. On the exact date: If scheduledDate falls inside [startDate, endDate], the task is shown.
  2. Overdue scheduled task: If the task has a scheduledDate in the past and is not done, it is treated as overdue and should appear in all date filters (so the user can still see and complete it), unless “hide overdue” is enabled.
    • Show when:
      (scheduledDate in [startDate, endDate])
      OR
      (scheduledDate < today AND task not done AND withOverdue == true)

Algorithm

Task inclusion requires passing both the date-range check (dueDate or scheduledDate) and the visibility window check (showInListFrom).

Summary of server logic

For a date range [startDate, endDate] and withOverdue:

  1. Due-date tasks:
    Show if dueDate != null AND dueDate >= startDate (pending until deadline).

  2. showInListFrom:
    Show only if showInListFrom == null OR showInListFrom <= visibility upper bound (min(currentDateTime, endDate 23:59) when currentDateTime is provided, else endDate 23:59).

  3. Scheduled-date tasks:
    Show if:

    • scheduledDate is in [startDate, endDate], OR
    • scheduledDate < today AND task not done AND withOverdue == true.

  4. Undated (optional):
    When includeUndated == true, also include pending tasks with dueDateTime == null AND scheduledDateTime == null.

  5. Combined:
    A task is included in the result if it satisfies the rules for whichever of dueDate / scheduledDate / showInListFrom / undated apply (and respects withOverdue for overdue scheduled tasks).

No-due-date list (GET /tasks/noDueDate)

Tasks with dueDateTime == null (scheduled-only tasks may still appear). Completed tasks with doneDateTime older than 7 days are excluded so the list does not grow unbounded with ancient completions.

Rename: startDueDate → showInListFrom

The property was renamed from startDueDate to showInListFrom to reflect that it controls from when the task is shown in the list, not a “start” of the due period. The database column may remain start_due_date_time for compatibility, or be migrated to a name like show_in_list_from; the API and domain use showInListFrom.

OverviewProjects Feature Guide