> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Jira

Jira iconJira icon
Loading version...

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

Supported resources External link iconProjectUserIssueTeamReleaseEpicSprintBoardWorklogBacklogComponent

Core support

Live eventsSee supported resources
Jira Cloud integration

This integration is designed for Jira Cloud. For Jira Server (self-hosted), use Port's Jira Server Ocean integration.

Setup​

Choose one of the following installation methods: Not sure which method is right for your use case? Check the available installation methods.

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.

Default mapping configuration​

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)
deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
- kind: user
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .accountId
        title: .displayName
        blueprint: '"jiraUser"'
        properties:
          emailAddress: .emailAddress
          displayName: .displayName
          active: .active
          accountType: .accountType
- kind: project
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .key
        title: .name
        blueprint: '"jiraProject"'
        properties:
          url: (.self | split("/") | .[:3] | join("/")) + "/projects/" + .key
- 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)
          jira_user_assignee: .fields.assignee.accountId
          jira_user_reporter: .fields.reporter.accountId
          assignee:
            combinator: '"or"'
            rules:
            - property: '"jira_user_id"'
              operator: '"="'
              value: .fields.assignee.accountId
            - property: '"$identifier"'
              operator: '"="'
              value: .fields.assignee.email
          reporter:
            combinator: '"or"'
            rules:
            - property: '"jira_user_id"'
              operator: '"="'
              value: .fields.reporter.accountId
            - property: '"$identifier"'
              operator: '"="'
              value: .fields.reporter.email
- kind: issue
  selector:
    query: 'true'
    jql: (statusCategory != Done) OR (created >= -1w) OR (updated >= -1w)
  port:
    entity:
      mappings:
        identifier: .key
        title: .fields.summary
        blueprint: '"jiraIssue"'
        relations:
          pull_request:
            combinator: '"and"'
            rules:
            - property: '"$title"'
              operator: '"contains"'
              value: .key

Capabilities​

See the capabilities page for more configuration options and examples.

Mapping & selectors per resource​

Use the explorer below to view sample payloads and the resulting Port entities for each resource type. For additional resources and advanced configurations, see the examples page.

Set up live events​

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Note that different events are supported depending on the resource type.

Live events base URL

For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.

Call the endpoint with your integration's identifier:

curl -X GET \
  'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
  -H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

In the response, look for the following fields under spec.appSpec:

{
  "spec": {
    "appSpec": {
      "liveEventsUuid": "abcdefghijk",
      "liveEventsIngestHostname": "ingest.ocean.getport.io"
    }
  }
}

Combine them to build the live events base URL:

https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>

For example, with the values above, the live events base URL is:

https://ingest.ocean.getport.io/live-events/abcdefghijk

This is the same URL configured for the integration.

Monitoring and sync status​

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Limitations​

Getting user emails​

By default, Jira does not include user emails in API responses. To enable this:

  1. Go to the Jira admin panel and verify your domain under Settings > Domains.
  2. After verification, claim your user accounts under the same Domains section.

Once complete, Jira API responses will include the emailAddress field. See Jira's documentation for full details.

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.

Additional examples of blueprints and the relevant integration configurations can be found on the jira examples page

Relevant Guides​

For relevant guides and examples, see the guides section.