Jira Server (self-hosted)

Loading version...

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

Supported resources ProjectUserIssue

Core support

Live eventsSee supported resources

Jira Server Support

This integration is specifically designed for Jira Server (Self-Hosted) installations. For Jira Cloud, use Port's Jira Cloud integration.

Setup

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

Authentication

The Jira Server integration supports two authentication methods:

Token authentication recommended

We recommend using Personal Access Token authentication for better security and easier management.

Personal Access Token (Recommended)

Personal Access Tokens provide a more secure authentication method and are the recommended approach.

1. Create a Personal Access Token in Jira Server:

   • Log in to your Jira Server as an administrator
   • Go to Jira Administration → System → User Management
   • Select the user account that will be used for the integration
   • Click Personal Access Tokens in the left menu
   • Click Create token
   • Enter a name for the token and click Create
   • Important: Copy the token value immediately as it won't be shown again

2. Configure the integration:

   • Use the token parameter in your integration configuration
   • Do not provide username and password when using token authentication

Basic Authentication (Username/Password)

Basic authentication uses a username and password combination.

1. Use an existing Jira user account:

   • Ensure the user has appropriate permissions to read projects, issues, and users
   • The user should have Browse Projects and Browse Users permissions

2. Configure the integration:

   • Use the username and password parameters in your integration configuration
   • Do not provide the token parameter when using basic authentication

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.

For the default mapping configuration and blueprints that come with this integration, see the examples page.

JQL support for issues

The Ocean Jira Server integration supports querying objects from the issue kind using JQL (Jira Query Language), making it possible to specifically filter the issues that are queried from Jira Server 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:

Default mapping configuration

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)

createMissingRelatedEntities: true
deleteDependentEntities: true

resources:
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .key
          title: .name
          blueprint: '"jiraServerProject"'
          properties:
            url: (.self | split("/") | .[:3] | join("/")) + "/projects/" + .key

  - kind: user
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .key
          title: .displayName
          blueprint: '"jiraServerUser"'
          properties:
            emailAddress: .emailAddress
            active: .active
            timeZone: .timeZone
            locale: .locale
            avatarUrl: .avatarUrls["48x48"]

  - kind: issue
    selector:
      query: "true"
      # jql: 'project = "KEY"' # Optional: Filter issues using JQL
    port:
      entity:
        mappings:
          identifier: .key
          title: .fields.summary
          blueprint: '"jiraServerIssue"'
          properties:
            url: (.self | split("/") | .[:3] | join("/")) + "/browse/" + .key
            status: .fields.status.name
            issueType: .fields.issuetype.name
            components: .fields.components | map(.name)
            creator: .fields.creator.displayName
            priority: .fields.priority.name
            labels: .fields.labels
            created: .fields.created
            updated: .fields.updated
            resolutionDate: .fields.resolutiondate
        relations:
          project: .fields.project.key
          assignee: .fields.assignee.key
          reporter: .fields.reporter.key

Mapping & selectors per resource

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 server 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.

Self-hosted

BaseUrl & webhook configuration

To enable real-time updates of the data in your software catalog, you need to define the liveEvents.baseUrl parameter.
This parameter should be set to the URL of your Jira Server integration instance, which needs to have the option to setup webhooks via HTTP requests/receive HTTP requests, so ensure the network is configured accordingly.

• If Jira Server and the integration are in the same cluster/network: Use an internal URL (e.g., a Kubernetes service DNS name).
  For Kubernetes deployments, create a service to expose the integration pod and use the service URL as liveEvents.baseUrl. If both the source system and integration are in the same cluster, an internal ClusterIP service is sufficient.
• If Jira Server is external to the integration's network: The integration must be exposed via an ingress, load balancer, or public URL that Jira Server can reach.

If liveEvents.baseUrl is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the scheduledResyncInterval parameter has to be set, or a manual resync will need to be triggered through Port's UI.

Debugging local integrations

To test webhooks or live event delivery to your local environment, expose your local pod or service to the internet using ngrok (e.g. ngrok http http://localhost:8000)

Monitoring and sync status

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