Jira

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

To integrate SEI with Jira, you must choose your Jira type:

• Jira Cloud

• Jira Data Center

Connect with Jira Cloud

For the Jira type as Cloud, you can choose how you want to connect Jira i.e.

• Jira Connect App

• Jira API Token

Using Jira Connect App

The Jira Connect App facilitates a seamless connection to Jira projects with minimal user intervention, requiring Jira admin configuration for the app.

Using the Jira Connect App allows you to retrieve all user emails from Jira, making it faster and easier to connect and manage the integration.

To set up the integration using the Jira Connect App:

1. Select Integrations under Settings.

2. Select Available Integrations, locate the Jira integration, and select Install.

3. Select Jira Software Cloud as the integration type.

4. Select the Jira Connect App tile to set up the connection with Jira.

5. In the Jira Connect App settings page add the basic overview information:

   • Integration Name: Name for your integration.

   • Description (optional): Add a description for the integration.

   • Tags (optional): Add tags for the integration if required.

1. Install the Jira Connect App. To do this, follow these simple steps:

   • Verify that you are an owner of the Jira account where you track issues. An easy way to check is to visit your organization page and verify that the organization is listed.

   • Go to the Atlassian Marketplace to install the app and configure the SEI app to access the Jira projects.

   • Install the App.

   • Generate and copy the Jira Connect App key, then paste it when requested by the Jira Connect app.

Note that the key expires after 10 minutes, so generate a new key if the current one expires.

1. Click on Validate Connection to validate the connection, and once successful, you'll have the integration set up under the Your Integrations tab.

The following permissions are required to configure the Jira Connect App integration:

• View email addresses of users: This permission allows the integration to access and view the email addresses of users within the Atlassian account.

• Read data from the application: This permission allows the integration to read data from the Atlassian account, such as data from Jira tickets, Jira projects etc.

Using API Key

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

Authenticate with Jira

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

To set up the integration using the Jira API Key:

1. Select Integrations under Settings.

2. Select Available Integrations, locate the Jira integration, and select Install.

3. Select Jira Software Cloud as the integration type.

4. Select the Using Jira API Token tile to set up the connection with Jira.

5. Configure the integration settings and authentication:

   • Integration Name: Name for your integration.

   • Description (optional): Add a description for the integration.

   • Tags (optional): Add tags for the integration if required.

   • Add the URL of your Jira integration instance, for example, "https://organization.atlassian.net". Make sure it's a valid URL.

   • Enter your Email address for the Atlassian account

   • Provide the API Key that you previously generated for your Atlassian account.

1. Configure the advanced integration settings if required:

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

Please note that after adding an integration, it may take up to 24 hours for the data to reflect on SEI. This means that any widgets you configure on Insights using this integration may not display data until the synchronization is completed.

Connect with Jira Software Data Center

Connect via Ingestion Satellite

To connect with the on-prem instances of Jira Software Data Center, you can use the Ingestion Satellite. The configuration process for the integration is similar to setting up the integration in the cloud but instead uses the ingestion satellite to communicate with the Atlassian server.

To set up the integration for the Jira Data Center:

1. Select Integrations under Data Settings.

2. Select Available Integrations, locate the Jira integration, and select Install.

3. Select Jira Software Data Center as the integration type.

4. Choose the Connect via Satellite option.

1. Define the integration settings:

   • Integration Name: Name for your integration.

   • Description (optional): Add a description for the integration.

   • Tags (optional): Add tags for the integration if required.

2. Configure the integration settings and authentication:

   • Enter the URL of your Jira On-prem instance, for example, <https://JIRA.ORGANIZATION-DOMAIN>. Ensure it's a valid URL.

   • Select the authentication method. You can choose between Using Jira Personal Access Token (recommended) or Jira Username and Password.

   • If using a personal access token, enter the token.

   • If using a username and password, enter the username and associated password.

