Jira Cloud Approval Workflow Admin Guide

Last Updated: October 10, 2026
Vendor: Cahaba Forge LLC

Cahaba Forge™ is a trademark of Cahaba Forge LLC.
Atlassian, Jira, and Forge are trademarks of Atlassian Pty Ltd.

This guide covers Jira Cloud behavior documented through release 1.6.2. See the Release Notes for version-specific changes.

Installation
Licensing
Global Configuration
Project Configuration
Custom Fields
Workflow Integration
Automation & Integration
Configuring Separation of Duties
Email Notifications
Audit Trail & Export
Admin Audit Log
Troubleshooting
Getting Help

1. Installation

Business Sign-off is a Forge app distributed through the Atlassian Marketplace. Unlike Data Center plugins, there are no JAR files, certificates, or server-side installations. Atlassian hosts and runs the app entirely within the Forge platform.

Installing from Atlassian Marketplace

Log in to your Jira Cloud instance as a Site Administrator
Go to Settings (gear icon) > Marketplace apps
You may be redirected to the new Connected apps page — if so, click Explore in the left sidebar
Search for Business Sign-off & Approval for Jira
Click Get app (or Try it free for an evaluation)
Review the requested permissions and click Get it now
Atlassian installs the app automatically — no restart or downtime required

Alternatively, visit the Atlassian Marketplace directly, search for the app, and click Get it now to install it on your Jira Cloud site.

Required Permissions and Scopes

During installation or an upgrade that adds permissions, the site administrator must review and authorize the App’s requested scopes.

Scope	Purpose
`storage:app`	Retain approval information, settings, and audit history within Atlassian’s infrastructure
`read:jira-work`	Read issue and project information needed for approvals
`write:jira-work`	Update approval-related Jira data
`read:jira-user`	Read user information for approver selection and display
`manage:jira-configuration`	Support configured Jira operations, including approval notifications
`write:app-data:jira`	Update app-managed Jira data
`report:personal-data`	Support Atlassian personal-data reporting
`write:project.property:jira`	Manage project-level panel visibility
`delete:project.property:jira`	Remove project-level panel visibility settings

The App’s installed permissions do not grant users unrestricted access. Issue-specific actions and lookups require permission to view the issue. Decision recording also checks issue-level Edit Issues permission when that setting is enabled. Global administration and audit exports require Jira administrator permission.

Upgrade from a version before 1.2.0: Approve the added project-property permissions, then open Project Settings → Business Sign-off and click Save for each previously enabled project. Reload the issue afterward. Approval data is not lost if the panel is temporarily hidden.

Accessing the App After Installation

Once installed, the app is available from:

Global configuration: Settings (gear icon) > Marketplace apps > find Business Sign-off & Approval for Jira in the Connected apps list > click … (three dots) > Configure
Project configuration: From your project board, click … (three dots) > Board settings > View space settings > Apps > Business Sign-off
Issue panel: The sign-off panel appears automatically in the issue context sidebar for enabled projects

Note: Only Jira Site Administrators can access the global configuration page. Project Administrators can access project-level settings.

Navigation shorthand: Throughout this guide, we use “Global Config” to refer to the full path: Settings (gear icon) > Marketplace apps > Connected apps > Business Sign-off > … > Configure. We use “Project Settings” to refer to: From your project board, click … (three dots) > Board settings > View space settings > Apps > Business Sign-off.

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

No Server Setup Required

Business Sign-off runs entirely on Atlassian’s Forge platform. There is no need to:

Provision or manage servers
Install certificates or trust stores
Configure file system paths or JVM arguments
Manage database connections or schemas

App-managed approval information is processed and stored within Atlassian’s infrastructure. Product support information sent directly to Cahaba Forge is covered separately in the Cloud Privacy Policy.

2. Licensing

Business Sign-off licensing is managed entirely by the Atlassian Marketplace. There are no license keys to copy, paste, or manage manually.

License States

State	Behavior
Active subscription	Licensed features available, subject to configuration and permissions
Evaluation / Trial	Features available during the Marketplace-managed trial
Inactive / Expired	New approval work restricted; existing-work and data-access exceptions described below

Atlassian manages available license types and eligibility for special licenses. Check the Marketplace subscription terms applicable to your site.

License Status Display

The global administration page displays the current license status in the header area. The status indicator shows:

The license status (e.g., ACTIVE)
The subscription expiry date (if applicable)

Trial Period

When you install the app for the first time, Atlassian automatically starts a free trial period. The trial duration is determined by Atlassian Marketplace policies (typically 30 days). During the trial, all features are fully functional with no restrictions.

What Happens When a License Expires

When the license becomes inactive:

Existing approval data and history remain available.
New approvers and other new-work operations remain restricted until the license is renewed.
Existing approval work can continue when the project is in finishing mode, including recording, withdrawing, and resetting decisions.
Personal-data reports, audit-history exports, and export cleanup remain available regardless of license state, subject to administrator permissions.
The issue panel explains license and finishing-mode restrictions.

License expiry is different from uninstalling. Do not uninstall as a renewal or recovery step; see the Cloud Privacy Policy for uninstall retention and recovery limitations.

Workflow checks: License expiry alone does not bypass BSO workflow conditions or validators. While BSO remains enabled, the three conditions and three validators continue to apply their configured checks. Do not rely on an expired license to unblock a transition. Full Disable and Finishing Mode bypass the validators; the individual condition behavior is described in Section 6.

Configuration changes require an active license. To continue existing approval work after expiry, finishing mode must already be enabled.

Tip: Manage your subscription at admin.atlassian.com.

3. Global Configuration

Access the global configuration page from Global Config. The configuration page opens to the Settings tab.

Only Jira Site Administrators can access this page.

If another administrator saves a conflicting change while you are editing, reload the latest configuration before reapplying your changes.

3.1 Plugin Enable/Disable

Toggle the Enable Plugin switch to activate or deactivate Business Sign-off across all projects.

When fully disabled:

All approval operations are blocked
Issue panels are hidden
Workflow approval enforcement is relaxed; see Section 6 for individual condition and validator behavior
Existing data is preserved (non-destructive)

Disable dialog: When turning the plugin off, a confirmation dialog presents two options:

Full Disable — immediately disables the plugin. All pending approvals are frozen in their current state. No new approvers can be added, and no decisions can be recorded.
Finishing Mode — the plugin enters a transitional state where existing approvers can still complete their decisions, but no new approvers can be added to any issue. Use Full Disable when you are ready to stop all approval work.

Finishing Mode is useful when you need to decommission the plugin gracefully without disrupting in-flight approvals.

Finishing Mode does not automatically exit when pending approvals are resolved or cleared. An administrator must change and save the configuration to re-enable BSO or fully disable it.

3.2 Approval Threshold

Set the global default percentage of approvals required for an issue to pass:

Threshold	Meaning	Example (4 approvers)
50%	At least half	2 must approve
66%	At least 66%	3 must approve
75%	Three-quarters majority	3 must approve
90%	Near-unanimous	4 must approve
100%	Unanimous	All 4 must approve

The number of required approvals is rounded up to a whole person. For example, a 75% threshold with 3 approvers requires all 3 to approve.

An approval remains Awaiting Decisions while the threshold remains reachable. With 4 approvers and a 75% threshold, 2 approvals, 1 return, and 1 outstanding decision can still pass. If 2 approvers return, passing is no longer possible. At 100%, one return makes the outcome fail.

Allow Project Threshold Override: When enabled, project administrators can set a different threshold for their project, subject to the minimum threshold floor.

Minimum Threshold: Sets the lowest threshold a project can configure. This prevents project administrators from setting an inappropriately low bar for approval. The minimum threshold must be less than or equal to the global threshold.

