Overview

The Approval Mappings Administration screen displays the list of configured Approval Mappings:

Here, you can add, edit, delete, copy, move and view your  Approval Mapping configurations.

The screen provides the capability to display :

• All configured mappings.
• The Mappings associated to the Only Selected fields Project and Issue Type.

Preliminary setup - Mapping Global Settings

The Global Settings button allows you to setup the following configurations:

• Automatic Workflow Transition (AWT/AWTR)
• Notify Approvals via Comment (NAC)

Automatic Workflow Transition global settings

The Automatic workflow transition global settings screen let you able to choose two alternative settings:

• Forced Automatic Transition (Default)
• Responsive Automatic Transition (Recommended setting)

When you enable the Forced Automatic Transition, the automatic transition fires not running any workflow post function and not checking any condition and validator.

When you enable the Responsive Automatic Transition, the automatic transition fires  running workflow post functions  only after checking conditions and validators.

If you enable the Responsive Automatic Transition, it's mandatory to select an User that will be used by the app to fire the transition.

The selected user will be recorded on issue's history as the author of the transition.

On saving, the application grants transition issue privileges to the selected user on any projects. 

Configure Notify Approvals via Comment Global Setting

The Notify approvals via comment  global setting allows you to enable the approval notification and the approbation/rejection via JIRA comments.

By default, this option is Disabled.

When enabling the functionality, you must specify the user that the app will use to append the Jira comment.

The chosen user will be recorded as the author of the approval notification on the JIRA comment.

When enabling this option globally, you will be able to activate the functionality on an Approval Mapping.

How to create Approval Mappings

1. Click Add Approval Mapping to create new Approval Mappings
2. Fill the fields Project and Issue Type showing up on the Add Approval Mapping screen and click Add
   
3. Set up your Approval Mapping configuration
   1. Select a workflow transition and drag and drop the Available Approvals under the Requested Approvals column  
      
   2. Optionally apply Advanced Settings
      

Advanced Setting of an Approval Mapping

Automatic Workflow transition

The Setup Automatic workflow transition allows you to enable:

• the Automatic transitioning of the issue based on received approbations (by default All approbations)
• the Automatic transitioning of the issue based on received rejections (by default All rejections)

If the Automatic Transition on approbations and/or rejections is enabled then the option Collect all replies to transition appears  in the panel:

This option allows to collect all replies before to transition which means that the app will wait every approver to express his vote before it transitions automatically following the minimum required approbations and/or rejections conditions that were configured.

Automatic Approval Request Notification via email

The Setup Automatic Request Approval notification screen allows to notify approvers automatically via email of a new pending approval request.

The notification is sent once when the issue moves in the selected Source Workflow Status 

If you need to resend automatically the Approval Request email notification after an elapsed time you need to setup the Approval Request Email Automation advanced setting.

Notify approval via comment

The Setup Notify approval via comment screen allows to enable

•  the automatic notification via comments of the approval request  when the issue moves in the selected source status 
•  the approval reply via comment, so that the app processes added comments in order to trigger, when the comment is a valid response, the approval change of status

Require Approval Comment

The Setup Require Approval Comment screen allows to require that the approver inserts an approval comment to justify the approval decision.

This setting is effective for approval responses provided via email and via issue web panel.

Sequential approval

Select Sequential Approval in order to enable the sequential approval.

It causes that the approval decision must be submitted in the order established on the requested approvals column.

You are able to establish the sequential order of the requested approvals via drag & drop:

You can choose to submit for approval the subsequent approval independently by the response gets on the preceding approval or only case of it gets an approbation (Default).

Optional approvals

Select Optional Approvals in order to choose the Optional Approvals.

The Optional Approvals consist of particular Approvals that case of they don't get the vote, the Approval is not considered but if they get the vote, their vote is considered same than other to evaluate the result of the approval stage.

By Default All approvals are considered  Mandatory.

If an issue requires at least one Optional Approval, the app behaves as described below:

• When the ‘Collect all replies before to transition’ is turned ON, the app expects to collect All Requested Approvals replies (with the exclusion of Optional Approvals replies) before to transition.
• When no ‘minimum required approbations/rejection (conditioned and unconditioned)’ exists,
  • the app allows the transition only when All Requested Approvals (with the exclusion of Optional Approvals replies) have been approved/rejected
• When any ‘minimum required approbations/rejection (conditioned and unconditioned)’ exists, the app evaluates the available settings as follows: 
  • All,the app allows the transition only when All Approvals (with the exclusion of Optional Approvals that have not gotten any reply) have been approved/rejected
  • Fixed Number, the app allows the transition only when the number of approvals has been reached (it includes either the optional and the mandatory approvals)
  • Percentage, the app allows the transition only when the percentage of approbations allowing to transition has been reached ( the percentage is evaluated counting the mandatory approvals and the optional approvals having replied).

 E.g. Case of it's requested the 50% of approbations to transition, If the evaluation of the formula Count(approbations)/[Count(Requested Approvals)- Count (Optional Approvals) + Count (Replied Optional Approvals)] is >= 50%,  the transition is unlocked.

