Persistence and dismissal
In the portal: Users, then a participant, to see and change one of their deliveries.
What it is
An item leaves the home screen for one of four reasons, and it is worth knowing which before you change anything.
Today is not one of its days. The schedule decides which days an item is due. On any other day it is simply not there.
The participant answered it, and it was not set to stay. This is the
persistent flag, and it is the one people ask about most.
The participant hid it. This is dismissal. The option is offered only when the delivery allows it.
The answer count has run out. A schedule can carry a lifetime count. Once that many answers exist, the item is finished for good.
Start here if somebody reports a card that will not go away. Check
persistent on the delivery first, then defaultPersistent on the sequence.
Almost every report of this shape is one of those two set to true. Check the
sequence even when the delivery looks right, because older sequences are the most
likely place to find it.
What it looks like
A daily check-in on a weekday schedule, over one week, for a participant who answers it on Monday and Tuesday and misses Wednesday.
| Day | On the home screen? | Why |
|---|---|---|
| Monday morning | yes | Monday is a scheduled day and no answer exists yet |
| Monday, after answering | no, if persistent is false | The slot is sealed and the item leaves |
| Monday, after answering | yes, with a tick, if persistent is true | The slot is sealed and the item stays as a record |
| Tuesday morning | yes | A new day is a new slot, and last night's answer says nothing about it |
| Wednesday night | yes, unanswered | Nothing removes an item for going unanswered during its own day |
| Thursday morning | yes | Wednesday's miss is recorded on Progress and changes nothing here |
| Saturday | no | Saturday is not a scheduled day |
When you would change one of these
You change persistent when you want a record on the screen rather than a
clean screen.
A worked example. A tenancy runs a course where the daily check-in should
disappear once answered, so the participant always knows what is left, but the
weekly reflection should stay ticked all week so they can see they did it. That
is persistent: false on the check-in and persistent: true on the reflection.
Nothing about the surface changes, and both can sit in the same one.
The controls
| Control | Where it lives | What it accepts | Default | What it does |
|---|---|---|---|---|
schedule | the delivery | once, weekly or custom | the sequence's defaultSchedule | Decides which days the item is due. No due day means no item. A list of weekdays applies to a weekly schedule, and to a custom schedule counted in weeks. On a custom schedule counted in days or hours the list is ignored. |
start | inside the schedule | instant, after, at | required, and always present | The item does not appear before this. Check this first when an item never appeared and the schedule looks right. A start of after three weeks means nothing shows for three weeks, and a start of at a date and time means nothing shows before it. Read the start before you look anywhere else. |
end | inside the schedule | never, after, at, responses | required, and always present | Where an item stops for good. The schedule's end is the only expiry, so check this when an item disappeared and nobody cancelled it. |
end.maxResponses | inside the schedule's end | a whole number | not set | A lifetime count. Once that many answers exist, the item never returns. |
persistent | the delivery | true or false | false | Whether an answered item stays with a tick, or leaves. |
dismissable | the delivery | true or false | false | Whether the participant is offered a way to hide it. |
status | the delivery | active, completed, cancelled, expired | active | Anything other than active removes the item from the home screen entirely, along with every future occurrence, whatever the schedule says. Setting it back to active brings the item back. Use an end on the schedule when you already know the date or the count that should retire an item, and use status when you need to stop one delivery now. |
Setting the schedule to nothing at all is not the same as leaving it out. Leaving the key out means "use whatever the sequence author set". Setting it explicitly to nothing means "this has no schedule", and that is honoured. An item with no schedule has a single occurrence that is due from its start to its end, so it stays on the screen until it is answered or dismissed.
How it renders
State is held per slot, not per delivery. Each due occurrence carries its own answer and its own dismissal. Answering Monday's check-in says nothing about Tuesday's, and hiding Monday's does not hide Tuesday's. A participant can clear one occurrence, and retiring a recurring item for good stays with you, on the schedule.
So an item that comes back the next day has not been un-finished. The participant finished one occurrence and a recurring schedule minted a new one. If it should only ever happen once, the fix is the schedule, either a single occurrence or a lifetime count, and never the persistence flag.
Being due is about the whole day, not the minute. A Tuesday item is due all
Tuesday, not at one moment on Tuesday. Times of day inside a schedule create
separate items to answer and drive the reminders, and every one of a due day's
items is answerable all day. They do not hide the item before the time arrives, so an
item scheduled at 20:00 is on the screen from the morning. On a custom schedule
with a period of hours they are ignored altogether, because that cadence builds its
own grid.
Times are wall clock, in the participant's own timezone. A schedule set to 09:00 is 09:00 wherever that person is. There is no offset stored anywhere and no conversion happens.
A dismissed item is hidden even when it is persistent. Dismissal wins.
Dismissing is not answering. The two are separate on purpose, so tidying a home screen never changes the record of how much of a programme somebody did. A dismissed occurrence still counts as unanswered on Progress.
Dismissal is a long press, on both phones. Holding the item opens a small
menu with one entry, Dismiss. Set dismissable to true on the items you are happy
for a participant to hide, and say how the gesture works in your onboarding content
if you want them to use it.
Nothing marks an item as missed while its day is still running. An occurrence is only counted as missed once its window has closed with no answer, and that happens on Progress rather than on the home screen.
Worked settings
A check-in that runs for six weeks and then stops. A weekly schedule on
weekdays, with end set to after six weeks. Nothing needs cancelling and
nobody has to remember. On the day after the last one, the item is simply not
due.
A questionnaire that is answered exactly three times, ever. Any schedule,
with end set to responses and maxResponses of 3. The third answer retires
it. This is the only control that counts answers rather than days.
A welcome message that stays on the screen. No schedule, persistent: true,
dismissable: true. It appears once, it stays with a tick after it is read, and
the participant can clear it themselves when they are done with it.
Next
An item goes away for one of four reasons. Work out which one before you change anything. A schedule that ends on a date or on a count retires an item by itself, so nothing has to be cancelled by hand and nobody has to remember.
Schedules and recurrence is the full
grammar of schedule, start and end.
What puts an item there is the other end: the three things that create a delivery in the first place.