Note: If you change the minimum threshold to a value higher than a project’s current override, the project’s effective threshold is raised to the new minimum on the next evaluation.

3.3 Eligible Approver Controls

Restrict who can serve as an approver across the instance. In both modes below, a candidate must also hold Browse Projects access to the issue’s project — a user without that access is not offered as an eligible approver.

Mode selection:

All Jira users — any user who holds Browse Projects access to the project can be added as an approver (subject to Decision Authority and SoD rules). This is not the whole Jira instance’s user directory — it’s every user the project’s permission scheme actually grants project access to.
Selected users only — only users matching the configured filters, and who also hold Browse Projects access, can be approvers

Filters (available when “Selected users only” is chosen):

Filter by Project Roles — toggle on, then select one or more project roles from the multi-select dropdown. Users in any of the selected roles for the issue’s project are eligible, provided they also have Browse Projects access.
Filter by User Groups — toggle on, then select one or more Jira groups from the multi-select dropdown. Users in any of the selected groups are eligible, provided they also have Browse Projects access.

Filters use OR logic: a user is eligible if they match any selected role or any selected group, and holds Browse Projects access. At least one filter must be enabled with at least one value selected.

Allow Project Eligible Approver Override: When enabled, project administrators can configure different eligible approver filters for their project.

Tip: If you select a project role that has no members in a particular project, no users from that role will be eligible in that project. Verify that selected roles are populated in the projects where you need them.

Tip: Role and group membership is independent of Browse Projects access in Jira’s permission scheme — an admin can configure the two inconsistently. If a configured role or group doesn’t also grant Browse Projects, its members won’t appear as eligible approvers until the project’s permission scheme is updated.

3.4 Decision Authority

The Require Edit Permission to Decide toggle controls the permission level required for an approver to record a decision (approve or return).

ON: Approvers must have Edit Issues permission for the specific issue to record their decision. This is the more restrictive setting and is appropriate when all approvers are active project contributors.
OFF: Approvers only need Browse Projects permission to record their decision. This is useful for read-only stakeholders, external reviewers, or users who need to approve work without having full edit access to the project. Issue-specific visibility and security restrictions still apply. Previously assigned approvers who lose project access are flagged in the panel.

Allow Project Decision Authority Override: When enabled, project administrators can set a different decision authority requirement for their project.

Note: Decision Authority controls who can decide (approve or return). It does not control who can be added as an approver — that is governed by Eligible Approver Controls and Approver Management Permissions.

3.5 Approver Management Permissions

Configure who can add and remove approvers from the issue panel. Three toggles control this:

Allow Reporter — the person who created the issue can add and remove approvers
Allow Assignee — the person assigned to the issue can add and remove approvers
Allow Administrators — Jira site administrators and project administrators can add and remove approvers

At least one of these toggles must be enabled. The app enforces this requirement and will not allow you to disable all three.

Note: These settings also govern Notify Approvers from the issue panel. Configured workflow actions manage approvers independently of the panel’s management settings, subject to their eligibility and approval rules.

3.6 Comment Requirements

Configure when approvers must provide a comment with their decision:

Option	Behavior
Always	Comment required for both approvals and returns
Approval Only	Comment required only when approving
Return Only	Comment required only when returning
Never	Comments are always optional

When a comment is required, the approver must enter text before submitting their decision. The decision button is disabled until a comment is provided.

Allow Project Comment Override: When enabled, project administrators can set different comment requirements for their project.

3.7 Separation of Duties (SoD)

Configure which issue participants cannot serve as approvers:

Assignee Cannot Approve — when enabled, the person assigned to work on the issue cannot approve or return it
Reporter Cannot Approve — when enabled, the person who created the issue cannot approve or return it

How violations are enforced:

When a SoD rule is active, the plugin enforces it at every decision point:

An approver who violates SoD is marked as ineligible in the issue panel. They retain their Added, Pending, Approved, or Returned status and show a separate eligibility indicator explaining the reason.
Ineligible approvers cannot record a decision — the approve and return buttons are hidden for them.
If an approver has already recorded a decision and the assignee or reporter later changes to match them, the plugin re-evaluates SoD in real time. The approver’s existing decision is preserved but flagged, and they cannot change or revoke it while the violation is active.
SoD enforcement is logged in the audit trail.

Allow Project SoD Override: When enabled, project administrators can set different SoD rules for their project.

Tip: For compliance frameworks like SOC 2 or SOX, enable both SoD toggles globally and do not allow project overrides. This ensures consistent enforcement across all projects.

3.8 Decision Locking

The Decision Locking Enabled toggle controls whether approved decisions become locked against changes after the issue transitions to a different workflow status.

How it works:

An approval is associated with the workflow status in which it was recorded.
If the issue later transitions to a different status, any APPROVED decisions from the previous status become locked.
Locked approvers see a lock icon next to their status in the issue panel. The “Change Decision” button is hidden, and a tooltip explains that the decision is locked because the issue has moved to a different status.
If the issue returns to the original status where the approval was recorded, the lock is released and the approver can change their decision.

Important details:

Only APPROVED decisions are locked. RETURNED (rejected) decisions are never locked, regardless of status transitions. This allows approvers who returned an issue to change their mind if the issue is reworked and re-submitted.
The Reset Approval Status post-function respects decision locking — it skips locked approvals and only resets unlocked decisions. Use its reset mode and role/group filter to target specific decision statuses or approvers (these replace the deprecated Reset Decisions by Role/Group post-function).
Check the lock indicator before relying on a particular decision being protected.

Allow Project Decision Lock Override: When enabled, project administrators can enable or disable decision locking for their project.

3.9 Diagnostic Logging

Enable diagnostic logging to help Cahaba Forge support investigate a reproducible problem.

Duration	Use case
1 hour	Quick investigation of a specific issue
2 hours	Reproducing an intermittent problem
4 hours	Monitoring a workflow during a release cycle
8 hours	Extended troubleshooting session

Select a duration, save the settings, and reproduce the problem. Additional diagnostic logging expires after the configured duration; this does not delete logs already collected. Standard operational error and warning logs remain active.

Access: Authorized Cahaba Forge developers can review platform-hosted logs through Atlassian’s controls. Jira administrators should contact support@cahabaforge.com rather than expecting access to the App’s Developer Console.

Privacy: Logs can include account and issue identifiers used for troubleshooting. See the Cloud Privacy Policy for logging, access, and retention information.

Tip: Use the shortest practical duration. Include the approximate reproduction time and whether diagnostics were enabled in your support request.

3.10 Pausing Approval Waiting Time

Approval waiting-time clocks pause when an issue leaves an active workflow status, such as when work is placed on hold, and resume when it returns to an active status. The issue panel and both BSO dashboard gadgets show a Paused badge on affected approvers.

This feature is enabled by default. Configure it in Business Sign-off → Settings, globally or through an available project override. Turn it off if your team prefers waiting-time figures that continue while work is inactive. Turning it off prevents new pauses; an already-paused clock can still resume.

Search the Paused BSO status with "BSO - Status" = "Paused".

4. Project Configuration

Access project-level settings from Project Settings.

Project Administrators and Jira Administrators can access project configuration. The global plugin must be enabled for project settings to take effect. If a save reports a conflicting administrator change, reload the latest configuration before trying again.

4.1 Enable for Project

Toggle Business Sign-off on or off for the project. When disabled:

The issue panel is hidden for all issues in the project
No new approvers can be added
Existing approver data is preserved

The project toggle requires the global plugin to be enabled. If the global plugin is disabled, the project toggle has no effect.

Finishing Mode: When disabling a project, a confirmation dialog presents the same two options as the global disable:

