Rulewell for Jira: documentation

Rulewell adds workflow validators, conditions and post functions that Jira's workflow editor doesn't have. It runs entirely on Atlassian's Forge platform.

Where Rulewell shows up

You can add rules either in Jira's workflow editor (open the workflow, select a transition, add a rule) or on the Rulewell admin page (Add a rule: pick the workflow, the transition and the kind of rule). Both store the rule on the transition in the same way.

Rules

Validators and conditions

• Field required when another field has a value. Pick the field to look at, the condition (has a value, is one of, is not one of) and the fields that become required. Values are compared by name, exactly as Jira shows them (option names, priority names, labels). The message ends with the names of the fields still missing. On a transition screen, the values people enter on the screen count.
• Linked work items in a status. Pick a link type (or any), which side of the link (for Blocks, "this work item is blocked by ..." is the inward side), and whether all of them must be in the statuses you pick, or none of them may be. "At least N such links" makes the link itself required. The message lists the work items in the way.
• All child work items done. Every sub-task and child work item one level down (stories under an epic, epics under a level above) must be in a Done-category status, or in the statuses you pick. Optionally refuse when there are no children.
• Attachment required. At least N attachments, optionally of given file types (extensions, not case-sensitive).
• Only people in a group or role (validators only). Groups, project roles in the work item's project, the assignee or the reporter. Everyone else gets your message.

Checks (Rulewell check validator)

• Work item matches JQL. The work item must match (or must not match) your JQL. Rulewell adds issuekey = <the work item> AND (...); leave out ORDER BY. The JQL is checked with Jira's strict parser when you save. JQL reads Jira's search index, which can trail an edit by a few seconds, and it sees the work item as saved (not values typed on the transition screen).
• Comment required. The person must type a comment of at least N characters on the transition screen, optionally only when the resolution is one you pick. The transition needs a screen: Jira only shows a comment box, and only hands the comment to validators, on transitions with a screen.

Post functions (Rulewell action)

Post functions run right after the move, in the background. Each run is in the run log.

• Copy fields from the parent to this work item, or from this work item to its parent or children. Optionally only into empty fields.
• Move the parent when all children are done. When every child is in a Done-category status (or the statuses you pick), the parent moves to the status you pick, through a transition Jira offers from its current status.
• Create a linked work item. Work type, project (or the same one), a summary with placeholders, a link type and direction (or create it as a child), fields to copy and the assignee.
• Assign by rule. In turn (round robin) or to whoever has the fewest open work items, from a group or a project role; or to the person in a user field, the component lead, or the parent's assignee. Jira notifies the new assignee as usual.
• Watchers and labels. Add or remove the person who made the move, the assignee, the reporter or people in a user field; add or remove labels.
• Add a comment with placeholders.

Placeholders: {key}, {summary}, {status}, {project}, {user} (the person who made the move).

Test on a work item

Every rule editor has a Test on a work item box. Enter a key and press the button:

• validators: "the move would be allowed" or "would be refused", with the exact message;
• conditions: "the transition would be shown" or "hidden";
• post functions: the list of changes it would make. Nothing is changed.

Tests use the work item as it is now. On a real move Jira also sees the values typed on the transition screen.

Usage and run log

Usage lists every workflow, transition and project that uses a Rulewell rule, with a summary of each rule. Jira admins can remove a rule from there. The list refreshes every hour and with Scan again.

Run log shows what post functions did (done, nothing to do and why, or failed with Jira's error) and which checks refused a move, for 90 days. Validators and conditions run inside Jira and are not logged.

Subscription

While the subscription is inactive, Rulewell never blocks work: validators let every move through, conditions show the transition, checks allow the move, post functions do nothing, and rules cannot be added or changed. Validators and conditions are switched off per project through the rulewell-license project property within an hour; they work again within an hour of renewal.

Troubleshooting

• A rule didn't fire. Open Usage: is the rule on the transition people use? Jira workflows often have several transitions into the same status.
• "A Rulewell rule on this transition has JQL Jira no longer accepts". A field in the JQL was renamed or deleted. Edit the rule and save it again; the editor shows Jira's error.
• A post function says "nothing to do". The run log says why (for example "2 of 3 children of OPS-12 not finished").
• A post function failed. The run log shows Jira's error, for example a field that isn't on the target work type's screen. Rate limits and short outages are retried twice.

Support

hello@greatwork.company. Include the workflow, the transition, one work item key and the message you saw.