Managing User Roles

Grants or removes permissions for one person, using the same role-and-scope pairs the user screen manages by hand. It is the op behind onboarding rules, access requests that end in an approval, and offboarding rules that strip everything at once.

The change takes effect straight away. Clarive drops the cached permissions for that person, so the next screen they open reflects the new grants without a logout.

Read the next section before you build anything on it. This op does nothing that lasts for a user who belongs to a user group.

Users in a user group

As soon as a person belongs to at least one user group, their permissions are worked out from those groups, and their own grants are replaced by the group merge every time the record is written. This op writes the record, so the grants it sets are discarded in the same step that saves them.

Nothing warns you. The op reports success, the record comes back under the Return Key, and the permissions in it are the group's. If you read that record you can see it for yourself: the pairs you asked for are missing.

For anyone in a group, change the group instead, with Managing User Group Roles. This op is for people whose security is managed individually.

Fields

Action

Assign or Unassign. A new op arrives set to Assign, and the field cannot be cleared from the form.

Assign adds. Grants the person already has stay where they are, and asking for a pair they already hold changes nothing and raises nothing.

Unassign removes only the pairs you list. A role that ends up with no scopes left disappears from the person's record entirely, which is what you want for offboarding and worth knowing if you expected an empty role to linger.

There is no replace. To swap one set of grants for another, put an Unassign op in front of an Assign op.

A hand-edited rule carrying any other word here runs to completion, rewrites the record unchanged and reports success.

User

Who to change. The list searches after three characters and shows the full name with the user id beside it; the id is what gets stored. You can also type your own text, so ${username} and plain ids both work, and ${var} expands against the stash before the lookup.

The match is exact on the user id, and the full name is not searched at run time even though the picker searches on it. A value that matches no user id stops the op. The op never creates a user, so an onboarding rule has to have created the account before this point.

One person per op. For a list of people, wrap the op in FOREACH CI.

The "modified by" stamp on that person's record is taken from the session running the rule. A rule running inside a job has no session, so the stamp comes out blank and the audit trail will not tell you which rule made the change.

Projects

The scopes the roles apply to. The picker holds several entries and lists the project-like resources in your installation: projects, and the groups that contain them. See Scope for what qualifies.

Alongside the resources it offers the variables you declared as a project-like resource, shown as variable: ${name}. A variable declared to hold plain text or a list is not in this picker. Pick one and the op resolves it when the rule runs. A variable holding a list of resource ids counts as several entries, and so does a comma-separated string, so one ${my_projects} entry can cover a whole portfolio.

The word all is special. Type it as an entry and the op works on every project-like resource in the installation. There is no confirmation step and no preview, so Unassign plus all strips the role everywhere in one op.

Entries that are not project-like resources are dropped without a word. A typo, a deleted resource or a topic id sitting in a variable produces no error and no grant, which is the usual reason an op "worked" but the person still cannot see anything.

An entry list that resolves to nothing at all, for instance a variable that came back empty, leaves the record untouched and still reports success.

Roles

Which roles to grant or remove. The picker takes several, lists every role defined under Roles, and offers the variables you declared as holding a value or a list.

Roles are matched by their id. A role id that does not exist is skipped silently, exactly like an unusable project entry. An empty list leaves the record untouched and reports success.

Every role in the list is applied to every scope in the list. Four roles and three projects means twelve pairs, in one op. When you need different roles on different projects, use one op per combination.

What comes back

With a Return Key set on the op, you get the person's record as it stands after the change. project_security in it is a list with one entry per role-and-scope pair, each naming the role, the scope and what kind of scope it is. Reading that back is the one reliable way to confirm a grant landed.

That record is raw, and it is not the same thing Load User hands you: the stored password hash and the API key are still in it. Do not write it into a log line, a notification body or a topic field. Use the entry you actually want, such as ${changed_user.email}.

Without a Return Key the change still happens. The record is not kept, that is all.

Failure and rollback

A user who cannot be found stops the op, as does a hand-edited rule with the action, roles or projects entry missing altogether. Everything else described above fails quietly instead. The op's Error Handling setting decides whether a stop ends the rule or is swallowed.

There is no automatic undo. Pair the op with a mirrored one on the rollback path and untick Run Forward on that copy, or the grant is applied twice. The reverse matters more: leave Run Rollback ticked on the forward op and it re-applies the same grant during a rollback pass, which quietly undoes the undo.

Combining with other ops

Guard the op. IF var condition THEN on a topic status or an approval flag in front of it keeps a workflow rule from handing out access on every save.

Put Load User before it to check the account exists and is active, and after it to read back what the person now holds.

For anyone in a user group, switch to Managing User Group Roles. The two ops are not interchangeable and the wrong one is silent about it.

Follow the change with Send a notification so the person knows what they can now reach.

Examples

Give a new joiner a working set of permissions on one project, once the onboarding topic is approved.

Action     Assign
User       ${username}
Projects   ${project}
Roles      developer

Strip a role everywhere when someone leaves. all covers every project-like resource, so nothing is missed and nothing has to be listed.

Action     Unassign
User       ${leaver}
Projects   all
Roles      developer, approver

Swap one role for another, as two ops in sequence.

Action     Unassign
User       foo_user
Projects   ${project}
Roles      developer

Action     Assign
User       foo_user
Projects   ${project}
Roles      approver