Skip to main content

Check out Port for yourself 

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.

Live event support

Currently, live events are not supported for integrations hosted by Port.
Resyncs will be performed periodically (with a configurable interval), 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

This integration supports OAuth2 for quick installation with default settings.

  1. Go to the Jira data source page in your portal.

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

  3. Click Connect.
    This will prompt you to authorize Port and install the integration with the following default settings:

    • Resync interval: Every 2 hours.

    • Send raw data examples: Enabled.

    See the Application settings section below for descriptions of these settings.

Answers to common questions about OAuth integrations can be found here:

OAuth integrations FAQ (click to expand)

What permissions do I need to install the integration using OAuth2?

Any level of permission will work. However, the data fetched depends on the user’s access level:

  • If the user has admin-level access, Port will fetch all project data.
  • If the user has restricted access (e.g., only specific projects), Port will fetch data based on those permissions.

Are there any differences in the sync behavior between OAuth2 and custom token-based installation?

Token-Based Installation requires users to manually generate and provide tokens, offering control over permissions but increasing the risk of setup errors.
OAuth2 Installation automates the process, simplifying setup and reducing errors while aligning access levels with the user’s permissions.

Can multiple integrations use the same OAuth connection? Can multiple organizations use the same OAuth connection?

There is no limit to the number of OAuth connections you can create for integrations or organizations.

What is the level of permissions Port requests in the OAuth2 authentication flow, and why?

The exact permissions Port requests will appear when connecting the OAuth provider.
Port requests both read and write access so the secrets can be used later for running self-service actions (e.g., creating Jira tickets).

What happens if my integration shows an authorization error with the 3rd party?

OAuth tokens are refreshed automatically by Port, including before manual syncs.
If you encounter an HTTP 401 unauthorized error, try running a manual resync or wait for the next scheduled sync, and the issue will resolve itself. If the error persists, please contact our support team.

What happens if I delete an installation of OAuth2?

  • Deleting an OAuth2-based installation will not revoke access to the third-party service.
  • Port will delete the OAuth secret, which prevents it from utilizing the connection for future syncs.
  • If you reinstall the integration, you will need to reconnect OAuth.
  • Actions relying on the deleted secret (e.g., creating a Jira ticket) will fail until the secret is recreated or the integration is reinstalled.

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:

  • Jira host: The URL of your Jira account, e.g https://example.atlassian.net/.
    When installing via OAuth, the url will be in this format: https://api.atlassian.com/ex/jira/<jira_cloud_id>.

  • Atlassian user email: The email of the user used to query Jira.

  • Atlassian user token: The API token used to query Jira, can be configured on the Atlassian account page.

You can also hover over the ⓘ icon next each setting to see a description.

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 filling in such a setting, its value will be obscured (shown as ••••••••).
For each such setting, Port will automatically create a secret in your organization.

To see all secrets in your organization, follow these steps.

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

OAuth account password change​

When installing the integration via OAuth:

If the password of the account used to authenticate with Jira changes, the integration will need to be reinstalled.
This is because the Jira API requires the use of an API token for authentication, and the token is generated using the account's password.

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

The project kind has a selector property, expand that specifies additional fields to be included in the response. It accepts a comma-separated string that allows you to include more fields in the response data that can be used in the mapping configuration. Possible values are description, lead, issueTypes, url, projectKeys, insight.

If not specified, it defaults to "insight".

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: project
    selector:
      query: "true"
      expand: "description,lead,issueTypes,url,projectKeys,insight"
    port:
      entity:
        mappings:
          identifier: .key
          title: .name
          blueprint: '"jiraProject"'
          properties:
            url: (.self | split("/") | .[:3] | join("/")) + "/projects/" + .key
            totalIssues: .insight.totalIssueCount

User​

User blueprint
{
 "identifier": "jiraUser",
 "title": "Jira User",
 "icon": "User",
 "description": "A Jira user account",
 "schema": {
   "properties": {
     "emailAddress": {
       "title": "Email",
       "type": "string",
       "format": "email", 
       "description": "User's email address"
     },
     "displayName": {
       "title": "Display Name",
       "type": "string",
       "description": "User's full name as displayed in Jira"
     },
     "active": {
       "title": "Active Status",
       "type": "boolean",
       "description": "Whether the user account is active"
     },
     "accountType": {
       "title": "Account Type",
       "type": "string",
       "description": "Type of Jira account (e.g., atlassian, customer)"
     }
   }
 },
 "mirrorProperties": {},
 "calculationProperties": {},
 "aggregationProperties": {},
 "relations": {}
}
Integration configuration
- kind: user
  selector:
    query: "true"
  port:
    entity:
      mappings:
        identifier: .accountId
        title: .displayName
        blueprint: '"jiraUser"'
        properties:
          emailAddress: .emailAddress
          displayName: .displayName
          active: .active
          accountType: .accountType