Full Disable — immediately disables the plugin for the project
Finishing Mode — existing approvers can complete their decisions, but no new approvers can be added. Finishing Mode remains active after pending approvals are resolved until an administrator changes and saves the configuration.

4.2 Panel Visibility

Choose which issue types can begin new approval work:

All standard issue types — standard issue types are included; subtasks are excluded by default.
Selected issue types — select the issue types that should support approvals from the project’s list.

The same issue-type eligibility applies to adding approvers through the panel and configured workflow actions.

If an issue already has approvers when its type becomes ineligible, the panel remains available for existing decisions, resets, removals, and administrator cleanup. A banner explains that new approvals are no longer allowed. Changing allowed types does not require discarding existing approval work.

Note: If a selected issue type is removed from the project, review and save your issue-type settings.

4.3 Approval Required

The Approval Required toggle controls whether Require Approval Passed can allow an issue with no assigned approvers to transition.

ON: Require Approval Passed blocks an issue that has not met its approval threshold, including an issue with no approvers.
OFF: Require Approval Passed passes when no approvers are assigned. If approvers are assigned, it still enforces the approval threshold. The Issue Has Approvers and Issue Is Approved conditions also allow the no-approvers exception.

Require Approvers still requires at least one eligible approver while BSO is enabled, regardless of Approval Required. Require Group/Role Approval still enforces its configured rules. Do not add these validators to a transition that should allow an issue without the required approvers.

Tip: For optional sign-offs, turn Approval Required OFF and review which validators are attached to the transition; this setting does not bypass every validator.

4.4 Threshold Override

This section is only visible if the global administrator has enabled Allow Project Threshold Override.

Use Global Setting — the project inherits the global threshold (displayed for reference)
Override — select a project-specific threshold from the dropdown

The override value must meet or exceed the Minimum Threshold configured globally. If the global minimum is 66%, the project cannot set a threshold below 66%.

4.5 Eligible Approver Override

This section is only visible if the global administrator has enabled Allow Project Eligible Approver Override.

Use Global Setting — the project inherits the global eligible approver mode and filters
Override — configure project-specific eligibility rules with the same options available globally (mode selection, role filters, group filters)

Project-level role filters apply to roles defined in the current project. If the project does not have a role that is selected in the filter, no users from that role will be eligible.

4.6 Decision Authority Override

This section is only visible if the global administrator has enabled Allow Project Decision Authority Override.

Use Global Setting — the project inherits the global decision authority requirement
Override — toggle the Require Edit Permission to Decide setting independently for this project

4.7 Comment Requirement Override

This section is only visible if the global administrator has enabled Allow Project Comment Override.

Use Global Setting — the project inherits the global comment requirement
Override — select a project-specific comment requirement from the dropdown (Always, Approval Only, Return Only, Never)

4.8 SoD Override

This section is only visible if the global administrator has enabled Allow Project SoD Override.

Use Global Setting — the project inherits the global SoD rules
Override — toggle Assignee Cannot Approve and Reporter Cannot Approve independently for this project

Note: Relaxing SoD rules at the project level (e.g., disabling “Assignee Cannot Approve” when it is enabled globally) may weaken compliance controls. Consider your organization’s audit requirements before overriding SoD rules.

4.9 Decision Locking Override

This section is only visible if the global administrator has enabled Allow Project Decision Lock Override.

Use Global Setting — the project inherits the global decision locking setting
Override — enable or disable decision locking independently for this project

4.10 Email Notifications

Email notification preferences are configured at the project level. Each notification type can be toggled or configured independently:

Email Approver When Added

Toggle on or off. When enabled, each approver receives an email notification when they are added to an issue. The email includes a direct link to the issue.

Email Reporter on Approver Decision

Select when to notify the issue reporter about individual approver decisions:

Option	Behavior
When Approved	Notify when an approver approves
When Returned	Notify when an approver returns
When Approved or Returned	Notify on every decision
Do Not Email	No notifications for individual decisions

Email Reporter on Approval Outcome

Select when to notify the issue reporter about the overall approval outcome (passed or failed):

Option	Behavior
When Approved	Notify when the issue reaches Approval Passed
When Returned	Notify when the issue reaches Approval Failed
When Approved or Returned	Notify on either outcome
Do Not Email	No outcome notifications

Email Assignee on Approver Decision

Same options as Email Reporter on Approver Decision, but sent to the current issue assignee.

Email Assignee on Approval Outcome

Same options as Email Reporter on Approval Outcome, but sent to the current issue assignee.

Tip: For high-volume projects, consider setting decision notifications to “Do Not Email” and using only outcome notifications. This reduces email noise while still ensuring stakeholders are informed when the final result is reached.

5. Custom Fields

Business Sign-off provides two locked, app-managed custom fields, created automatically during App installation without manual provisioning. Jira’s Fields administration shows them as LOCKED and does not offer Edit or Delete. Existing installations retain their field identifiers and values.

5.1 BSO - Approvers

A multi-user custom field that displays the current list of approvers assigned to an issue.

Key characteristics:

Type: User (collection: list)
Read-only: The field cannot be edited directly (issue edit screen, bulk edit, or REST API). Approvers are managed exclusively through the Business Sign-off issue panel and workflow post-functions.
Updated automatically: When an approver is added or removed through the issue panel or a post-function, the field reflects the current approver list. This keeps the field available for JQL, list columns, and board cards.
JQL: Searchable using standard user field syntax:
- "BSO - Approvers" = currentUser() — find issues where you are an approver
- "BSO - Approvers" = "<Atlassian account ID>" — find issues where a specific user is an approver
- "BSO - Approvers" IS NOT EMPTY — find issues with any approvers assigned

5.2 BSO - Status

A read-only field showing the issue’s approval status.

Status	Administrator-visible meaning
Not Started	No approvers are assigned, or all assigned approvers are still Added and have not entered review
Awaiting Decisions	Approval has started, the threshold is not yet met, and remaining decisions can still meet it; a recorded decision is not required for this status
Approval Passed	The configured approval threshold has been met
Approval Failed	Remaining decisions cannot meet the configured approval threshold
Paused	Approval would otherwise be Awaiting Decisions, and all approvers currently awaiting a decision have paused waiting time

Status precedence: 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 yet entered review do not prevent Paused.

Key characteristics:

Read-only: Managed through BSO actions rather than direct field edits.
JQL: Search using the displayed status:
- "BSO - Status" = "Approval Passed"
- "BSO - Status" = "Approval Failed"
- "BSO - Status" = "Paused"
- "BSO - Status" IS EMPTY
Updated automatically: Approval actions and relevant workflow changes update the field. A temporary reporting-field delay does not mean approval assignments, decisions, or audit history were lost.

5.3 Approval Statistics

Approval statistics are available for supported advanced integrations. Prefer BSO - Approvers and BSO - Status for routine searches, dashboards, and automation.

For the approval-statistics read interface, see Section 7.5. Do not write App-managed approval data to create assignments, change decisions, or override workflow checks.

5.4 Audit Persistence

BSO retains selected approval audit events as native Jira data. These records can remain after the App is uninstalled.

Integrity checks provide evidence of detected changes; they do not prevent an authorized Jira user from altering or deleting native data. Uninstalling and reinstalling does not promise automatic recovery or restoration.

Use Audit History and supported CSV exports for routine compliance review. See Section 10 and the Cloud Privacy Policy for verification, retention, and deletion information.

6. Workflow Integration

Business Sign-off provides workflow conditions, validators, and post-functions that integrate with Jira’s workflow engine. These components allow you to enforce approval requirements at transition points and automate approver management.

