Jira system admins have to do a lot within larger companies and cannot take care about individual projects out of hundreds. Therefore, you can setup and configure all necessary sign-off/approval-rules for my app "Group Sign-Off/Multi-Approvals for Jira" as project administrator, now: such rule for sign-off/approval will be stored as a default value within a new context of the related custom field for the maintained project only. Additionally, all screens will be adjusted to also contain this Group Sign-Off field except for the screen of the issue-create-operation.
Create additional customfield(s)Please create any many new customfields of type "Group Sign-Off" as you need, like "Steering Committee", "Product Board" etc. Within this documentation, I am focussing on one new customfield named "Sign-Off". If you are not familiar with creation of new customfields, please have a look at the Atlassian documentation for this standard feature of JIRA. | |
In order to get the related unique ID of your new customfield, please click on the "configure" menu item as visible on the screenshot. | |
Within the URL, you will find the unique ID of your customfield as parameter, here: 10100. Please write it down to remember. You will need it while configuring listeners later. | |
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:
Simple Example of a definition fpolscheit representative sign-off=(fpolscheit OR representative) If you want to put additional information in front of the user name, you can add this as a comment straight after the user name without any spacing and enclosed by /* and */. Attention: you have to use the combination of name and comment as unique identifier within the sign-off rule. Background: you may have different roles and act in different contexts. Simple Example with additional user infos fpolscheit/*Manager*/ representative/*Alternative Voting by*/ sign-off=(fpolscheit/*Manager*/ OR representative/*Alternative Voting by*/) | |
Dynamic Rule(s) for more complex but flexible approachesInstead 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 custom fields like single- or multi-user pickers etc. A dynamic rule MUST start with a first line just containing "// conditional rule". Then, users and a rule has to be defined as described below. Within a dynamic rule, the reserved words in blue within the following complex example are mandatory!
If you are using getUsersByCustomfield(), getUsersByProjectRole(), getUsersByGroup() the name of the referred element (custom field, project role or group) will be displayed in front of the retrieved user name since Group Sign-Off version 1.4.0. Complex Example with different syntax: use a customfield (multi-user or user picker) to dynamically specify voters // conditional rule users =""+helper.getUsersByCustomfield(issue,"Board Members",","); Please use the exact syntax above for dynamically specifying the list of user(s) based on the referred custom field. Users must be a comma separated list, that why the operand is a comma. The rule must be a sequence of users, concatenated by a boolean operand (AND or OR). By the first voting, the content of the customfield, referenced by name as parameter, will be taken over and the members will become a fix list. Instead of using the custom field's name, you can also use it's ID: please put that number into the quotes like "10023" instead of "Board Members". Complex Example with different syntax: a set of conditional definitions depending on issue's data // conditional rule if ( helper.contains(issue.getComponentObjects(),"Component A") ) { users = "fpolscheit, admin"; rule = "fpolscheit OR admin"; } else if ( helper.contains(issue.getComponentObjects(),"Component B") && (issue.getPriorityObject().getName() == "Blocker")) { users = "admin, tester"; rule = "admin AND tester"; } else { users = "admin"; rule = "admin"; } You can also access all function of an issue provided by the Atlassian Java API, like within the following sample of extracting the issue's reporter and use this for approval: Complex Example accessing issue's functions to dynamically retrieve approver name(s), here: issue's reporter // conditional rule If you are using multiple custom fields to retrieve all users, who have to decide all together, you have to concatenate the custom fields content and use a logical operator within the dynamic rule. The sample below illustrates proper usage. Concat of multiple custom fields' contents // conditional rule users =""+helper.getUsersByCustomfield(issue,"Board Members",",") + helper.concat(helper.getUsersByCustomfield(issue,"Managers", ","), ","); All members of the custom field "Managers" will be appended but if there is at least one user, only. Concat of multiple custom fields' contents (also: some maybe empty) // conditional rule users = "" + helper.getUsersByCustomfield(issue, "myApprovers1",",") + helper.concat(helper.getUsersByCustomfield(issue, "myApprovers2",","), ",") + helper.concat(helper.getUsersByCustomfield(issue, "myApprovers3",","), ","); rule = "" + helper.getUsersByCustomfield(issue, "myApprovers1","AND") + helper.concat(helper.getUsersByCustomfield(issue, "myApprovers2","AND"), "OR") + helper.concat(helper.getUsersByCustomfield(issue, "myApprovers3","AND"), "OR“); // in case that the first customfield 'myApprovers1' is empty: get rid of leading ',' // within the user list as well as the leading 'AND' within the rule: users = users.replace(/^\s*,\s*/,"“); rule = rule.replace(/^\s*AND\s*/,""); Advanced feature for experienced power-user:
| Pay attention: using a dynamic rule, it's resulting set of deciders will be automatically turned into a static equivalent by the first decision for integrity reasons! Background information: if someone has voted (declined or signed-off) and the members of a decision would be changed later, you can manipulate the total result by removing deciders with unwanted votes or add additional deciders. To avoid this, an automatic transition into a fix set of deciders will be done together with the first vote. |
Additional OptionsAdditional options can be added at the end of the definition like shown below. Vote/decide multiple times revoking prior one
Vote/decide multiple times revoking prior one - but limited to revert declines, only
Disable delegation of decisions
Confirm decision by entering password again (re-authenticate)
Disable forcing a comment if decline
Overwrite standard behavior to reload an issue after deciding
Disable displaying individual users
Display decision buttons for deciders only if their decision has got an immediate and direct effect on the total result
Simple Example of a definition with additional option in bold fpolscheit representative sign-off=(fpolscheit OR representative) optionOnce=false | Re-authenticate by entering password to confirm decision if configured as option. |
Special Function(s)
with param-1: Boolean value TRUE or FALSE, whereas true indicates sign-off and false indicates decline Advanced Sample: sign-Off rule based on function calls and boolean algebra fpolscheit sign-off=check(true, 2, fpolscheit,representative,anotherPerson) OR check(false, 1, fpolscheit,representative,anotherPerson) If at least one decider declines, the sign-off will be "declined" or if at least two deciders have voted for sign-off, the result will be "signed-off". Based on 3 possible results of function check(null, true, false), the sequence of both function calls combined with OR is important: if you change both, it will not work properly! Based on boolean logic, false OR null results in null, whereas null OR false results in false which is what you would like to get. So, the check for declined votes via check(false,...) has to be the second part after the OR-connector. A more complex sample combines the check-function with other dynamic helper-functions retrieving sets of deciders: at least 2 deciders out of the project roles "Developers" and "Administrators" have to sign-off, so that this rule switches into the state "signed-off". But if 1 decider declines, it results into "declined", immediately. Complex Sample: combination of check-function with dyn. helper-functions // conditional rule Expanation: using a dynamic rule, that rule must get a string in quotes like rule = "check(true, 2, x, y, z) OR check(false, 1, x, y, z)", whereas x, y, z is build by helper-functions like a concat of getUsersByProjectRole().
with list of related deciders as comma-separated params like shown within the sample below: just expand your sign-off rule by prepending a call to the function wait_for_all() if you want to overrule the default behavior of switching into the final state as soon as possible. Using a dynamic rule, you have to prepend a call to "wait_for_all()" by concat your original rule like illustrated within the following sample: Sample: Conditional rule using function "wait_for_all()" // conditional rule users = ""+helper.getUsersByCustomfield(issue,"Approvers",","); rule = "wait_for_all(" + users+ ") " + helper.concat(helper.getUsersByCustomfield(issue,"Approvers","AND"), "AND"); | |
Create additional listener(s) for automatic workflow transition(s)You can add multiple listeners to define a switch within your workflow. In case of a signed-off issue, the automatically executed workflow transition should be different from the one in case of declining that issue. As soon as enough individual decisions have been done to determine the final result of the overall decision, this listeners will execute the specified workflow transition immediately like JIRA's event system. Nobody has to check decisions manually!Within admin mode, please select "system -> advanced -> listeners" in order to insert a new listener. The class name must be de.polscheit.jira.plugins.listener.WorkflowAutoTransition whereas the name of the listener can by like you want. | |
After having created a new listener, you must edit it: just click on the related button on the right side of the listener. You must specify three parameters:
Attention: please take care, that your IDs exist and that the specified workflow transition can be executed within your workflow sequence. In case of any problem, the listener cannot execute it. Therefore, I recommend to test your settings carefully! | |
Modify your workflow(s) with new Condition(s)At the point of time when a group decision shall happen, it does not make sense to click on the related button and continue the workflow without synchronisation with the result of the decision. So, you have to block the further processing by adding a workflow condition "Group Sign-Off".You have to specify the customfield, the workflow condition checks if the result of the rule is equal to the specified value: in that case, the related workflow transition will be visible and executable by a permitted user. | |
Modify your workflow(s) with new Validator(s)Alternatively, you can configure workflow validators for your transitions to define prerequisite results of the related group sign-off field(s) accordingly. | |
Modify your workflow(s) with new Post Function(s)
You have to specify the customfield, the workflow post funciton will use to modify/reset. |
|
Email-Notifications (available since v2.4.1)Each project admin can enable Email-Notifications per Group Sign-Off custom field within the related project administration. Additionally, you can specify which issues fields shall be included in such emails for information without the necessity to open the related issue itself (see sample below). As a decider, you just have to click on the button "Sign-Off" or "Decline" within the email: if you are already logged in to your Jira within an open browser - such single click is enough to approve! Otherwise, you have to log in for security reasons but that's it. | |
Custom Events "Issue Signed-Off Event" and "Issue Declined Event" for automatic Notifications/EmailsAs soon as a final decision has been determined, a related "Issue Signed-Off Event" or "Issue Declined Event" are fired. This feature is available since version 1.7.0. | |
Within a project's notification scheme, you can configure automatic sending of emails to various persons of interest like reporter, watchers etc. Please refer to the original documentation of Atlassian, if you are not familiar with Notification Schemes of Jira. | |
Having properly configured notifications for issue signed-off or declined events, the related users will get emails analog to Jira's standard notification "issue update" like shown on sample email on the right. | |
JQL functionsPendingForCurrentUser(project key, Group Sign-Off customfield name)You can search for all issues of a specified project having a pending decision for the specified Group Sign-Off custom field of the currently logged-in user. CheckForCurrentUser(project key, Group Sign-Off customfield name, decision)You can search for all issues of a specified project being "signed-off" or "declined" for the specified Group Sign-Off custom field of the currently logged-in user. CheckForUser(project key, Group Sign-Off customfield name, decision, user)You can search for all issues of a specified project having a decision as 'pending', 'signed-off' or 'declined' for the specified Group Sign-Off custom field by the specified user. | |
Support of "Rich filters" on Jira dashboards | |
ReportingReport of all pending decisions within specified project or by individual (multi-project) filter. |