Jira

Introduction

This topic describes integration between Admin By Request and Jira for cloud-based Jira implementations. The integration is relatively simple, comprising three mechanisms: one to create issues in Jira from requests made in ABR, one to handle approved requests and one to handle declined requests. This is the extent of our Jira integration; it is up to the customer to further automate the updating of tickets through Jira automation rules.

Nevertheless, we include in this topic two simple automation rules to illustrate how some things might be done. Customers can use these as the basis for their own automation workflows.

IMPORTANT:

  • The integration covered here is available for Jira Cloud, but not on-premise installations like Jira Data Center Edition.

  • Disclaimer - Admin By Request is not a Jira consultancy and we do not have extensive experience working with Atlassian tools, including Jira. Our integrations and examples are provided for the customer's convenience; they do not carry any warranty whatsoever and must be used entirely at the customer's own risk. We recommend testing everything in a non-production environment and we are not liable for any downtime or loss of productivity or data that might result from using the integrations.

In this article

Prerequisites

1. Creating custom fields

2. Creating a custom Request Type

3. Integrating Jira with Admin By Request

Updating Jira issues

Creating Jira automation rules

Prerequisites

To complete the setup, you will need the following:

  1. A Jira Service Management username and an Admin By Request Portal username.

    You must have administrator access to both Jira Service Management and the ABR Portal.

  2. A Jira Service Management API token associated with your username.

    For information on managing API tokens in Jira, refer to https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/.

  3. An API key in your ABR Portal:

    1. Log in to the portal and navigate to Settings > Windows Settings.

    2. In the left menu, click Data, followed by tab API KEYS.

    3. To create a new API key, click button Add New.

    4. If you want to name this key, click Edit description and name it accordingly.

    5. Click Save to save the new API key:

    Copy the key to the clipboard, ready for pasting in the next step.

    The following test uses VS Code to send a curl statement to the ABR server's API interface.

    A successful test returns 200 OK, plus a list of ABR requests in JSON format.

    Note that if there are no ABR requests in any category (pending, approved, denied or quarantined) then the server will still return 200 OK, but no JSON data:

    1. In your portal, identify the URL to use for API requests. The example below shows https://dc1api.adminbyrequest.com/requests, but your URL might be slightly different.

    2. Enter the following curl statement, using your URL and your API key:

      Copy 
      curl -X GET "https://dc1api.adminbyrequest.com/requests" \
          -H "apikey: <your API key>" 

    3. Send the curl statement. The following examples show the response in VS Code from the ABR server using firstly the REST client and secondly the Thunder client.

      REST client

      Thunder client

      There are multiple ABR requests returned across all states (pending, approved, denied, etc.) - only the first request is shown. Scroll the response you get back to see all requests.

Once you have this information, we’re ready to get started.

There are three main tasks required to configure Jira integration. The next three sections describe each task in detail.

1. Creating custom fields

The integration requires you to set up a few custom fields. These fields hold information about:

  • The ID of the request from Admin By Request (can be used for further automation).

  • The name of the approver (if the request is approved from the platform or via another integration).

  • The reason supplied if a request is denied.

  1. Log in to Jira Service Management and click the cog in the upper right corner to navigate to Settings > Issues:

  2. In the left menu, select Custom fields:

  3. In the Custom fields screen, click button Create custom field and select Field Type Short text (plain text only):

  4. Name the field (e.g. ABR Request ID) and, optionally, provide a description.

  5. Repeat these steps for field ABR Handled by.

  6. Repeat the steps one more time for field ABR Reason, but select the multiline option Paragraph (supports rich text) as the Field Type.

    NOTE:

    You don’t have to select any specific views for the fields - these will be assigned when creating the Request Type in the next section.

  7. Finally, find the ids of the fields just created. To do this, make sure at least one issue exists in your project. Identify the issue number and enter the following URL in a browser:

    Copy 
    https://<your-jira-website>.atlassian.net/rest/api/2/issue/<your-jira-issue-number>?expand=names

    Copy and paste the resulting JSON into an editor that can format it nicely (e.g. Notepad++) and find the labels of the fields created.

    The following example has issue number ABRJIRA-40 (from the "key" field) and shows both field id (customfield_10064) and field name for ABR Request ID:

    The field id for ABR Request ID is needed later in task Example 2 - Approving or Denying ABR Requests in Jira.

    NOTE:

    This is an example - your field id(s) will almost certainly be different.

2. Creating a custom Request Type

