Connect systems to Jira

This article describes how to connect applications to Jira via REST API to create new processes.

About Jira

A widely used tool in agile software development is Atlassian's Jira software. It is primarily used to manage tasks (called "processes" or "9s") that can be scheduled and tracked on different boards, and one of its big advantages is its high degree of customisation.

For example, by default, a Jira process has a short description, a priority and an operation type (user story, bug, task,...). Depending on the application, processes can also be supplemented with additional custom fields.

The process steps that a process must go through can also be customised, and Jira also provides interfaces to communicate with other systems: For example, processes can be created automatically using a REST API, while other systems can be notified of changes to a process using configurable webhooks. In the following sections, we'll look at what such a connection to Jira might look like.

‍

The use case

In our example, we will consider call centre software used by customer service agents to record customer concerns. Each call from a customer is categorised by the customer service agent based on various characteristics and maintained with all the necessary information. The concern recorded in this way is our business project to be transferred to Jira, which we will simply call CallCenterTicket, but it is important to remember that Customer Advisors work in different areas and the Jira processes are defined differently for each area.

In the call centre software, all customer concerns are structured identically, but the resulting Jira processes can have completely different structures. Information required by department A in a particular Jira field may be irrelevant to department B. Depending on the context, our connection must be able to decide which values should be written to which Jira field. First, we will look at how we can transfer the data to Jira.

‍

Address the interface

As already mentioned, Jira offers a REST interface. The latest version of the API is here documented. If you don't want to manually implement the necessary API calls, you can use the NuGet package instead Atlassian.sdk , which can be used to control various Atlassian products. Creating a new Jira process is pretty easy:

 var client = Jira.CreateRestClient("https://my-jira.url", "Jira-Username", "Jira-Password");  
 var issue = client.CreateIssue("PROJECTKEY");  
 issue.Summary = "Titel des Vorgangs";  
 issue.Description = "Beschreibung des Vorgangs";  
 issue.Type = "1";  
 issue.Priority = "3";  
 issue.CustomFields.AddById("customfield_10036", "Inhalt eines CustomFields");  
 issue.SaveChanges();  

In fact, Jira mostly works with strings as keys for fields and their possible values. However, these keys are not fixed and need to be adjusted depending on the Jira configuration.

The first step is to create a new component where all API calls to the Jira system will be made. We will call this component JiraService. The JiraService is only responsible for creating the issue in Jira. If we were to expose our business object CallCenterTicket directly to it, we would have an unwanted dependency on our business logic. So we introduce a new JiraIssueData data class as an intermediate layer, which already contains all the Jira-relevant data. All our JiraService needs to do is read this data class and make the appropriate API calls. We will look at exactly how this data class is filled with the right information later. For now, here is a simple version of the JiraService:

 public class JiraService  
 {  
   public void CreateIssue(JiraIssueData issueData)  
   {  
     var client = Jira.CreateRestClient("https://my-jira.url", "Jira-Username", "Jira-Password");  
     var issue = client.CreateIssue(issueData.ProjectKey);  
     issue.Summary = issueData.Summary;       
     issue.Description = issueData.Description;  
     issue.Type = issueData.IssueType;  
     issue.Priority = issueData.Priority;  
     foreach (var customField in issueData.CustomFields)  
     {  
       issue.CustomFields.AddById(customField.Key, customField.Value);  
     }  
     issue.SaveChanges();  
   }  
 }  
 public class JiraIssueData  
 {  
   public string ProjectKey { get; set; }  
   public string Summary { get; set; }  
   public string Description { get; set; }  
   public string IssueType { get; set; }  
   public string Priority { get; set; }  
   public Dictionary<string, string> CustomFields { get; set; }  
 }  

Of course, the connection details to the Jira system shouldn't be fixed in the code, but for our example, let's leave it that way. Now you can create Jira processes. But how do we get from the CallCenterTicket business object to the required JiraIssueData object?

Package the data

When creating the Jira process, we must consider the following data sources:

• The data of the CallCenterTicket itself
• Additional information that the customer advisor only provides when creating the Jira ticket (such as the Jira project to which the transaction is to be assigned)
• The Jira configuration that applies to the customer advisor

So we need a component that receives these data sources and uses them to create a JiraIssueDataobject. The Call Centre Ticket It already exists in our business logic (but is not described in more detail here). Let's create classes for the other two data sources:

// Die für den aktuellen Kundenberater gültige Konfiguration
public class JiraConfiguration
{
    public string CustomerFieldKey { get; set; }
    public string OriginFieldKey { get; set; }
    public string IssueType { get; set; }
    public string IssuePriority { get; set; }
}

// Die vom Kundenberater manuell ausgewählten Optionen zum Jira-Vorgang
public class JiraIssueOptions
{
    public string JiraProject { get; set; }
    public JiraIssueTemplate Template { get; set; }
}

public enum JiraIssueTemplate
{
    Simple,
    Advanced
}

Here the CSR can still select the Jira project for which the process is to be created and also a template, which is immediately relevant.

All other parameters are controlled by the JiraConfiguration defined for each CSR, and let's manage these data sources together using a simple JiraIssueDataFactory:

public class JiraIssueDataFactory
{
    public static JiraIssueData Create(
        CallCenterTicket ticket, 
        JiraIssueOptions options, 
        JiraConfiguration configuration)
    {
        var issueData = new JiraIssueData
        {
            ProjectKey = options.JiraProject,
            Summary = ticket.Summary,
            IssueType = configuration.IssueType,
            Priority = configuration.IssuePriority
        };

        var issueDescription = ticket.ErrorDescription;
        if (options.Template == JiraIssueTemplate.Advanced)
        {
            issueDescription += $"{Environment.NewLine}- {ticket.Workaround}";
        }
        issueData.Description = issueDescription;

        if (!string.IsNullOrEmpty(configuration.CustomerFieldKey))
        {
            issueData.CustomFields.Add(configuration.CustomerFieldKey, ticket.CustomerDisplayText);
        }

        return issueData;
    }
}

Ultimately, this determines what the Jira process to be created will look like, taking into account the three data sources mentioned above. For example, the issue description will be extended if the CSR has selected "Extended" as the template. In addition, the "customerDisplayText" will only be used if the corresponding custom field has been maintained in the configuration for the customer advisor.

Through the factory, we get an instance of JiraIssueData, which we add to the previously created JiraService to be able to pass it on.

‍

Conclusion

Creating your own processes in Jira is quite easy thanks to the REST API and the SDK package. Gathering the relevant data is more complicated. This example is simple.

If the logic in the JiraIssueDataFactory gets more complex and more criteria need to be considered, it is recommended to outsource the complex parts back to your own components, but such a factory can also be implemented for other business objects using the same pattern. There is no need to customise the JiraService, as the JiraIssueData instance is already filled with all the necessary information by the factory.

‍