> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Date Fields

> Display and edit date, datetime, and time values in Nextedy RISKSHEET columns with localized formatting, timezone-safe behavior, and formula integration.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Add a Date Column

Add a column with `type` set to `date` in your sheet configuration:

```yaml theme={null}
{
  "columns": [
    {
      "id": "dueDate",
      "header": "Due Date",
      bindings: "dueDate",
      "type": "date"
    }
  ]
}
```

Risksheet automatically converts values from the Polarion storage format to ISO `YYYY-MM-DD` strings for display and editing. Date columns parse values in local time to avoid timezone offset problems that can shift dates by one day.

## Date Column Types

Risksheet supports three temporal column types, each handling a different precision level:

| Type       | Stores        | Internal Format | Display Example     | Polarion Field Type              |
| ---------- | ------------- | --------------- | ------------------- | -------------------------------- |
| `date`     | Date only     | `YYYY-MM-DD`    | 2025-03-15          | DateOnly, Date, Calendar, String |
| `datetime` | Date and time | ISO datetime    | 2025-03-15T14:30:00 | Date, Calendar, String           |
| `time`     | Time only     | `HH:mm:ss`      | 14:30:00            | TimeOnly, String                 |

The type system supports automatic conversion between Polarion's internal storage formats and the display format. You can display any Polarion field as a date column regardless of its underlying storage type, as long as the field contains date-compatible values.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-Icoak49xQVOW38R/risksheet/diagrams/guides/columns/date-field-configuration/diagram-1.svg?fit=max&auto=format&n=-Icoak49xQVOW38R&q=85&s=49478a308f767128ed2b5d017e7ccc6a" alt="diagram" style={{ maxWidth: "680px", width: "100%" }} width="680" height="320" data-path="risksheet/diagrams/guides/columns/date-field-configuration/diagram-1.svg" />
</Frame>

## Customize the Display Format

Use the `format` property on the column definition to control how dates appear in the grid:

```yaml theme={null}
{
  "id": "dueDate",
  "header": "Due Date",
  bindings: "dueDate",
  "type": "date",
  "format": "dd/MM/yyyy"
}
```

Common format patterns:

| Pattern            | Output           | Description                        |
| ------------------ | ---------------- | ---------------------------------- |
| `yyyy-MM-dd`       | 2025-03-15       | ISO date (default for `date` type) |
| `dd/MM/yyyy`       | 15/03/2025       | European day-month-year format     |
| `MM/dd/yyyy`       | 03/15/2025       | US month-day-year format           |
| `dd MMM yyyy`      | 15 Mar 2025      | Short month name format            |
| `d MMMM yyyy`      | 15 March 2025    | Full month name format             |
| `yyyy-MM-dd HH:mm` | 2025-03-15 14:30 | Date with time (for `datetime`)    |
| `HH:mm:ss`         | 14:30:00         | Time only (for `time`)             |

The format string uses the locale-aware formatting library configured by the `global.culture` setting in sheet configuration:

```yaml theme={null}
global:
  culture: en
```

Changing `global.culture` affects month names, day names, number separators, and the default date format. For example, setting `"culture": "de"` displays month names in German ("Marz" instead of "March") and uses the appropriate locale conventions.

<Warning title="Format property and save errors in version 24.5.0">
  In version 24.5.0, adding a `format` property to date-only columns (`type: "date"`) caused save errors due to a timezone fix regression. If you encounter save failures when editing date fields:

  1. Remove the `format` property from the affected date column
  2. Enter dates in `YYYY-MM-DD` format directly in the cell (do not use the calendar popup)
  3. Update to a later version that includes the fix

  This issue does **not** affect `datetime` columns. If you must use a custom date format, test thoroughly after upgrading before re-adding the `format` property.
</Warning>

## Configure Date Fields on Upstream Columns

When displaying a date from an upstream linked work item, set both `type` and `readOnly` explicitly:

```yaml theme={null}
{
  "id": "reqDueDate",
  "header": "Req. Due Date",
  bindings: "linkedRequirement.dueDate",
  "type": "date",
  "readOnly": false,
  "level": 1
}
```

Setting `readOnly` to `false` enables editing of the upstream linked item's date field directly from the Risksheet grid, without needing to open the work item in the Polarion editor.

<Warning title="Case sensitivity of `readOnly`">
  The `readOnly` property **must** use an uppercase **O**: `"readOnly": false`. Writing `"readonly": false` (all lowercase) is silently ignored and the column remains read-only. This is the most common configuration mistake when making upstream columns editable. See [Enable Editing of Upstream Columns](/risksheet/guides/columns/edit-upstream-columns) for additional details.
</Warning>

<Tip title="Verifying Upstream Editability">
  After adding an upstream date column with `readOnly: false`, reload the risksheet and click the cell. If the date picker does not appear and the cell shows a read-only indicator, double-check the following:

  * The `readOnly` property uses the exact casing `readOnly` (capital O)
  * The `type` property is explicitly set to `"date"`
  * The current user has write permissions on the upstream work item
  * The grid is not in revision/comparison mode (which forces read-only)
</Tip>

## Use Date Fields in Formulas

Date values are accessible in formula expressions as `YYYY-MM-DD` strings. Because this format orders segments from most significant (year) to least significant (day), simple string comparison produces chronologically correct results:

```yaml theme={null}
formulas:
  isOverdue: 'function(info){ var due = info.item[''dueDate'']; if(!due) return '''';
    var today = new Date().toISOString().split(''T'')[0]; return due < today ? ''OVERDUE''
    : ''OK''; }'
  daysUntilDue: function(info){ var due = info.item['dueDate']; if(!due) return null;
    var dueDate = new Date(due + 'T00:00:00'); var today = new Date(); var diff =
    Math.ceil((dueDate - today) / (1000*60*60*24)); return diff; }
columns:
- id: overdueFlag
  header: Status
  formula: isOverdue
- id: countdown
  header: Days Left
  formula: daysUntilDue
  type: int
```

