[Canonical page](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-update/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# TaskUpdate

A partial edit of one existing task, matched by `id`. Goes in `tasks.update` of a [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-changes.md>) object. Every field except `id` is optional: a field left out keeps its stored value.

## Fields

The fields have the same meaning as in [`TaskData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-data.md>). Each field has three states:

- left out (or `undefined`): the stored value stays
- `null`: clears an optional field, or restores the default of a field that has one
- a value: replaces the stored value

| Field | Type | Default | Description |
|---|---|---|---|
| `id` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) | required | Id of the task to edit. |
| `parent` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) `\| null` | unchanged | New parent task. A value equal to `config.root_id`, or `""`, means no parent. |
| `start_date` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) `\| null` | unchanged | New start. |
| `end_date` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) `\| null` | unchanged | New end. |
| `duration` | `number \| null` | unchanged | New duration, in working time, in the task's `duration_unit`. |
| `constraint_type` | [`ConstraintType`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#constrainttype>) `\| "" \| null` | unchanged | New constraint. `""` and `null` both clear it. |
| `constraint_date` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) `\| null` | unchanged | Date of the constraint. |
| `auto_scheduling` | `boolean \| null` | unchanged | Whether the planner moves the task. |
| `unscheduled` | `boolean \| null` | unchanged | Marks the task as unscheduled. |
| `progress` | `number \| null` | unchanged | Completion of the task. |
| `calendar_id` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) `\| null` | unchanged | Calendar of the task. |
| `priority` | `number \| null` | unchanged | Leveling priority. |
| `leveling_delay` | `number \| null` | unchanged | Leveling delay, in elapsed time in the task's `duration_unit`. With no date in the same update, the stored start moves by the difference, snapped onto the working calendar. |
| `pauses` | [`Pause`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#pause>)`[] \| null` | unchanged | Replaces the whole list; `null` clears it. With no date in the same update, start and duration stay and the end is recomputed. |

`type` and `duration_unit` can't be changed through an update.

An update without dates, `pauses` or `leveling_delay` keeps the task's stored start and duration. Fields not listed above are ignored. An entry of [`ScheduleResult.updates`](<https://docs.dhtmlx.com/planning-engine/js/api/types/schedule-result.md>) is therefore a valid `TaskUpdate`: its `kind` and `reason` are ignored. To clear leveling on a task, set `pauses: []` and `leveling_delay: 0`.

## Used by

- [`Project#apply`](<https://docs.dhtmlx.com/planning-engine/js/api/project-apply.md>): `changes.tasks.update` edits the accepted state
- [`Project#preview`](<https://docs.dhtmlx.com/planning-engine/js/api/project-preview.md>): `changes.tasks.update` edits a copy of the baseline
- [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/js/api/project-evaluate.md>): each candidate's `changes.tasks.update`
- [`Project#suggestAssignments`](<https://docs.dhtmlx.com/planning-engine/js/api/project-suggest-assignments.md>): with `clearFirst: true`, the cleared delays and pauses come back in `changes.tasks.update`

## Example

```js
const changes = {
  tasks: {
    update: [
      { id: 2, start_date: "2026-03-09 08:00" },
      { id: 3, duration: 4, constraint_type: "" },
      { id: 5, pauses: [], leveling_delay: 0 },
    ],
  },
};
```

## Related

- [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-changes.md>) - the change set that holds updates
- [`TaskData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-data.md>) - the meaning of each field
- [`Project#apply`](<https://docs.dhtmlx.com/planning-engine/js/api/project-apply.md>) - committing an update
- [Editing a project](<https://docs.dhtmlx.com/planning-engine/js/live-projects/editing-a-project.md#update-records>) - omitted vs `null` in update records
- [Clear leveling](<https://docs.dhtmlx.com/planning-engine/js/how-to/clear-leveling.md>) - resetting `pauses` and `leveling_delay`