LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • How to configure Jira with Cortex
  • Set a default JQL query for your Jira integration
  • Fallback logic for default JQL
  • Adding filter logic to the default JQL query in a Scorecard
  • How to connect Cortex entities to Jira
  • Discovery
  • Editing the entity descriptor
  • Identity mappings
  • Expected results
  • Scorecards and CQL
  • Background sync
  • FAQs and troubleshooting
  • Still need help?​

Was this helpful?

Export as PDF
  1. Ingesting data into Cortex
  2. Integrations

Jira

Last updated 1 month ago

Was this helpful?

is a project management tool that helps developers track and manage bugs and issues.

By integrating Jira with Cortex, you can drive improvements and coordinate issue management across teams. Through the integration, you can create Jira issues directly in Cortex based on an Initiative's action items. The integration also allows you to enhance insights into a number of key values for your entities:

  • Customer facing incidents

  • Security tickets

  • Ongoing projects

How to configure Jira with Cortex

It is possible to configure the integration with a Jira Cloud instance or a self-hosted Jira instance (using either basic auth or OAuth). You can also use Cortex Axon Relay to securely integrate your on-premises data. See the tabs below for instructions on each option.

Jira Cloud

Prerequisites

Before configuring Cortex with Jira Cloud:

  • Create a

    • To generate a token, you must have the Browse users and groups in Jira and access to the needed Jira projects.

Configure the integration in Cortex

  1. In Cortex, navigate to the :

    1. In Cortex, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations," click Jira.

  2. Click Add configuration.

  3. In the Jira integration modal, "Jira Cloud" is selected by default in the upper right corner. Configure the integration form:

    • Account alias: Enter an alias for your account.

    • Subdomain: Enter the subdomain for your Jira instance.

      • For example, this field would take cortex-docs from https://cortex-docs.atlassian.net.

    • Base URL: This field automatically populates atlassian.net.

      • If you are using a legacy Jira Cloud instance (i.e., you access your Jira instance on jira.com), change the base URL from the dropdown.

    • Email: Enter the email address associated with the user who generated the token in Jira.

      • Note: The email address associated with a given Jira token must match the email address of the user associated with that token.

    • API token: Enter your Jira API token.

  4. Click Save.

Jira on-prem (Basic)

Prerequisite

Configure the integration in Cortex

    1. In Cortex, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations," click Jira.

  1. Click Add configuration.

  2. In the upper right corner of the Jira integration modal, click the dropdown labeled Cloud. Select On-prem (basic auth).

  3. Configure the Jira integration form:

    • Account alias: Enter an alias for your account.

    • Host: Enter the URL for your Jira on-premises host.

    • Frontend host: Enter the URL for your Jira on-premises frontend host.

    • Username and Password: Enter your Jira username and password.

  4. Click Save.

Jira on-prem (OAuth)

Prerequisites

To integrate Cortex with Jira using OAuth, you must be running a self-hosted Jira instance with Jira server version 8.22 or higher.

Step 1: Create an application link from Jira

  1. In your Jira server, navigate to Settings > Applications > Application Links. Click Create link.

  2. Configure the application link settings:

    • Application type: Select External.

    • Direction: Select Incoming.

    • Redirect URL: For default configuration, enter the URL of your Cortex instance appended with /oauth/internal/jira. For a non-default configuration, enter the URL of your Cortex instance appended with /oauth/internal/jira/.

    • Permission: Select write.

  3. Click Save.

  4. The application link will have an associated client ID and client secret. Copy these values and store them in a secure location, as you will need them in the next steps.

Step 2: Configure the integration in Cortex

    1. In Cortex, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations," click Jira.

  1. Click Add configuration.

  2. In the upper right corner of the Jira integration modal, click the dropdown labeled Cloud. Select On-prem (OAuth).

  3. Configure the Jira integration form:

    • Account alias: Enter an alias for your account.

    • Host: Enter the URL for your Jira on-premises host.

    • Frontend host: Enter the URL for your Jira on-premises frontend host.

    • Client ID and Client secret: Enter the client ID and secret associated with the application link you created in the previous steps.

  4. Click Save.

  5. You will be redirected to the Jira settings page. Click Install next to your integration name.

    • A confirmation modal will appear, asking you to allow Cortex access to your Jira account.

    • The accessing user can be a user persona or a system account. We recommend using a system account to maintain your organization's access in case the user who set up the integration leaves your organization.

Configure Jira with Cortex Axon Relay

Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to Remove Integration in Settings.

