Managing User Group Roles

Grants or removes role-and-scope pairs on a user group, the same pairs the group's permissions table holds. Since anyone who belongs to a group takes their security from the group, this is the op to reach for when the people affected are managed in groups rather than one at a time. Managing User Roles covers the individually managed case, and it has no effect on someone who is in a group.

The op edits the group record and nothing else. Read the next section before you build a rule on it.

The change does not reach the members on its own

Every person carries a worked-out copy of their permissions, rebuilt from the groups they belong to whenever their own record is written. Permission checks read that copy, not the group.

This op updates the group record and stops there. The members' copies are left alone, so the people in the group keep whatever they had. The op does drop the installation's permission caches on its way out, which makes the next few permission checks slower but changes nothing about the answers they give, since the copies they re-read are the stale ones.

Open the group in the user group screen and save it and every member is recalculated in batches. That is why the change appears to work when you do it by hand and appears to do nothing when a rule does it.

Two ways to finish the job from a rule: save each member afterwards, or treat this op as a way to prepare a group whose membership is assigned later, since taking someone into the group recalculates them.

Fields

Action

Assign or Unassign. A new op arrives set to Assign, and the form will not let you clear it.

Assign adds to what the group already grants and does nothing when the pair is already there. Unassign removes only the pairs you list, and a role left with no scopes drops out of the group record altogether. There is no replace: put an Unassign op in front of an Assign op when you mean to swap a set.

A hand-edited rule with any other word here runs, rewrites the group record unchanged and reports success.

User Group

Which group to change. One group per op, picked from the list of existing groups.

This picker holds nothing but real groups. It does not offer variables and it does not accept text you type, so the group cannot come from the stash. A rule that has to decide the group while it runs needs one op per group behind an IF var condition THEN branch.

A group that no longer exists, in a rule written before it was deleted, stops the op.

Projects

The scopes the roles apply to. The picker takes several entries and lists the project-like resources in your installation, meaning projects and the groups that hold them. Scope explains what qualifies.

The list also offers the variables you declared as a project-like resource, shown as variable: ${name}. A variable declared to hold plain text or a list does not appear here at all. Entries are used as they are, and this is where the op differs from its per-user counterpart. A variable holding a single resource id is fine. A variable holding a list of ids is not unpacked into entries, and it stops the op with an error rather than assigning anything. Pick the scopes directly, one entry each.

Typing all as an entry is honoured: the roles are applied across every project-like resource in the installation. Unassign with all clears the role from the group everywhere, in one op and with no confirmation.

Entries that are not project-like resources are dropped without a word, so a stale id produces no error and no grant. A comma-separated string is treated as one entry and lands in that same bin, so proj_foo,proj_bar typed as a single entry grants nothing.

Roles

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

Roles are matched by id, and an id that matches nothing is skipped in silence. The same restriction as Projects applies, but without the error: a variable holding a list of role ids is not unpacked, so it matches nothing and the op finishes having changed nothing at all. Pick the roles themselves.

Every role is applied to every scope. Three roles across four scopes is twelve pairs in one op.

What comes back

With a Return Key set, you get the group's record after the change, including its mid, its name and its project_security. That last one is a list rather than a tree: one entry per role-and-scope pair, each naming the role, the scope and what kind of scope it is. Reading it back is the way to confirm the op did what you asked, since the members tell you nothing.

Without a Return Key the change still happens and the record is discarded.

Failure and rollback

A group that cannot be found stops the op, as does a hand-edited rule missing the action, the group, the roles or the projects entry. A list variable in Projects stops it too. Everything else on this page fails quietly. The op's Error Handling setting decides whether a stop ends the rule.

There is no undo. Build one from a mirrored op with the opposite Action, and untick Run Forward on it so it only runs on the way back. Untick Run Rollback on the forward op as well, or it applies the same change again during a rollback pass and cancels the mirror.

Combining with other ops

Guard it with IF var condition THEN so a workflow rule only changes group permissions at the point a request is approved, rather than on every save of the topic.

Reach for Managing User Roles instead when the people involved are not in any group. Use Load User to find out which case you are in: its groups entry is empty for an individually managed person.

Tell people what changed with Send a notification, and say when it takes effect if the members still need recalculating.

Examples

Open up a new project to an existing group once its setup topic is approved.

Action       Assign
User Group   qa-team
Projects     proj_foo
Roles        tester

Take a role away from a group across everything it covers.

Action       Unassign
User Group   contractors
Projects     all
Roles        developer

Swap a role for a narrower one, as two ops in a row.

Action       Unassign
User Group   qa-team
Projects     proj_foo
Roles        approver

Action       Assign
User Group   qa-team
Projects     proj_foo
Roles        reviewer