Jira

CatalogScorecards

Jira 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

Setup and configuration

Getting started

In order to connect Cortex with your Jira Cloud instance (hosted on atlassian.net or jira.com), you'll first need to create a Jira API token.

To generate a token, you'll need to have the Browse users and groups permissions in Jira and access to the needed Jira projects.

Configuration for Jira Cloud instances

Once you’ve created a Jira token, you can configure the integration in Cortex from the Jira page in Settings.

caution

If you do not see the settings page you're looking for, you likely don't have the proper permissions and need to contact your admin.

From settings, you'll see the option to Add Jira configuration. This will open a modal where you can enter details about the config. By default, the configuration modal will be set for Jira Cloud.

• Account alias: The name that Cortex will associate a given configuration with.
• Subdomain: Corresponds to the URL for your Jira instance; this only takes the subdomain, not the entire URL. For example, this field would take cortex-docs from https://cortex-docs.atlassian.net.
• Base URL: This will populate with atlassian.net by default. If you're using a legacy Jira Cloud instance - i.e. your Jira instance is accessed on jira.com - change the base URL from the dropdown.
• Email: The email address associated with the user who generated the token in Jira.
• API token: The token generated in the previous step.

caution

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

Once you save your configuration, you'll see the last four characters of the token you entered. 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 so you can add a configuration for each additional by repeating the above process.

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

Configuration for self-hosted Jira instances

To configure a self-hosted Jira instance, select Add Jira configuration from settings. Select one of the On-prem options from the dropdown in the modal.

Basic authentication

Select On-prem (basic auth) from the dropdown to use basic authentication to connect to Jira and provide the following information:

• Account alias: The name that Cortex will associate a given configuration with.
• Host: URL for your Jira on-prem host.
• Frontend host: URL for your Jira on-prem frontend host.
• Username: Jira username.
• Password: Password associated with Jira username.

OAuth authentication

You can use OAuth to connect to Jira if you're running a self-hosted instance with Jira Server version 8.22 or higher. This requires an application link from Jira:

1. Navigate to Settings → Applications → Application Links → Create Link in your Jira server.
2. Select "External" for the application type and "Incoming" for the direction.
3. For default configuration, enter the URL of your Cortex instance in for the redirect URL and /oauth/internal/jira. For non-default configuration, enter the URL of your Cortex instance and /oauth/internal/jira/{accountAlias}.
4. Select "Write" for the permission and click save.
5. Copy the client ID and client secret for the created link.

In the configuration modal in Cortex, select On-prem (OAuth) from the dropdown and enter the client ID and client secret, along with alias, host, and frontend host.

caution

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 help@cortex.io 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.

Jira default JQL

From settings, you can also set a custom JQL query for your Jira integration. When Cortex queries for Jira issues, the statusCategory is directly grabbed from the API response.

The default query - statusCategory in ("To Do", "In Progress") - will filter your Jira tickets to display only those with to-do and in-progress status, 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.

The custom JQL query 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.

Registration

Discovery

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 entity tag. 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 entity descriptor.

caution

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

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	Configuration alias in Cortex (when multiple configurations are created)

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

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

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.

You can confirm that users' Jira accounts are connected from the Jira user mappings section in Settings.

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. Discovered entities will have a Jira tickets tab under Integrations in the sidebar of an entity's homepage.

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.
• Priority: The issue's priority level in Jira - Lowest, Low, Medium, High, Highest. This will display with the icon that corresponds to the priority level in your Jira instance.
• 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.

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

Developer homepage

From the Issues tab of your developer homepage, you'll be able to see all the issues assigned to you that are pulled in. The issues that display will depend both on the Jira instances you've connected and the JQL query defined in Settings.

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.

First select Create issue to open a modal to create an issue configuration.

• Integration: If you have multiple task tracking tools, select Jira from the Integration dropdown.
• Name: A name for the configuration.
• Use project defined in entity yaml: This toggle will use the Jira project defined in a given entity's YAML and will override the "Project" field with "Default project."
  • Default project: The Jira project where the issue will be created if there is no project defined in the entity YAML.
• Project: Options available in the dropdown are pulled in from the specific Jira instances configured in Settings.

Next, select the Issue Type and the Subtask Issue Type from the respective dropdowns. Then, select how the sub-task's fields should be populated on issue creation. Finally, you can choose to include or exclude groups of entities, or define a more advanced filter.

The issue configuration will apply to all entities that meet the filter criteria. Once an entity is passing the rule, Cortex will automatically close the associated ticket.

You can read more about creating Jira issues from Initiatives in our walkthrough.

Dev homepage

The Jira integration enables Cortex to pull information about issues into the Dev homepage. You can find open issues assigned to you under the Issues tab.

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

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.

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

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.
3. Verify that the Jira token you added is still valid. You can run the following curl command to confirm:

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}}"

Still need help?

The following are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:

• Email: help@cortex.io, or open a support ticket in the in app Resource Center
• 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.