1. Configure advanced integration settings as needed:

   • Select your preferred time zone from the available options.

   • Choose which fields you want to exclude from ingestion.

     You may want to exclude fields containing sensitive information like summary, description, and comments. Excluded fields won't be evaluated for hygiene or best practices compliance.

2. Once you've configured the integration, click on Download YAML File to download the satellite.yml file.

Once you have downloaded the satellite.yml file update it following the instructions here.

Here’s a sample satellite.yml file which uses username and password for authentication.

satellite:
  tenant: <ACCOUNT_NAME>
  api_key: <SEI_API_KEY>
  url: 'https://staging.api.propelo.ai'
integrations:
  - id: '<INTEGRATION_ID>'
    url: '<ATLASSIAN_ORGANIZATION_URL>'
    username: <ATLASSIAN_USERNAME>
    application: jira
    api_key: <ATLASSIAN_PASSWORD>
    metadata:
      timezone: '<TIMEZONE>'
      sensitive_fields:
        - description
        - userDetails
jira:
  allow_unsafe_ssl: true

Here’s a sample satellite.yml file which uses a Personal Access Token and password for authentication.

satellite:
  tenant: <ACCOUNT_NAME>
  api_key: <SEI_API_KEY>
  url: 'https://staging.api.propelo.ai'
integrations:
  - id: '<INTEGRATION_ID>'
    url: '<ATLASSIAN_ORGANIZATION_URL>'
    application: jira
    api_key: <ATLASSIAN_API_KEY>
    metadata:
      timezone: <ATLASSIAN_ACCOUNT_TIMEZONE>
      sensitive_fields:
        - summary
        - description
jira:
  allow_unsafe_ssl: true

If you encounter any issues during the integration process, go to the Satellite integration Troubleshooting and FAQs.

Connect via Cloud

To set up the integration for the cloud instance of Jira Data Center follow the steps below:

1. Select Integrations under Data Settings.

2. Select Available Integrations, locate the Jira integration, and select Install.

3. Select Jira Software Data Center as the integration type.

4. Choose the Connect via Cloud option.

1. Define the integration settings:

   • Integration Name: Name for your integration.

   • Description (optional): Add a description for the integration.

   • Tags (optional): Add tags for the integration if required.

2. Configure the integration settings and authentication:

   • Enter the URL of your Jira On-prem instance, for example, <https://JIRA.ORGANIZATION-DOMAIN>. Ensure it's a valid URL.

   • Select the authentication method. You can choose between Using Jira Personal Access Token (recommended) or Jira Username and Password.

   • If using a personal access token, enter the token.

   • If using a username and password, enter the username and associated password.

1. Configure advanced integration settings as needed:

   • Select your preferred time zone from the available options.

   • Choose which fields you want to exclude from ingestion.

     You may want to exclude fields containing sensitive information like summary, description, and comments. Excluded fields won't be evaluated for hygiene or best practices compliance.

2. Click on Validate Connection to run the pre-flight checks and validate the connection. Once successful, you'll have the integration set up under the Your Integrations tab.

Troubleshooting

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

1. When using a username and password for authentication, edit the generated satellite.yml file and use your Atlassian account 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-DE-3121"

1. While using the generated managed 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=DE-3121

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

To find the correct timezone, go to https://<organization>.atlassian.net/rest/api/2/myself

ADFS-based Auth for JIRA connectivity via 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: <pwd>

Replace <pwd> 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	This field specifies the authentication method to be used, in this case, ADFS.
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. Select Integrations under Settings.

2. Find your Jira integration and edit it.

3. 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. Select Integrations under Settings.

2. Find your Jira integration and edit it.

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

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

Reauthenticate

If your integration health is failing due to expired credentials, you can easily re-authenticate by following these steps to update your access token:

• Go to the Integrations, and select your integration from the Your Integrations tab.

• Click on Monitoring.

• Click on the Change Authentication button at the top right corner.

• Follow the prompts and enter your email and the new API Key.

• Click Validate Connection to complete the re-authentication process.

By following these steps, you'll successfully re-authenticate with the Jira platform using your new access token, resolving any issues caused by expired credentials.