Skip to main content

Jira Connector

The Jira Connector integrates Alvao with Jira, streamlining ticket management and communication.

Key features include:

  • Create Jira work items directly from Alvao for a seamless workflow.
  • Ensure consistent ticket statuses with automatic bidirectional synchronization.
  • Keep messages and attachments in sync between both platforms for effective collaboration.
  • Access Jira work items directly from Alvao for quick and easy navigation.

Example process:

The Development ticket status is mapped on the ToDo Jira work item status in this example. When a ticket in Alvao goes into this status, a work item of defined type is created in Jira. When the work item enters the In Progress status, the ticket automatically goes to the Development pending status. After resolution of the work item (Done status), the ticket in Alvao transits to the Testing status.

Technical requirements​

  • Jira Cloud or Server

SaaS​

  • ALVAO ITSM or Service Desk subscription

On-premise installations​

  • ALVAO Service Desk
  • Alvao REST API accessible from internet

Installation​

Administrator rights are required for the installation.

  1. Download the JiraConnector.zip package.

  2. In the Administration - Service Desk - Services tree, select the folder where you want to import the sample service to connect to Jira, and use the Import command to load the JiraConnectorServiceEnu.xml file, which is included in the JiraConnector.zip file.

  3. Go to Administration - Applications and enable the Jira Connector application.

    Manual download: JiraConnector.xml

Jira Personal Access Token​

  1. In Jira, create dedicated account for this integration, name it "Alvao Connector" and create a Personal Access Token (PAT).

  2. Go to the Administration - Settings - Advanced page. Use the New setting command to create the JiraIntegrationToken0 setting with value:

    • For Jira Cloud (SaaS), enter value in the format <username>:<PAT>, e.g., james.smith@onmicrosoft.com:TT3xGF0T97pYKtidC3mcL5SC_71xB9irVIZozbnHg.
    • For Jira Server (on-premise), enter the PAT.

  3. Make sure the account has following permissions:

    • Project permissions:
      • Browse projects
      • Create issues
      • Create attachments
      • Add comments
      • Transition issues
    • Global permissions
      • Browse users and groups (when using setting TicketReporter=Requester)
tip

You can use multiple access tokens if, for example, you need to integrate Jira from different organizations into a single Alvao instance. Create a new setting and increment the number at the end of the setting name. Then use this number in the AccessToken item in the service setting below.

Setting up webhooks in Jira​

  1. In Jira, create a new webhook and set up:
    • Name – enter Alvao Connector.
    • Status - Enabled
    • URL - enter the URL of the Alvao REST API, followed by the path /connectors/jiraCallback/{issue.key}, e.g.: https://contoso.onalvao.com/AlvaoRestApi/connectors/jiraCallback/{issue.key}.
    • Scope – set the webhook to be triggered by only selected projects, e.g., project = JIRAPROJECT.
    • Events – enable Comment – created.
  2. Set the webhook to be triggered by workflow transitions that you want to synchronize to Alvao (they are part of the StatusMap).

Setting up service in Alvao​

  1. In Administration - Service Desk - Services, select the service you want to connect to Jira and use Edit - Properties.

  2. In the Other section, find the External Application - Connector Settings custom field and edit the value.

    The default value:

{
    "ConnectorType": "Jira",
    "URL": "https://jira.contoso.com",
    "AccessToken": "0",
    "AttributeMap": {
        "summary": "[$TicketTitle$]",
        "description": "[$OriginalMessage$]",
        "issuetype.name": "Bug",
        "project.key": "JIRAPROJECT",
        "customfield_10123": "[$TicketID$]"
    },
    "StatusMap": {
        "ToDo": "Development",
        "In Progress": "Development pending",
        "Done": "Testing"
    },
    "SyncCommunication": true,
    "DisplayOpenExternalCommand": true,
    "TicketReporter": "Requester",
    "CustomHttpHeaders": {
        "X-AlvaoHeader": "Header value"
    }
}

Legend:

  • ConnectorType - enter the text Jira.

  • URL - enter the URL of the Jira, e.g., https://jira.contoso.com.

  • AccessToken - enter the Personal Access Token (PAT) setting number that you used in advanced settings (typically 0).

  • AttributeMap - specify the list of Jira issue fields and their values. You can use the same variables in the values, as for the status change notification template to requesters.

  • StatusMap – specify the mapping of the Jira work item statuses to Alvao ticket statuses. When first moving to a status in Alvao that is present in the mapping, a work item is created in Jira. The created work item's id is stored in the External Application – the ticket ID custom field. Status synchronization occurs when the status changes in either Alvao or Jira.

    Statuses in Alvao are in Alvao’s default language, while statuses in Jira are in Jira’s default language.

  • SyncCommunication – (true | false). If enabled each ticket communication record (email message, note, etc.) is propagated as a comment of the related Jira work item, and every work item comment in Jira that is marked as public is logged in Alvao ticket communication and the ticket assignee is notified by email or MS Teams bot.

  • ShowOpenExternalTicketCommand – (true | false). If enabled, the Open related Jira ticket command is displayed on the Ticket page of each synchronized ticket.

  • TicketReporter – choose who will be designated as the Jira work item reporter:

    • Default – the user whose PAT is used in the connector configuration.
    • Requester – the Alvao ticket requester; The Alvao user is paired with Jira user by username. If no matching Jira user is found, the Default option is used.
    • Specific Jira user's username, e.g., user@contoso.com.

  • CustomHttpHeaders – optionally additional HTTP headers sent to Jira REST API.