Recurring Tasks

Repeating tasks

Some work comes back. A monthly backup check, a quarterly access review, a weekly report, the first-Monday-of-the-month patching window. Any task in FreeITSM can be given a repeat, and the next occurrence is created for you rather than left to somebody's memory.

The developer guide is Repeating tasks — Developer Guide.

Related: Tasks · Scheduled tasks (cron jobs) · Calendar

Requested by dschipfel in discussion #94.

---

🔴 A fixed schedule needs a scheduled job on the server, and nothing tells you if it is missing. Repeats set to on a fixed schedule are created by cron/task_recurrence.php. A fresh install has no scheduled tasks at all, so until somebody sets that job up, a fixed-schedule repeat produces nothing — no error, no log entry, just a repeat that quietly never happens. Run it once a day; the commands for Windows and Linux are on Scheduled tasks.

Repeats set to after this one is completed are unaffected. They are created inside the web request that completes the previous occurrence, so they work perfectly well on an installation with no scheduled tasks whatsoever.

---

1. Setting one up

Open a task, find Repeats in the panel, and click Set up a repeat. You can also right-click a card on the board and choose Set up a repeat without opening it at all.

A subtask cannot repeat on its own. A repeat belongs to the piece of work, not to a step inside it — otherwise you would get orphaned subtasks whose parent was never repeated.

---

2. Two ways to repeat

This is the first choice in the editor and the one worth thinking about, because the two behave differently the moment work runs late.

	After this one is completed	On a fixed schedule
Next occurrence appears	when you finish the current one	on its date, regardless
Its date is counted from	the day you actually finished	the pattern, fixed in advance
If you are a week late	everything shifts a week	you now have two to do
Two open at once	never	possible
Needs the cron job	no	yes
Right for	a monthly check, a routine chore	a compliance review, an audit, anything dated

After completion is what most people mean by "a monthly check". If February's is done on the 5th, March's falls a month after the 5th. Nothing is created while the current one is still open, so you never have two of the same job waiting.

A fixed schedule is what a compliance review needs. The March audit is due in March even if February's was never done. Missed occurrences accumulate rather than being quietly skipped, and if the server was off for a week the job catches up rather than losing them.

🔑 The question that settles it: if running late should push the next one back, choose after completion. If running late should leave you with two to do, choose a fixed schedule.

---

3. How often

A pattern is a frequency and an interval — every N days, weeks, months or years — plus, for weekly and monthly repeats, a choice of which days.

Frequency	What you can say
Daily	every day, or every N days
Weekly	every week or every N weeks, on any combination of weekdays
Monthly — by day number	the 1st, the 15th, the 28th, or the last day of the month
Monthly — by named weekday	the first Monday, the third Wednesday, the last Friday
Yearly	every year or every N years, optionally in a chosen month, with the same day-number or named-weekday choice

"Every second week on Monday and Thursday" is a single rule, not two.

Two edges worth knowing, because both are places a naive implementation drops a month:

• The last day of the month is entered as -1 in the day-number box. It is not the same as 31, and month-end work needs it: -1 gives you 28 February, 30 April and 31 January without three separate rules. A day number longer than a short month — the 31st in February — falls back to that month's last day rather than skipping the month.
• The fifth Monday of a month that only has four falls back to the last one. The month is never skipped.

---

4. When it stops

Ending	Behaviour
Never	keeps going until you stop it
On a date	the last occurrence is the final one falling on or before that date
After a number of occurrences	the count includes the task you set the repeat up on

⚠️ Five means five, including the one in front of you. Asking for five occurrences gives you this task plus four more, not five more. This is deliberate — it is what people mean by "do this five times" — but it is the number most likely to surprise you, so Preview shows the whole list.

---

5. What carries over

Each of these is chosen separately:

• Description
• Subtasks
• Assignee (and team)
• Tags
• Links to tickets, changes and contracts
• Attached documents

They are separate because the right answer differs by job. Carrying the attachments is right for a checklist that uses the same forms every month, and wrong for an audit that is supposed to gather fresh evidence each time.

Two things are not optional:

• A new occurrence always arrives open and unfinished, never in the status the previous one was closed into.
• It keeps the gap between the start date and the due date, so a fortnight of work stays a fortnight.

---

6. When the next one actually appears

An occurrence is created when work on it can start, not when it falls due.

• A task whose start date is a fortnight before its due date appears a fortnight ahead.
• A task with only a due date is a point-in-time job and appears on the day.

There is deliberately no "days of notice" setting. The lead time is the duration you have already given the task, which is a better answer than a number that would be wrong for half of them.

🔑 This is why the board only ever holds work you could actually be doing now. Set something to repeat weekly for a year and you do not get 52 cards on day one. Future occurrences of a fixed schedule are still visible on the calendar — drawn faintly, with no task behind them yet — so you can see the plan without the board filling up with jobs nobody can start.

---

7. Preview

"Every second Tuesday of the month, five times" is not a sentence most people can turn into dates in their head. Preview, beside Save, lists every occurrence the current settings would produce, with start and due dates.

• It works on unsaved settings, so you can try a rule before keeping it.
• The task you are on is shown as the first occurrence, because it counts towards the total.
• Anything that already exists is marked, so previewing an established repeat shows what it has done as well as what it will do.
• A repeat with no ending shows the first 25 and says so.
• If the settings produce nothing at all, it says so plainly — usually a sign that the ending, or the day you chose, is not what you meant.

A repeat set to fire after completion has no dates to list: its next date is counted from the day the work is actually finished, which has not happened. Preview explains that rather than guessing.

---

8. Finding your way around a series

A task belonging to a repeat carries a small repeat icon on the board and the calendar. In the panel it shows its position — occurrence 3 of 12 — and a link back to the task the series started from, so the original is one click away from any occurrence.

---

9. Stopping a repeat

Stop repeating ends the series and never deletes anything. Occurrences already created are real work, some of it done, so switching a repeat off means "no more of these" rather than "pretend the last six months did not happen".

Changing the settings and saving again replaces the rule for future occurrences and leaves existing ones alone.

---

10. If a repeat is not happening

In rough order of likelihood:

1. It is a fixed schedule and the cron job is not set up. By far the commonest cause, and it is silent. See the banner at the top and Scheduled tasks.
2. The next occurrence is not due to start yet. A task with no start date appears on its due date, not before. Use Preview to see when it is expected.
3. The series has ended. A count includes the first task, so "5" reaches its end sooner than you might expect. Preview shows whether anything is left.
4. The settings produce no further date at all. Preview says so explicitly.
5. It is set to repeat after completion and the current one is still open. Nothing will appear until it is finished — that is the mode working correctly.