Formula columns that reference date fields are automatically read-only. The formula executes during cell rendering with the `{item}` context object providing access to all work item properties.

<Tip title="Date Comparison in Formulas">
  When comparing dates in formulas, always construct Date objects with an explicit time component (e.g., `new Date(due + 'T00:00:00')`) to avoid timezone-related off-by-one errors. String comparison (`due < today`) works for simple before/after checks but use Date arithmetic for calculating intervals.
</Tip>

## Use Conditional Formatting with Dates

Combine date formulas with cell decorators to visually highlight overdue or approaching deadlines:

```yaml theme={null}
cellDecorators:
  dueDateHighlight: function(info){ var due = info.item['dueDate']; if(!due) return;
    var today = new Date().toISOString().split('T')[0]; $(info.cell).toggleClass('overdue',
    due < today); $(info.cell).toggleClass('due-soon', due >= today && due <= new
    Date(Date.now() + 7*86400000).toISOString().split('T')[0]); }
```

Then reference the decorator in the column definition using the `cellRenderer` property. This applies CSS classes (`overdue`, `due-soon`) that you can style with custom CSS to show red or yellow backgrounds.

## System Date Fields

Certain system date fields are always read-only regardless of column configuration:

| Field           | Description                  | Auto Read-Only |
| --------------- | ---------------------------- | -------------- |
| `created`       | Work item creation timestamp | Yes            |
| `updated`       | Last modification timestamp  | Yes            |
| `id`            | Work item identifier         | Yes            |
| `status`        | Workflow status              | Yes            |
| `type`          | Work item type               | Yes            |
| `project`       | Project identifier           | Yes            |
| `outlineNumber` | Document outline number      | Yes            |
| `author`        | Work item creator            | Yes            |
| `resolution`    | Resolution value             | Yes            |

These fields cannot be edited through the Risksheet grid even with `readOnly: false`. Save attempts to protected fields are silently ignored by the server.

## Complete Example

Here is a full configuration snippet showing date columns with formatting, upstream binding, and a formula-driven overdue indicator:

```yaml theme={null}
{
  "global": {
    "culture": "en"
  },
  "formulas": {
    "isOverdue": "function(info){ var due = info.item['dueDate']; if(!due) return ''; var today = new Date().toISOString().split('T')[0]; return due < today ? 'OVERDUE' : 'OK'; }"
  },
  "columns": [
    {
      "id": "dueDate",
      "header": "Due Date",
      bindings: "dueDate",
      "type": "date",
      "format": "dd MMM yyyy",
      "level": 1
    },
    {
      "id": "completedDate",
      "header": "Completed",
      bindings: "completedDate",
      "type": "date",
      "level": 1
    },
    {
      "id": "reqDueDate",
      "header": "Req. Due Date",
      bindings: "linkedRequirement.dueDate",
      "type": "date",
      "readOnly": false,
      "format": "dd/MM/yyyy",
      "level": 1
    },
    {
      "id": "overdueFlag",
      "header": "Overdue?",
      "formula": "isOverdue",
      "level": 1
    },
    {
      "id": "createdDate",
      "header": "Created",
      bindings: "created",
      "type": "datetime",
      "format": "yyyy-MM-dd HH:mm",
      "readOnly": true,
      "level": 1
    }
  ]
}
```

## Troubleshooting

**Date displays in wrong format** -- Verify the `format` property uses the correct pattern syntax (case-sensitive: `MM` for month, `mm` for minutes). Check that `global.culture` matches your expected locale.

**Date field shows wrong date (off by one day)** -- This occurs due to timezone conversion when using `datetime` type for date-only fields. Set the column `type` to `date` (not `datetime`) for date-only values. The `date` type parses values in local time specifically to prevent this problem.

**Upstream date column is not editable** -- Check that `readOnly` uses uppercase O (`readOnly`, not `readonly`). Verify the `type` property is explicitly set to `"date"`. Confirm the user has write permissions on the upstream work item and the grid is not viewing a historical revision.

**Save error when editing date column (v24.5.0)** -- Remove the `format` property from date-only columns as a workaround. Enter dates in `YYYY-MM-DD` format directly in the cell. Upgrade to a version newer than 24.5.0 for the permanent fix.

**Duration fields not displaying correctly** -- Duration columns use Polarion's DurationTime format. If you see raw numeric values instead of formatted durations, check that the column `type` is set to `duration` and the underlying Polarion field is a DurationTime type.

## Verify

After configuring a date column, reload the risksheet page. You should now see the date field displayed in your chosen format. Click the cell to confirm that the date picker appears and editing works correctly. For upstream columns, verify that changes save without error by entering a date and pressing `Ctrl+S`.

## See Also

* [Add a Basic Column](/risksheet/guides/columns/add-basic-column) -- column type configuration basics
* [Enable Editing of Upstream Columns](/risksheet/guides/columns/edit-upstream-columns) -- making upstream columns editable
* [Configure Column Sorting](/risksheet/guides/columns/sorting) -- sorting by date columns
* [Configure Calculated Columns](/risksheet/guides/columns/calculated-columns) -- formulas using date values
* [Apply Conditional Formatting](/risksheet/guides/styling/conditional-formatting) -- highlighting overdue dates
* [Render Custom Data](/risksheet/guides/columns/custom-data-rendering) -- custom cell rendering for date-derived displays

<LastReviewed date="2026-06-24" />