SEI Jira integration

Jira is a proprietary issue tracking product that allows bug tracking and agile project management.

Use the SEI Jira integration to integrate SEI with Jira in the Cloud.

info

The 202401.2 release included a new experience for the Jira integration, focused on simplifying and streamlining the user journey. The feature is currently in BETA. To learn more, go to Jira 2.0

Configure Jira

Before you configure the SEI Jira integration, you must generate an Atlassian API token.

Use a service account

The user creating the token must have read access to all projects that you want SEI to track, and the user must be able to search issues within the SEI-relevant projects.

Due to the scope of visibility required, consider using a managed service account, rather than a personal user account, to create the token.

1. Create an Atlassian API token. For instructions, go to the Atlassian documentation on Managing API tokens for your Atlassian account.
2. Make sure to copy the token somewhere that you can retrieve it when you configure the integration.

Configure the integration

Cloud

1. In your Harness Project, select the SEI Module, and go to your Account.
2. Select Integrations under Data Settings.
3. Select Available Integrations, locate the Jira integration, and select Install.
4. Configure the integration:
   • Add the URL of your Jira integration instance, for example, "https://organization.atlassian.net". Make sure it's a valid URL.
   • Enter your Jira account email as the value for the Username field.
   • Provide the API key that you previously generated within your Atlassian account.
   • If necessary, add a custom JQL (Jira Query Language) query. This query will determine which issues are ingested by SEI. Leave this field blank if you want to ingest all issues.
   • Select your Preferred Time Zone from the available options.
   • Choose the Fields you wish to exclude from ingestion. You might exclude fields containing sensitive information such as Summary, Description, and Comments. Excluded fields will not be evaluated for hygiene or adherence to best practices.
   • Finish configuration and Save the integration.

To integrate with the on-premises Jira instances, you must username and password authentication and an Ingestion Satellite.

Self-managed

To integrate with the on-premises (self-managed) Jira instances you can configure the integration using satellite. The steps for configuring the integration using Satellite is similar to configuring the integration on cloud, with the exception of using satellite to communicate with the Atlassian server.

To integrate with on-premises Jira instances, you can use your Atlassian account Username and Password with the relevant permission for authentication. Make sure to select the satellite integration checkbox while configuring the integration.

Once you save the integration a satellite.yml file will be automatically generated and downloaded to your computer. Update it following the instructions here.

If you experience any issues while configuring the integration using the Ingestion Satellite, refer to the Ingestion Satellite Troubleshooting and FAQs.

Here’s a sample satellite.yml file

satellite:
  tenant: <ACCOUNT_ID>
  api_key: <ACCOUNT_API_KEY>
  url: "https://app.harness.io/gratis/sei/api" # Note that this URL is relative to the Environment of your Harness Account.
integrations:
  - id: "<INTEGRATION_ID>"
    application: jira
    url: "<ATLASSIAN_JIRA_URL>"
    username: <ATLASSIAN_EMAIL>
    api_key: <ATLASSIAN_API_KEY>
    metadata:
      timezone: "<TIMEZONE>"
      sensitive_fields:
        - summary
        - description
        - comment
jira:
  allow_unsafe_ssl: true

info

The timezone field within the metadata should be in the Atlassian standard version.

To find the correct timezone, go to https://<ORGANIZATION_ATLASSIAN_URL>/rest/api/2/myself

Troubleshooting

If you encounter any authentication issues, consider the following options:

• While using a username and password for authentication, edit the generated satellite.yml file and use your Jira password as a value for api_key in the YAML and keep the user_name as is.
  
  Test with the following curl command:

curl -u "USERNAME:PASSWORD" -X GET "https://host:port/context/rest/api/search?jql=key-<JIRA_KEY>"

• While using the generated managed token (Bearer token) for authentication leave the user_name blank and use the managed token that you are generating for api_key.
  
  Test with the following curl command:

curl -H "Authorization: Bearer MANAGED_TOKEN" -X GET "https://host:port/context/rest/api/search?jql=key=<JIRA_KEY>

ADFS-based authentication for JIRA using Satellite

ADFS (Active Directory Federation Services) is a Microsoft service that provides single sign-on authentication to users across multiple applications or systems. When integrating with Jira using ADFS-based authentication via Satellite, specific fields need to be configured in the satellite.yml file.

Update the satellite.yml file:

Remove:

username:
api_key:

Replace with:

authentication: adfs
adfs_url: <ADFS_SERVER_ENDPOINT>
adfs_client_id: <CLIENT_IDENTIFIER> / <APPLICATION_ID>
adfs_resource: <RESOURCE_IDENTIFIER>
adfs_username: <ADFS_USERNAME>
adfs_password: <ADFS_PASSWORD>

Replace <ADFS_PASSWORD> with the actual password for the specified ADFS username. Ensure the rest of the file remains unchanged.

Field	Description
authentication	This field specifies the authentication method to be used, in this case, ADFS.
adfs_url	The URL of the ADFS server endpoint where authentication requests will be sent.
adfs_client_id	The client identifier or application ID assigned to your application in the ADFS configuration. It uniquely identifies your application to the ADFS server.
adfs_resource	The identifier of the resource for which the access token is being requested. In the context of Jira integration, it specifies the URI of the Jira OAuth API on the ADFS server.
adfs_username	The username used for authentication. This could be a service account or a specific user account authorized to access Jira via ADFS.
adfs_password	The password associated with the specified ADFS username. It is important to keep this information secure.

Add the Salesforce mapping

If you also have an SEI Salesforce integration, you can link Salesforce tickets to Jira issues by using a custom Jira field.

1. In your Harness Project, select the SEI Module, and go to your Account.
2. Select Integrations under Data Settings.
3. Find your Jira integration and edit it.
4. Under Salesforce Field Mapping, select the Jira field that contains your Salesforce case IDs.

Add custom hygiene misses

The Issue Hygiene Report widget uses data from Jira to calculate hygiene scores. These scores represent hygiene misses in a designated time frame. A hygiene miss means that a ticket in your issue management system was missing an important field, failed to change status in a timely manner, or was assigned to an inactive user.

What constitutes a miss depends on your hygiene categories. There are several built-in hygiene categories, and you can add custom hygiene categories by configuring Custom Hygiene Misses in your issue management integration.

To add custom hygiene categories:

1. In your Harness Project, select the SEI Module, and go to your Account.

2. Select Integrations under Data Settings.

3. Find your Jira integration and edit it.

4. Select Add Custom Hygiene Miss Criteria and configure the new hygiene category:

   • Name: Enter a name for the category. This name appears on the Issue Hygiene Report widget along with the category's score.
   • Field: Select the Jira field that provides data for this category.
   • Operator: Specify the operator, such as Missing or Greater Than, that determines if there was a hygiene miss for this category.

   The Operator represents an undesired state for the specified Field. For example, if your desired state is for the specified Field to be populated, then your undesired state is that the field is empty. Therefore, you would set the Operator to Missing.

5. To get scores for custom hygiene categories, you must modify the category Weights in your Issue Hygiene Report widgets. Custom categories don't have an initial weight, so you must modify all instances of this widget to include your custom categories in the hygiene score calculations. For instructions, go to Configure the Issue Hygiene Report.