Create a Role
Goal
Create a role in your tenant so it can be assigned to users — and know where to go next to give it any actual access.
Prerequisites
- You are signed in to the Admin Control Center as a platform administrator.
Steps
- Open the Roles page from the left navigation.
- Select New. A drawer opens.
- Enter a display name — what people will read — and a logical name, which is the role's identity. Add a description of what the role is for.
- Select Save.
- Give the role some access: open Solutions, open the solution the application lives in, and use its Roles page (see Grant a Role Access to Records). A role that has just been created permits nothing at all.
A role has two names
This trips people up once and then never again, so it is worth a moment.
| What it is | Can you change it? | |
|---|---|---|
| Display name | The words people read — "Sales & Pre-Sales" | Yes |
| Logical name | The role's identity — sales | No |
The logical name is not a label. It is the claim a signed-in user's token carries, and it is the key each environment stores the role's permissions under. Changing it would leave every one of those grants pointing at a role that no longer exists — silently, because "a role with no grants" is a perfectly valid state that simply permits nothing. Nobody would notice until somebody could not open a record. It works exactly like a table's logical name, and is fixed for exactly the same reason.
The display name is only ever read by people, so changing it breaks nothing. If you want the role to read differently, change that.
Roles you create here are system roles: their logical name carries no publisher prefix,
because a role your organisation invents belongs to you, not to anybody's app. A role with a
prefixed name like par_sales was created inside a solution, or arrived with one.
Editing a role
Click a role's row — or tick it and select Edit — to open the drawer again. The display name and the description are editable; the logical name is shown, locked, so you can still read the identity a package or an error message refers to.
If you genuinely need a different logical name — you will rarely want to — that is deliberate work rather than an edit:
- Create the new role.
- Grant it the same access, in each solution. Copy role on the solution's Roles page does this in one step (see Grant a Role Access to Records).
- Move its users across (see Assign a Role to a User).
- Delete the old role.
A role grants nothing on its own
Creating a role gives it a name and nothing else. What it may do is decided inside a solution — and that is not an accident of where the screen was put. A permission names a table, tables belong to an environment, and a grant that is to reach Test and Prod has to travel in a package. Standing inside a solution fixes both of those at once, which is why that screen never has to ask you which environment you mean.
| The role | Its permissions | |
|---|---|---|
| Scope | The whole tenant | One solution, in one environment |
| Holds | The name and description | What it may create/read/update/delete, and to which records |
| Where | This page | Solutions → your solution → Roles |
| Assigned to | Users, on the Users page | Nothing — they are the role's grants |
What happens behind the scenes
The role is created in your tenant, with no permissions. When a user holding it signs in, the role travels in their token as a claim; each environment then looks up what that name has been granted there.
Troubleshooting
- "A role named … already exists." — a role with that name is already present. Choose a different name.
- The logical name box is greyed out. — you are looking at an existing role, and that name is fixed. If you wanted to change what the role is called, change the display name just above it; that one is editable and nothing breaks.
- You cannot delete a role — a role that is still assigned to one or more users cannot be deleted. Remove it from those users first (see Assign a Role to a User), then delete it.
- Edit is greyed out. — it acts on exactly one role. Tick a single row, or just click the row you want.
- I created a role and the user still cannot do anything. — expected. Grant it access on a solution's Roles page, in each environment where it should reach something.