Skip to main content

Jira

Port's Jira integration allows you to model Jira resources in your software catalog and ingest data into them.

Jira cloud only

This integration supports Jira Cloud at the moment. To integrate Port with Jira Server, use Port's webhook integration.

Overview​

This integration allows you to:

  • Watch for Jira object changes (create/update/delete) in real-time, and automatically apply the changes to your software catalog.
  • Define self-service actions that can create/delete Jira objects or perform any other logic on Jira resources.

Supported Resources​

The resources that can be ingested from Jira into Port are listed below.
It is possible to reference any field that appears in the API responses linked below in the mapping configuration.

Setup​

Choose one of the following installation methods:

Using this installation option means that the integration will be hosted by Port, with a customizable resync interval to ingest data into Port.

Beta feature

The Hosted by Port option is currently in beta, and is still undergoing final testing before its official release.

Should you encounter any bugs or functionality issues, please let us know so we can rectify them as soon as possible.
Your help is greatly appreciated! ⭐

Live event support

Currently, live events are not supported for integrations hosted by Port.
Resyncs will be performed periodically every 1 hour by default (can be configured differently after installation), or manually triggered by you via Port's UI.

Therefore, real-time events (including GitOps) will not be ingested into Port immediately.
Support for live events is WIP and will be supported in the near future.

Installation

To install, follow the following steps:

  1. Go to the Data sources page of your portal.

  2. Click on the + Data source button in the top-right corner.

  3. Click on the relevant integration in the list.

  4. Under Select your installation method, choose Hosted by Port.

  5. Configure the integration settings and application settings as you wish (see below for details).

Application settings

Every integration hosted by Port has the following customizable application settings, which are configurable after installation:

  • Resync interval: The frequency at which Port will ingest data from the integration. There are various options available, ranging from every 1 hour to once a day.

  • Send raw data examples: A boolean toggle (enabled by default). If enabled, raw data examples will be sent from the integration to Port. These examples are used when testing your mapping configuration, they allow you to run your jq expressions against real data and see the results.

Integration settings

Every integration has its own tool-specific settings, under the Integration settings section.
Each of these settings has an ⓘ icon next to it, which you can hover over to see a description of the setting.

Port secrets

Some integration settings require sensitive pieces of data, such as tokens.
For these settings, Port secrets will be used, ensuring that your sensitive data is encrypted and secure.

When changing such a setting, you will be prompted to choose an existing secret or create a new one:



Port source IP addresses

When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses.
You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:

54.73.167.226  
63.33.143.237  
54.76.185.219

Configuration​

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

JQL support​

The Ocean Jira integration supports querying objects from the issue kind using JQL, making it possible to specifically filter the issues that are queried from Jira and ingested to Port.

To use JQL filtering, add to the selector object a jql key with your desired JQL query as the value. For example:

resources:
  - kind: issue # JQL filtering can only be used with the "issue" kind
    selector:
      query: "true" # JQ boolean expression. If evaluated to false - this object will be skipped.
      jql: "status != Done" # JQL query, will only ingest issues whose status is not "Done"
    port:

Limitations​

Getting user emails from Jira​

By default, Jira does not attach user emails to its API responses. For example, when making an API request to Jira to get an issue, fields such as assignee, creator, reporter and other user fields, will only include information such as the internal user ID and user display name, but not the user email.

In order to display the user email in API responses (and also use that data in the mapping from Jira to Port), follow these steps:

Verify your domain in Jira:

  • Go to the Jira admin panel.
  • Go to the Settings tab.
  • Select Domains in the sidebar on the left.
  • If your domain (for example - acme.com) does not appear in the list, click on Add domain.
  • Enter your domain name and click on Next.
  • Verify your domain ownership in whichever way is convenient for you.

When you are done, you will see in the domain menu that your domain is listed, and its status is VERIFIED under the Domain status column.

Claim your Jira user accounts:

  • Go to the Jira admin panel.
  • Go to the Settings tab.
  • Select Domains in the sidebar on the left.
  • Find your verified domain in the list whose accounts need to be claimed.
  • Click the 3 horizontal dots (...) under the Actions column.
  • Select Claim accounts.
  • You will receive an email from Jira when the claim process is complete.

