Grant a Role Access to Records

Goal

Decide what each role may do with the records in an environment — as part of the solution that ships the application, so the same access reaches Test and Prod.

Prerequisites

• You are signed in to the Admin Control Center.
• A solution is open (see Create a Solution).
• The tables you want to grant access to exist in the environment. A table is created with its data behind it, so every table you can see is one you can grant access to.

Two questions, not one

Every line of a role answers two separate questions, and understanding the split is most of understanding this screen:

• A permission — what can they do? Create, Read, Update, Delete on a table.
• A policy — to which records? From Records I own, through My unit and below, to Every record.

That is why each cell in the grid is a dropdown rather than a checkbox: a checkbox can only answer the first question.

Giving the role to a team

Above the grid is a list of the environment's teams, with a tick box each. Everybody in a ticked team holds this role here, on top of anyone the role was given to directly on the Users page. Both ways count at once: somebody in a ticked team who also holds the role personally holds it once.

That is the second half of what putting somebody in a team means. Team membership already decided which records a permission reaches — the My teams' policies — and now it can decide which permissions they hold as well.

It is your organisation's own decision, so it never travels in a solution. A package brings a role and what that role may do; who holds it is about your people, and a publisher has no business saying. So this list is the same whichever solution you are standing in, and an uninstall does not touch it.

It takes effect on the next request, like every other change on this screen — including when somebody joins or leaves the team afterwards.

Platform privileges — the things that are not about a table

Above the grid is a short list of tick boxes: Import a solution, Export a solution, Import data. These are the capabilities that have no table behind them, so the second question does not apply — there are no records for a policy to filter. They are held or not held, which is why they are tick boxes and not dropdowns.

They are held per environment, like everything else on this screen: a role that may import a solution into Dev does not thereby import one into Prod.

Managing users and roles is not here, and that is deliberate rather than an omission. Users and roles are tenant-wide — they exist whichever environment you are in — so "may manage users, in Dev" is not a sentence that means anything. Those stay with the platform administrator.

The "All tables" row does not cover a privilege. It means every table, and the platform is not one. A privilege is granted by ticking it.

Steps

1. Open Solutions, then open the solution your application lives in.
2. Open Roles in the solution's navigation.
3. Either select New to create a role this solution owns, or Add existing role to grant access to a role your organisation already has.
4. In the grid, set each cell to a policy, or leave it on Not granted.
5. The first row is All tables. A grant made there covers every table — including ones you create later, which a row-per-table grant would not.
6. Select Save.

The change takes effect on the next request. There is no delay to wait out.

Why this is inside a solution, and why it never asks which environment

A permission names a table, and tables belong to an environment; a grant that is to reach Test and Prod has to travel in a package. Opening a solution has already fixed both — a solution belongs to one environment — so the screen has no environment to ask you about. To grant the same role different access somewhere else, export the solution and import it there, or switch environments and work in that environment's solution.

Which roles the list shows

A role is in a solution for one of two reasons, and both are in the list:

• The solution owns it — created here with New, so its logical name carries the publisher prefix (par_sales).
• The solution grants it something — a role your organisation already had, brought in with Add existing role.

Adding an existing role writes nothing by itself; it joins the solution the moment you grant it something and save. Granting your own sales role something never makes it the publisher's: whether a role belongs to a package is decided by its prefix, so an uninstall cannot take your role away.

Remove from solution clears only the grants this solution makes. A role the solution owns cannot be removed that way — it belongs to the package, so removing it means deleting the role on the Admin Control Center's Roles page.

The layer you are editing

The cells show what this solution grants. Where another layer already grants something the solution leaves empty, the cell says so — Already granted elsewhere: … — rather than folding it in. That distinction matters because the screen writes back what it shows: if it showed the merged answer, one save would copy your local edits, and other solutions' grants, into your package.

The default ("Main") solution is the exception. It is not a package, so its grid edits your environment's own grants: they travel in nothing, and they win over anything a solution grants. That is where to make a local adjustment you do not want to ship.

Copying a role

Two roles that differ by one or two cells are common — "Sales" and "Sales Manager", "Support" and "Support Lead" — and re-granting the second one cell by cell is how you end up with a security role that differs from its sibling somewhere nobody meant.

1. Open the role you want to start from.
2. Select Copy role.
3. Give the new role a display name, the name people read on the Roles page and in the Users list, such as Field Sales (read only).
4. Give the new role a logical name (prefixed, like every other component this solution authors).
5. Select Copy, adjust the cells that should differ, and Save.

The copy takes the permissions as they are on screen, including edits you have not saved yet — copying a role you have just been adjusting should copy what you are looking at.

