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

In Jira Cloud, Business Sign-off is surfaced through the issue view, Jira administration, project settings, workflow conditions, workflow validators, workflow post-functions, and two read-only synced custom fields.

What's Changed from the Data Center Version

If you used the Data Center version, these are the changes that matter most:

• Installation is now Cloud-first. You install the app from Atlassian Marketplace or your Cloud distribution flow, not by uploading a JAR through Universal Plugin Manager.
• The panel remains on the issue view, but the platform is different. The app now runs on Atlassian Forge and uses Jira Cloud extension points instead of a server-side plugin.
• The approver decision vocabulary is the same. Both the Cloud and Data Center versions use Return for sending work back for changes.
• The overall status model changed slightly. In Cloud, an issue can show Not Started when approvers exist but none have been notified yet.
• The BSO custom fields are synced, read-only Cloud fields. They are no longer a place where the app itself provides custom editing UI. The live approver workflow happens in the issue panel and through workflow automation.
• The old custom JQL functions from Data Center are not part of the Forge version. In Cloud, use synced fields such as BSO - Status in Jira search and reporting instead.
• Global and project configuration moved to Jira Cloud app locations.
  Global configuration: Jira administration under Apps
  Project configuration: Project settings → Apps
• No server-side configuration exists. There are no filesystem changes, database changes, or server console steps in the Cloud version.
• Audit and compliance records are still core to the product. The Forge version keeps issue-level approval history, synced fields, and audit export features, but the storage model is Atlassian-hosted rather than Data Center-hosted.

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 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
• 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 the current issue type is included in the project configuration, the panel appears on the Jira issue view.

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 statuses:

Status	Meaning
Added	The approver has been assigned but has not yet been notified for review.
Pending	The approver has been notified and can now approve or return the issue.
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	Approvers exist, but none have been notified yet.
Awaiting Decisions	Review is in progress and no return has occurred yet.
Approval Passed	The configured threshold has been met with approvals.
Approval Failed	The approved percentage does not meet the configured threshold.

The overall status is determined by whether the approved percentage meets the configured threshold. A Returned decision does not automatically fail the issue — it only contributes to the approval calculation like any non-approval.

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 = Approval Failed (50% < 75%)
• 3 Approved, 1 Returned = Approval Passed (75% ≥ 75%)

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 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

If you type fewer than two characters, the dialog waits for more input. If you want to browse eligible users without typing a search term, use the people icon button in the dialog.

Notify Approvers or Request Re-review

After approvers are added, the panel can send review notifications.

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: clears existing decisions back to Pending and asks everyone to review again

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.

Business Sign-off skips some same-day notification repeats. If an approver was already notified earlier that day, they may be skipped by the bulk notification action.

The Notify Approvers action is permission-based. In the current Forge implementation, it is intended for the issue reporter, issue assignee, or a Jira/project administrator.

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.

Comments are limited to 450 characters in the Forge version.

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

Important Cloud behavior:

• 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 the user cannot change it.

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.

Review Audit History

The issue panel includes Audit History, which opens an issue-level history modal.

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

Depending on the issue history, entries can include:

• approver added
• approver removed
• approved
• returned
• decision changed
• decision reset
• notification sent
• reminder sent
• re-review requested
• approval status changed

Custom Fields, Search, and Reporting

The Forge version ships with two synced Jira custom fields:

• BSO - Approvers
• BSO - Status

These fields are updated by the app from live approval data. In the Forge version, they are read-only synced fields. They are not the primary place where users work with approvals.

Cloud behavior to note:

• the app no longer relies on custom JQL functions such as bsoApprovers() or bsoStatus()
• the main user workflow is the issue panel
• synced fields are primarily for Jira-native list views, dashboards, exports, and searching

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

Example Jira Cloud JQL using the synced status field:

"BSO - Status" = "Approval Passed"

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

"BSO - Status" is not EMPTY

BSO - Approvers

BSO - Approvers is a synced list of the current approvers on the issue. It is useful for visibility and reporting, but in the Forge version the actual approver-management workflow happens in the issue panel and workflow automation.

The create/edit-screen behavior in Jira Cloud is not the same as the old server-style custom field workflow. In the Forge version, the live approval workflow happens in the issue panel and through workflow automation.

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

Notification emails are sent through Jira Cloud's native issue notification API and include a link back to the issue.

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 automation.
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

If the app is in Finishing Mode, the panel may remain visible only on issues that already have approvers.

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 and the panel is in read-only mode
• the user you searched for is not currently eligible because of role, group, SoD, or inactive-account rules

I cannot approve or return

Common causes:

• you are still in Added status and have not been notified yet
• project settings require 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

Notify Approvers did not email everyone I expected

The app skips some repeat notifications on the same day. If an approver was already notified earlier that day, the bulk notify action may skip them.

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

The app uses Jira Cloud user-context checks for some administrator/project-administrator detection. If the required user consent is missing, Jira may treat the admin check as unavailable until access is granted again.

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.

The app shows a license warning

When the Marketplace license is inactive, Business Sign-off stays visible in read-only mode where possible. Existing history remains visible, but write actions such as adding approvers or recording decisions are blocked until the license is active again.

FAQ

Why does my approver row say Added instead of Pending?

Added means you have been assigned as an approver but have not yet been notified for review. Once a notification is sent, your status changes to Pending and the decision buttons become available.

Why does the Cloud guide say Return instead of Reject?

The Forge version uses Return as the decision label for sending work back for changes.

Can I use the old custom JQL functions from the server version?

No. The Forge version uses synced Jira Cloud custom fields and issue properties instead of the older server-style custom JQL functions.

Are the BSO custom fields editable?

Not as part of the normal approval workflow. In the Forge version, BSO - Approvers and BSO - Status are synced app-managed fields used for visibility, search, and reporting.

Where should users go for setup help?

Use the 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 Administrator Guide.

Cahaba Forge LLC | https://cahabaforge.com