See also a customer use case implemented via this feature at: Capability to define a mixture of mandatory and optional approvers.

Condition enabling/disabling the approvals

Select Condition enabling/disabling the approvals in order to enable the approvals when the Conditional Rule, evaluated on the issue, returns true.

Abstain

Select Abstain in order to enable or disable the Abstain option for the specific Mapping.

On enabling this option you allow to approvers to abstain from taking the approval decision.

An abstention is evaluated as an agreement to the decision taken by the votes of all the other approvers.

This setting overrides the Abstain Global setting.

Super Approvers

Select Super Approvers in order to setup expressions identifying the users enabled to provide the approval response on behalf of the effective approver.

Transition on rejecting

Select Transition on rejecting in order to select the transition to perform on rejecting

E-Mail Templates

Select the E-Mail Templates option in order to  to choose the email templates to apply when notifying the Approval Request and an Approval Reply emails.

Approval Reply Notification Scheme

Select the Approval Reply Notification Scheme option in order to  to choose the Approval Reply Notification Schema to apply when notifying the Approval Reply emails.

Minimum Required approbations/rejections

You can setup the Minimum Required approbations and rejections conditioned or unconditioned rules to specify if the approval step can be considered approved or rejected based on subset of  stakeholders reply.

  See Minimum Required approbations and rejections for further information and examples regarding this setting.

Minimum Required approbations/rejections unconditioned 

Minimum Required approbations unconditioned

Select Minimum Required approbations unconditioned  in order to set-up how many approbations are needed in order to enable  the associated workflow transition or, case of the /wiki/spaces/HAP/pages/12006169 option is ON, triggering the automatic transition of the issue .

Minimum Required rejections unconditioned

Select Minimum Required rejections unconditioned  in order to set-up how many approbations are needed in order to enable  the associated workflow transition or, case of the /wiki/spaces/HAP/pages/12006169 option is ON, triggering the automatic transition of the issue.

Minimum Required approbations/rejections conditioned

 Select Minimum Required approbations/rejections conditioned in order to set-up the minimum required approbations/rejections allowing to transition or, case of the /wiki/spaces/HAP/pages/12006169 option is ON, triggering the automatic transition of the issue.

Decision Automation

Select Decision Automation to allow an automatic approval change status (Automatic Decision) when the approval requests are found in pending after a given amount of time (Elapsed Time). 

The automatic decision will be traced as performed by the selected user.

Approval Request Email Automation

This setting allows to run automatic email reminders when an approval is still in pending after the specified amount of time (Elapsed Time) that has passed between the current data/time and latest notification data/time (when applicable) or the approval’s submit date/time.

 The Submit date is considered on behalf of the latest Notification Date only case of the Approval Request was never notified.

In addition, you are able to select (optionally) a Date Field chosen from a list including the Due Date and each existing Data picker custom field.

The value on the Data field, on the concerned issue, when specified, will establish the start date for running the automatic email reminders.

The Skip Notification field, when specified, will establish if the app must run automatic email reminding basing on the evaluation of the selected Conditional rule.

The periodical evaluation of the email automation depends by the Approval Service's Schedule.
Navigate on the Jira Service Administration screen to configure Approval Services (Class name: com.herzum.approval.service.email.ApprovalRequestAutomation) reusable across different Approval Mappings.

 Some sample use case example can be reviewed at:

• Automate resending the Approval Request email notification after an elapsed time
• Approval Emails Automation

Approval Status shows on Customer Portal

This setting allows to enable the approval status view on the Customer Portal on Mapping or Single Issue Approval configuration basis:

Editing an Approval Mapping

You are able to update existing  Approval Mappings.

When updating an Approval Mapping the approval data associated to existing issues are made consistent with the applied changes.

When editing an Approval Mapping, you will display its status on the  Approval Mapping Administration screen.

An Approval Mapping can assume the following Status:

•  if existing issues are consistent with current Approval Configuration 

• if the Approval Mapping has been configured but on exit it has not be saved yet.

   In order to save the mapping just click on 

•  if the operations to make existing issues consistent with the new Approval Mapping have not been completed jet. 

  While the mapping is locked the Edit and Delete operations are disabled.

  In order to check if the app has completed restoring consistency, just click on :

  • If the operations of restoring the consistence of the Approval mapping configuration on the existing issues have been completed,  the lock disappears
  • if the operations are still in progress, the following pop-ups can be displayed
    • If elapsed time is less the one hour
      
    • if elapsed time is greater the one hour
      

