User Guide

Table of Contents

Overview

Business Sign-off adds a Jira-native approval panel directly to supported Jira issues in Jira Cloud. From the issue view, users can:

• see the current approval state
• review the current list of approvers
• add or remove approvers, if allowed by project configuration
• notify approvers when work is ready for review
• approve, return, change, or withdraw their own decision
• review an issue-level audit history of approval activity

The issue panel is the main place to work with approvals. Read-only BSO fields support Jira search and reporting, and two dashboard gadgets show your approval work. Administrators configure permissions and workflows.

Before You Start

Business Sign-off must already be installed and enabled by your Jira administrator.

If you do not see the Business Sign-off panel on an issue where you expect it, check with your Jira administrator or see the Cloud Administrator Guide.

Where the App Appears in Jira Cloud

After your Jira administrator installs and configures the app, users will see Business Sign-off in these Jira Cloud locations:

• Issue view: the Business Sign-off panel appears in the issue context area on supported issue types
• Project settings: project-level configuration page under Apps
• Jira administration: global configuration page under Apps
• Workflow editor: Business Sign-off workflow conditions, validators, and post-functions
• Dashboards: two gadgets, BSO - My Approval Queue and BSO - My Approval Requests
• Custom fields:
  • BSO - Approvers
  • BSO - Status

Using Business Sign-off on an Issue

Open the Business Sign-off Panel

When Business Sign-off is enabled for the project and your issue type supports approvals, open the Business Sign-off panel in the issue context area. You need permission to view the issue.

An issue that already has approvers can retain the panel if its type later becomes ineligible. A banner explains that existing approval work can continue, while new approvers cannot be added.

If the panel does not appear, common reasons include:

• the app is not enabled globally
• the app is not enabled for the current project
• the current issue type is excluded by project settings
• the project is in full disable mode
• the issue is a subtask and the project is configured for All Standard Issue Types

Understand Approval Status

Individual approver statuses

Each approver has one of these decision states. Paused, Ineligible, and lock indicators provide additional information; they do not replace the approver’s recorded decision state.

Status	Meaning
Added	The approver has been assigned but review has not yet been requested. An assignment email is separate from the review request.
Pending	Review has been requested; the approver is awaiting a decision, subject to permissions and restrictions. This does not guarantee email delivery.
Approved	The approver has approved the issue.
Returned	The approver has returned the issue for changes.

Overall issue statuses

The issue-level approval status shown in the panel and BSO - Status field can be:

Status	Meaning
Not Started	No approvers are assigned, or all assigned approvers are still Added and approval has not entered review.
Awaiting Decisions	Approval has started, the threshold has not yet been met, and remaining decisions can still satisfy it. A recorded decision is not required.
Approval Passed	The configured approval threshold has been met.
Approval Failed	Remaining decisions can no longer satisfy the threshold.
Paused	Approval would otherwise be Awaiting Decisions, and all approvers currently awaiting a decision have paused waiting time.

Paused replaces only Awaiting Decisions; it does not replace Not Started, Approval Passed, or Approval Failed. If any approver currently awaiting a decision has an active waiting clock, the issue remains Awaiting Decisions. Newly added approvers who have not entered review do not prevent Paused.

The overall status is determined by whether the approved percentage meets the configured threshold. A Returned decision does not automatically fail the issue if the remaining decisions can still meet the threshold. At a 100% threshold, one return makes passing impossible.

Example with a 75% threshold and 4 approvers:

• 3 Approved, 1 Pending = Approval Passed (75% ≥ 75%)
• 2 Approved, 2 Pending = Awaiting Decisions (50% < 75%)
• 2 Approved, 1 Returned, 1 Pending = Awaiting Decisions (one more approval can reach 75%)
• 1 Approved, 2 Returned, 1 Pending = Approval Failed (even the remaining approval cannot reach 75%)
• 3 Approved, 1 Returned = Approval Passed (75% ≥ 75%)

Paused Approval Waiting Time

When configured by your administrator, approval waiting time pauses when an issue leaves an active workflow status, such as when work is placed on hold, and resumes when it returns to an active status. The issue panel and both dashboard gadgets show a Paused badge on affected approvers. This is enabled by default; an administrator can change the setting.