You can also use the Test all configurations button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

The Jira integration has multi-account support. You can add a configuration for each additional by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Jira page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.

Set a default JQL query for your Jira integration

The default JQL applies to jira.issues() and jira.numOfIssues() but not to jira.rawJql().

Set default JQL query at a tenant level

The default query — statusCategory in ("To Do", "In Progress") — will filter your Jira tickets to display only those with To Do and In Progress statuses, excluding closed tickets. The indeterminate status category will map to In Progress according to the API. Cortex does not use the status field for mapping these categories.

Entering a custom JQL query on the Jira integration settings page allows you to override the default for all entities in your workspace. To map issues with a custom status, you can write a custom JQL query that uses status instead of statusCategory.

Set default JQL query at entity level

x-cortex-issues:
    jira:
      projects:
      - name: PROJECT_A
        alias: Jira Project A
      defaultJql: "project = project_a"

Fallback logic for default JQL

It is possible to set custom JQL at both the entity and tenant level, but note the fallback logic:

  1. If any JQL is passed into a query, Cortex uses that.

  2. If not, Cortex uses entity-level default JQL.

  3. If not, Cortex uses tenant-wide default JQL.

  4. If none, then no JQL is used for filtering.

Adding filter logic to the default JQL query in a Scorecard

The CQL statement will use the default JQL setting in a Scorecard rule only if you do not define additional filter logic. Any filter logic applied to the statement will override the default JQL query.

To work around this: If you need to include additional filter logic on your query in a Scorecard, you can move the filter logic to the filter clause.

For example, if your default JQL query is set to "project = project_a", then you can add jira.issues() to a Scorecard rule to automatically surface only the issues relating to Project A. However, you cannot use jira.issues(some_other_filter_logic) in a Scorecard; Cortex will not append your default JQL to the additional filter logic.

In this example, the workaround would be to add a filter clause: jira.issues().filter(some_other_filter_logic).

How to connect Cortex entities to Jira

Discovery

Without an override, a ticket's label, component, or project must exactly match the entity tag in the descriptor.

Editing the entity descriptor

If you need to override automatic discovery, you can define one of the following x-cortex-issues blocks in your Cortex entity descriptor.

Note: For all of the following, alias is optional, and the default Jira configuration will be used if not provided. You can use Jira labels, components, or projects to match entities.

Each of these blocks has the same field definitions.

Field
Description
Required

name

Label name in Jira

✓

alias

Alias for the configuration in Cortex (only needed if you have opted into multi-account support)

x-cortex-issues:
  jira:
    labels:
      - name: labelA
        alias: alias1
      - name: labelB
x-cortex-issues:
  jira:
    components:
      - name: component1
        alias: alias1
x-cortex-issues:
  jira:
    projects:
      - name: project1
        alias: alias1
x-cortex-issues:
  jira:
    defaultJql: 'status = "In Progress"'

Identity mappings

Cortex maps Jira accounts to team members defined in the team catalog, so you do not need to define Jira users in a team member's YAML file.

Expected results

Entity pages

Once the integration is established, you'll be able to pull in data about the issues in any linked Jira instances for a given entity:

  • Number of issues: Unresolved issues associated with an entity that have the JQL status "in progress" or "to do"

  • Number of issues from JQL query: Issues associated with an entity that match an arbitrary JQL query

Cortex will tie Jira tickets directly to entities within the catalog. Click Issue tracking in the entity's sidebar to see associated Jira tickets.

From this tab you can find a list of all issues with a label that matches the entity tag.

  • Key: The issue key (or "ticket number") for a Jira issue.

  • Issue summary: Title of the Jira issue and the user designated as the issue reporter.

  • Assignee: User designated as the issue assignee.

  • Created: Date the issue was created.

  • Due: Due date for the issue, if applicable.

This list will also be available from a team's homepage when the team's entity tag matches a label, component, or project in Jira.

Initiatives

Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.

From the Issues tab of an Initiative, you can automatically create a Jira ticket from a failing rule.

Dev homepage

Issues are refreshed every 5 minutes. You can use the Refresh Jira issues button to manually refresh issues at any point.

Scorecards and CQL

With the Jira integration, you can create Scorecard rules and write CQL queries based on Jira issues.

Issues

Number of unresolved issues associated with the entity, where unresolved is defined as the JQL status = "Open" OR status = "To Do".

Definition: jira.numOfIssues()

Example

For a Scorecard measuring entity maturity, you can use this expression to make sure entities have fewer than 3 Jira issues:

jira.numOfIssues() <= 10
Issues from JQL query

Number of issues associated with the entity based on arbitrary JQL query.

Definition: jira.numOfIssues(jqlQuery: Text | Null)

Example

For a more specific rule in an entity maturity Scorecard, you can use this expression with a JQL query to make sure entities have no more than 3 open customer-facing tickets.

jira.numOfIssues("status = \"Open\" and labels = \"customer-facing\"") <= 3

Background sync

The developer homepage runs a background job every 5 minutes to refresh the Issues tab.

FAQs and troubleshooting

I've added a Jira integration, but I'm not sure what JQL is being generated to query Jira.

My Scorecard rules are failing, even though there are tickets in my Jira instance.

Make sure that the ticket has a label, component, or project that matches exactly with the entity tag or the list defined in your entity descriptor.

I received "Configuration error: Integration error for Jira: Unexpected HTTP response 0".

When using Jira Cloud, you'll need to create a Jira API token and add it on in Jira Settings in Cortex. The email address in Settings must be the same as the user that the token is associated with. Cortex also expects only the subdomain of your Jira instance, not the entire URL.

I received "Configuration error: Jira: Unexpected HTTP response 403: Forbidden".

  1. Make sure that the entity name in Cortex matches the label, component, or project name in Jira.

  2. Make sure the subdomain and base URL correspond with the Jira instance you're trying to connect.

curl -D- \
-X GET \
-H "Authorization: Basic {{your-token}}" \
-H "Content-Type: application/json" \
"https://{{your-domain}}.atlassian.net/rest/api/2/issue/{{valid-ticket-number}}"

The following options are available to get assistance from the Cortex Customer Engineering team:

  • Chat: Available in the Resource Center

  • Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

If you're using a self-hosted instance of Jira, you'll need to verify that your Cortex instance is able to reach the Jira instance. We route our requests through a static IP address. Reach out to support at to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Jira instance.

In Cortex, navigate to the :

If you're using a self-hosted instance of Jira, you'll need to verify that your Cortex instance is able to reach the Jira instance. We route our requests through a static IP address. Reach out to support at to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Jira instance.

In Cortex, navigate to the :

See for instructions.

Configure the integration for multiple Jira accounts

You can set a custom JQL query for your and for . This allows you to filter which Jira issues are surfaced on entity pages or in other places in Cortex where CQL is used.

Note that if you define additional filter logic for your default JQL query when writing a Scorecard rule, you must add that logic in a filter clause. See for more information.

From the in Cortex, you can set a custom JQL query for your Jira integration.

When Cortex queries for Jira issues, the statusCategory is directly grabbed from the .

You can configure default JQL for entities in their . For example:

By default, Cortex will tie Jira tickets to entities by searching for any tickets where the label, component, or project field for the issue includes the Cortex . For example, if your entity tag is “my-entity,” then the corresponding tickets in Jira should have “my-entity” as a label, component, or project.

If your Jira label/component/project doesn't cleanly match the Cortex entity tag, you can override this in the Cortex .

By default, Cortex will surface outstanding issues per entity in the catalog with a default query: statusCategory in ("To Do", "In Progress"). If you'd like to override this, you can provide a new default query with:

You can confirm that users' Jira accounts are connected from the .

Priority: The issue's priority level in Jira - Lowest, Low, Medium, High, Highest. This will display with the that corresponds to the priority level in your Jira instance.

Read about creating Jira issues from Initiatives in the documentation: .

The Jira integration enables Cortex to pull information about issues into the . You can find open issues assigned to you under the . The issues that display will depend both on the Jira instances you've connected and the JQL query defined in Settings.

See more examples in the in Cortex.

When running Scorecard rules, Cortex appends AND (component = entity-tag OR labels = entity-tag OR project = entity-tag) to the , where entity-tag is the .

Verify that the Jira token you added is still valid. You can run the following to confirm:

Still need help?

Email: , or open a support ticket in the in app Resource Center

Jira
Jira API token
permissions
Jira settings page
help@cortex.io
Jira settings page
help@cortex.io
Jira settings page
Internally hosted integrations
​
Jira settings page
API response
JQL
Jira user mappings section in Settings
icon
Creating issues based on initiatives
dev homepage
Issues tab
CQL Explorer
curl command
​
help@cortex.io
Jira integration instances
individual entities
Adding filter logic to the default JQL query in a Scorecard
entity tag
JQL you defined
entity YAML
entity tag
entity descriptor