Okaystep documentation
Okaystep adds approval steps to Jira workflow transitions in software and business projects. A move into a gated status waits until the approval is approved.
Set up in four steps
- Create a policy. Jira settings > Apps > Okaystep > Policies > New policy. Name it, pick the statuses that need approval to enter (for example Done or Approved), and optionally limit it to projects, work types, the statuses it is moving from, or a JQL query.
- Add steps. Each step has approvers and a rule:
- Approvers: people, groups, project roles (resolved in the work item's project), user picker fields on the work item, and the reporter's manager (from the Manager directory tab).
- Rule: any one approver, all of them, or a number (N of M).
- Rejections: one rejection ends the request, or only when the approvals needed can no longer be reached.
- Fallback approvers cover people who are away without a delegate, decide alone when nobody else resolves, and after the escalation time can decide for everyone still pending.
- Reminders: a comment every N hours while the step waits (0 = off). Steps run in order; each step's approvers are worked out when it starts.
- Add the validator. Setup tab > pick the policy > Check workflows. Every transition into a gated status should carry "Approval required (Okaystep)". Press Add validator to add it (Jira publishes the workflow change), or add it yourself in the workflow editor under Validators.
- Try it. Move a work item into the gated status. Jira refuses the move, Okaystep files the request (if "Request approval automatically" is on) and @mentions the approvers.
Deciding
- Approvals panel on the work item: Approve or Reject with a comment. If you cover for an
away colleague you get "Approve for
" buttons; each decision counts for one approver. - Apps > My approvals: everything waiting on you, your own requests, and your away window.
- Comment command: a comment that starts with
/approveor/reject(then your reason) records your decision. Okaystep replies when it can't record it (not your step, comment required, already decided). Switch it off in Settings. - Admin override: with "Jira admins may approve or reject a step for everyone" on, admins see Admin buttons on the panel. A comment is required and the override is logged.
Rules that keep the control honest
- The requester can't approve their own request (also not as a delegate or admin) unless the policy allows self-approval.
- A comment is required to reject (on by default); you can also require one to approve.
- An approval is used up when the work item enters the status. Moving it out and back in needs a new approval.
- If the subscription lapses, nothing can be requested or decided and the validator lets every move through, so work is never trapped.
Away and delegation
Apps > My approvals > Away and delegate: first and last day (UTC, inclusive) and an optional delegate. While you're away your delegate decides for you; with no delegate, each step's fallback approvers do. Delegates see your approvals in their own My approvals list.
Search with JQL
| Field | Example |
|---|---|
okaystepStatus | okaystepStatus = pending (also approved, rejected, cancelled, none) |
okaystepApprover | okaystepApprover = currentUser() (pending approvers and their delegates) |
okaystepStep | okaystepStep = "Finance" |
okaystepPolicy | okaystepPolicy ~ "budget" |
okaystepRequested | okaystepRequested >= -7d (date of the latest request, UTC) |
okaystepRequests | okaystepRequests > 1 (asked more than once) |
Audit trail
Every request, step start, decision (with who decided for whom), reminder, escalation, override, withdrawal, blocked move and use is recorded. See it per work item on the panel, or site-wide under Jira settings > Apps > Okaystep > Audit trail, with a CSV export for the last 365 days.
Manager directory
Jira has no manager field. Paste "person,manager" lines (email addresses Jira lets you search, or account ids) under Manager directory, press Check, then Import. Steps that use "the reporter's manager" look the reporter up there.
Workflows as code
If you manage workflows through Jira's REST API, the validator's rule configuration can carry
{"policyId": "<id>"} to pin one policy to that transition, or a whole policy
({"policy": {"name": "...", "steps": [...]}}). Okaystep checks it like the admin page does and
lists it under Policies as "Defined in a workflow".
Moving from Data Center
Rebuild each approval as a policy (target status, steps, approvers, rule), add the validator with the Setup tab, and try it on a test project next to your old setup before switching.
Support
hello@greatwork.company. Include the policy name, a work item key, the statuses it moved between and the message you saw.