Change Topic Status If Matches
Declares a transition and the conditions under which it is offered, in one op. When the topic's category, its current status or the roles the user holds do not match, the transition is not added to the topic's Change Status menu and nobody is told why.
This is the op most rule workflows are built from. Reach for Change Topic Status instead when the surrounding rule has already made the decision and the transition should apply to whatever the topic is doing right now.
Fields¶
The form is split into two groups. IF INPUT MATCH THESE... holds the conditions,
THEN SET TOPIC STATUS TO... holds the transition itself.
Select Topic Categories¶
The topic categories the transition applies to. Pick as many as you want. Leave it empty and the transition applies to every category that uses the rule, which is what you want for a rule shared across categories.
Roles¶
The roles that grant the transition. Leave it empty and the transition is granted to every role the user already holds, which comes out as no role restriction at all.
With roles listed, the op keeps the overlap between them and the roles the user holds on this topic. No overlap, no transition. Role membership is resolved through the topic's projects, so the same person can get the transition on one topic and not on another.
The picker also lists your global variables. A variable selected here is expanded against the stash before the comparison runs, so a variable holding a role id works.
From Status¶
The statuses the transition starts from. Leave it empty and it starts from every status assigned to the category.
On a real topic only one entry can survive, because the topic sits in exactly one status. Listing five From Statuses does not offer five transitions, it offers one when the topic is in any of the five, and none otherwise.
To Status¶
Where the topic lands. The only field the form will not let you leave blank. Each entry produces its own transition, so three To Statuses give the user three menu entries.
You can type a value that is not in the list instead of picking one. Type carefully: the picker stores status identifiers, and a status whose identifier is not assigned to the topic's category is thrown away after the rule finishes, with nothing written anywhere. A transition that never appears even though the rule looks right is almost always a To Status the category does not carry.
Deployment Type¶
What taking the transition does.
| Deployment Type | Effect |
|---|---|
No Job |
the status changes in place, no job is created, the transition appears in the Change Status menu |
Promote |
the transition appears under Promote and starts a deployment job |
Demote |
the transition appears under Demote and starts a backout job |
Static |
never offered in the Change Status menu, reserved for the deployment path |
A Deployable status reached with Promote or Demote is kept out of the Change
Status menu, because it is meant to be reached by running the deployment. Two things put it back:
another transition in the same rule that reaches it with No Job, or the
Change topic status logically (no deployment) permission on the category, which offers the
promote and demote targets in the menu to the users who hold it. Static targets are filtered out
under every condition.
Picking anything other than No Job also narrows the From Status list to whatever the nearest
enclosing IF From Status IS selected. With No Job that
narrowing does not happen, which shows up when the full workflow is listed rather than when a single
topic is looked at.
Only back to original status¶
Unchecked by default. Once a topic lands in one of the To Status entries through this op, the only
transition offered from there is the one back to the status it came from. The lock clears as soon as
the topic goes back. Root users are not restricted, and neither is anyone holding
Change a topic to any available status in its category on that category.
The lock is worked out by reading the saved rule and matching the recorded move against this op's To Status and From Status lists. A To Status written as a variable is not recognised by that match, so the checkbox does nothing on a transition whose target is a variable.
What the rule produces¶
Each transition op appends to the workflow list in the stash. Nothing is replaced, so several
transition ops in one rule accumulate, and identical transitions collapse into a single menu entry.
After the rule finishes, every transition whose From Status or To Status is not in the category's status list is discarded. If the category has no statuses at all, the workflow fails with an error rather than returning an empty menu.
A rule that throws an error behaves differently depending on who asked. On the topic screen you get an error about the topic workflow. In the Promote and Demote menus and in the category workflow view the error is swallowed and you get an empty list. A workflow rule that has been deactivated is never run, and every transition disappears at once.
Listing mode¶
Clarive sometimes runs a workflow rule to collect every transition it could ever produce, rather than the ones available right now. The Promote and Demote menus and the category workflow view work that way, and so does the check that marks menu entries valid or invalid for root users.
In that mode the op stops measuring anything against the user or the topic. Select Topic Categories
is not checked. Roles still decides which role goes on each transition, but it is no longer
intersected with the roles the user holds, so transitions for roles the user does not have are listed
too. From Status is still the source list, and it is no longer narrowed to the status the topic is
in, so every entry produces a transition. What comes out is the full product of roles, From Statuses
and To Statuses.
One condition does survive: on a Promote, Demote or Static transition an enclosing
IF From Status IS still cuts the From Status list down. Beyond
that, do not use the category workflow view to confirm that a condition works. Open a topic as the
user you are testing.
Combining with other ops¶
Wrap this op in IF Project IS to make a transition project-specific, or in IF Role IS when several transitions share the same role gate and you would rather set it once.
IF From Status IS overlaps with the From Status field here. Use the field when one transition is involved and the op when a group of them share an origin.
For conditions the three workflow IF ops do not cover, such as a topic field or a variable another
op wrote, use IF var condition THEN. The rule already carries
the topic's current status, its category, its identifier and the projects it belongs to, so those
are available to test without loading anything.
A workflow rule can do work as well as declare transitions. Send a notification alongside the transition ops tells the next person in the chain, and Load Related Topic lets a transition depend on the state of a parent release.
To change a status from inside a running job, this is the wrong op. Use Change Topic Status from the job palette.
Examples¶
Approvers move a topic out of review, in two directions, with no job involved.
IF INPUT MATCH THESE...
Select Topic Categories Change
Roles approver
From Status In Review
THEN SET TOPIC STATUS TO...
To Status Approved, Rejected
Deployment Type No Job
A promotion into a deployable status, restricted to release managers, that locks the topic until it is demoted back.
IF INPUT MATCH THESE...
Select Topic Categories Release
Roles release_manager
From Status Approved
THEN SET TOPIC STATUS TO...
To Status In PROD
Deployment Type Promote
Only back to original status checked
Anyone who can see the topic may cancel it from any status. Both condition fields left empty, so the category and role checks do not apply.
IF INPUT MATCH THESE...
Select Topic Categories (empty)
Roles (empty)
From Status (empty)
THEN SET TOPIC STATUS TO...
To Status Cancelled
Deployment Type No Job