Pausing waiting time does not itself record a decision. A Pending approver retains that decision state alongside the Paused indicator. Turning the feature off prevents new pauses; an already-paused clock can still resume.

Add an Approver

If you have permission to manage approvers on the current issue, you can add approvers from the panel.

1. Open the Jira issue.
2. In the Business Sign-off panel, click Add Approver.
3. Search for a user by name.
4. Select the user from the result list.

Business Sign-off only shows users who are currently eligible based on project settings and current issue context. Depending on configuration, a user may be excluded because:

• they lack Browse Projects access to the project
• they are not in an allowed project role
• they are not in an allowed Jira group
• they are the issue reporter and reporter SoD is enabled
• they are the issue assignee and assignee SoD is enabled
• their account is inactive

Browse the available eligible candidates, or type at least two characters to search by name. If a user is missing, ask your administrator to check eligibility and project access.

Notify Approvers or Request Re-review

After approvers are added, users with approver-management permission can send review notifications from the panel. Adding an approver may send an assignment email, but Notify Approvers is the separate action that requests review.

Open Notify Approvers to choose one of these actions:

• Notify new approvers only: sends email to approvers still in Added status and moves them into Pending
• Notify all new and pending approvers: sends email to all undecided approvers
• Reset all decisions and notify all approvers: requests another review and resets unlocked decisions to Pending; locked approvals are skipped

The dialog also shows:

• how many approvers have never been notified
• how many are pending
• how many approved
• how many returned
• when approvers were last notified
• whether locked decisions will be skipped during re-review

You can include an optional note of up to 150 characters when notifying or requesting re-review.

Notification rate limiting helps prevent duplicate reminder notifications. Repeated Notify Approvers requests may skip reminders. This reminder limit does not apply to Re-review Requested or Approver Added notifications.

Approve or Return an Issue

Only the approver themselves can record their own decision.

1. Open the issue.
2. In your approver row, click Approve or Return.
3. Enter a comment if the project requires it.
4. Submit the decision.

Decision comments are limited to 450 characters. Depending on project settings, comments may be required for approval, return, both, or neither. Withdrawal always requires a comment.

An approver cannot submit a decision while still in Added status. They must first be notified and move into Pending status.

Change or Withdraw a Decision

If project settings allow it, an approver who has already decided can click Change Decision.

From the change-decision dialog, the approver can:

• switch from Approved to Returned
• switch from Returned to Approved
• Withdraw the decision back to Pending

Decision restrictions:

• withdrawing a decision always requires a comment
• approved decisions can be locked after an issue status change if decision locking is enabled
• returned decisions are not locked by the same status-change rule

If a decision is locked, the panel shows a lock indicator and you cannot change or withdraw that approval. Re-review and workflow resets skip locked approvals. A Returned decision is not locked by this status-change rule, though other permissions or restrictions can still prevent an action.

If your role, group membership, project access, or Separation of Duties eligibility changes, the panel can show an Ineligible indicator and explanation. Read that explanation and contact your administrator if access or configuration needs review.

Remove an Approver

Users who can manage approvers can remove them from the issue panel.

1. Find the approver row.
2. Click Remove.
3. Confirm the action.

If the approver already approved or returned, the confirmation dialog warns that removing them will discard their recorded decision from the live approval state.

Removal changes the approver list and can change the overall approval outcome; it does not erase the historical approval record. Removing an approver does not send a separate removal email. If removal changes the outcome to passed or failed, reporter/assignee outcome emails may be sent according to project preferences.

Review Audit History

In the issue panel, click History to open the issue’s Audit History.

The history modal shows:

• approval statistics for the current issue
• the current overall approval status
• paged history entries
• a Decisions Only filter
• an All filter

History records show participating users, action times, and comments where applicable. Use All or Decisions Only to focus the list. Administrative CSV exports can include integrity verification, but native Jira records are not protected against editing or deletion by users with the relevant permissions. Ask your administrator about evidence exports; see the Cloud Privacy Policy for personal-data handling.

Depending on the issue history, entries can include:

• approver added
• approver removed
• approved
• returned
• decision changed
• decision reset
• notification sent
• reminder sent (from a manual Notify Approvers action)
• re-review requested
• approval status changed