Deleting an Approval Mapping

 When deleting an Approval Mapping the approval data associated to existing issues are deleted.

Bulk operations

Overview

The Bulk Operation utility allows you to copy, move or delete the existing Approval Mappings massively.

1. Click Bulk Operations to navigate the Bulk operations screen
   
2. Choose the operation you wish to perform and the type of input for the selected Operation
   
   1. the option Copy let you able to create new mappings for the selected Destination Projects or  Projects/Issue Types or Projects, IssueTypes, Source Statuses and Transitions destinations basing on the  selected Source Project or a Project/Issue Type or a Project, IssueType, Source Status and Transition. 
   2. the option Move let you able to create new mappings for the selected Destination Projects or  Projects/Issue Types or Projects, IssueTypes, Source Statuses and Transitions destinations basing on the  selected Source Project or a Project/Issue Type or a Project, IssueType, Source Status and Transition  and associate them to the selected and, same time delete the Source mappings..
   3. the option Delete let you able to delete any mappings associated to the selected Projects or Projects/Issue Types or Projects, IssueTypes, Source Statuses and Transitions.
   4. the option Edit let you able to update already existing mappings for the selected Destination Projects or  Projects/Issue Types or Projects, IssueTypes, Source Statuses and Transitions destinations basing on the  selected Source Project or a Project/Issue Type or a Project, IssueType, Source Status and Transition.

Constraints and expected behavior 

Basing on the type of input that you have selected, there are some constraints with regard to the Destination Mappings targets.

Bulk Edit 

The Bulk  'Edit'option allows you to update existing approval mapping configurations basing on the setting applied on an existing mapping.

Bulk Edit by Project 

Constraint 1: the source and the destination Projects have the same Workflow Scheme.

Constraint 2: the destination projects include only the Projects for whom at least 1 approval mapping exists

Expected Behavior: For each Mapping that belongs to the destination projects and for each Mapping that belongs to the source project, the app checks If Source Mapping.Issue Type=Destination Mapping.Issue Type and Source Mapping.Source Status=Destination Mapping.Source Status and Source Mapping.Transition=Destination Mapping.Transition; if the checks returns true, the destination Mapping is updated basing on the settings applied on the source mapping.

Any already existing pending approval is made consistent with the new settings.

Bulk Edit by Project and Issue Type

Constraint 1: the source and the destination Projects/Issue Types have the same Workflow.

Constraint 2: the destination projects/issue Types include only the Projects/Issue Type for whom at least 1 approval mapping exists

Expected Behavior: For each Mapping that belongs to the destination projects/Issue Types and for each Mapping that belongs to the selected source project/Issue Type, the app checks If Source Mapping.Issue Type=Destination Mapping.Issue Type and Source Mapping.Source Status=Destination Mapping.Source Status and Source Mapping.Transition=Destination Mapping.Transition; if the checks returns true, the destination Mapping is updated basing on the settings applied on the source mapping.

Any already existing pending approval is made consistent with the new settings.

Bulk Edit by Project, Issue Type, Source Status and Transition

Constraint 1: the source and the destination Projects/Issue Types have the same Workflow.

Constraint 2: the destination Projects, Issue Types, Source Statuses and Transitions have an Approval Mapping

Expected Behavior: The destination Mappings are updated basing on the settings applied on the source mapping.

Any already existing pending approval is made consistent with the new settings.

 The Bulk Edit operations allows to select a destination only for targets already set with an Approval Mapping.

Bulk Copy and Move

The Bulk  Copy and Move options allows you to create new Approval Mapping configurations basing on the setting applied on an existing mapping.

Constraint for any bulk Copy and Move operation: the chosen destinations must not have an already configured Approval Mapping.

Constraint for the bulk Copy and Move operations per Project:  the Source Project and the Destination Projects share the same Workflow scheme.

Constraint for the bulk Copy and Move operations per Project and Issue Type: the Source Project and Issue Type and the Destination Projects/Issue Types share the same Workflow.

Differently, the bulk Copy and Move operations per Project, IssueType, Source Status and Transition has no constraint (except the general one above).

 The Bulk Copy and Move operations allow to select a destination only for targets not already set with an Approval Mapping.

Bulk operations by example

The following example illustrates all steps to follow in order to perform the bulk copy of the existing mappings on a source project on three target projects:

1. Check the options Copy and Project and click Next
   

2. Select the source project and the target projects in order to create the same Approval Mappings configured toward the source project for the target projects
   

   
   

   You are able to perform this operation on target projects having the same Workflow schema.

   The target projects select-list includes only projects having the same Workflow schema of the source project.

3. Click Confirm to perform the action
   
4. On completing the operation, a dialog reports the number of Mappings that have been updated. Click Ok to exit.