Team​

Team blueprint
{
"identifier": "jiraTeam",
"title": "Jira Team",
"icon": "Users",
"description": "A team within the organization",
"schema": {
    "properties": {
    "organizationId": {
        "title": "Organization ID",
        "type": "string",
        "description": "Unique identifier for the parent organization"
    },
    "teamType": {
        "title": "Team Type",
        "type": "string",
        "description": "Type of team (e.g., MEMBER_INVITE, OPEN)",
        "enum": [
        "MEMBER_INVITE",
        "OPEN"
        ]
    },
    "description": {
        "title": "Description",
        "type": "string",
        "description": "Team description"
    }
    }
},
"relations": {
    "members": {
    "target": "jiraUser",
    "title": "Users",
    "description": "The Jira users belonging to this team",
    "required": false,
    "many": true
    }
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {}
}
Integration configuration
- kind: team
  selector:
    query: "true"
    includeMembers: true
  port:
    entity:
      mappings:
        identifier: .teamId
        title: .displayName
        blueprint: '"jiraTeam"'
        properties:
          organizationId: .organizationId
          teamType: .teamType
          description: .description
        relations:
          members: if .__members != null then .__members | map(.accountId) else [] end

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"
     },
     "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"
     },
     "labels": {
       "items": {
         "type": "string"
       },
       "title": "Labels",
       "type": "array"
     },
     "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"
     },
     "resolutionDate": {
       "title": "Resolved At",
       "type": "string",
       "description": "The datetime the issue changed to a resolved state",
       "format": "date-time"
     }
   }
 },
 "calculationProperties": {
   "handlingDuration": {
     "title": "Handling Duration (Days)",
     "icon": "Clock",
     "description": "The amount of time in days from issue creation to issue resolution",
     "calculation": "if (.properties.resolutionDate != null and .properties.created != null) then ((.properties.resolutionDate[0:19] + \"Z\" | fromdateiso8601) - (.properties.created[0:19] + \"Z\" | fromdateiso8601)) / 86400 else null end",
     "type": "number"
   }
 },
 "mirrorProperties": {},
 "aggregationProperties": {},
 "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
   },
   "assignee": {
     "target": "jiraUser",
     "title": "Assignee",
     "required": false, 
     "many": false
   },
   "reporter": {
     "target": "jiraUser",
     "title": "Reporter",
     "required": false,
     "many": false
   }
 }
}
Integration configuration
- kind: issue
 selector:
   query: "true"
   jql: "(statusCategory != Done) OR (created >= -1w) OR (updated >= -1w)"
 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
         creator: .fields.creator.emailAddress
         priority: .fields.priority.name
         labels: .fields.labels
         created: .fields.created
         updated: .fields.updated
         resolutionDate: .fields.resolutiondate
       relations:
         project: .fields.project.key
         parentIssue: .fields.parent.key
         subtasks: .fields.subtasks | map(.key)
         assignee: .fields.assignee.accountId
         reporter: .fields.reporter.accountId

Let's Test It​

This section includes a sample response data from Jira. In addition, it includes the entity created from the resync event based on the Ocean configuration provided in the previous section.

Payload​

Here is an example of the payload structure from Jira:

