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 account for the integration​

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

  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, where <username> is the account's email address.
    • For Jira Server (on-premise), enter the PAT of the dedicated user account.

  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 accounts and their 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.

Jira Cloud scoped API token​

As an alternative to the classic API token described above, Jira Cloud also supports service accounts managed at the organization level, with scoped API tokens (credentials) that restrict access to only the permissions they need.

  1. Sign in to Atlassian as an organization administrator.
  2. Go to Directory – Service accounts and create a new service account (e.g., name it Alvao Connector).
  3. Open the service account and use the Create credentials command.
  4. When prompted to choose the credential type, select API token.
  5. Give the credentials a label, e.g. Alvao Connector, choose the app Jira, and select the following classic scopes:
    • read:jira-work – browse projects, read issues, list transitions and attachments.
    • write:jira-work – create issues, add comments, upload attachments, execute transitions.
    • read:jira-user – resolve users (ticket reporter, comment authors, integration account lookup).
  6. Click Create, then copy the generated API token immediately (it is shown only once).
  7. Use the token in the JiraIntegrationToken0 advanced setting in the format <username>:<token>, where <username> is the service account's email address.
tip

The scopes above are usually sufficient on their own, since a project's default permission scheme typically already grants the required project permissions to any account with Jira product access. If you use a custom/restricted permission scheme, make sure the account also has the permissions listed above assigned for the relevant project – scopes only define which API operations are allowed, they do not replace project-level permissions.

info

Requests authenticated with a scoped API token must be sent to the Jira Cloud API gateway (https://api.atlassian.com/ex/jira/<cloudId>) instead of the site's own domain (https://<your-site>.atlassian.net). Set the URL in the Connector Settings accordingly.

Getting the cloud ID​

The <cloudId> identifies your Jira Cloud site and is required for the gateway URL. Get it by opening the following URL in a browser (no authentication required):

https://<your-site>.atlassian.net/_edge/tenant_info

The response contains the cloudId, e.g.:

{ "cloudId": "30f44b5f-3325-410e-887e-8086fbb413eb" }

Changing the URL in the connector settings​

When using a scoped API token, set the URL attribute in the connector's External Application - Connector Settings to the gateway URL with the cloud ID, instead of the site's domain:

"URL": "https://api.atlassian.com/ex/jira/30f44b5f-3325-410e-887e-8086fbb413eb"

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. When using a Jira Cloud scoped API token, enter the API gateway URL with the cloud ID instead, e.g., https://api.atlassian.com/ex/jira/30f44b5f-3325-410e-887e-8086fbb413eb.

  • 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 transition 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 transition 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.