All workflow components support both company-managed and team-managed projects. Jira’s workflow editor and available configuration paths differ by project type.

6.1 Workflow Conditions

Conditions control whether a transition is visible to the user. If a condition is not met, the transition button does not appear. Business Sign-off provides three conditions:

Issue Has Approvers

Shows the transition only when at least one approver is assigned to the issue.

Use case: Gate a “Submit for Review” transition so it only appears after approvers have been added.
Availability: The transition can remain visible when approval information is unavailable, the App is inactive for the project, or approval is optional and no approvers are assigned. Use a validator to enforce a required approval gate.

Issue Is Approved

Shows the transition only when the approval status is Approval Passed (the approval threshold has been met).

Use case: Gate a “Deploy to Production” transition so it only appears after the issue has been approved.
Availability: The transition can remain visible when approval information is unavailable, the App is inactive, or approval is optional and no approvers are assigned. Use Require Approval Passed to enforce the approval requirement.

Issue Is Returned

Shows the transition only when the approval status is Approval Failed.

Use case: Show a “Rework” or “Send Back” transition only when the issue has been returned by approvers.
Availability: This condition hides the transition when no approval information is available or the App is inactive for the project. A return path is shown for an active failed approval.

Note: Conditions control transition visibility; validators enforce whether a requested transition can proceed. Configure both when your workflow needs both behaviors.

6.2 Workflow Validators

Validators control whether a transition is allowed to proceed. If a validator fails, the transition is blocked and an error message is displayed. Business Sign-off provides three validators:

Require Approvers

Blocks the transition unless at least one eligible approver is assigned to the issue.

Use case: Ensure that issues cannot advance past a review stage without having approvers assigned.
Behavior when Approval Required is OFF: The validator still requires at least one eligible approver while BSO is enabled; Approval Required does not bypass this validator.

Require Approval Passed

Blocks the transition unless the approval status is Approval Passed.

Use case: Prevent issues from moving to a “Done” or “Deployed” status without meeting the approval threshold.
Behavior when Approval Required is OFF: Passes when no approvers are assigned and approval is not required. If approvers are assigned, the approval threshold is still enforced.

Require Group/Role Approval

Blocks the transition unless approvers from specific groups and/or roles have approved. This validator has a configuration UI that appears in the workflow editor.

Behavior when Approval Required is OFF: Configured group/role rules still apply while BSO is enabled; Approval Required does not bypass them.

Configuration options:

Rule logic: Choose AND (all rules must be satisfied) or OR (at least one rule must be satisfied)
Rules: Add one or more rules, each specifying:
- Source type: Project role or user group
- Source value: The specific role or group
- Minimum count: Minimum number of approvers from this source that must be assigned (default: 1)
- Minimum approved: Minimum number of approvers from this source that must have approved (optional; defaults to the minimum count)

Example: To require approval from at least one member of the “QA” role and at least one member of the “Security” group, add two rules with AND logic:

Rule	Source type	Source value	Min count	Min approved
1	Project Role	QA	1	1
2	User Group	security-reviewers	1	1

6.3 Workflow Post-Functions

Post-functions automate approver management and notification tasks on workflow transitions. Business Sign-off offers the following actions:

Add Approvers

Automatically adds approvers to the issue when the transition fires.

Source types:

Source	Description
Specific users	Add named users by account ID
Project role	Add all members of a selected project role
User group	Add all members of a selected user group
User picker custom field	Add the user(s) from a specified user picker field on the issue

The configuration UI allows you to select the source type and configure the specific source. All eligibility rules (eligible approver filters, SoD) are applied when the post-function executes — ineligible users are skipped.

Remove Approvers

Removes approvers from the issue when the transition fires.

Modes:

Mode	Description
Remove all	Remove all approvers from the issue
Pending only	Remove only approvers who have not yet decided (preserves decided approvers)
Specific users	Remove named users by account ID

The configuration UI allows you to select the removal mode and, for specific users, configure which users to remove.

Notify Approvers

Sends email notifications to approvers who have not yet decided.

Modes:

Mode	Description
All undecided	Notify all approvers who have not yet approved or returned
New only (ADDED)	Notify only approvers in the ADDED status (recently added, not yet notified)
Pending only	Notify only approvers in the PENDING status (previously notified but not yet decided)

Reset Approval Status

Resets decided approvals back to PENDING, allowing the approval cycle to start over. Choose a reset mode and, optionally, a role/group filter.

Reset mode — controls which decision statuses are reset:

Reset Mode	Behavior
Reset all decisions	Resets both APPROVED and RETURNED decisions (respecting decision locking). Default.
Reset returned decisions only	Resets only RETURNED decisions. Approvals are left untouched.
Reset approved decisions only	Resets only APPROVED decisions (respecting decision locking). Returns are left untouched.

Filter by role/group (optional) — narrows the reset to approvers in the selected project role(s) and/or group(s). Toggle on Filter by Project Role and/or Filter by Group and pick the values. Filters use OR logic within the role/group dimension (an approver matches if they belong to any selected role or any selected group). Leave both toggles off to reset every approver that matches the reset mode.

An approver must match the selected decision status and any enabled role/group filter to be reset.

Notify after reset: Enabled by default. Sends a notification to affected approvers after their decisions are reset. Explicitly disabled settings remain disabled; review this option when editing older workflow configurations.

Interaction with decision locking:

Reset Mode	Decision Locking OFF	Decision Locking ON
Reset all decisions	Reset all APPROVED + RETURNED	Reset unlocked APPROVED + all RETURNED; skip locked APPROVED
Reset returned decisions only	Reset all RETURNED	Reset all RETURNED (APPROVED untouched regardless of lock)
Reset approved decisions only	Reset all APPROVED	Reset unlocked APPROVED only; skip locked APPROVED

Note: Reset returned decisions only makes decision locking irrelevant for that transition — RETURNED decisions are never locked, so only stale rejections are cleared.

Use case: Add this post-function to a “Rework” or “Reopen” transition so that when an issue is sent back for changes, approvals are cleared and the approval cycle restarts.

Phase-Gate Recipe

For phase-gate workflows where an issue moves through multiple review stages, you typically want to preserve approvals from earlier phases while clearing stale rejections:

Enable Decision Locking (global or project setting) — this protects APPROVED decisions made in earlier statuses.
Add Reset Approval Status with Reset mode = Reset returned decisions only to your phase transitions — this clears stale rejections without touching approvals.
Optionally add a role/group filter to target only the current stage’s approvers.
Add new approvers for each phase as needed — the overall status reflects the aggregate state.

Selective Notify

Sends notifications to approvers matching specific role and/or group filters. This is a targeted version of the Notify Approvers post-function.

Configuration:

Filter by Roles — toggle on and select one or more project roles. Only undecided approvers who are members of a selected role are notified.
Filter by Groups — toggle on and select one or more user groups. Only undecided approvers who are members of a selected group are notified.
Filters use OR logic: an approver is notified if they match any selected role or any selected group.
Notify mode: Same options as the standard Notify Approvers post-function (all undecided, new only, pending only).

Use case: Notify only the QA team’s approvers when the issue transitions to “QA Review”, without bothering approvers from other teams.

Reset Decisions by Role/Group (deprecated)

This legacy action is also referred to as Selective Reset in release notes.

⚠ Deprecated — use Reset Approval Status instead. The Reset Approval Status post-function now supports role/group filtering combined with decision-status modes, so it can express everything Reset Decisions by Role/Group can (and more — e.g. “reset only the QA role’s returned decisions”). Existing workflow configurations that use Reset Decisions by Role/Group continue to work unchanged, but new configurations should use Reset Approval Status. The Reset Decisions by Role/Group entry remains in the workflow-editor picker, tagged “(deprecated — use Reset Approval Status)”.