Two things it deliberately does not do:

• It does not copy the role in other environments. Only this one. The same role means different things in Dev and Prod, so copying "what this role may do" can only sensibly mean what it may do here.
• It does not copy who holds the role. Those are your people, and duplicating a role is not a reason to duplicate its membership. Assign the new role to whoever should have it (see Assign a Role to a User).

What a new environment starts with

Only the Maker role, granted everything on all tables and all three platform privileges. Every other role starts with nothing — including a role a user already holds. That is deliberate: access is something somebody granted, and "nothing" is the only default that is safe to be wrong about.

The tenant administrator is not in the grid at all. They are all-access by definition and bypass this screen, so that revoking the wrong thing can never lock you out of the screen that would put it back.

When a solution brings the role

An installed solution can bring security roles with it — the role and what it may do, because an app that ships without its roles is an app nobody can use. Those grants are already in force when the solution finishes installing; nobody has to re-grant them.

You can still change them from the Main solution, and your change wins:

• Narrow or widen a cell and your setting is what applies, whatever the solution set.
• Set a cell back to Not granted and it stays not granted — the solution's grant does not come back the next time you open the screen.
• Update the solution and your changes survive. An import brings the solution's own grants up to date and leaves yours alone.
• Uninstall the solution and its grants go with it. Anything you set stays; a cell you had changed reverts to your value, and a cell only the solution granted becomes Not granted.

Who holds a role is never part of a package. Those are your people, and assigning the role is always something somebody here does (see Assign a Role to a User).

The policies, narrowest first

Every one of these can be chosen, and every one is enforced:

Policy	Reaches
No records	Nothing. A permission granted this way does nothing — useful only to switch something off without removing the row.
Records I own	Records owned by this user personally.
Mine and my teams’	The above, plus records owned by any team they belong to.
My teams’ records	Records owned by a team they belong to.
My unit	Records owned inside their own organisational unit.
My unit and below	Their unit and every unit under it.
My unit and above	Their unit and every unit it reports up through.
My whole branch	The topmost unit above them, and everything under it.
Every record	The whole environment.

Everything but Every record depends on who owns a record and where units sit in the organisation. A record's owner is set when it is created and can be handed on afterwards (see Change who owns a record); units and teams are tables in the environment, so you build your organisation there and the policies follow it.

A record's unit is its owner's unit, set when the record is created and again whenever it is given to somebody else. Moving a person to another unit later does not move what they already own; reassign those records if they should follow. A person with no unit owns records that no unit policy reaches.

A policy the engine cannot evaluate is listed under the grid but cannot be selected — a grant the engine cannot evaluate would show access on this screen that the user does not actually have. Today every built-in policy is evaluable, so nothing appears there.

What a user sees when a grant is narrow

A user is not shown commands their role does not reach. On a table they cannot create records in, there is no New button; on one they cannot delete from, no Delete; and a table they may read but not update opens its records read-only, with no Save. So a narrowed grant reads as a simpler app rather than as a wall of refusals — and the permission is still checked on the server every time, whatever the screen chose to show.

Troubleshooting

• "… is not a permission this environment can grant." — the table was deleted after the role was written. Reopen the screen and set the grant again.
• "… is listed twice." — a role holds a permission under exactly one policy. Set the cell once.
• A user still cannot see records after I granted the role. — check which role their token actually carries; a grant to "Sales" does nothing for a user whose claim says "sales". If you gave the role to a team, check they are in it — under Teams.
• There is no list of teams on the screen. — the environment has none yet, or its organisation model has not been seeded. Create a team under Teams and reopen the role.
• I removed everything and now nobody can use the app. — that is what it does. Grant the role again; as an administrator your own access is unaffected.
• "You do not hold the '…' privilege in this environment." — the person is trying to import a spreadsheet, or import or export a solution, and their role has no tick against it. Tick it in Platform privileges above the grid.
• "… is a platform privilege, so it is held or not held." — a privilege was sent with a policy on it. Nothing on the screen can do this; it comes from a solution package that named one.
• The grid is empty. — no environment is selected at the top of the window, or that environment has no tables yet.
• A role I added has disappeared from the list. — you saved it with nothing granted. A role is in the solution because the solution grants it something; add it again and grant it something.
• I granted the role in Dev and nothing changed in Prod. — expected: permissions are per-environment. Export the solution and import it into Prod (see Import a Solution into an Environment), which is exactly what putting the grants in a solution is for.

Related scenarios

• Write a Data Policy — when none of the built-in policies says what you mean.
• Put a User in a Team — what the team policies read.
• Create a Role.
• Assign a Role to a User.