Administration (Jira Cloud)
- 1 Global prerequisite(s)
- 2 Create/Modify Group Sign-Off fields
- 3 Static Rule
- 4 Dynamic Rule(s) for more complex but flexible approaches
- 4.1 Complex Example with different syntax: use a customfield (multi-user or user picker) to dynamically specify voters
- 4.2 Complex Example with different syntax: a set of conditional definitions depending on issue's data
- 4.3 GDPR makes it necessary to use account ids
- 4.4 Access issue data for conditions
- 4.5 Complex Example accessing issue's functions to dynamically retrieve approver name(s), here: issue's reporter
- 4.6 Concat of multiple custom fields' contents
- 4.7 Concat of multiple groups, which may be also empty without a decider and 4-eyes-principle
- 4.8 Restricted displaying depending on issue's status
- 4.9 Restricted displaying depending on an issue's multi-select custom field
- 4.10 Special Function(s)
- 4.11 Advanced Sample: sign-Off rule based on function calls and boolean algebra
- 4.12 Complex Sample: combination of check-function with dyn. helper-functions
- 4.13 Complex sample: one member of each project role must sign-off or one member of all must decline
- 5 Modify your workflow(s)
- 6 Additional options
- 6.1 Disable delegation of decisions
- 6.2 Enable justification of decisions by comments
- 6.3 Disable forcing a comment if decline
- 6.4 Disable displaying individual users
- 6.5 Disable displaying all deciders and reduce to the current user's decisions
- 6.6 How to configure "Revert (all | my) decisions"
- 6.7 Display decision buttons for deciders only if their decision has got an effect on the final result
- 7 Email Notifications for all deciders
- 8 Search via JQL
- 9 Bulk decisions & project panel “my pending decisions”
- 10 Integration into Confluence as a macro kind of “Jira issues”
- 11 Integration as a new gadget on your dashboard
- 12 Audit logging
- 13 Sequential approvals
Subpages:
Global prerequisite(s)
GDPR - necessary permissions
Permissions required: "Browse users and groups" -> global permission.
According GDPR, this app does not store any personal data by itself. All user entered data are stored within Jira properties within your own Jira instance hosted by Atlassian: no data will be stored outside your Jira instance at all!
Create/Modify Group Sign-Off fields
(System) Admins: configure fields for Company-managed as well as Team-managed projects
Please create new fields of type "Group Sign-Off" as many as you need, like "Steering Committee", "Product Board" etc.
Switch into your Jira Administration → System → Group Sign-Off fields (you have to scroll down the menu to find this item) or alternatively, click on "configure" within the related section on page "Manage apps" as shown on the sample screenshot on the right.
Click on the icon "+" to add a new field
enter a unique name for your new field
on tab "(dynamic) Rule", enter your rule for determining the related deciders (users) as well as the sign-off formula
on tab "Context", enter all valid issue types as well as projects to specify which issues will display this new field
on tab "Context", you can optionally upload your own icons for the buttons "decline" and "sign-off" being presented to the deciders
on tab "Auto-Transitions", you can optionally specify the transition ID of your related workflow (see: allowed issues as configured on tab "Context"), which will be triggered automatically in case of a final "sign-off" or "decline"
on tab “Blocking transitions“, you must configure which workflow transitions, identified by ID, will be blocked until this Group Sign-Off field is finally decided. After creating this field, do not forget to add the condition “GSO: Block transition until finally decided” to these workflow transitions.
finish by hitting on the button "Create"
Click on the pencil icon in the middle of the screen to edit that row's field configurations (analog to create such a field)
Click on the tray-icon in the middle of the screen to move that row's field on tab "inactive fields": all data are kept but inactive fields will not be displayed on the screen. On tab "inactive fields", you can finally delete a field or revert your action by moving it back to "active fields".
Configuration of Group Sign-Off fields in Team-managed projects by the team
Additionally to all admins, using the global app configuration, all project-specific Group Sign-Off fields can be maintained within team-managed projects by the team themselves (see section “Team-managed projects“ in Usage (Jira Cloud) ).
How to get the transition ID for auto-transitions?
In team-managed projects, Atlassian has improved the GUI to edit workflows but hides the internal transition ID. As a transition name is optional, this cannot be an alternative because it is not guaranteed unique, although it would be the easiest approach. Therefore, you have to do the following 5 steps to get the transition ID within team-managed projects, once:
In company-managed projects, you can switch into the Jira Administration as a system admin. There, open the related workflow and click on EDIT, then switch from the graphical view to the text view to see the transition IDs of all your transitions:
Static Rule
You have to determine, who is allowed to make a decision. Using the feature of setting a default value of a customfield, you can define it once and it will be taken over while creating a new issue automatically.
A definition of a decision is divided into two parts and stored as value within the related customfield:
the list of responsible users being able and allowed to decide and
a rule to determine the final result of the decision.
The list starts at the first character, first line with the login name of the responsible user: one user per line. Each line has to be terminated by a line-break. If the login name is unknown, it will not be displayed on the screen. The list of users end with a blank line for a better overview.
The rule for the decision starts with "sign-off=" followed by a boolean expression. Internal validation of the rule will be done by replacing all login names by their related decisions (sign-off = true and decline = false, pending = nothing). As soon as this rule results in a final TRUE or FALSE, it triggers the configured listener (see below). Having no individual decisions at the beginning or necessary pending ones, the result cannot be determined and nothing happens. The boolean expression can contain brackets "(" and ")" as well as "AND" and "OR" to describe the relationship of individual decisions. If the IT-boss or her/his representative can decide, one of both sign-offs is enough, and the business product owner has to sign-off as well the rule would be like: (boss OR representative) AND productOwner.
GDPR makes it necessary to use account ids
If an automatic conversion from a user name or email into an account id is not possible, which depends on various scenarios and cannot be simply answered, you have to use the account id of deciders instead. Generally, that should not be necessary but in case you need it for uniqueness, you can find the accountId of a user as described below.
How to get the account id of a user?
The easiest way to find your account id is to click on your icon on the sidebar (left/most down icon with your avatar image) and then on the "Profile" link. Then, have a look at the URL within your browser: your accountId is the string after the last "/" marked bold in the sample below:
Sample: https://******.atlassian.net/people/557058:7b5dfd59-30f7-4f0e-864d-34fb8ba6e452
Such accountId has to be adjusted by replacing the colon (":") by double underscores ("__") and all minus ("-") by a single underscore ("_").
Simple Example of a definition
fpolscheit
representative
sign-off=(fpolscheit OR representative)
If you want to put additional information to the user name, you can add this as a comment straight after the user name and enclosed by /* and */:
Simple Example with additional user infos
fpolscheit /* Manager */
representative /* Alternative Voting */
sign-off=(fpolscheit /* Manager */ OR representative /* Alternative Voting */)
By clicking on "Update", each user name will be replaced by it's related account id before storage within a Jira property due to GDPR. If the automatic migration to an account id is not possible, a WARNING hint will be written at the end of the rule as comment and a related warning sign will be displayed on the right side of the field name within the overview list of all group sign-off fields. Such scenario occurs, if for example a specified user name is not unique (API request /rest/api/3/user/search?query=username results in multiple account ids).
Use comments to display them as additional infos:
Dynamic Rule(s) for more complex but flexible approaches
Instead of explicitly declare a list of users and a sign-off rule using boolean algebra, you can specify a dynamic rule, which extracts the users out of referred other fields like multi-user pickers. A dynamic rule MUST start with a first-line just containing "// conditional rule". Then, users and a rule have to be defined as described below:
Within a dynamic rule, the reserved words in blue within the following complex example are mandatory!
Within a condition, you can access all issue fields like issue.summary, issue.customfield_xyz, etc. as JSON objects; see sample extract, below:
issue = {
"statuscategorychangedate": "2021-10-03T22:13:08.902+0200",
"fixVersions": [],
"resolution": null,
"lastViewed": "2021-11-04T17:23:09.785+0100",
"priority": {"self": "https://polscheit.atlassian.net/rest/api/2/priority/3","iconUrl": "https://polscheit.atlassian.net/images/icons/priorities/major.svg","name": "Major","id": "3"},
"labels": [],
"aggregatetimeoriginalestimate": null,
"timeestimate": null,
"versions": [],
"customfield_11549": null,
"issuelinks": [],
"assignee": {"name": "unassigned"},
"status": {"self": "https://polscheit.atlassian.net/rest/api/2/status/10002","description": "","iconUrl": "https://polscheit.atlassian.net/images/icons/statuses/open.png","name": "To Do","id": "10002","statusCategory": {"self": "https://polscheit.atlassian.net/rest/api/2/statuscategory/2","id": 2,"key": "new","colorName": "blue-gray","name": "To Do"}},
"components": [],
"customfield_11536": [{"self": "https://polscheit.atlassian.net/rest/api/2/customFieldOption/10159","value": "administrators","id": "10159"}],
"aggregatetimeestimate": null,
"subtasks": [],
"reporter": {"self": "https://polscheit.atlassian.net/rest/api/2/user?accountId=557058%3A7b5dfd59-30f7-4f0e-864d-34fb8ba6e452","accountId": "557058:7b5dfd59-30f7-4f0e-864d-34fb8ba6e452","avatarUrls": {"48x48": "https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/FP-0.png","24x24": "https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/FP-0.png","16x16": "https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/FP-0.png","32x32": "https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/FP-0.png"},"displayName": "Frank Polscheit","active": true,"timeZone": "Europe/Berlin","accountType": "atlassian"},
"issuetype": {"self": "https://polscheit.atlassian.net/rest/api/2/issuetype/10001","id": "10001","description": "A user story. Created by JIRA Software - do not edit or delete.","iconUrl": "https://polscheit.atlassian.net/secure/viewavatar?size=medium&avatarId=10515&avatarType=issuetype","name": "Story","subtask": false,"avatarId": 10515,"hierarchyLevel": 0},
/* ... and many others left out within this sample extraction */
}
Additional functionalities are also provided via an helper object (see samples below):
contains(collection, string)
contains(collection, id as number)
getCF(issue, customfieldName)
getCFms(issue, customfieldName) to retrieve a customfield's value in milliseconds
getUsersByCustomfield(issue, customfieldName, operand) to retrieve a (list of) user(s)
customfieldName can be any custom field of type single-user picker or multi-user picker*) getUsersBy