Resets decisions for approvers matching specific role and/or group filters. This is a targeted version of the Reset Approval Status post-function.

Configuration:

Filter by Roles — toggle on and select one or more project roles. Only matching approvers have their decisions reset.
Filter by Groups — toggle on and select one or more user groups. Only matching approvers have their decisions reset.
Filters use OR logic: an approver is reset if they match any selected role or any selected group.
Notify after reset: Optional toggle — when enabled, sends a notification to the affected approvers after their decisions are reset.

Updating an existing workflow: To replicate a Reset Decisions by Role/Group configuration in Reset Approval Status, set the same role/group filter there and leave the reset mode at “Reset all decisions”. You can then remove the Reset Decisions by Role/Group post-function from the transition.

Use case (legacy): When an issue moves from “Dev Review” to “QA Review”, reset only the QA approvers’ decisions (from a previous cycle) while preserving the dev team’s existing approvals.

6.4 Setting Up a Basic Approval Workflow

Follow these steps to configure a simple approval gate in your project’s workflow.

Step 1: Enable the Plugin

Go to Global Config (see Section 1 for navigation)
Toggle Enable Plugin to ON
Configure your preferred threshold, SoD rules, and other global defaults

Step 2: Enable for Your Project

Go to Project Settings
Toggle Enable to ON
Set Approval Required to ON
Configure panel visibility and any project overrides

Step 3: Edit Your Workflow

Go to Project Settings > Workflows (or Jira Settings > Workflows for shared workflows)
Click Edit on the workflow you want to modify
Select the transition that should require approval (e.g., “In Review” to “Done”)

Step 4: Add a Validator

On the selected transition, open the Rules panel
Under Validators, click Add validator
Select Require Approval Passed (Business Sign-off)
Save the validator

This blocks the transition until the approval threshold is met.

Step 5: Add a Post-Function (Optional)

On an earlier transition (e.g., “To Do” to “In Review”), open the Rules panel
Under Post-functions, click Add post-function
Select Notify Approvers (Business Sign-off)
Configure the notification mode (e.g., “All undecided”)
Save the post-function

This sends a notification to all undecided approvers when the issue enters the review stage.

Step 6: Publish the Workflow

Click Publish to activate the workflow changes
Jira may prompt you to save a backup — this is recommended

Step 7: Test

Create or open an issue in the project
Add one or more approvers from the issue panel
Verify that the validator blocks the transition until the threshold is met. If a condition is also configured, check transition visibility.
Have the approvers approve the issue
Verify that the transition becomes available

Tip: Start with a simple setup (one validator on one transition) and expand from there. You can add conditions to hide transitions until approval is possible, and post-functions to automate approver assignment and notification.

7. Automation & Integration

Business Sign-off provides multiple integration points that allow administrators to build automated approval workflows tailored to their environment. This section brings together supported workflow actions, fields, Jira Automation, JQL, and the approval-statistics read interface.

7.1 Workflow-Driven Automation

Workflow functions are the primary mechanism for automating approvals. By combining post-functions, validators, and conditions on your Jira workflow transitions, you can build fully automated approval gates without any manual intervention beyond the actual approval decision.

Available building blocks:

Function Type	Functions	Purpose
Conditions (3)	Has Approvers, Is Approved, Is Returned	Control which transitions are visible based on approval state
Validators (3)	Require Approvers, Require Approval Passed, Require Group/Role Approval	Block transitions that don’t meet approval requirements
Post-Functions (6)	Add Approvers, Remove Approvers, Notify Approvers, Reset Approval Status, Selective Notify, Reset Decisions by Role/Group (deprecated — use Reset Approval Status)	Automate approver assignment, notifications, and resets on transitions

Note: See Section 6 for detailed configuration of each workflow function.

Design pattern — Automated approval gate:

A common pattern combines post-functions on an early transition with validators on a later transition:

“Start Review” transition (e.g., In Progress → In Review):
- Post-function: Add Approvers (from a project role, e.g., “Reviewers”)
- Post-function: Notify Approvers (all undecided)
- This automatically assigns and notifies the right people when work moves to review
“Approve for Release” transition (e.g., In Review → Ready for Release):
- Condition: Issue Is Approved (hides the transition until approval passes)
- Validator: Require Approval Passed (blocks the transition if approval hasn’t passed)
- This ensures no issue can advance without sign-off
“Return to Development” transition (e.g., In Review → In Progress):
- Post-function: Reset Approval Status (with notify = true)
- This resets all decisions and re-notifies approvers when work is sent back

Design pattern — Multi-stage approval:

For workflows requiring approvals at multiple stages (e.g., technical review, then management sign-off):

“Submit for Technical Review” transition:
- Post-function: Add Approvers from “Technical Reviewers” role
- Post-function: Notify Approvers
“Submit for Management Approval” transition:
- Validator: Require Group/Role Approval (rule: “Technical Reviewers” role, minimum 2 approved)
- Post-function: Add Approvers from “Management” group
- Post-function: Notify Approvers
“Approve for Production” transition:
- Validator: Require Group/Role Approval (rule: “Management” group, minimum 1 approved)
“Return to Development” transition (from any review stage):
- Post-function: Reset Approval Status with a role/group filter for the current stage’s role/group (the deprecated Reset Decisions by Role/Group post-function did the same thing)
- This resets only the current stage’s approvals, preserving earlier stage decisions

7.2 Custom Field Integration

Business Sign-off creates two custom fields that integrate with Jira’s native functionality:

BSO - Approvers (multi-user field, read-only):

Appears on issue views, board cards (if configured), and issue lists
Displays the current approver list, kept in sync automatically from the issue panel (read-only — not directly editable)
Can be added to Jira dashboards as a column in filter results
Can be used in board card layout to show approvers directly on Kanban/Scrum boards

BSO - Status (read-only text field):

Displays the current approval status, including Paused (see Section 5.2)
Can be added as a column in issue lists and dashboards
Updated automatically — no manual intervention needed

Tip: Add both BSO fields to your team’s default issue list columns. This gives everyone visibility into approval status without opening each issue individually.

7.3 Jira Automation Rules

Jira’s built-in Automation for Jira can interact with Business Sign-off through the custom fields. Automation rules cannot directly invoke BSO approval actions or write to the read-only BSO fields. They can, however, read the BSO fields in conditions and act on approval status.

What automation can do:

Read BSO - Status in conditions — e.g., “If BSO - Status equals Approval Passed, then transition the issue”
Read BSO - Approvers in conditions — e.g., “If BSO - Approvers is not empty, then…”
Use BSO fields in notifications — include approval status in automated Jira notification templates

Example automation rules:

Rule	Trigger	Condition	Action
Auto-transition on approval	Field value changed: BSO - Status	BSO - Status = “Approval Passed”	Transition issue to “Approved” status
Notify manager on return	Field value changed: BSO - Status	BSO - Status = “Approval Failed”	Send email to issue reporter
Escalate stale approvals	Scheduled (daily)	BSO - Status = “Awaiting Decisions” AND updated < -7d	Send email notification to approvers

Note: Use BSO workflow actions to add or remove approvers. Do not configure Jira Automation to edit the read-only fields or write approval data directly.

7.4 JQL Queries & Dashboards

Business Sign-off’s custom fields and issue properties enable powerful JQL queries for dashboards, filters, and reporting.

Before building custom JQL gadgets: the app ships two dashboard gadgets, BSO - My Approval Queue and BSO - My Approval Requests, that cover the most common personal views with no JQL required. Both are per-user, scoped to open issues, and self-service. Users add them from any dashboard via Add gadget and search for BSO. Users configure their own gadgets; Jira issue access and BSO permissions still apply. The JQL patterns in this section remain the route for everything the gadgets deliberately leave out: closed-issue history, cross-team rollups, aging and throughput reporting, and audit evidence. See the Dashboard Gadgets section of the User Guide for per-gadget options.