A custom Request Type enables Jira to identify any requests coming from theAdmin By Request servers.

  1. Login to Jira and, from the Switch to... menu, select Jira Service Management:

  2. From within Jira Service Management, either create a new project or select the project you want to integrate with. Open the project and select Project settings towards the bottom of the left menu:

  3. From the Project settings menu, select Request types:

  4. On the Service requests screen, use the Create request type button (top right) to create a request type (click the button and select Create blank):

  5. Give the request type a name and select the Issue type as either:

    • [System] Service request

      This sends requests to Jira and updates them as they get approved or denied, OR

    • [System] Service request with approvals

      Works in the same way as the ordinary service request type, but allows designated approvers to approve or deny requests from within Jira.

      With a bit of automation, this also enables Jira to call the Admin By RequestAPI to approve or deny requests directly from within Jira.

    NOTE:

    The automation example (Example 2 - Approving or Denying ABR Requests in Jira) requires that [System] Service request with approvals is the option chosen at this point:

  6. Select the portal group to assign to this new request type (or leave all options blank):

  7. Finally, drag and drop the three newly created custom fields, as well as the Description field into the view of the new request type:

    NOTE:

    • Make sure you are on the Request form tab and not Issue view or Workflow statuses.

    • Make sure the Description field is added along with the three custom fields. Summary and Instructions should already be there.

    • You can leave the ABR Request ID field as “Use preset value and hide from portal” if you do not wish the ABR Request ID to be visible.

  8. Save the changes.

    Everything is now ready to create the ABR-Jira integration.

3. Integrating Jira with Admin By Request

Now that the pre-requisites are in place, head over to https://jira.adminbyrequest.com to start the setup process.

  1. From the Set up Jira integration screen, check once again that you've completed all the prerequisite steps and click button Start setup:

  2. Retrieve your Atlassian API Token as well as your Admin By Request API key and enter these into the setup form alongside your Atlassian username and instance URL:

    NOTE:

    Your username needs to be one that is authorized to make API calls. It is generally the email address recorded under your profile at the top right of the Jira Service Management screen:

  3. Next, you are prompted to select the Jira service desk to associate with the integration:

    If you have more than one service desk project in Jira, a drop-down arrow will appear at the right of the Service desk field, allowing you to select the one you want.

  4. The final screen is where the custom fields you created are associated with the three required by the ABR integration. Request type is already selected for you - choose the other three to match your custom fields:

  5. Click Finish installation to complete setting up the Jira integration.

    New requests from Admin By Request will now be sent to your Jira instance as service requests.

You can check the status of your Jira integration via the portal (Settings > Integrations > Jira):

Updating Jira issues

When a user makes a request via ABR for either an "Admin Session" or to execute something "Run As Admin", a Jira issue is created in your selected service desk instance.

NOTE:

It can take several minutes after the ABR request is submitted for the issue to be created in Jira.

The Jira Summary indicates the type of request: Admin session or Run as admin. This field is updated once the request is either APPROVED or DENIED.

For example, the following list of issues shows one "Run as admin request" waiting for approval, two "Admin session" requests approved and one admin session denied:

What next?

The preceding sections cover the extent of the Admin By Request Jira integration. If you want to do more with Jira issues once they have been created, you can use Jira automation to populate issues with more information or to carry out actions such as email notifications.

IMPORTANT:

The examples provided in the next section are for convenience only - we do not support any Jira automation rules and they must be used entirely at the customer's own risk.

If you do decide to work with Jira automation, note the following:

Creating Jira automation rules

Using the Jira Audit log

The Jira Audit log is a very useful tool when working with Jira automation, especially as an aid in troubleshooting.

Each rule has its own Audit Log:

Linking back to the ABR Portal

A future release of the Jira integration will almost certainly include a link back to the ABR Portal "Requests" page, from where requests can be approved or denied. Until this is available, Example 1 below provides a workaround that customers can implement using a Jira rule (Action 1 - set fields, Description).

  1. Trigger:

  2. IF Request Type is ABR Request for Access:

  3. Action 1 - set fields:

  4. Action 2 - Set Status to Waiting for Approval (possibly optional, depending on workflow):

  5. Action 3 - Send email:

  1. Trigger:

  2. IF Approved:

  3. Action 1 - Send web request (PUT). Important - make sure you read up on API calls here (API Overview) and here (Requests API):

  4. Action 2 - Add Comment to Jira issue (Important - make sure you identify the correct customfield ids - yours might be different from the example):

  5. Action 3 - Set Status to Resolved:

  6. IF Declined:

  7. Action 1 - Send web request (DELETE). Important - make sure you read up on API calls here (API Overview) and here (Requests API):

  8. Action 2 - Add Comment to Jira issue (Important - make sure you identify the correct customfield ids as described in 1. Creating custom fields - even if your field names are the same as the example, your customfield ids might be different):

  9. Action 3 - Set Status to Resolved: