Issue Approval - User Guide

Overview

Issue approval - is a tool that allows requesting approvals in issues. This process can be set up on various statuses depending on configuration in project. After the approval process is set up by project administrator, approval functionality is ready to use in issues!

Please see the Project administrator's guide to set up configuration.

Approval process

The whole process is held by 2 actors: the one who requests this approve (requester) and the one who is supposed to approve this request (approver). Only current assignee of the issue can be requester, while only those users who have access to issue may be approvers.

Please note if user looses access to issue he/she won't be able to leave his/her vote.

I. Create approval request (for issue assignee)

In certain statuses (it is configured by project administrator), issue assignee can create an approval request (can be limited to certain project roles).

To do so follow the steps below:

Press Request approval button in "Approvals" panel.
A dialog window with approval request settings to fill up.

Depending on the selected Type of approval, fields and approval mechanism itself will differ.

If Approval Teams are created in current project, a new field "Approval actor" will be available. This field defines the mode approvals will be counted - based on individual or team approvals.

There are 2 types:

All at once	In turns

All at once

In turns

Approval actor: User

Approval actor: Team

In this type, all approvers in the list will simultaneously receive a notification with a proposal approve request in issue. Since then any approver can approve or decline request.

Approval actor: User

Approval actor: Team

In this type notification is sent to each of the approvers only after previous approver made his/her choice. Each approver can vote in his/her turn only.

Approvers

Approval actor: User

Select users who will be approvers of this request. these users will be sent a notification message with proposal to leave a vote in this issue.

Requester can select

Select All or Minimum of to set how many of the approvers needed to resolve this request.

If selected All, request will be declined if at least one approver declines request.
If selected Minimum of, must define the required number of approvers. Request can be approved if selected number of users Approved request.
- Optionally set "wait for all approvers" checkbox to wait for all approvers to leave their vote even if the minimum number of required approvals is reached.

Approval actor: Team

Select Teams to be used as approvers. Each Team contains individual users who will get notifications with a proposal to approve request. But final result will be counted based on each team's collective decision. Required number of Team approvals and number of approvals within each team can be set in a corresponding menu.

Approvers

Approval actor: User

Select users in the corresponding fields in a particular order. Each of the approvers can approve of decline request only if it is his/her turn.

If at any step any of the approvers declines request - the whole approval process will be finished with the Declined status.

Approval actor: Team

Each team will be asked for approval in its turn. Each member within a team will get notification simultaneously. After team's collective decision is made, next team's members opinion will be asked until the list of responsible teams is over.

Number of approvals within each team can be set in a corresponding menu.

Comment

This message will be added to the notification message sent to approvers. Also this test can be pasted as issue comment if this is configured in project settings.

Comment

This message will be added to the notification message sent to approvers. Also this test can be pasted as issue comment if this is configured in project settings.

3. Press Create request to launch approval request.

4. After request has been created, issue assignee can optionally Edit request approval or Cancel request at any time. Request can be also Viewed at any time.

II. Approval (for approvers)

Right after a potential approver gets an email, one can either Approve or Decline this request in the corresponding panel in issue.

Once the necessary amount of votes is reached, request receives a status. In general there can be several statuses for request:

Pending - approval request is in process (not completed)

Approved - necessary amount of users approved request

Declined - necessary amount of users declined request

Expired - issue has not been updated more than the set number of days

In All at once mode you can withdraw your vote by clicking Withdraw vote button.

III. Reopen request

Issue assignee can reopen previous request in case it was finished with one of the following statuses: Approved, Declined, Expired. A pop-up window with previous request settings will appear.

IV. Proxy-approvals

Certain project roles can be granted permission to vote on behalf of the approvers in issue.

This person can vote to Approve or Decline on behalf of the approver. Or press Cancel to drop this approver from the approvers list in current issue.

Any action is duplication in Approval history tab in issue.

State:

Approval request is created and every approver has not left their vote yet.

State:

A responsible person (profile icon is displayed) has voted Approve on behalf of one of the approvers.

