Administration (based on new custom field type)
Since the major version 4 of this app for Jira Cloud, you can use the new custom field type “Group Sign-Off / Multi-Approval Field” to create and configure additional approval fields, including automatic workflow transitions once a final decision is reached — without the need to modify workflows.
- 1 Create a new approval field for Company-managed projects
- 2 Create a new approval field for Team-managed projects
- 3 How to Configure a “Group Sign-Off/Multi-Approval Field“
- 3.1 Deciders
- 3.1.1 Four-eyes principle
- 3.1.2 Multiple subsets of deciders
- 3.2 Conditions
- 3.3 Voting Rules
- 3.4 Options
- 3.4.1 Processing of decisions
- 3.4.2 Delegations & Business Continuity
- 3.4.3 Voting behavior
- 3.4.4 Security and privacy
- 3.4.5 Look & Feel
- 3.5 Auto-Transitions
- 3.6 Advanced (code-based definitions)
- 3.1 Deciders
- 4 How to set a “Default Value”
- 5 Different business scenarios …
Create a new approval field for Company-managed projects
Summary:
Create a new custom field of type “Group Sign-Off/Multi-Approval Field”.
Specify the contexts (projects and issue types) for this field.
Configure the approval via “Edit custom field config”.
Detailed approach:
As an administrator, switch into the “Jira admin settings” (1), choose “Work Items” (2), then select “Fields” (3) in the menu on the left side.
Create a new custom field representing a new approval: click on “Create new field“ (4), select the type “Group Sign-Off/Multi-Approval Field” (5), then enter the new field name (6). Optionally, add any description for this field as well.
Commit the creation by clicking on the “Ok” button on the bottom right side of the page. Now, you will see the list of all fields again. Enter the name of your created custom field within the search box (7) to focus on your field in the list of all your custom fields. Then, expand the context menu “…” (8) and select “Contexts and default values“ (9).
Within the section “Contexts and default values”, please specify in which project(s) and issue type(s) the new custom field shall be used.
To reduce the number of custom fields, you can create multiple contexts for the same custom field: add additional contexts for certain projects and issue types (10) or edit the default context (10) by switching from global (all work items) to the related projects and issue types. For each context, you can configure different approval definitions.
Click on “Edit custom field config” (11) to enter your approval definitions.
Proceed with the configuration of the new custom field below.
Create a new approval field for Team-managed projects
Summary:
Create a new custom field of type “Group Sign-Off/Multi-Approval Field”.
Enter the name of the new custom field.
Detailed approach:
As a user with project administration permissions, switch to any issue of your team-managed project, scroll down to the section “Activity”, expand the tab “Multi-Approvals“ (1), and click on the button “Team-managed approval fields“ (2).
A pop-up window occurs with an overview of all your team-managed custom fields of type “Group Sign-Off/Multi-Approval Field”. On this overview, you can delete your custom fields (4), edit their configurations (3), or create a new custom field (5) for additional approvals.
After clicking on “New Approval Field”, you must enter the name of the new custom field (6).
Then proceed with the configuration below ...
After configuring the field, review the displayed information and complete the setup by clicking the button “OK” (7) to confirm.
Then click on Jira’s native button “Configure” on your issue view (8).
Finally, add your new custom field to the screen of your team-managed project by dragging and dropping it from the right-hand side into the “Description Fields” or “Context Fields” section (9), then click “Save Settings” (10) to commit.
How to Configure a “Group Sign-Off/Multi-Approval Field“
A configuration of an approval custom field consists of different parts: deciders, conditions, voting rules, options, and auto-transitions. They are organized in tabs for better handling on the screen, reducing scrolling. By clicking on “Next step” or “Prev step”, you can move forward or backward.
If you prefer to view all configuration data of an approval custom field on a single screen, enable the “Expand as single page” checkbox at the bottom of the page. Your selection will be saved and remembered in your user profile.
Please note that entering data may be slower than in the tab-based view due to the large number of input fields.
Deciders
For an approval, you must specify who is authorized to approve. These approvers are organized into a subset of users. A subset can have an optional name (1), which is displayed on the issue screen as the grouping title for these users, such as “Management” or “Change Advisory Board (CAB)”.
Click on “Add deciders” (2) to select the source of deciders. Available types of sources are:
User Picker Fields
Asset/CMDB Fields (requires Jira Insights)
Jira Groups
Project Roles
Static User Lists
On the right side of the selected source of deciders, you must choose the corresponding source, such as a specific custom field (user picker) that determines the deciders, or a particular project role.
Using Jira Insight, you can also select any Asset/CMDB field and specify which attribute should be used to determine the decider(s), for example, the asset owner.
You can add multiple sources of deciders to combine as many as you need by clicking on “Add deciders”. For example, the approvers shall be the reporter of an issue, all members of the project role “Approvers”, and all members of the Jira group “Management”.
Four-eyes principle
You can also enable “exclude deciders” (3) to enforce the four-eyes principle. If the reporter belongs to a configured project role or Jira group used as deciders, they cannot approve their own issues — select the “reporter” field to exclude them automatically.
Multiple subsets of deciders
You can group users by their source into a subset of deciders. Also, add as many subsets (4) as needed to organize your deciders, grouping by name for your business requirements. The subsets will be automatically numbered for better identification because their names are optional.
If you configure multiple subsets, you must define how to combine these: concatenate them or use subset conditions (5). The related conditions for each subset are placed on the tab “Conditions”. If you choose “concat”, then all users of each subset are appended to the list of deciders.
Having configured who shall decide, please click on the button “Next step” to continue with the definition of conditions.
Conditions
Conditions for subsets of deciders (conditional approvers)
If you have configured multiple subsets of deciders and enabled conditional mode, you must define the corresponding set of conditions for each subset. Each condition consists of a field, a comparison operator, and a reference value. When multiple conditions are configured, all of them must be true for the related subset of deciders to apply.
Pre-Conditions (delay approval until …)
Approvals normally start immediately. You can also define conditions that must be fulfilled before the approval begins, such as waiting for the issue to reach a certain status.
Post-Conditions (terminate approval when …)
Normally, approvals end automatically when their voting logic produces a final result. In some cases, you may need to terminate the process based on specific conditions, such as a timeout (for example, 3 weeks before the due date of an issue if no decision is made). For each post-condition, specify the final state to apply: Approved, Declined, or Aborted (no decision reached in time). If you configure multiple post-conditions, these are treated separately and independently.
Voting Rules
For each subset, configure what’s necessary to finally approve/sign-off or decline (10). Having defined multiple subsets, also determine how to combine the results of each voting rule by configuring the related operator (11): “OR” or “AND”.
Various predefined logics are available:
Additional hints are also displayed on the screen for intuitive usage.
Options
An approval can be controlled by various options. They are grouped into the following categories:
Processing of decisions
Generally, deciding in parallel shortens the total time of approval, but in some business areas, it is necessary to decide sequentially (one after the other).
Delegations & Business Continuity
It is recommended to delegate as a decider but also allow admins to delegate in the name of a decider in case of sudden illnesses or other scenarios in order not to be blocked in business.
Voting behavior
You can specify that each decider must justify the individual decision, which will be documented within the issue’s comments.
Emails are helpful, but getting too many can be a pain: as an admin, you can configure if deciders will get notification emails for pending decisions.
Security and privacy
In some environments, it is required to re-authenticate before deciding to ensure that no misuse is done: this is also possible using the built-in feature of multi-factor authentication (MFA).
In some environments, it is okay that all users see who decided when and what. In others, this is sensitive information that must be hidden from the public.
Look & Feel
Depending on the position on the screen (Description section on the left, or context section on the right), it is better not to display the full name of deciders and only display their avatar to save space.
Auto-Transitions
Optionally, you can configure which workflow transitions shall be triggered if a decision is finally approved/signed-off or declined. Within the select box, you can choose multiple target status, which will be tried transitions into - one after the other - until a transition is successfully executed. This is very helpful, using a group sign-off custom field in different contexts with different workflows! The available target statuses are grouped by their (shared) projects for better maintainability.
Advanced (code-based definitions)
For company-managed Group Sign-Off custom fields, you can configure approvals using code, similar to the approach used in previous app versions before version 4.x. Please test your code to ensure it works correctly, avoiding any impacts in daily business due to misconfigurations.
In opposite the username/key in Jira Data Center, you must reference any user by an accountId due to GDPR!
If you enter any code within the text input field, then the checkbox “use advanced code“ will be displayed at the bottom of the page. You must enable this checkbox; otherwise, the code is stored but ignored.
For better readability and maintainability, the new approach using interactive definitions is recommended. In case of complex approval definitions, this advanced code is still the best and most flexible choice.
Testing with integrated simulator
To check your advancedCode, written in JavaScript and accessing Jira data via helper-functions like helper.getCF(), or helper.getUsersByGroups(), please select a suitable issue belonging to one of your configured projects for that group sign-off field: enter the first characters of an issue key or summary to get a list of related issues for faster selection. Then click on the button “▶ Testing”, which becomes clickable after having selected a reference issue.
Your code will be executed using the fields' data of your referenced issue. Syntax errors, runtime errors, etc. are listed below. For semantical checks, that test-run will generate the following output for tracing: displaying detailed information to verify the code works as expected.
In this sample, the referenced field name contains an invalid quote character due to mis-typing, which must be corrected. Also, the value of the variable “groups” can be NULL like in the case, which causes a runtime error because null.forEach() is not allowed: use groups?.forEach() to fix, here.
Having fixed all errors, all deciders and their role for determining the final result will be shown, like:
In section “Debug Information“, you see all field access: the related data extractions and additional field information like the related field type (array, text, etc.) which can help analyzing problems, like invalid usage of a loop (e.g. forEach) based on a text-field instead of an array.
In section “Determined users as deciders“, you see a list of all users being determined as deciders based on your advancedCode and the current field’s data of your reference issue.
Additionally, you can simulate any decision (approve, decline, pending) per user via a combobox.
Section “Determined rule/logic“ lists your determined rule based on your advancedCode and the current field’s data of your reference issue for verification and analysis.
In section “Simulated decisions applied to rule logic“, you will see the determined (final) result based on your simulated decisions for verifications and analysis.
Auto-assign users belonging to multiple contexts
If you have configured that a user belongs to multiple different contexts — such as groups or Jira project roles — these users are listed below under “Simulated decisions applied to rule logic” for transparency and analysis.
As an individual, a user only has one vote. It usually does not make sense for the same person to vote differently in, for example, Group A and Group B. In addition, with rules such as:
(A OR B) AND C
a situation may occur where a single user belongs to both A and C. If the user’s individual decision is combined through OR logic within that group, the result could incorrectly allow that one person to approve the entire decision alone. Using the build-in algorithm for best-fitting assignment to one context, if the user in this sample declines then the user will be assigned to C and the decision becomes finally declined. If the user approves and somebody else has also approved before, belonging to C, the user will be automatically assigned to A and the decision becomes finally approved.
In practice, these users often act as “decision jumpers” that help accelerate the overall decision process by deciding in the context of the group where approval is most urgently needed. However, in complex scenarios it is not always obvious which assignment produces the correct or most meaningful outcome — and as a decider, you should not have to spend time analyzing complicated rule structures manually.
The app automatically assigns users who belong to multiple contexts to the best-fitting context.
At runtime, and based on the other decisions, a best-fit algorithm automatically assigns users who belong to multiple contexts to the most suitable context and applies their decision only there. This ensures that each person contributes only a single effective vote, which is applied in the most impactful context according to the configured rule, helping to achieve efficient and fast decision-making.
The resulting assignment is displayed on screen for transparency, verification, and analysis as well as the final overall result.
On the issue view, extending details, you will see the best matching context being marked, and the user, belonging to multiple contexts, is listed only once, now:
How to set a “Default Value”
Generally, this is not needed at all, because your configuration for that group sign-off custom field should contain either related pre-conditions or will start immediately for the visually configured deciders, or by determing the necessary users and rule as part of the advanced code instead of using such a static default value.
The app will set the field value for a concrete issue automatically.
If you still need to explicitly set this field's value, please use Jira Automation to assign a JSON object with the following structure:
{
"decision":"Pending",
"started":"YYYY-MM-DD",
"pendingBy":["accountId-1", "accountId-2", "accountId-3"],
"approvedBy":[],
"declinedBy":[],
"history":[],
}Different business scenarios …
Find all issues with a pending Group Sign-Off Field but assigned to inactive users
Use the following JQL and replace <fieldName> by your Group Sign-Off Field to find all related issues. Save that filter (“save as”) and create a filter subscription running frequently as you need, for example, each Monday at 10:00 AM to get a list of related issues, so that you can delegate these to others. So, you are no longer blocked by waiting for decisions, which will never happen because a decider has left the company or has been deactivated for other reasons …
<fieldName>.decision = Pending AND <fieldName>.pendingBy in inactiveUsers()