Project response data
{
  "expand": "description,lead,issueTypes,url,projectKeys,permissions,insight",
  "self": "https://myaccount.atlassian.net/rest/api/3/project/10000",
  "id": "10000",
  "key": "PA",
  "name": "Port-AI",
  "avatarUrls": {
    "48x48": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413",
    "24x24": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=small",
    "16x16": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=xsmall",
    "32x32": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=medium"
  },
  "projectTypeKey": "software",
  "simplified": true,
  "style": "next-gen",
  "isPrivate": false,
  "properties": {},
  "entityId": "7f4f8d6f-705b-4074-84be-46f0d012cd8e",
  "uuid": "7f4f8d6f-705b-4074-84be-46f0d012cd8e"
}
User response data
{
  "accountId": "U-PA",
  "accountType": "app",
  "active": true,
  "avatarUrls": {
    "16x16": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png",
    "24x24": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png",
    "32x32": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png",
    "48x48": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png"
  },
  "displayName": "AI",
  "key": "",
  "name": "",
  "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=U-PA"
},
{
  "accountId": "U-PA-2",
  "accountType": "app",
  "active": true,
  "avatarUrls": {
    "16x16": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png",
    "24x24": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png",
    "32x32": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png",
    "48x48": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png"
  },
  "displayName": "AI-2",
  "key": "",
  "name": "",
  "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=U-PA-2"
}
Team response data
{
    "description": "Port-AI",
    "displayName": "AI",
    "organizationId": "10000",
    "teamId": "T-PA",
    "teamType": "OPEN"
},
{
    "description": "Port-AI",
    "displayName": "AI-2",
    "organizationId": "10000",
    "teamId": "T-PA-2",
    "teamType": "OPEN"
}
Issue response data
{
  "expand": "operations,versionedRepresentations,editmeta,changelog,customfield_10010.requestTypePractice,renderedFields",
  "id": "10000",
  "self": "https://myaccount.atlassian.net/rest/api/3/issue/10000",
  "key": "PA-1",
  "fields": {
    "statuscategorychangedate": "2023-11-06T11:02:59.341+0000",
    "issuetype": {
      "self": "https://myaccount.atlassian.net/rest/api/3/issuetype/10001",
      "id": "10001",
      "description": "Tasks track small, distinct pieces of work.",
      "iconUrl": "https://myaccount.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium",
      "name": "Task",
      "subtask": false,
      "avatarId": 10318,
      "entityId": "a7309bf9-70c5-4237-bdaf-0261037b6ecc",
      "hierarchyLevel": 0
    },
    "timespent": "None",
    "customfield_10030": "None",
    "project": {
      "self": "https://myaccount.atlassian.net/rest/api/3/project/10000",
      "id": "10000",
      "key": "PA",
      "name": "Port-AI",
      "projectTypeKey": "software",
      "simplified": true,
      "avatarUrls": {
        "48x48": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413",
        "24x24": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=small",
        "16x16": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=xsmall",
        "32x32": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=medium"
      }
    },
    "customfield_10031": "None",
    "customfield_10032": "None",
    "fixVersions": [],
    "aggregatetimespent": "None",
    "resolution": "None",
    "customfield_10027": "None",
    "customfield_10028": "None",
    "customfield_10029": "None",
    "resolutiondate": "None",
    "workratio": -1,
    "watches": {
      "self": "https://myaccount.atlassian.net/rest/api/3/issue/PA-1/watchers",
      "watchCount": 1,
      "isWatching": true
    },
    "lastViewed": "None",
    "created": "2023-11-06T11:02:59.000+0000",
    "customfield_10020": "None",
    "customfield_10021": "None",
    "customfield_10022": "None",
    "priority": {
      "self": "https://myaccount.atlassian.net/rest/api/3/priority/3",
      "iconUrl": "https://myaccount.atlassian.net/images/icons/priorities/medium.svg",
      "name": "Medium",
      "id": "3"
    },
    "customfield_10023": "None",
    "customfield_10024": "None",
    "customfield_10025": "None",
    "labels": ["infra"],
    "customfield_10026": "None",
    "customfield_10016": "None",
    "customfield_10017": "None",
    "customfield_10018": {
      "hasEpicLinkFieldDependency": false,
      "showField": false,
      "nonEditableReason": {
        "reason": "PLUGIN_LICENSE_ERROR",
        "message": "The Parent Link is only available to Jira Premium users."
      }
    },
    "customfield_10019": "0|hzzzzz:",
    "timeestimate": "None",
    "aggregatetimeoriginalestimate": "None",
    "versions": [],
    "issuelinks": [],
    "assignee": {
      "self": "https://myaccount.atlassian.net/rest/api/3/user?accountId=712020%3A05acda87-42da-44d8-b21e-f71a508e5d11",
      "accountId": "712020:05acda87-42da-44d8-b21e-f71a508e5d11",
      "emailAddress": "username@example.com.io",
      "avatarUrls": {
        "48x48": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "24x24": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "16x16": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "32x32": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png"
      },
      "displayName": "User Name",
      "active": true,
      "timeZone": "UTC",
      "accountType": "atlassian"
    },
    "updated": "2023-11-06T11:03:18.244+0000",
    "status": {
      "self": "https://myaccount.atlassian.net/rest/api/3/status/10000",
      "description": "",
      "iconUrl": "https://myaccount.atlassian.net/",
      "name": "To Do",
      "id": "10000",
      "statusCategory": {
        "self": "https://myaccount.atlassian.net/rest/api/3/statuscategory/2",
        "id": 2,
        "key": "new",
        "colorName": "blue-gray",
        "name": "To Do"
      }
    },
    "components": [],
    "timeoriginalestimate": "None",
    "description": "None",
    "customfield_10010": "None",
    "customfield_10014": "None",
    "customfield_10015": "None",
    "customfield_10005": "None",
    "customfield_10006": "None",
    "security": "None",
    "customfield_10007": "None",
    "customfield_10008": "None",
    "aggregatetimeestimate": "None",
    "customfield_10009": "None",
    "summary": "Setup infra",
    "creator": {
      "self": "https://myaccount.atlassian.net/rest/api/3/user?accountId=712020%3A05acda87-42da-44d8-b21e-f71a508e5d11",
      "accountId": "712020:05acda87-42da-44d8-b21e-f71a508e5d11",
      "emailAddress": "username@example.com.io",
      "avatarUrls": {
        "48x48": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "24x24": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "16x16": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "32x32": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png"
      },
      "displayName": "User Name",
      "active": true,
      "timeZone": "UTC",
      "accountType": "atlassian"
    },
    "subtasks": [],
    "reporter": {
      "self": "https://myaccount.atlassian.net/rest/api/3/user?accountId=712020%3A05acda87-42da-44d8-b21e-f71a508e5d11",
      "accountId": "712020:05acda87-42da-44d8-b21e-f71a508e5d11",
      "emailAddress": "username@example.com.io",
      "avatarUrls": {
        "48x48": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "24x24": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "16x16": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png",
        "32x32": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png"
      },
      "displayName": "User Name",
      "active": true,
      "timeZone": "UTC",
      "accountType": "atlassian"
    },
    "aggregateprogress": {
      "progress": 0,
      "total": 0
    },
    "customfield_10001": "None",
    "customfield_10002": "None",
    "customfield_10003": "None",
    "customfield_10004": "None",
    "environment": "None",
    "duedate": "None",
    "progress": {
      "progress": 0,
      "total": 0
    },
    "votes": {
      "self": "https://myaccount.atlassian.net/rest/api/3/issue/PA-1/votes",
      "votes": 0,
      "hasVoted": false
    }
  }
}

