HISTORY
HISTORY([field])
A field's value as of each update of the schedule, from the first saved update to today: a level over time, which holds each update's value from that update's data date until the next. HISTORY makes no unit conversion of its own, so a duration must say how it is counted: HISTORY(INDAYS([Remaining duration])), never HISTORY([Remaining duration]).
Arguments
| Argument | What to give it |
|---|---|
| [field] | A number, duration or date field of the row, in brackets: built-in, attribute or formula column. A duration wrapped in INDAYS or INHOURS. Or a field of the one row a relation reaches, such as Task[% complete] on an assignment. Text fields are refused. |
What each kind gives:
| Field | HISTORY gives |
|---|---|
| A number, or a duration counted in days or hours | A level over time. Read it with AT, MAX, MIN, AVERAGE or CHANGE. |
| A date | A date over time: the date as it was forecast at each update. Read it with AT, MAX or MIN. |
A blank in an update stays blank until a later update has a value; the earlier value isn't carried forward. Rows line up across updates by key: a task by its code, an assignment by its task's code and its resource. A row an update didn't have has no value there: an assignment added since is blank before the update that added it (AT there is blank, not its first value).
Examples
Formula=WORKDAYS(MIN(HISTORY([Finish date])), [Finish date])
How far the task's finish has slipped from the earliest finish it was ever forecast for.
Formula=MAX(HISTORY(INDAYS([Remaining duration])))
The most remaining work the task has had at any update, in days of its own calendar.
Formula=CHANGE(HISTORY([% complete]), [Actual start])
The progress made between each update and the one before, as an amount over time: the task's earned progress, period by period.
Formula on assignments=HISTORY(Task[% complete])
On an assignment: its task's progress as of each update.
Measure (on the project)=WORKDAYS(MIN(HISTORY([Finish date])), [Finish date])
As a measure: how far the project finish has moved from its best forecast.
Reach for something else when
| You want | Use |
|---|---|
| A field in one saved plan, not at every update | BASELINE or SCHEDULE with IN |
| What was added between updates, from a total to date | CHANGE of the history |
| Planned work over time, from dates rather than updates | SPREAD |
Common questions
Why must I say days or hours for a duration?
The engine won't guess the unit for you. The editor says: "HISTORY counts a duration in days or hours; say which: HISTORY(INDAYS([Remaining duration])) or HISTORY(INHOURS([Remaining duration]))".
The editor refuses this=HISTORY([Remaining duration])
Can I see how a text field changed, like a phase?
No: “HISTORY needs a number, a duration or a date, and [Phase] is Text”.
What is an update?
A data date. The last version saved with that data date stands for it. Each past update's values are worked out the way the baseline's are: from that version's own stored tasks, at its own data date.
Can I read the history of a formula column?
Yes: the column is worked out on each past update, from that update's own rows. But such a column can't itself read HISTORY or BASELINE() or make a what-if, and a column can't read its own history: "HISTORY can't read the column it is in".