Configuring Jira Service Management approvals
Jira Service Management allows you to add an approval step to a status in a workflow, which allows you to specify if an approval is needed for issue types (and their associated request types) that are mapped to the workflow. The option to add an approval step is only available if the workflow is associated with at least one Jira Service Management project. If you add an approval step to the workflow, and that workflow is also used by a non-Jira Service Management project, the issues in the non-Jira Service Management projects can still be worked on in the usual way, but the approval step will not be enforced for those issues.
You can configure more than one approval step on a workflow, and you can specify if the approval step requires one or more approvers. For example, you may want a manager to initially approve a request, and then two members of your finance team to make the final approval on the request. You can also decide whether you want the customer to select the approver, or if you want the approver to be selected from a predefined list.
If you want to enforce an approval, so that an approver must make a decision before the request can be progressed, you should set the approval step on a status that only has two outgoing transitions, one to Decline and one to Approve. You can set the approval step on a status that has more than two outgoing transitions, but you can only enforce two of these, the additional transitions can be actioned by a Jira Service Management agent. For example, there may be exceptional circumstances where you can't wait for an approval, so you need a way to progress the request manually.
Having additional transitions on the status with the approval step allow your agents to progress the request. Transitions used by the approval step skip transition screens, so if your decline or approve transitions are going to a 'Done' status, add a post function that sets the resolution of the request so it's considered closed by Jira Service Management.
- Decline: This transition leads to a Done status, and should have a post function that sets the resolution to close the request.
- Description: This is generated from the status description, but it won't show on your customer portal.
How it works
An approval step is an additional configuration item that you can place on a workflow status. When a request is transitioned into this status, the nominated approver/s will receive an email informing them that they have pending approvals. If the approval step only has two exiting transitions, it can't be actioned by anyone until the approver has either approved or declined the request. An agent can add, edit or remove approvers, but can't transition the request until it's been approved. If there are more than two exiting transitions, an agent will be able to transition the issue via the transitions not used in the approval step for Decline or Approve.
To add a user picker custom field to your JIRA instance and configure an approval step on a workflow, you need to have the JIRA administrator global permission. To add a field to a request type, you need to have the JIRA administrator global permission or the administrator project role for that project.
Jira Service Management request types are mapped to JIRA issue types, and the issue types are in turn mapped to a workflow. When you add the approval step to a workflow, it will applied to all issue types mapped to that workflow, and hence all request types mapped to those issue types. It's important to make sure your approval step is valid for all issue types. If you want to add an approval step for one request type that's mapped to a workflow which is applied to multiple request types, you should create a separate workflow and issue type that you can map to the request type individually. For more information on how to do this, read up on creating issue types, associating issue types with projects, and working with workflows.
Before you add the approval step, you should ensure that the status has at least two outgoing transitions. If either of the transitions you want to use for Decline or Approve lead to a status in the Done category, you should also configure a post function on the transition to set the resolution of the request.
To add an approval step:
- In the upper-right corner of the screen, select Administration
> Projects, and select the relevant project. - In the Project settings menu, select Workflow. All workflows associated with your project will display.
- Select Edit
in the Actions column of the workflow you want to modify. - Select the status you wish to add the approval step to. The status dialog will display.
- Check the Add approval check box in the status dialog. The Add approval dialog will display.
- Fill in the Add approval dialog with your user picker custom field, how many approvers are required, and which transitions to use for approval and decline.
- Click Create to add your approval step.
Don't forget to click Publish to make your workflow available! You should also check that if the transitions you're using for the approval step lead to a status in the Done category, they should have a post function to set the resolution of the request so that it shows as closed.
Depending on your use case, there are 3 ways to configure the user picker custom field that you selected on your approval step.
- You want your customers to select the approvers - this is useful if you don't know who the approver may be, but the customer does, for example their manager. In this scenario, you need to make sure the user picker custom field is available on the portal so that the customer can make the selection when they create the request.
To add the user picker custom field to your request type:
- In the upper-right corner of the screen, select Administration > Projects, and select the relevant project.
- Select the required project from the project list.
- In the Project settings menu menu, select Request types.
- Select Edit fields in the Actions column of the request type you want to add the field to.
- Click + Add field and select the field you want to add, and click Apply. The field will be added to your request type.
- Edit the Display name (this is the name that will display on your customer portal) and Field help (this is the information that displays next to the field on the customer portal) fields by selecting them and entering your text. You can also decide whether to make the field optional or not at this point. Click Update to save your changes.
- The field is added as Shown. You can change the order of the fields by dragging and dropping.
- In the upper-right corner of the screen, select Administration
- You want to set a pre-defined list of approvers - This is useful if the customer doesn't know who the approver may be, or if you know that there is a set list of approvers for the request. The customer won't need to enter any approvers when they create the request, and when the request is transitioned to the status that has the approval step, the pre-defined set of approvers will be notified. In this scenario, you need to add the user picker custom field to your request type as described above, and then select the option to Hide it. At this point, Jira Service Management will ask you to populate a list of approvers. Save this, and your field is hidden and your list of approvers is set.
- You want your agents to specify the approvers - This is useful if the customer doesn't know the approver, and the approver depends on the information on the request. In this case, the agent will need to review the request, and manually add an approver. View the request in your service project, and the user picker custom field is displayed in the People section of the request. You can make any changes you need to make inline. Note that there is also an Approval section that lists all approvers, however you can't make any edits here. If the field isn't showing, you may need to get a Jira administrator to check the field is still available on your project screens.