Custom field JQL examples:

Find all issues where I am an approver:

"BSO - Approvers" = currentUser()

Find all issues approved in a project:

"BSO - Status" = "Approval Passed" AND project = PROJ

Find issues awaiting approval decisions:

"BSO - Status" = "Awaiting Decisions" AND project = PROJ

Find issues that failed approval:

"BSO - Status" = "Approval Failed"

Find issues where a specific user is an approver:

"BSO - Approvers" = "<Atlassian account ID>"

Find issues with no approvers assigned:

"BSO - Approvers" IS EMPTY

Find paused approval work:

"BSO - Status" = "Paused" AND project = PROJ

Use the custom-field queries above for JQL searches. For additional approval statistics, see the read-only REST interface in Section 7.5.

Dashboard ideas:

The Jira updated date measures general issue activity, not the exact age of an approval request or the date approval passed. Use BSO gadgets for approval waiting time and audit exports for event dates.

Dashboard Gadget	JQL Filter	Purpose
My Pending Approvals	`"BSO - Approvers" = currentUser() AND "BSO - Status" = "Awaiting Decisions"`	Personal approver inbox. The built-in BSO - My Approval Queue gadget covers this case directly, including per-approver decision status. Use this filter instead when you need to include closed issues or combine it with other criteria.
Approval Bottlenecks	`"BSO - Status" = "Awaiting Decisions" AND updated < -3d`	Stale approvals needing attention
Recently Updated Approved Issues	`"BSO - Status" = "Approval Passed" AND updated >= -7d AND project = PROJ`	Approved issues with recent Jira activity
Failed Approvals	`"BSO - Status" = "Approval Failed" AND project = PROJ`	Issues returned by approvers

7.5 Advanced Approval-Statistics Integrations

For integrations that need approval statistics beyond the displayed custom fields, use the approval-statistics read interface through Jira’s standard issue-property API:

GET /rest/api/3/issue/{issueKey}/properties/bso-signoff

Use this interface to read approval status and aggregate statistics. It does not expose approver identity or decision-comment content. Reading approval information does not grant permission to change BSO assignments or decisions.

The read interface provides status, approvedCount, returnedCount, pendingCount, totalApprovers, percentage, threshold, approvalRequired, pluginActive, and lastUpdated. Use percentage for the approved percentage.

The property reports the approval outcome; it does not report Paused. Use BSO - Status to search or display paused approval work. Use the custom-field JQL examples in Section 7.4 for routine searches and dashboards.

Use supported audit exports for detailed compliance evidence.

7.6 Common Automation Scenarios

The following scenarios illustrate how to combine the integration points above to solve common approval workflow requirements.

Scenario 1: Simple Peer Review

Goal: Require the assigned reviewers to approve before an issue can move to Done.

Step	Configuration
Project setting	Enable Business Sign-off, set threshold to 100%
Workflow: “Submit for Review” transition	Post-function: Add Approvers (from project role “Developers”)
Workflow: “Submit for Review” transition	Post-function: Notify Approvers (all undecided)
Workflow: “Done” transition	Validator: Require Approval Passed
Workflow: “Done” transition	Condition: Issue Is Approved (hides transition until approved)

Scenario 2: Regulatory Change Approval

Goal: Require sign-off from both a technical reviewer and a compliance officer, with full audit trail.

Step	Configuration
Global setting	Enable SoD (assignee + reporter), decision locking, comment required on all decisions
Project setting	Eligible approvers: Selected Users, filtered by “Change Approvers” group
Workflow: “Submit for Review” transition	Post-function: Add Approvers (from “Technical Reviewers” role)
Workflow: “Submit for Review” transition	Post-function: Add Approvers (from “Compliance Officers” group)
Workflow: “Submit for Review” transition	Post-function: Notify Approvers (all undecided)
Workflow: “Approve for Release” transition	Validator: Require Group/Role Approval (Technical Reviewers: min 1 approved AND Compliance Officers: min 1 approved)
Workflow: “Return to Development” transition	Post-function: Reset Approval Status (notify = true)

Scenario 3: Lightweight Team Acknowledgment

Goal: Have team members acknowledge a decision without blocking the workflow.

Step	Configuration
Project setting	Enable Business Sign-off, Approval Required = Off
Project setting	Threshold = 50%, comment required = Never
Workflow	No validators or conditions needed — approvals are informational only
Usage	An authorized approver manager assigns the team members, who then record decisions. No workflow gates.

Scenario 4: Automated Daily Approval Status Report

Goal: Send a daily summary of issues awaiting approval and lacking recent Jira activity.

Step	Configuration
Jira Automation rule	Trigger: Scheduled (daily at 9 AM)
Jira Automation rule	JQL condition: `"BSO - Status" = "Awaiting Decisions" AND project = PROJ AND updated < -2d`
Jira Automation rule	Action: Send email to project lead with list of matching issues

8. Configuring Separation of Duties

Separation of Duties (SoD) helps prevent conflicts of interest in approval workflows. Business Sign-off blocks decisions that violate configured SoD rules and displays the reason.

8.1 How SoD Works

SoD rules prevent specific issue participants from serving as approvers:

Assignee rule: When enabled, the person assigned to work on the issue cannot approve it. This ensures the person doing the work cannot also sign off on it.
Reporter rule: When enabled, the person who created the issue cannot approve it. This ensures the requester cannot self-approve.

Real-time enforcement: SoD is not just checked when an approver is added — it is continuously re-evaluated. If the issue’s assignee or reporter changes after approvers have been added, Business Sign-off automatically re-evaluates all existing approvers against the updated SoD rules. An approver who was previously eligible may become ineligible if they are now the assignee or reporter.

Prevention, not flagging: SoD violations are hard-enforced. An ineligible approver cannot record a decision — the app blocks the action and displays the reason. This is stronger than a soft warning that can be overridden.

Visibility in the issue panel: When an approver has a SoD violation, the issue panel displays a warning badge next to their name with a tooltip explaining the reason (e.g., “Cannot approve — user is the issue assignee”). The approver’s decision buttons are disabled.

Audit trail: Relevant history entries show whether the SoD check passed, failed, or was not applicable.

8.2 SOC 2 Type II Recommendations

If your organization is pursuing or maintaining SOC 2 Type II compliance, the following configuration provides strong controls for the Change Management and Access Control trust service criteria:

Setting	Recommended Value	Rationale
Assignee cannot approve	Enabled (global)	Prevents the person implementing a change from approving it
Reporter cannot approve	Enabled (global)	Prevents the requester from self-approving
Decision locking	Enabled (global)	Prevents approval withdrawal after issue progresses through workflow
Eligible approvers	“Selected Users” filtered by a designated approver role or group	Restricts sign-off authority to authorized personnel
Approval threshold	75% or 100%	Ensures sufficient review coverage
Workflow validator	“Require Approval Passed” on production deployment transitions	Blocks deployment without sign-off
Audit CSV export	Use for evidence review	Provides evidence for auditor review

Tip: For production change management, add the Require Approval Passed workflow validator to the transition that moves issues into a “Ready for Deploy” or “Done” status. Verify the gate in your own workflow, including disabled-App, optional-approval, and license scenarios.

8.3 SOX (Sarbanes-Oxley) Recommendations

For organizations subject to Sarbanes-Oxley compliance, Business Sign-off supports the internal controls over financial reporting (ICFR) requirements:

Setting	Recommended Value	Rationale
Assignee cannot approve	Enabled (global)	Separates execution and approval
Reporter cannot approve	Enabled (global)	Prevents self-authorization
Decision locking	Enabled (global)	Protects approved decisions after the issue advances, subject to the locking rules
Eligible approvers	“Selected Users” filtered by a designated group (e.g., `sox-approvers`)	Restricts sign-off authority to authorized controllers
Approval threshold	100% (unanimous)	All designated approvers must sign off
Workflow validator	“Require Group/Role Approval” with specific department groups configured	Ensures cross-departmental sign-off (e.g., Finance + IT)
Audit CSV export	Quarterly exports for compliance reporting	Provides evidence trail for external auditors
Comment requirements	“Always”	Documents the rationale for every approval and return

Note: SOX auditors typically require evidence that controls were in place and operating effectively throughout the audit period. Schedule quarterly CSV exports (see Section 10.4) covering the prior quarter and retain them alongside your other compliance artifacts.

8.4 Verifying SoD Enforcement

To verify that SoD rules are working correctly in your environment:

Navigate to an issue in a project where Business Sign-off is enabled
Assign yourself as the issue assignee
In the Business Sign-off panel, attempt to add yourself as an approver
The app should block the addition and display an error message: “Cannot add approver — user is the issue assignee”
Check the panel’s eligibility indicator and refusal message. Review available issue history; do not assume every refused selection creates an audit entry.

To verify the reporter rule:

Create a new issue (you are automatically the reporter)
Have another user add you as an approver on that issue
The app should block the addition with a message: “Cannot add approver — user is the issue reporter”

To verify real-time re-evaluation:

Add User A as an approver on an issue where User A is not the assignee or reporter
Change the issue’s assignee to User A
Observe that User A’s row in the panel now shows a SoD violation badge
User A can no longer record a decision until the assignee is changed to someone else

9. Email Notifications

Business Sign-off sends targeted email notifications to keep approvers and stakeholders informed about approval activity. Notifications are delivered through Jira’s built-in mail system — no external SMTP configuration is needed beyond what Jira Cloud provides out of the box.

9.1 How Notifications Work

Jira delivery: Approval notifications use Jira Cloud’s mail delivery; no external SMTP setup is required.
Context: Messages include issue information and relevant approval context, such as the decision, comment, or outcome.
Delivery limits: Jira permissions, recipient availability, and mail delivery affect whether a notification reaches its recipient.
Approval actions: Notification delivery failures do not prevent the underlying approval action from completing. Review notification history and contact support if delivery is missing.

9.2 Notification Types

Notification	Trigger	Recipients
Approver Added	Panel or workflow assignment when Email Approver When Added is enabled	Newly added approvers
Approval Requested	Panel Notify Approvers or configured workflow notification	Undecided approvers matching the selected mode and filters
Re-Review Requested	Manual Request Re-Review	Approvers whose decisions are reset for review
Decision Made	Approval or return	Reporter and/or assignee, according to project preferences
Outcome Reached	Overall outcome reaches or changes to passed/failed, including changes caused by removals	Reporter and/or assignee, according to outcome preferences
Workflow Reset	Reset Approval Status with notification enabled	Approvers affected by that reset

Removal notifications: Removing an approver does not send that person a separate removal email. If removal changes the overall outcome to passed or failed, the reporter and/or assignee may receive an outcome email according to project preferences. A removed approver who is also the reporter or assignee can receive that outcome email.

Added versus requested: Adding an approver can send the added-approver email. Notify Approvers is a separate action that asks undecided approvers to review; use it after preparing the approver list.

Reset defaults: Reset Approval Status notifies affected approvers by default. Existing configurations with notification explicitly disabled remain disabled.

Outcome messages: Subsequent decisions do not repeatedly send the same settled-outcome message; another outcome email is sent when the outcome changes.

9.3 Configuring Notifications

Notification preferences are configured at the project level in Project Settings (see Section 1 for navigation). There are no global notification toggles — all notification types are available by default, and each project controls its own preferences.

The following notification settings are available per project:

Setting	Options	Default
Email Approver When Added	On / Off	On
Email Reporter on Approver Decision	When Approved / When Returned / When Approved or Returned / Do Not Email	Do Not Email
Email Reporter on Approval Outcome	When Approved / When Returned / When Approved or Returned / Do Not Email	When Approved or Returned
Email Assignee on Approver Decision	When Approved / When Returned / When Approved or Returned / Do Not Email	When Approved or Returned
Email Assignee on Approval Outcome	When Approved / When Returned / When Approved or Returned / Do Not Email	When Approved or Returned

Tip: For most teams, the recommended configuration is: Email Approver When Added = On, both on Approver Decision settings = Do Not Email, and both on Approval Outcome settings = When Approved or Returned. This minimizes notification noise while ensuring stakeholders are informed when the final outcome is reached.

9.4 Notification Rate Limiting

Business Sign-off applies rate limiting to Approval Requested notifications to help prevent duplicate reminder notifications.

Repeated manual or workflow Notify Approvers requests may skip reminder notifications because of rate limiting.
Rate limiting does not apply to the Re-Review Requested notification, which notifies affected approvers regardless of prior reminder notifications.
The reminder limit does not apply to Approver Added notifications.

10. Audit Trail & Export

Business Sign-off records approval activity, including assignments, decisions, resets, notifications, and changes to overall outcomes, for accountability and compliance review.

10.1 Viewing Audit History

To view the audit history for an issue:

Navigate to the issue in Jira
In the Business Sign-off panel (right sidebar), click the History button
The history modal displays all approval actions in reverse chronological order (newest first)

Each history entry includes:

Field	Description
Action	The type of action (e.g., Approver Added, Decision Approved, Status Changed)
Actor	The user who performed the action
Target	The approver affected by the action (if applicable)
Timestamp	When the action occurred
Comment	The decision comment (for approval/return actions)
SoD Result	Whether the SoD check passed, failed, or was not applicable
Source	How the action was triggered (UI, Workflow Post-Function, Event Trigger)

Audit History remains available when an issue has history but no current approvers. Overall-outcome changes appear as separate history entries. Workflow-generated actions appear as System.

Filtering: Use the filter toggle at the top of the history modal to switch between All History (every action) and Decisions Only (approvals, returns, decision changes, and resets).

More history: Use Load More to review additional entries on issues with long histories.

10.2 Audit Record Integrity

CSV exports offer Include Integrity Verification, enabled by default and adjustable for each export.

Verification reports detected changes to audit records and distinguishes legitimate privacy redactions from unexplained changes. Use the results as part of your evidence review and contact support if an unexpected result needs investigation.

These checks detect accidental corruption or casual editing. They do not make records immutable, prevent editing or deletion by users with the relevant Jira permissions, or establish that every authorized action was appropriate. Retain downloaded evidence according to your organization’s controls.

10.3 Audit Retention and Privacy

Selected approval audit events are retained as native Jira data and may remain after the App is uninstalled. This supports evidence retention, but it is not an automatic restore or reinstall-recovery feature.

Users with relevant Jira permissions can alter or delete native Jira data. Integrity checks detect changes rather than preventing them.

Historical records retain identity and issue-context snapshots. Account-closure handling can redact names and authored comments while retaining records and identifiers. Review the Cloud Privacy Policy when establishing retention rules or responding to a privacy request.

10.4 CSV Export

Use audit CSV exports to provide compliance evidence or perform offline analysis. Jira administrator permission is required to start, view, download, and delete exports.

Access: Open Global Config → Audit Export.

