# Feature OP-9221 - Add new Custom Field Type: DateTime

Project: OpenProject
Status: tested
URL: https://community.openproject.org/work_packages/OP-9221

## Planning

| Attribute | Value |
| --- | --- |
| Date |  |
| Priority | Medium |
| Target versions | 18.0.0 |
| Sprint |  |
| Backlog bucket |  |
| Votes | 17 |
| List |  |
| Roadmap |  |
| Relevance |  |

## OPEN POINTS / FEEDBACK

_No work packages_

## Features and Chunks

_No work packages_

## Bugs and other work packages

| ID | Type | Subject | Status | Assignee | Target versions | Spent time | Module |
| --- | --- | --- | --- | --- | --- | --- | --- |
| OP-20521 | Bug | Adding a help text for DateTime CFs triggers an error | confirmed |  | 18.0.0 |  | Administration / Custom fields |

## Technical Details

| Attribute | Value |
| --- | --- |
| Module | Administration / Custom fields |
| Feature Flag |  |
| Requires doc change | No |
| Enterprise plan | Community (COM) |

## Details

| Attribute | Value |
| --- | --- |
| Pull preview |  |
| Mockups |  |
| Accessibility | No |

## People

| Attribute | Value |
| --- | --- |
| Assignee |  |
| Accountable |  |
| Product manager |  |
| Feature Lead |  |
| Developers | Klaus Zanders |
| Designer |  |
| Ordered by |  |
| Signed off by |  |
| Interest by |  |

## Estimates and progress

| Attribute | Value |
| --- | --- |
| PD (min) |  |
| PD (max) |  |
| Work |  |
| Labor costs |  |

## Description

**As** an administrator or project member working with work packages  
**I want to** record and filter a date _and time_ in a work package custom field  
**so that** I can track exact points in time (e.g. deadlines, appointments, deployment windows).

**Acceptance criteria**

*   Administrators can create a work package custom field with the new format **&quot;Date and time&quot;**. The format is only offered for work package custom fields.
    
*   The value is entered with a flatpickr date and time picker:
    
    *   It shows and accepts the value in the user&#x27;s time zone and in the user&#x27;s date/time format, with a 12- or 24-hour clock depending on that format.
        
    *   Typed input in the user&#x27;s format is accepted.
        
*   The picker is used everywhere the field can be edited: the work package form, the new work package dialog, inline edit in the table and details view, and bulk edit.
    
*   In inline edit, Enter saves and Escape cancels. Picking a value and closing the calendar saves it.
    
*   Values are shown in the user&#x27;s time zone and format in the table, the details view and the activity.
    
*   Work packages can be sorted by the field.
    
*   Filters for datetime custom fields and the built-in datetime attributes (e.g. &quot;Created on&quot;, &quot;Updated on&quot;) offer:
    
    *   **on**: a date picker; matches the whole day in the user&#x27;s time zone.
        
    *   **between**: two date and time pickers next to each other; matches the exact times entered. Either end can be left open.
        
    *   **&gt;=** (on or after) and **&lt;=** (on or before): one date and time picker.
        
    *   The existing relative day operators.
        
*   Filters for **date** fields (built-in and custom) also offer **&gt;=** and **&lt;=**, using the date picker.
    
*   The above applies both to the work package filters and to the Primer-based filters (e.g. the project list).
    
*   API v3:
    
    *   The custom field is exposed with type `DateTime` and ISO 8601 values.
        
    *   The filter schema reports `[1]Date`/`[1]DateTime` for `>d`/`<d`.
        
    *   The operators are documented in the API filter docs.
        

**Technical notes**

*   **Storage and casting:**
    
    *   Values are stored as ISO 8601 UTC strings (`YYYY-MM-DDTHH:MM:SSZ`), so sorting is a plain string sort.
        
    *   Filters cast the value to a timestamp in SQL (`CfDateTime#sql_for_field`).
        
*   **New operators:**
    
    *   `GreaterOrEqualDateTime` (`>d`) and `LessOrEqualDateTime` (`<d`).
        
    *   The existing date `>d`/`<d` operators that only existed in the reporting moduler are now enabled for all date filters.
        
    *   The datetime &quot;on&quot; filter keeps the API type `[1]DateTime`: its value is the start of the day in the user&#x27;s time zone. This is unchanged to stay backwards compatible.
        
*   **Time zone:**
    
    *   The user&#x27;s time zone is provided to the frontend via the `current_user` meta tag.
        
    *   The picker sends UTC ISO values. It displays its value in a separate visible input, while a hidden input carries the UTC value.
        
*   **Angular:**
    
    *   New `OpBasicSingleDatetimePickerComponent` (`opce-basic-single-datetime-picker`) and Primer form DSL input `single_datetime_picker`.
        
    *   The Angular filters use the datetime picker for `>d`/`<d` and &quot;between&quot;. &quot;On&quot; keeps the date picker.
        
*   **Primer filters:**
    
    *   Split into `BaseDateForm`, `DateForm` and `DateTimeForm`. Each defines a `VALUE_FIELDS` table mapping operators to input fields.
        
    *   The table is passed to the Stimulus filters controller via `data-value-fields`. The controller uses it to show the right input and read its value.
        
*   **Known limitation:** flatpickr&#x27;s range mode only supports one time for both ends of the range. Datetime &quot;between&quot; therefore uses two separate pickers.
    

**Permissions and visibility considerations**

*   _To whom is this feature visible?_
    
    *   Administrators can create &quot;Date and time&quot; custom fields.
        
    *   The field itself is visible and editable under the same rules as other work package custom fields
        
    *   The new filter operators are available to everyone who can use the work package table
        
*   _When is it not visible?_
    
    *   The format is not offered for custom fields of other resources (projects, users,etc.).
        
    *   The field is not shown where the work package custom field itself is not shown.
        

**Translation considerations**

*   Field format label: &quot;Date and time&quot; (DE: &quot;Datum und Zeit&quot;).
    
*   The operator labels reuse the existing &quot;&gt;=&quot; and &quot;&lt;=&quot; translations. No new keys.
    

**Out of scope**

*   &quot;Date and time&quot; custom fields for resources other than work packages.
    
*   A single range picker with two times for datetime &quot;between&quot; (not supported by flatpickr).
    
*   New operators for project phase and phase gate filters, which keep their own operator set.
    
*   Choosing a time zone per value. Values are always entered and displayed in the user&#x27;s time zone.
    

_Set the_ **To be informed/consulted teams** _field to include all teams necessary to be informed of the changes._