That's it! Now Jira API responses will include the emailAddress field when returning a user from Jira.

Jira docs

All of the steps outlined here are also available in Jira's documentation

Examples​

To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your data sources page. Find the integration in the list of data sources and click on it to open the playground.

Examples of blueprints and the relevant integration configurations:

Project​

Project blueprint
{
  "identifier": "jiraProject",
  "title": "Jira Project",
  "icon": "Jira",
  "description": "A Jira project",
  "schema": {
    "properties": {
      "url": {
        "title": "Project URL",
        "type": "string",
        "format": "url",
        "description": "URL to the project in Jira"
      },
      "totalIssues": {
        "title": "Total Issues",
        "type": "number",
        "description": "The total number of issues in the project"
      }
    }
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Integration configuration
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .key
          title: .name
          blueprint: '"jiraProject"'
          properties:
            url: (.self | split("/") | .[:3] | join("/")) + "/projects/" + .key
            totalIssues: .insight.totalIssueCount

Issue​

Issue blueprint
{
  "identifier": "jiraIssue",
  "title": "Jira Issue",
  "icon": "Jira",
  "schema": {
    "properties": {
      "url": {
        "title": "Issue URL",
        "type": "string",
        "format": "url",
        "description": "URL to the issue in Jira"
      },
      "status": {
        "title": "Status",
        "type": "string",
        "description": "The status of the issue"
      },
      "issueType": {
        "title": "Type",
        "type": "string",
        "description": "The type of the issue"
      },
      "components": {
        "title": "Components",
        "type": "array",
        "description": "The components related to this issue"
      },
      "assignee": {
        "title": "Assignee",
        "type": "string",
        "format": "user",
        "description": "The user assigned to the issue"
      },
      "reporter": {
        "title": "Reporter",
        "type": "string",
        "description": "The user that reported to the issue",
        "format": "user"
      },
      "creator": {
        "title": "Creator",
        "type": "string",
        "description": "The user that created to the issue",
        "format": "user"
      },
      "priority": {
        "title": "Priority",
        "type": "string",
        "description": "The priority of the issue"
      },
      "created": {
        "title": "Created At",
        "type": "string",
        "description": "The created datetime of the issue",
        "format": "date-time"
      },
      "updated": {
        "title": "Updated At",
        "type": "string",
        "description": "The updated datetime of the issue",
        "format": "date-time"
      }
    }
  },
  "calculationProperties": {},
  "relations": {
    "project": {
      "target": "jiraProject",
      "title": "Project",
      "description": "The Jira project that contains this issue",
      "required": false,
      "many": false
    },
    "parentIssue": {
      "target": "jiraIssue",
      "title": "Parent Issue",
      "required": false,
      "many": false
    },
    "subtasks": {
      "target": "jiraIssue",
      "title": "Subtasks",
      "required": false,
      "many": true
    }
  }
}
Integration configuration
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: issue
    selector:
      query: "true"
      jql: "statusCategory != Done"
    port:
      entity:
        mappings:
          identifier: .key
          title: .fields.summary
          blueprint: '"jiraIssue"'
          properties:
            url: (.self | split("/") | .[:3] | join("/")) + "/browse/" + .key
            status: .fields.status.name
            issueType: .fields.issuetype.name
            components: .fields.components
            assignee: .fields.assignee.emailAddress
            reporter: .fields.reporter.emailAddress
            creator: .fields.creator.emailAddress
            priority: .fields.priority.id
            created: .fields.created
            updated: .fields.updated
          relations:
            project: .fields.project.key
            parentIssue: .fields.parent.key
            subtasks: .fields.subtasks | map(.key)

Relevant Guides​

For relevant guides and examples, see the guides section.

Alternative installation via webhook​

While the Ocean integration described above is the recommended installation method, you may prefer to use a webhook to ingest data from Jira. If so, use the following instructions:

Note that when using this method, data will be ingested into Port only when the webhook is triggered.

Webhook installation (click to expand)

In this example you are going to create a webhook integration between Jira and Port, which will ingest Jira issue entities.

Port configuration

Create the following blueprint definition:

Jira issue blueprint
{
  "identifier": "jiraIssue",
  "description": "This blueprint represents issues from Jira",
  "title": "Jira Issue",
  "icon": "Jira",
  "schema": {
    "properties": {
      "summary": {
        "type": "string",
        "title": "Summary"
      },
      "description": {
        "type": "string",
        "title": "Description"
      },
      "lastChangeType": {
        "type": "string",
        "title": "Last change type",
        "description": "The type of the latest change made to this issue"
      },
      "changingUser": {
        "type": "string",
        "title": "Changing user",
        "description": "The user that made the latest change"
      },
      "issueUrl": {
        "type": "string",
        "title": "Issue URL",
        "format": "url",
        "description": "URL to the issue"
      },
      "issueType": {
        "type": "string",
        "title": "Type",
        "description": "The type of the issue"
      },
      "status": {
        "type": "string",
        "title": "Status",
        "description": "The status of the issue"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}

Create the following webhook configuration using Port's UI

Jira issue webhook configuration

  1. Basic details tab - fill the following details:

    1. Title : Jira mapper;
    2. Identifier : jira_mapper;
    3. Description : A webhook configuration to map Jira issues to Port;
    4. Icon : Jira;

  2. Integration configuration tab - fill the following JQ mapping:

    [
      {
        "blueprint": "jiraIssue",
        "entity": {
          "identifier": ".body.issue.key",
          "title": ".body.issue.key + \" - \" + .body.issue.fields.summary",
          "properties": {
            "summary": ".body.issue.fields.summary",
            "description": ".body.issue.fields.description",
            "status": ".body.issue.fields.status.name",
            "lastChangeType": ".body.issue_event_type_name",
            "changingUser": ".body.user.displayName",
            "issueUrl": "(.body.issue.self | split(\"rest\") | first) + \"browse/\" + .body.issue.key",
            "issueType": ".body.issue.fields.issuetype.name"
          }
        }
      }
    ]

  3. Click Save at the bottom of the page.

Create a webhook in Jira

  1. Log in to Jira as a user with the Administer Jira global permission;
  2. Click the gear icon at the top right corner;
  3. Choose System;
  4. At the bottom of the sidebar on the left, under Advanced, choose WebHooks;
  5. Click on Create a WebHook
  6. Input the following details:
    1. Name - use a meaningful name such as Port Webhook;
    2. Status - be sure to keep the webhook Enabled;
    3. Webhook URL - enter the value of the url key you received after creating the webhook configuration;
    4. Description - enter a description for the webhook;
    5. Issue related events - enter a JQL query in this section to filter the issues that get sent to the webhook (if you leave this field empty, all issues will trigger a webhook event);
    6. Under Issue - mark created, updated and delete;
  7. Click Create at the bottom of the page.
Jira events and payload

In order to view the different payloads and events available in Jira webhooks, look here

Done! any change you make to an issue (open, close, edit, etc.) will trigger a webhook event that Jira will send to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.

Let's Test It

This section includes a sample webhook event sent from Jira when an issue is created or updated. In addition, it includes the entity created from the event based on the webhook configuration provided in the previous section.

Payload

Here is an example of the payload structure sent to the webhook URL when a Jira issue is created:

Webhook event payload
{
  "timestamp": 1686916266116,
  "webhookEvent": "jira:issue_created",
  "issue_event_type_name": "issue_created",
  "user": {
    "self": "https://account.atlassian.net/rest/api/2/user?accountId=557058%3A69f39959-769f-4dac-8a7a-46eb55b03723",
    "accountId": "557058%3A69f39959-769f-4dac-8a7a-46eb55b03723",
    "avatarUrls": {
      "48x48": "https://secure.gravatar.com/avatar/9df2ac1caa70b0a67ff0561f7d0363e5?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-1.png"
    },
    "displayName": "Your Name",
    "active": true,
    "timeZone": "Europe/London",
    "accountType": "atlassian"
  },
  "issue": {
    "id": "10000",
    "self": "https://account.atlassian.net/rest/api/2/10000",
    "key": "PI-1",
    "fields": {
      "statuscategorychangedate": "2023-06-16T11:51:06.277+0000",
      "issuetype": {
        "self": "https://account.atlassian.net/rest/api/2/issuetype/10002",
        "id": "10002",
        "description": "Epics track collections of related bugs, stories, and tasks.",
        "iconUrl": "https://account.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10307?size=medium",
        "name": "Epic",
        "subtask": false,
        "avatarId": 10307,
        "entityId": "66c6d416-6eb4-4b38-92fa-9a7d68c64165",
        "hierarchyLevel": 1
      },
      "timespent": "None",
      "project": {
        "self": "https://account.atlassian.net/rest/api/2/project/10000",
        "id": "10000",
        "key": "PI",
        "name": "Port Integration",
        "projectTypeKey": "software",
        "simplified": true,
        "avatarUrls": {
          "48x48": "https://account.atlassian.net/rest/api/2/universal_avatar/view/type/project/avatar/10413"
        }
      },
      "fixVersions": [],
      "aggregatetimespent": "None",
      "resolution": "None",
      "resolutiondate": "None",
      "workratio": -1,
      "watches": {
        "self": "https://account.atlassian.net/rest/api/2/issue/PI-1/watchers",
        "watchCount": 0,
        "isWatching": false
      },
      "issuerestriction": {
        "issuerestrictions": {},
        "shouldDisplay": true
      },
      "lastViewed": "None",
      "created": "2023-06-16T11:51:05.291+0000",
      "priority": {
        "self": "https://account.atlassian.net/rest/api/2/priority/3",
        "iconUrl": "https://account.atlassian.net/images/icons/priorities/medium.svg",
        "name": "Medium",
        "id": "3"
      },
      "labels": ["cloud", "infra"],
      "issuelinks": [],
      "assignee": {
        "self": "https://account.atlassian.net/rest/api/2/user?accountId=557058%3A69f39947-769f-4dac-8a7a-46eb55b03705",
        "accountId": "557058:69f39947-769f-4dac-8a7a-46eb55b03705",
        "avatarUrls": {
          "48x48": "https://secure.gravatar.com/avatar/9df2ac1caa70b0a67ff0561f7d0363e5?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-1.png"
        },
        "displayName": "Your Name",
        "active": true,
        "timeZone": "Europe/London",
        "accountType": "atlassian"
      },
      "updated": "2023-06-16T11:51:05.291+0000",
      "status": {
        "self": "https://account.atlassian.net/rest/api/2/status/10000",
        "description": "",
        "iconUrl": "https://account.atlassian.net/",
        "name": "To Do",
        "id": "10000",
        "statusCategory": {
          "self": "https://account.atlassian.net/rest/api/2/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "New"
        }
      },
      "components": [],
      "timeoriginalestimate": "None",
      "description": "We need to migrate our current infrastructure from in-house to the cloud",
      "attachment": [],
      "summary": "Migrate Infra to Cloud",
      "creator": {
        "self": "https://account.atlassian.net/rest/api/2/user?accountId=557058%3A69f39947-769f-4dac-8a7a-46eb55b03705",
        "accountId": "557058:69f39947-769f-4dac-8a7a-46eb55b03705",
        "avatarUrls": {
          "48x48": "https://secure.gravatar.com/avatar/9df2ac1caa70b0a67ff0561f7d0363e5?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-1.png"
        },
        "displayName": "Your Name",
        "active": true,
        "timeZone": "Europe/London",
        "accountType": "atlassian"
      },
      "subtasks": [],
      "reporter": {
        "self": "https://account.atlassian.net/rest/api/2/user?accountId=557058%3A69f39947-769f-4dac-8a7a-46eb55b03705",
        "accountId": "557058:69f39947-769f-4dac-8a7a-46eb55b03705",
        "avatarUrls": {
          "48x48": "https://secure.gravatar.com/avatar/9df2ac1caa70b0a67ff0561f7d0363e5?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-1.png"
        },
        "displayName": "Your Name",
        "active": true,
        "timeZone": "Europe/London",
        "accountType": "atlassian"
      },
      "aggregateprogress": {
        "progress": 0,
        "total": 0
      },
      "environment": "None",
      "duedate": "2023-06-19",
      "progress": {
        "progress": 0,
        "total": 0
      },
      "votes": {
        "self": "https://account.atlassian.net/rest/api/2/issue/PI-1/votes",
        "votes": 0,
        "hasVoted": false
      }
    }
  },
  "changelog": {
    "id": "10001",
    "items": [
      {
        "field": "status",
        "fieldtype": "jira",
        "fieldId": "status",
        "from": "10000",
        "fromString": "To Do",
        "to": "10001",
        "toString": "In Progress"
      }
    ]
  }
}

Mapping Result

The combination of the sample payload and the webhook configuration generates the following Port entity:

{
  "identifier": "PI-1",
  "title": "PI-1 - Migrate Infra to Cloud",
  "blueprint": "jiraIssue",
  "properties": {
    "summary": "Migrate Infra to Cloud",
    "description": "We need to migrate our current infrastructure from in-house to the cloud",
    "status": "To Do",
    "lastChangeType": "issue_created",
    "changingUser": "Your Name",
    "issueUrl": "https://account.atlassian.net/browse/PI-1",
    "issueType": "Epic"
  },
  "relations": {}
}

Import Jira Historical Issues

In this example you are going to use the provided Python script to fetch data from the Jira API and ingest it to Port.

Prerequisites

This example utilizes the same blueprint and webhook definition from the previous section.

In addition, it requires a Jira API token that is provided as a parameter to the Python script

Create the Jira API token

  1. Log in to your Jira account.
  2. Click Create API token.
  3. From the dialog that appears, enter a memorable and concise Label for your token and click Create.
  4. Click Copy to copy the token to your clipboard, you will not have another opportunity to view the token value after you leave this page.

Use the following Python script to ingest historical Jira issues into port:

Jira Python script for historical issues
# Dependencies to Install
# pip install jira
# pip install requests

from jira import JIRA
import requests
import json
import os

def authenticate_with_jira(server, username, api_token):
    # This function authenticates with JIRA and returns a JIRA object
    return JIRA(server=server, basic_auth=(username, api_token))

def send_to_port(data, port_url):
    # This function sends issue data to Port
    headers = {'Content-Type': 'application/json'}
    response = requests.post(port_url, headers=headers, data=json.dumps(data))

    # Check the response from Port
    if response.status_code != 202:
        print(f"Error sending issue {data['issue']['key']} to Port: {response.status_code}")
    else:
        print(f"Issue {data['issue']['key']} successfully sent to Port.")

    return response

def process_issues(issues):
    # This function processes the issues from JIRA
    total_issues_processed = 0

    for issue in issues:
        try:
            description = issue.fields.description if issue.fields.description else None

            data_to_send = {
                "issue": {
                    "key": issue.key,
                    "fields": {
                        "summary": issue.fields.summary,
                        "description": description,
                        "status": {"name": issue.fields.status.name},
                        "issuetype": {"name": issue.fields.issuetype.name},
                        "self": issue.self,
                    },
                    "lastChangeType": "",
                    "self": issue.self,
                },
                "user": {"displayName": issue.fields.creator.displayName},
            }

            response = send_to_port(data_to_send, os.getenv('PORT_URL')) ## Your WEBHOOK_URL after creating the Port Webhook
            if response.status_code == 202:
                total_issues_processed += 1

        except Exception as e:
            print(f"Error processing issue {issue.key}: {str(e)}")

    return total_issues_processed

def main():
    jira_server = os.getenv('JIRA_SERVER')  ## This is your Jira Domain https://{your_domain}.atlassian.net
    username = os.getenv('USERNAMES')
    api_token = os.getenv('API_TOKEN')
    status_list = ["In Progress", "To Do"]
    status = ','.join(f'"{s}"' for s in status_list)

    jira = authenticate_with_jira(jira_server, username, api_token)

    start_at = 0
    max_results = 20
    total_issues_processed = 0

    while True:
        issues = jira.search_issues(f'status in ({status})', startAt=start_at, maxResults=max_results)
        if not issues:
            break

        total_issues_processed += process_issues(issues)
        start_at += max_results

    print(f"Total issues processed: {total_issues_processed}")

if __name__ == "__main__":
    main()


Environment variables requirement

The script requires the following environment variables:

  • PORT_URL - the webhook URL generated by Port after creating the webhook configuration;
  • JIRA_SERVER - your Jira domain, for example https://{YOUR_DOMAIN}.atlassian.net;
  • USERNAMES - your Jira username;
  • API_TOKEN - your Jira API token (created in the previous step).

Done! you can now import historical issues from Jira into Port. Port will parse the issues according to the mapping and update the catalog entities accordingly.