Export option	Details
Date Range mode	Select up to 50 projects and a start/end date, with a maximum span of 500 days
Issue List mode	Enter up to 50 issue keys to retrieve their complete approval history regardless of event date
Decisions only	Restrict output to decision-related events
Include Integrity Verification	Enabled by default; clear it for an export if verification is not needed

Running an export:

Select Date Range or Issue List mode.
Enter the projects/date range or issue keys.
Review Decisions only and Include Integrity Verification.
Click Start Export.
Review progress and any message explaining that no records match.
When complete, click Download to save the CSV.

Limits and retention:

Up to 50 projects in a Date Range export, or 50 issue keys in an Issue List export.
Up to a 500-day Date Range.
Up to 5 concurrent exports across administrators.
Completed or failed stored exports older than 72 hours are eligible for removal when an administrator next accesses export information. This is not an exact deletion deadline; running exports and cleanup failures can delay removal.
Downloaded copies are outside the App’s retention controls. Store them securely under your organization’s evidence-retention rules.
Export access and cleanup remain available without an active App license, subject to administrator permissions.

CSV exports protect against spreadsheet formula execution when opened in common spreadsheet applications.

Tip: For recurring compliance reporting, export the relevant period and retain the CSV alongside your other compliance artifacts.

11. Admin Audit Log

The Admin Audit Log records all administrative configuration changes made to Business Sign-off. This provides accountability for who changed what, when, and why.

11.1 Accessing the Admin Audit Log

Go to Global Config
Click the Admin Audit tab

Only Jira Administrators can access the Admin Audit Log.

11.2 Audited Actions

Action	Description
Global Configuration Changed	Any change to global settings (with field-level from/to tracking)
Project Configuration Changed	Any change to project-level settings
Plugin Enabled	The plugin was enabled globally
Plugin Disabled	The plugin was disabled globally
Export Started	An administrator initiated an audit CSV export
Export Downloaded	An administrator downloaded a completed CSV export
Diagnostic Logging Toggled	Diagnostic logging was enabled or disabled

Field-level change tracking: For configuration changes, the audit log captures exactly which fields changed, with from and to values for each field.

11.3 Filtering

The Admin Audit Log supports the following filters:

Action type: Filter by a specific action type
Time presets: Last 7 days, 30 days, 90 days, or custom date range

Expandable rows: Click on any audit entry to expand it and view the detailed field changes with field name, old value, and new value.

11.4 Integrity

Administrative history identifies the administrator, action time, and changed settings. Review the recorded changes to investigate configuration decisions and compare them with your approved change-management process.

Audit information supports accountability; it should not be treated as an immutable record or a substitute for Jira access controls and your evidence-retention procedures.

12. Troubleshooting

12.1 Plugin Not Appearing on Issues

Check global enable: Go to Global Config and verify that the plugin is enabled globally.
Check project enable: Go to Project Settings for the issue’s project and verify that the project is enabled.
Check panel visibility: In the project settings, verify the Panel Visibility setting. If set to “Selected Issue Types,” confirm that the current issue’s type is included.
Check issue type: All Standard Issue Types excludes subtasks from new approval work. Existing approvers can keep the panel available on an excluded type.
Refresh the page: The issue context panel loads asynchronously. Try refreshing the browser page (Ctrl+Shift+R / Cmd+Shift+R).

Tip: If the panel still does not appear after verifying all settings, try opening the issue in a private/incognito browser window to rule out caching or extension interference.

12.2 Approvers Cannot Be Added

Check approver management permissions: Verify the Approver Management Permissions section in global settings. Confirm that the current user matches one of the enabled roles (reporter, assignee, or administrator).
Check issue status category: Approvers cannot be added to issues in the Done status category.
Check finishing mode: If the project or plugin is in Finishing Mode, new approver additions are blocked.
Check eligible approver filters: If eligible approvers are set to “Selected Users,” verify the user’s role/group membership.
Check license status: An inactive license blocks new approvers. Existing-work exceptions require project finishing mode (see Section 2).
Check issue type and access: The issue must allow new approval work and the candidate must have Browse Projects access. Existing approvals on an excluded type do not permit new assignments.

12.3 Approver Cannot Change Their Decision (Locked)

Decision locking is enabled and the issue has transitioned since the decision was recorded.
Only APPROVED decisions are locked. Returned decisions are never locked.
Return to original status to unlock: Move the issue back to the status it was in when the decision was recorded.
Workflow reset behavior: The Reset Approval Status post-function skips locked decisions.
Disable decision locking in global or project config to unlock all decisions immediately.

Note: Decision locking protects downstream workflow stages that rely on earlier sign-offs. Disabling it should be a deliberate decision.

12.4 Approver Cannot Be Removed (Decided)

Decided approvers are protected from removal by non-admin users.
Admin override: Only Jira Administrators or Project Administrators can remove decided approvers.
Check approver management permissions: Verify that the administrator role is enabled in global settings.
Reset first, then remove: Where the decision is unlocked, use Request Re-Review to reset it to PENDING before removal. Decision-locking restrictions still apply.

12.5 Workflow Validators Not Working

Verify the validator is on the correct transition in the Jira workflow editor.
Check that the plugin is enabled for the project.
For “Require Group/Role Approval”: Verify group/role names and minimum counts in the validator configuration.
Check approver statuses: Validators require APPROVED status, not just ADDED or PENDING.

12.6 Custom Fields Not Updating

Confirm the App is installed and current: BSO fields are provisioned automatically during installation and are locked, app-managed fields.
Compare with the issue panel: A stale or missing reporting-field value does not by itself indicate lost assignments, decisions, or audit history.
Check the App version: Releases 1.6.1 and 1.6.2 improved reporting-field synchronization. Review the release notes if your site runs an older version.
Refresh and recheck: Reporting changes may not be visible immediately.
Contact support: If fields remain absent or stale, provide an example issue and the approximate time of the affected approval action. Do not uninstall or attempt to recreate the locked fields as a troubleshooting step.

12.7 Email Notifications Not Sending

Check project notification preferences in Project Settings.
Confirm the recipient has the relevant Jira project/issue access and a usable Atlassian email address.
Distinguish Approver Added from the separate Notify Approvers request.
Check notification history; repeated Approval Requested reminders may be suppressed by rate limiting (see Section 9.4).
Review notification history for available delivery information.
Enable short-duration diagnostics, reproduce the issue, and contact support with the time and affected issue. Jira administrators do not need Developer Console access.

12.8 Enabling Diagnostic Logging

Go to Global Config
Scroll to the Diagnostic Logging section
Toggle diagnostic logging On
Select a duration: 1 hour, 2 hours, 4 hours, or 8 hours
Click Save
Reproduce the issue
Contact support@cahabaforge.com with the approximate reproduction time so support can review the relevant logs
Additional diagnostic logging expires after the configured duration; previously collected logs remain subject to Atlassian’s retention policies.

Note: Diagnostic logging increases log output. Always set the shortest duration that allows you to reproduce the issue.

13. Getting Help

If you encounter issues not covered in this guide, or need assistance with configuration, compliance setup, or troubleshooting:

General Support

Email: support@cahabaforge.com
Website: https://cahabaforge.com/contact

Security Issues

Email: security@cahabaforge.com

When contacting support, please include:

Your Jira Cloud site URL (e.g., https://yourcompany.atlassian.net)
The browser and version you are using
Steps to reproduce the issue
Screenshots or screen recordings
The issue key (e.g., PROJ-123) if the issue is specific to a particular Jira issue
Whether diagnostic logging was enabled (see Section 12.8)

Tip: Enabling diagnostic logging before contacting support significantly speeds up troubleshooting. Enable it, reproduce the issue, then note the time — the support team can correlate your report with the detailed logs.

Refer to the Support Policy for response time commitments and service level details.

← Back to Documentation