Cohorts
In the portal: Settings, then Cohorts.
What it is
A cohort is a named group inside a tenancy. It carries three things of its own: a sign-up link, a picture, and a set of starting journeys that everybody joining through that link is put on.
Everything else it shares with the tenancy around it. The same colours, the same tabs, the same content library, the same administrators, the same coaches. A cohort is a way of splitting who gets what, not a way of splitting the product.
It is also the answer to the question people ask first, which is how a brand new participant ends up with anything on their home screen at all. Nothing on the home screen is placed by hand. A journey creates the deliveries, and the cohort is what puts the journey on the person.
When you would use one
A network runs one tenancy and gives each employer on it a cohort. Each employer gets its own link to hand its own staff, its own starting programme, and its own name on the sign-up page. The network keeps one content library, one set of colours and one team of administrators.
That shape is the normal one. A tenancy each, for everybody, is not. The full comparison is on Standing up a tenancy.
Creating one
- Click Cohorts in the left sidebar.
- Click Create, at the top right of the list.
- Click Upload in the picture box at the top of the form, and choose a file.
- Type the cohort's name in Name.
- Read the grey code now showing at the right hand end of the Name field.
- Type a sentence in Description.
- Choose the journeys everybody should start on in Default journeys.
- Type a sign-up code in Sign-up code.
- Click Save.
Steps 3, 6, 7 and 8 are all optional, and a cohort with none of them is a perfectly good way of grouping people you will assign content to some other way.
Step 5 is not busywork. The code is built from the name as you type, with spaces turned into underscores and everything put in capitals. It is the cohort's permanent identifier, it cannot be changed afterwards, and renaming the cohort later does not change it. It is also what a bulk invitation spreadsheet uses to say which cohort each row joins, so it is worth reading now.
The code is derived rather than typed, on purpose, so it always matches the name it was made from. If you need a particular code, name the cohort so that it produces the one you want.
The controls
| Setting | What it accepts | Default | What it does |
|---|---|---|---|
name | up to 128 characters | none, required | The cohort's name. It is what a participant sees on the sign-up page when they follow this cohort's link. |
code | capitals, numbers and underscores, starting with a letter, up to 64 | derived from the name | The permanent identifier, unique inside the tenancy and fixed once created. Used by bulk invitations to name the cohort. |
description | up to 500 characters | empty | Internal only. No participant sees it. |
defaultJourneyIds | any number of journeys | empty | The starting journeys. Everybody who joins this cohort is put on all of them. Its own section below. |
signupCode | 1 to 20 characters, letters, numbers, - and _ | empty | The word the sign-up link is built from. Stored in capitals however you type it. Empty means this cohort has no link. |
assetId | a picture from the media library | empty | The cohort's picture. It must be a public asset, and the save is refused if it is not. |
status | Active or Archived | Active | Archived closes the sign-up link and takes the cohort out of the default list view. Nothing else changes and nobody is removed. |
Two more fields are read only, and appear on the row rather than in the form.
| Field | Notes |
|---|---|
signupUrl | The sign-up link, worked out from signupCode every time the row is read and never stored. No code means no link. Copies in one click. |
externalId | Only filled in when the cohort came from an external list. See Tracking a list you already keep. |
Sign-up codes are one shared pool across cohorts and tenancies. A code used by a
tenancy blocks the same code on a cohort and the other way round, and the message is
That sign-up code is already in use. That is what lets somebody type a code into
the app and land in exactly one place.
A cohort with participants in it is protected from deletion. The delete is refused
with cohort_in_use, so nobody is ever cut loose by a tidy-up. Archive it instead, or
move the participants first.
The starting journeys, and this is the part that matters
defaultJourneyIds is how a new participant gets their first content. It is a
list of journeys. Everyone who joins the cohort is put on every journey in the list,
at that journey's start.
They are applied at every point somebody gains a cohort, and there are four:
- an admin creates the participant with a cohort on them
- an admin moves the participant into the cohort
- somebody signs up through the cohort's sign-up link or code
- somebody claims an invitation that carried the cohort
So a person cannot end up in a cohort by any route and arrive empty handed. That is the design, and it is why the list is worth getting right before you hand the link out.
A cohort is chosen at the point somebody joins. Give each cohort its own sign-up link, so that the link a person was sent decides it. See Moving somebody between cohorts.
Nothing already running is ever touched
Joining a cohort only ever adds. If the person is already on one of those journeys, their run is left exactly as it is, wherever it has got to. It is not reset to the start, it is not restarted, and a finished one is not reopened.
This is what makes a re-join safe. Somebody who joins, leaves and comes back keeps the progress they had. A retry after a failed sign-up does not wipe what the first attempt created.
Assigning a journey to a person by hand is the opposite: that resets the run to its start node. If you want somebody back at the beginning, that is the way to do it, and re-joining a cohort is not.
Only published journeys are assigned
A journey in the list is assigned only if it is published. Draft and archived journeys are skipped, and the person joins without that journey's content. So if a new participant's home screen looks empty, an unpublished journey in this list is the first thing to check.
The picker in the portal only offers published journeys, so the usual cause is not authoring. More often the journey was published when you picked it, and has since been put back to draft, or archived, or replaced. The same goes for journeys that arrive in a cohort's list through an import file, because an import writes the list straight in.
So check the status of every journey in the list before you hand the link out, and check it again after anybody edits one of those journeys. That check takes a few seconds, and it is what stands between a new participant and an empty home screen.
The list applies to the next intake
The list is read at the moment a person joins, and never again. Add a journey to a cohort today and everybody who joined yesterday keeps exactly what they had. Only people who join after the change get it.
So when a cohort is already populated, changing its starting journeys is a change to the next intake, not to the current one. To reach the people already there, assign the journey to them directly, which also means their runs start at the beginning.
Moving somebody between cohorts
A participant's cohort is set when their record is created. The cohort field is on the create form, so the cohort is decided at the moment somebody joins.
Re-invite somebody and they keep the record they already have. An invitation for an address that is already in the tenancy re-uses the record it finds, so the invitation's cohort is not applied and its starting journeys are not added.
So give each cohort its own sign-up link, and let the link a person was sent make the decision for you.
Tracking a list you already keep
At a few thousand employers nobody creates the cohorts by hand.
A tenancy's cohorts can track a list you already keep somewhere else, daily, with nobody running anything. A company new to your list turns up as a cohort with a working sign-up code generated for it. A company that leaves is archived rather than deleted, because people may be attached to it. A company that comes back is reported for a human to look at rather than reopened automatically.
The sync owns the name and nothing else. The description, the starting journeys, the picture and a status somebody set by hand are never overwritten. So the pattern is: let the sync create the cohort, then set its starting journeys yourself, and they survive every run after that.
Your own system stays the authority. A company that is missing, or named wrongly, is fixed there and the platform follows the next day. One list, not two.
The sync fails safe. A feed the sync cannot read, or one missing the fields it needs, applies nothing at all rather than half of itself. A feed that would archive an unusually large share of the active cohorts stops and reports instead, because that shape is far more often a broken feed than a real closure.
Switching the sync on is one configuration entry naming the feed, so this is a setup conversation rather than a build. Ask us.
How to check it worked
Open the sign-up link in a private browser window. You should see the cohort's own name and the tenancy's logo.
Check every journey in Default journeys reads Published. This is the check that makes sure a new participant lands on content, and it is worth doing on the day you hand the link out and after any change to those journeys.
Join it yourself once. Sign up through the link with a test address and look at the home screen. What that account sees is exactly what the next real person will see, and it is the only check that covers the whole chain in one go.
Next
You can now create a cohort, give it a link, and say precisely what somebody joining through that link will have on their home screen a second later.
How a participant joins is the other half: what the person on the end of that link actually sees.
How a journey works is what happens next, once the starting journeys are on them.