Mapping Result​

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

Project entity in Port
{
  "identifier": "PA",
  "title": "Port-AI",
  "icon": null,
  "blueprint": "jiraProject",
  "team": [],
  "properties": {
    "url": "https://myaccount.atlassian.net/projects/PA",
    "totalIssues": 100
  },
  "relations": {},
  "createdAt": "2023-11-06T11:22:05.433Z",
  "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
  "updatedAt": "2023-11-06T11:22:05.433Z",
  "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}
User entity in Port
{
  "identifier": "U-PA",
  "title": "AI",
  "team": [],
  "properties": {
    "accountId": "U-PA",
    "displayName": "AI",
    "active": true,
    "accountType": "app",
    "avatarUrl": "https://secure.gravatar.com/avatar/ab3787cd0c16633ae050dff9d5ab15fc?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FS-0.png"
  },
  "relations": {},
  "icon": "User"
}
Team entity in Port
{
  "identifier": "T-PA",
  "title": "Port-AI",
  "icon": "Users",
  "properties": {
    "organizationId": "10000",
    "teamType": "OPEN",
    "description": "Port-AI"
  },
  "relations": {
    "members": [
      "U-PA",
      "U-PA-2"
    ]
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {}
}
Issue entity in Port
{
  "identifier": "PA-1",
  "title": "Setup infra",
  "icon": null,
  "blueprint": "jiraIssue",
  "team": [],
  "properties": {
    "url": "https://myaccount.atlassian.net/browse/PA-1",
    "status": "To Do",
    "issueType": "Task",
    "components": [],
    "creator": "username@example.com.io",
    "priority": "Medium",
    "created": "2023-11-06T11:02:59.000+0000",
    "updated": "2023-11-06T11:03:18.244+0000"
  },
  "relations": {
    "parentIssue": null,
    "project": "PA",
    "assignee": "username@example.com.io",
    "reporter": "username@example.com.io",
    "subtasks": []
  },
  "createdAt": "2023-11-06T11:22:07.550Z",
  "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
  "updatedAt": "2023-11-06T11:22:07.550Z",
  "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}

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.