Standing up a tenancy
In the portal: Settings, then Tenants.
Why this one is yours
Creating a tenancy makes you an admin of it. The platform grants that place in the same action that creates the tenancy.
An admin can read everything about every participant in that tenancy: their answers, their health readings, their screening results, and their messages with a coach.
So this is an access decision rather than a preference, not a setup chore to pass to whoever has ten minutes free. Whoever creates a tenancy can read patient records in it from that moment on. Keep it with the few people who are meant to hold that reach, and where somebody else should hold it, have them create the tenancy themselves.
Your sales team does not need it. They need a link they can send to a company, and there is a role that gives them exactly that link and nothing else. Inviting your staff invites someone at that role, and Roles and permissions sets out what it can and cannot read.
What a tenancy is
A tenancy is one customer's own space in the platform. It has its own participants, its own content, its own colours and its own sign-up link. Nothing inside one is visible from another.
Two consequences are worth holding on to before you start.
One login can hold a place in several tenancies, and each place is granted separately. Being in one gives a person nothing in any other. Somebody who works across two is invited into both, then moves between them with the switcher in the top bar.
Content does not travel on its own. Journeys, sequences and pictures belong to the tenancy they were made in. The setup form can copy a chosen set into the new tenancy while you create it, and after that the two are separate.
Tenancy or cohort, and this decision comes first
Most of the time the answer is a cohort, not a tenancy. It is worth settling before you create anything, because a tenancy's code is fixed once it is saved.
A cohort is a named group inside a tenancy. It carries its own sign-up link, its own picture, and its own set of journeys that people joining through that link are put on. Everything else it shares with the tenancy around it: the colours, the tabs, the content library, and the administrators.
A tenancy is a separate space. Its own participants, content, colours, tabs and sign-up link, and nothing inside it is visible from any other.
So the question is: does this customer need something a cohort cannot give them?
| They need | Give them |
|---|---|
| Their own sign-up link and their own starting journeys | a cohort |
| Their own logo, colours or tab names | a tenancy |
| Their own administrators, who must not see anybody else's participants | a tenancy |
| A different level of the product from everybody else | a tenancy, because levels sit on tenancies |
| Nothing on this list | a cohort |
What that looks like at scale. A network with thousands of employers on it gives nearly all of them a cohort: one link each, one starting programme each, one shared space. A few dozen that need their own look, their own administrators, or a level of their own are promoted to a tenancy of their own.
That shape is the normal one. A tenancy each, for everybody, is not.
At that scale nobody creates the cohorts by hand, and they do not have to: see Tracking a list you already keep.
Before you start
- You are signed in to the portal and your role is Admin.
- You have agreed the name. The tenancy's code is built from the name and is fixed forever once you press Save, so it is worth settling the name first.
- You know whether people should be able to sign themselves up, and under what code.
The runbook: stand up the tenancy
- Sign in to the portal.
- Click Settings, at the foot of the left sidebar.
- Click Tenants in the list that opens.
- Click Create, at the top right of the list.
- Click Upload in the picture box at the top of the form.
- Choose the logo file from your computer.
- Type the tenancy'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 a value in Tier. See below if you are not sure.
- Type a sign-up code in Sign-up code.
- Click Save.
On Tier. A tier is the level of the product a customer is on, and it is where you set out what that level includes: which journeys and sequences, which behaviours you want to encourage, and which services their people can reach. Every tenancy carries one.
A new platform starts with a single tier called Default. If that is the only value in the list, that is your answer. Agree your tiers with us before you create tenancies against them, because the tier is what the level is read from.
Each tier withholds the parts of the product that level does not include, so a customer on a lower tier does not see them.
*Today: a tier records which level a customer is on and changes nothing about what anybody can see or do. Set it correctly anyway, because it is the record you will gate on later.Steps 5, 6, 9 and 11 are optional. Skip 5 and 6 if you have no logo yet, or click Select instead to pick a picture already in the media library. Skip 11 if nobody should be able to sign themselves up: an empty sign-up code closes self sign-up completely, so people join by invitation only until you set one, and you can add one later. A cohort can also carry its own sign-up code, which is how one tenancy hands different companies different links.
Step 8 is not busywork. The code is derived from the name as you type, with spaces turned into underscores and everything put in capitals. It is the tenancy's permanent identifier, it can never be changed, and renaming the tenancy later does not change it. Read it once now. Renaming is easy and changes nothing else, so a tenancy can end up called one thing and coded another, which is normal and not worth fixing.
Leave Status alone. A tenancy is created Active, and Active and Archived are the two states it holds.
Copying content in at the same time
The form has three more tabs, Journeys, Attributes and Configurations, and every one of them is optional. Submitting with nothing selected gives you an empty tenancy, which is a perfectly normal thing to do.
Everything the tabs offer comes from the tenancy you are in right now, not from a library. If you want to copy from a different one, switch first with the switcher in the top bar, then start the form again. Getting this wrong gives you an empty tenancy rather than a wrong one, so it costs you a pass and nothing else.
Picking a journey brings the things it needs with it: its sequences, its atoms, its home surfaces and its pictures. Those arrive already ticked and locked in the other lists, so you can see what is coming without being able to drop a piece the journey depends on.
If something cannot be copied, a red panel names the item. Save stays refused until you fix that item where it lives, so a half-copied tenancy is never created. The usual cause is a picture with no code.
What Save actually does
Four things, in one go. The tenancy is created. You are given an Admin place in it. You are switched into it, so the top bar now shows its name. Anything you picked on the other tabs is copied in.
A panel then reports that the tenancy is ready, with a count of rows applied and rows failed. A count of zero failed is what you want.
Then invite somebody in
Nobody can see a tenancy at all until somebody invites them into it, whatever their role, so do that next: Inviting your staff.
How to check it worked
The top bar carries the new name. The switcher at the top right of the portal shows the tenancy you are working in. If it shows the old one, the create did not finish.
The settings are there. Go to Settings, then Configurations. A freshly created tenancy has fifteen rows. Fewer than that means the create was interrupted, and the safe fix is to tell whoever supports your platform rather than to add rows by hand.
The sign-up link resolves. Go to Settings, then Tenants, and click the new row. Copy the Sign-up URL and open it in a private browser window. You should see the tenancy's own name and logo on the sign-up page. If you see a different brand, the sign-up code has landed on something else.
If it did not work
A message says that code or sign-up code already exists. Two different causes wear the same message. Either the code built from your name is already taken by another tenancy, or the sign-up code you typed is. Change the name slightly, or change the sign-up code, and save again.
"That sign-up code is already in use." Sign-up codes are shared across tenancies and cohorts in one pool, so a code used by a cohort somewhere else blocks it here. Pick another.
The save fails and no message names a field. Look at the grey code beside the name. It cannot be longer than 32 characters, and a long name makes a long code. Shorten the name.
A red panel says something blocks the setup. One of the things you picked on the content tabs points at something that cannot be copied. Fix that item where it lives, then start the form again. Nothing has been created yet, so there is nothing to clean up.
The panel reports rows failed. The tenancy exists and is fine. What failed is some of the copied content. Each failure is named with the item and the reason, and they can be imported again afterwards.
"Switch into this tenancy to manage it." You are trying to edit a tenancy while working inside a different one. Switch into it with the top bar first.
What you can now do
Stand up a tenancy end to end: create it, bring a journey and everything it needs across with it in the same action, and get a salesperson a sign-up link without giving them sight of a single participant.
The three checks under How to check it worked are worth running every time. They take a minute, and they catch the two failures that otherwise surface days later: a create that did not finish, and a sign-up code that landed on the wrong tenancy.