Custom Fields, Search, and Reporting

Business Sign-off provides two read-only, App-managed Jira fields:

• BSO - Approvers
• BSO - Status

The App updates these fields automatically. Use them in Jira list columns, dashboards, and searches. Manage assignments and decisions through BSO actions in the issue panel; you cannot directly edit the fields.

BSO - Status

BSO - Status can be added to issue navigator views, dashboards, and reports. It shows one of these values:

• Not Started
• Awaiting Decisions
• Approval Passed
• Approval Failed
• Paused

Example JQL searches:

"BSO - Status" = "Approval Passed"

"BSO - Status" in ("Awaiting Decisions", "Approval Failed")

"BSO - Status" IS NOT EMPTY

Find paused approval work:

"BSO - Status" = "Paused"

BSO - Approvers

BSO - Approvers displays the current approver list. It is read-only, including on issue edit screens, in bulk edits, and through the Jira REST API. Manage approvers through the issue panel or administrator-configured workflow actions.

Find issues where you are an approver:

"BSO - Approvers" = currentUser()

Find issues without assigned approvers:

"BSO - Approvers" IS EMPTY

A reporting-field delay does not mean assignments, decisions, or audit history were lost. If a field looks stale, open the issue panel and ask your administrator for help.

Dashboard Gadgets

Business Sign-off ships two Jira dashboard gadgets that give you a personal view of approval work in progress. Both are scoped to you: they show only issues where you are involved, and each person sees their own results even when the dashboard is shared with a team.

Both gadgets show open Jira issues only. The gadget’s approval-state filter is separate from the issue’s Jira workflow status. For approval history, closed-issue reporting, or audit evidence, see Reporting on Closed Issues below.

Adding and Configuring Gadgets

To add a gadget:

1. In the Jira left sidebar, expand Dashboards. Starred dashboards are listed directly underneath; use View all dashboards to find others, or the + beside Dashboards to create a new one.
2. Open the dashboard and click Edit. The header switches to edit mode and shows Add gadget, Change layout, and Done.
3. Click Add gadget to open the Add a Gadget panel on the right.
4. Type BSO in the Search gadgets box.
5. Click Add on BSO - My Approval Queue or BSO - My Approval Requests.
6. The new gadget opens its configuration form straight away. Set the options and click Save. To accept the defaults, save without changing anything.
7. Close the Add a Gadget panel and click Done to leave edit mode. Dashboard changes save automatically as you make them.

To change a gadget’s options:

Gadget configuration is only available while the dashboard is in edit mode.

1. Click Edit on the dashboard.
2. On the gadget you want to change, open the ⋯ menu and choose Configure.
3. Set the options and click Save.
4. Click Done to leave edit mode.

The same ⋯ menu also offers Duplicate, Delete, and a Highlight color for the bar across the top of the gadget. Each gadget instance keeps its own settings, so you can add the same gadget more than once with different filters. A common setup is one copy filtered to a single project and another showing all projects.

Outside edit mode, each gadget header has controls to collapse, maximize, refresh, and copy a link to the gadget. The i icon shows a one-line summary of what the gadget lists.

A valid Business Sign-off license is required. If the license has lapsed, the gadget shows a license message in place of results.

Note: Atlassian periodically updates the Jira Cloud navigation. The exact menu labels and paths may vary slightly from what is described here.

Screenshot coming soonThe Business Sign-off gadgets in the Jira Add a Gadget panel.

BSO - My Approval Queue

Lists open issues where you are an approver. This is your personal approval inbox: the work waiting on your decision.

Each row shows:

Column	Description
Type	The issue type icon
Key	The issue key, linked to the issue
Summary	The issue summary
Issue Status	The Jira workflow status
My Decision	Your status on this issue: Added, Pending, Approved, or Returned; a separate Paused badge can accompany Pending
Decided	Approvers who have approved or returned, out of the total approvers on the issue
Days	Time in your current approver status; Pending waiting time excludes paused periods. This is not the Jira workflow-status age.

Configuration options:

Option	Choices	Default
Approval Status	Select one or more: Added (not yet notified), Pending (needs my action), Approved by me, Returned by me, Paused; or choose All	Pending
Project	All Projects, or a single project	All Projects
Max Results	10, 25, 50, All	10
Refresh Interval	Never, Every 15 Minutes, Every 30 Minutes, Every 1 Hour, Every 2 Hours	Never

