Jira Server Integration Guide

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

The Jira Server Connection, just like it's cloud counterpart, enables you to integrate your Jira instance with Zenduty on an account level, map Zenduty Services with Jira Projects, allowing you to create incidents in Zenduty for Jira Issues, and vice-versa, create Jira Issues for Zenduty Incidents with synchronized statuses and notes.

In Jira:

1. Log into your Jira instance.
2. Go to https://id.atlassian.com/manage-profile/security/api-tokens and retrieve your API token.

In Zenduty:

1. Click on your profile bubble on the top-right corner and then on Account.
2. To integrate Jira with Zenduty, follow these steps to add a new key and configure account level settings:

   • Navigate to the Connections section, choose Jira On-Premise and click on Add New Key.

   • Enter your Jira Username and Base URL.

   • Paste the API token that you copied earlier into the provided field.

   • Additionally, you will need to choose the account level setting. This can be either single or multiple Jira projects per Zenduty service.

     • If you choose single Jira project per Zenduty service, each Zenduty service can be mapped to only one Jira project.
     • If you opt for multiple Jira projects per Zenduty service, keep in mind that the project direction is locked at the account level. This means that a specific Jira project can only be mapped to a Zenduty service as either an incoming or outgoing source across all services.

   • It's essential to carefully consider the implications of selecting multiple Jira projects per Zenduty service, as this configuration restricts the flexibility of mapping Jira projects to Zenduty services based on their individual needs.

3. Now, go to Teams on Zenduty and click on the team you want to add the integration to.

4. Next, go to Services and click on the relevant Service.

5. Go to Integrations and then Add New Outgoing Integration. Select the application Jira Server from the menu.

6. Follow these steps to configure integration settings for connecting your Zenduty service with a Jira project:

   • In the configuration section, start by selecting the appropriate tenant from the list of tenants associated with your account.
   • Next, choose the specific Jira project that you intend to connect to this Zenduty service.
   • Select the desired Issue Type that aligns with your integration requirements.
   • Choose the Integration Type based on the direction of data flow:
     • Incoming (Jira -> Zenduty): For data flowing from Jira to Zenduty.
     • Outgoing (Zenduty -> Jira): For data flowing from Zenduty to Jira.
     • Two-Way (Zenduty <-> Jira): For bidirectional data flow between Zenduty and Jira.
   • Customize your integration further by adding all the necessary custom mappings to meet your specific requirements.

7. Enable Sync Jira Comments live to sync comments and notes between Jira and Zenduty

8. In certain advanced use cases, such as integrating with the Epic issue type, custom field mapping becomes essential. This is particularly useful when dealing with specific attributes, like the Epic Name. By default, this feature is disabled, but it can be enabled to accommodate your unique integration requirements.

   • Identify the specific use case, such as integrating with the Epic issue type, where custom field mapping is necessary.

   • Navigate to the integration settings and locate the option for custom field mapping.

   • Enable the custom field mapping feature to unlock the ability to map fields dynamically.

   • Once enabled, you can map the fields to dynamic inputs provided by the integration platform. In the case of sending messages to Jira, these dynamic inputs form the basis for the fields that will be included in the message.

   • To create custom fields in Jira, navigate to Settings -> Issues -> Custom Fields from the left panel. Click on the Create Custom Field button on the top right and select the field type as desired. For eg: the Paragraph custom field can be used for Incident Summary or the Short Text field for most single line use-cases.
     

   • For instance, if you are dealing with an Epic issue type, you may want to map custom fields like Epic Name to ensure accurate and comprehensive data transfer between Zenduty and Jira.

   • By leveraging custom field mapping for advanced use cases, you can tailor the integration to handle specific attributes and data points, enhancing the flexibility and functionality of your integration with Jira.

   • You can also incorporate the alert payload field as a dynamic variable. Utilize the syntax {{incident.field_name}} to represent dynamic variables for incident-related fields. For alert-related payload fields, employ the syntax {{incident.firstAlertPayload.field_name}} to seamlessly integrate dynamic variables associated with the first alert payload.

   • In addition to the incident properties, you can use use the properties of the alert that triggered the incident using {{incident.firstAlertPayload.key1.key2}} or essentially {{incident.firstAlertPayload.someJSONpath}}.

   

9. Now, click on Test Issue Creation then go to your Jira Dashboard, you should see a new issue created.

Note

When creating a mapping of Zenduty service to Jira Project via this connection, you will only be able to create it only if there is no Jira Outgoing Integration mapped to that service for that particular project.

Alert Rule Jira Custom Fields

To Access the Incoming JIRA Custom fields, one would need to check for the custom fields in the Alert Payload that comes from JIRA.

In Alert rules, When either in JIRA Bidirectional (Jira <-> Zenduty) or Incoming JIRA configuration (Jira -> Zenduty)

• Payload search can be used to look into the Custom Fields that JIRA Sends.
• We can look into the latest alerts to get the ID of the Custom field that is needed.
  

Once we access this, one can essentially have the same functionality that JQL filter provides with Custom Fields.

Jira Custom Field Mapping

Jira Custom Fields can be used to create/update Jira tickets that need Custom Fields to be set upon creation of an Incident.

In a Default Jira setup, a common use-case for the same is the required Custom field "Resolution Notes" while closing a Epic Jira Ticket.

Upon activating Jira Custom Fields, the required fields for the given Issue type are automatically added as it needs to be set.
Any additional fields can be set be clicking the Add Field button on the top-right.

• You can also add Dynamic variables that take information from the incident and auto append it to the JIRA message.