This mechanism can be used when initial approver is requested a decision, but is unable to access Jira at the moment yet. So asking a proxy approver to leave vote would be at hand. Or if you need to drop some approver from the request without starting it from all over.

Extra features

Automatic transitions

If approval status reaches its final status (Approved, Declined, Expired), issue can automatically change its status if it set up by project administrator.

JQL

You can use JQL functions to search for issues that relate with approval functionality.

approvalRequestStatus("")

Searches for issues with the mentioned current approval status(es) of the last (actual) request

Allowed syntax	Example:

Allowed syntax

Example:

Field: issue

Operators: IN

issue in approvalRequestStatus("Pending")

issues where request status is Pending

issue in approvalRequestStatus("Pending","Expired")

issues where request status is either Pending or Expired

approvalStatusHistory("")

Searches for issues with the mentioned approval status(es) has ever been within issue's lifetime.

For example, each issue may have several approval processes within its lifetime. This function helps to find issues with even if mentioned approval status relates to previous approval results.

Allowed syntax	Example:

Allowed syntax

Example:

Field: issue

Operators: IN

issue in approvalStatusHistory("Pending")

issues where approval request status has been "Pending" at least once

issue in approvalStatusHistory("Pending","Expired")

issues where approval request status has been "Pending" or "Expired" at least once

issueApproverActual("")

Searches for issues where mentioned user(s) is an approver of the last (actual) request

Allowed syntax	Example:

Allowed syntax

Example:

Field: issue

Operators: IN

issue in issueApproverActual("user")

issues where mentioned user "user" is one of the approvers

issue in issueApproverActual("user", "user1")

issues where mentioned user "user" or "user1" is one of the approvers

issueApproverHistory("")

Searches for issues where mentioned user(s) has been an approver at least once in any approval request within issue's lifetime.

Allowed syntax	Example:

Allowed syntax

Example:

Field: issue

Operators: IN

issue in issueApproverHistory("user")

issues where mentioned user "user" has even been one of the approvers

issue in issueApproverHistory("user","user1")

issues where mentioned user "user" or "user1" has ever been one of the approvers

issueCurrentApproverActual()

Searches for issues where current user is an approver in the last (actual) request.

Allowed syntax	Example:

Allowed syntax

Example:

Field: issue

Operators: IN

issue in issueCurrentApproverActual()

issues where current user is an approver

issues in issueCurrentApproverActual("Pending","Expired","Declined","Approved")

issues where the current user is an approver and user's approval decision status is either Pending, Expired, Declined, or Approved

issueCurrentApproverHistory()

Searches for issues where current user has been an approver in any approval request within issue's lifetime.

Allowed syntax	Example:

Allowed syntax

Example:

Field: issue

Operators: IN

issue in issueCurrentApproverHistory()

issues where current user has ever been an approver

issues in issueCurrentApproverHistory("Pending","Expired","Declined","Approved")

issues where the current user was an approver at any period of the issue life cycle and user's approval decision status is either Pending, Expired, Declined, or Approved

FAQ

Before creating request approvals, project administrator must create configuration for this issue type. Then issue assignee can create approval request.

the whole process looks like this:

Project administrator must create configuration for a particular issue type.
Issue assignee can now create approval requests depending on the settings.
Approvers will receive notification and will be able to lea

Only issue assignee can create approval requests in issues. It can be done if the following conditions are met:

Issue is in the status that allows creating requests.
(If configured) Assignee has the correct role.

There are two options to fix this situation.

I. If you are issue assignee, you press "Edit request" button and change the list op approvers. Note, in this case all votes left will be cancelled.

II. If you are in a role that allows to Manage approvals, you can cross out a user from the list of approvers.

JQL

You can use JQL filter to find issues where you are an approver

Examples:

issue in issueCurrentApproverActual() - lists issues where you are an approver and issue is currently waiting for your participation for approval

issue in IssueCurrentApproverHistory() - lists issues where you have ever been requested an approval

Yes. There is a possibility to automatically trigger issue post-function depending on approver's action. You can set up an action if request is approved, declined or if even no action is performed.

Automatic commenting upon these actions can also be configured.