Pending excludes paused approvers. Select both Pending and Paused to include active and paused requests awaiting your decision. Select at least one status before saving; All includes every approver status.

When you filter to a single project, the gadget title updates to include the project key. That makes multiple copies of the gadget easy to tell apart on the same dashboard.

Screenshot coming soonThe BSO - My Approval Queue gadget on a Jira dashboard.

BSO - My Approval Requests

Lists open issues where you are the reporter, assignee, or either, according to your configuration, and which have approvers attached, along with their approval state. Use this to track requests you are waiting on, as opposed to decisions you owe other people.

Issues with no approvers attached are not shown. Without approvers there is no approval request to track.

Rows show Type, Key, Summary, Issue Status, Decided, and Days columns, plus BSO Status. Here Days reflects approval waiting time or the age of a settled approval/return, rather than time in the Jira workflow status. Paused waiting periods are excluded where applicable.

The Open approval-state filter includes Not Started, Awaiting Decisions, and Paused. Returned selects Approval Failed; an issue with an individual Returned decision can still be Awaiting Decisions or Approval Passed.

Column	Description
BSO Status	The overall approval state: Not Started, Awaiting Decisions, Approval Passed, Approval Failed, or Paused

Rows are expandable. Click the expand control to view individual approver status, decision date, and waiting time, including Paused indicators. Open the issue to read full decision comments. Expand all and Collapse all controls apply to all rows at once.

Configuration options:

Option	Choices	Default
Show issues where I am	Reporter, Assignee, Either reporter or assignee	Reporter
Approval State	Open (Not Started, Awaiting Decisions, or Paused), Returned (Approval Failed), Approved (Approval Passed), All states	Open
Project	All Projects, or a single project	All Projects
Max Results	10, 25, 50, 100, All	50
Refresh Interval	Never, Every 5 minutes, Every 15 minutes	Never

This gadget has a 500-issue reporting limit. If a banner says the results were truncated, select a project to narrow the list. Max Results = All still respects this limit; it does not show every matching Jira issue when there are more than 500.

Screenshot coming soonThe BSO - My Approval Requests gadget with a row expanded to show per-approver status.

Reporting on Closed Issues

Both gadgets are deliberately scoped to work in progress, so neither is the right tool for approval history, throughput reporting, or audit evidence.

For those, build Jira filters and dashboards on the BSO custom fields described in Custom Fields, Search, and Reporting:

"BSO - Approvers" = currentUser() AND "BSO - Status" = "Approval Passed" AND resolved >= -30d

"BSO - Status" = "Approval Failed" AND project = PROJ AND updated >= -7d

Those filters work with any standard Jira gadget, such as Filter Results or Pie Chart. Your Jira administrator can also use supported audit CSV exports when you need evidence for review. Jira’s resolved and updated dates measure Jira activity, not the exact approval date; use approval history or audit exports for event dates.

Email Notifications

Depending on project configuration, Business Sign-off can send Jira Cloud email notifications for:

Notification	When	Who Receives
Approver Added	When a user is added as an approver	The added approver
Approval Requested	When approvers are notified for review	New or pending approvers, depending on the action
Re-review Requested	When existing decisions are reset for another review cycle	All affected approvers
Approver Decision	When an approver approves or returns	Reporter and/or assignee, if configured
Approval Outcome	When the issue reaches Approval Passed or Approval Failed	Reporter and/or assignee, if configured

Notifications are delivered through Jira Cloud/Atlassian infrastructure; no Cahaba Forge-operated external mail service is required for App notifications. Messages include relevant issue and approval context and a link back to the issue.

Notification delivery depends on Jira permissions, recipient availability, mail delivery, and project preferences. Delivery failures do not undo the underlying approval action. Review history and contact your administrator if an expected notification is missing.

Common Scenarios

Scenario: Change Approval Board

A team requires multiple approvers before an issue can move forward:

1. Approvers are added from the issue panel or via workflow post-functions.
2. Approvers are notified when the issue is ready for review.
3. Each approver approves or returns the issue from the Business Sign-off panel.
4. Workflow conditions or validators enforce the required approval state before transition.

Scenario: Regulatory Sign-off

A compliance-sensitive project needs stronger control:

1. Eligible approvers are restricted to specific project roles or Jira groups.
2. Separation of Duties prevents the reporter and/or assignee from approving.
3. Comments are required on approvals and/or returns.
4. The audit history on the issue captures the decision timeline.
5. Administrators can export approval history from the global configuration page.

Scenario: Lightweight Review

A team wants visible sign-off without introducing a new workflow status:

1. An approver is added from the issue panel.
2. The approver is notified when work is ready.
3. The approver reviews the issue and approves or returns it.
4. The team tracks live state using the panel and BSO - Status field.

Troubleshooting

The Business Sign-off panel does not appear

Check these first:

• the app is installed and enabled globally
• the current project has Business Sign-off enabled
• the current issue type is included in project settings
• the issue is not excluded by the All Standard Issue Types rule for subtasks
• the project or global configuration is not in full disable mode

Finishing Mode keeps existing approval work available while preventing new approvers from being added.

I cannot add an approver

Common causes:

• you are not allowed to manage approvers on this issue
• the project is in finishing mode
• the App license is inactive, which restricts new approvers even when existing work can continue in Finishing Mode
• the issue type no longer permits new approval work
• the user you searched for is not currently eligible because of role, group, Browse Projects access, SoD, or inactive-account rules

I cannot approve or return

Common causes:

• you are still in Added status and have not been notified yet
• you cannot view the issue, or project settings require issue-level Edit Issues permission and you do not have it
• you are no longer eligible to approve
• Separation of Duties prevents you from deciding
• your approved decision has been locked because the issue moved to a different workflow status
• the license is inactive and existing work is not permitted by the current Finishing Mode configuration
• the issue has reached Done and the displayed message explains an action restriction

Notify Approvers did not email everyone I expected

Check your approver-management permission, the selected notification option, the recipients’ current decision states, and project notification settings. Reminder rate limiting helps prevent duplicates and may skip repeated requests. It does not apply to Re-review Requested or Approver Added emails. Review notification history and ask your administrator to investigate missing delivery.

Jira asks for app access or an admin permission check seems wrong

If Jira asks you to grant App access, follow the consent prompt. If access is still refused, ask your Jira administrator to confirm your permissions and the App’s approved access. Do not assume that seeing a control grants permission to use it.

The app was updated and features stopped working after new permissions were added

If a new app version introduces new Forge scopes, a Jira administrator may need to approve the updated app access before all features resume normal operation.

If the panel disappeared after an upgrade from a version before 1.2.0, ask your administrator to approve the added permissions and save Business Sign-off project settings for previously enabled projects. Approval data is not lost; see the Administrator Guide for the required steps.

The app shows a license warning

When the Marketplace license is inactive, existing approval data and history remain available where the panel is visible. Adding approvers and other new-work operations are restricted. Existing approval work can continue when finishing mode is already enabled, including recording, withdrawing, and resetting decisions, subject to normal permissions and decision locks. Dashboard gadgets display a license message instead of results.

License expiry does not automatically bypass workflow approval checks. Configuration changes require an active license, so an administrator cannot rely on enabling finishing mode after expiry. Ask your administrator to review the subscription and existing configuration.

The app is in Finishing Mode

Finishing Mode allows existing approval work to continue while preventing new approvers from being added. It does not automatically end when pending approvals are completed or cleared. An administrator must change and save the configuration to re-enable BSO or fully disable it.

FAQ

Why does my approver row say Added instead of Pending?

Added means you have been assigned but review has not yet been requested. An Approver Added email does not itself start review. Ask someone with approver-management permission to use Notify Approvers; Pending decision controls are subject to your permissions and eligibility.

Are the BSO custom fields editable?

No. BSO - Approvers and BSO - Status are read-only, App-managed fields for visibility, search, and reporting. Manage approvers through the issue panel or configured workflow actions.

Where should users go for setup help?

Use the Cloud Administrator Guide for global setup, project configuration, workflow rules, audit export, and other admin-facing tasks.

← Back to Documentation

For administrator setup instructions, see the Cloud Administrator Guide.

Cahaba Forge LLC | https://cahabaforge.com