SURVEY ON JIRA INTEGRATION USING REST APIs

SURVEY ON JIRA INTEGRATION USING REST APIs Arpitha Prasad 1, Nirmala H. 2 Department of Computer Science and Engineering, SJB Institute of Technology, Bangalore, India ABSTRACT: JIRA is a proprietary issue tracking product, developed by Atlassian. The basic building blocks of JIRA add-on development are the Atlassian Connect framework, the JIRA REST APIs, and webhooks. This paper will point to a number of resources to helps get integrated with JIRA. To integrate an existing application with JIRA remotely, there are two resources that can be used to get acquainted with JIRA: JIRA platform and JIRA applications Keywords: JIRA-bug tracking tool, REST APIs [1] INTRODUCTION [1.1] What does JIRA mean? JIRA is a tool used for bug tracking, issue tracking, and project management, developed by Australian Company Atlassian. The name JIRA is derived from the Japanese word Gojira which means Godzilla. Originally the company used Bugzilla (a bug-tracking tool, developed by the Mozilla Foundation), for bug tracking and the developers in their office started calling it by the code name Gojira, the Japanese name for Godzilla (the original blackand-white Japanese Godzilla films are also their office favourites). When they developed their own bug tracker, the Go got dropped - hence the name JIRA. JIRA is offered in three packages: JIRA Core includes the base software. JIRA Software is intended for use by development teams and includes Core and Agile. JIRA Service Desk is intended for use by IT or business service desks. JIRA is written in Java and uses the Pico inversion of control container, Apache OFBiz entity engine, and WebWork 1 technology stack. For remote procedure calls (RPC), JIRA supports REST, SOAP, and XML-RPC. JIRA integrates with source control programs such as Clearcase, Concurrent Versions System (CVS), Git, Mercurial, Perforce, Subversion and Team Foundation Server. It ships with various translations including English, French, German, Japanese, and Spanish. The main features of JIRA for agile software development are the functionality to plan development iterations, the iteration reports and the bug tracking functionality (A JIRA Bug is usually abbreviated to JB). JIRA is a commercial software Arpitha Prasad, Nirmala H. 446

SURVEY ON JIRA INTEGRATION USING REST APIs product that can be licensed for running on-premises or available as a hosted application. Atlassian provides JIRA for free to open source projects meeting certain criteria, and to organizations that are non-academic, non-commercial, non-governmental, non-political, nonprofit, and secular. For academic and commercial customers, the full source code is available under a developer source license. JIRA provides bug tracking, issue tracking, and project management functions. It has been developed since 2002. According to Atlassian, JIRA is used for issue tracking and project management by over 25,000 customers in 122 countries around the globe. Some of the organizations using JIRA for bug-tracking and project management are Fedora Commons, Hibernate, JBoss, Skype, Spring Framework and The Apache Software Foundation uses JIRA and Bugzilla. JIRA includes tools allowing migration from competitor Bugzilla. Compared to Bugzilla, JIRA is more internally customisable. Bugzilla has a single, fixed, state machine to represent the lifecycle of a 'bug'. All such bugs are assumed to follow the same fixed pattern of detection, repair and test. All bugs must also have the same lifecycle. JIRA allows this state machine to be changed by its users, and also for different classes of issue to be tracked, each with their own state machine. This makes JIRA far more flexible: it may be used as a more general "issue tracker" rather than solely a bug tracker, tracking new feature requests, system admin tasks, Scrum tasks or any other feature that its users might require. To avoid the overhead of configuring JIRA for each new task type, pre-built configurations such as GreenHopper (now JIRA Agile) can be bought-in, which provide a pre-configured JIRA environment with tasks and behaviours appropriate for popular management methodologies. [2] JIRA REST APIS [2.1] JIRA APIs The JIRA platform provides both Java APIs and REST APIs that can be used to interact with JIRA programmatically. These APIs are common to all JIRA applications. In addition, JIRA Software and JIRA Service Desk provide APIs for application-specific functionality. For example, the JIRA Software REST API has methods for creating sprints, creating boards, retrieving epics, etc. To work with JIRA in Atlassian Connect, one will need to use JIRA's REST API to get data from JIRA, and listen to webhooks to respond to events. The JIRA REST APIs are used to interact with JIRA remotely, for example, when building Connect add-ons for JIRA Cloud or configuring webhooks. [2.2] JIRA REST APIs JIRA REST APIs are the only remote APIs supported for JIRA. The examples on this page and in the tutorials use the JIRA platform REST API, but many of the principles can also be applied to the REST APIs for the JIRA applications. The Atlassian REST APIs provide a standard interface for interacting with JIRA and other applications. REST APIs provide access to resources (data entities) via URI paths. To use a REST API, application will make an HTTP request and parse the response. Methods will be the standard HTTP methods like GET, PUT, POST and DELETE. REST APIs operate over HTTP(s) making it easy to use with any programming language or framework. The input and output format for the JIRA REST APIs is JSON. JIRA uses the Atlassian REST plugin to implement the JIRA APIs. The REST plugin is bundled with JIRA. YBrowsing and Testing REST APIs from the Application UI. Since the specifics of the REST API vary between Atlassian applications, the best way to learn about the REST API Browser for product is to use the REST API Browser built into JIRA instance. The REST API Browser allows to browse, inspect and try the REST API Browser for any application. It's a tool for discovering the REST APIs and other remote APIs available in Atlassian applications. The browser is built into several types of Atlassian applications, including Stash and recent versions of Confluence and JIRA. It's also a part of the Developer Toolbox plugin (included by default in developer instances of Atlassian applications) or 447

available separately. One can add their own REST APIs to JIRA by creating a JIRA plugin that includes the REST plugin module. A Simple Example: Creating an Issue in JIRA The examples below use curl. Ideally, should use the REST API Browser to investigate how the API works, but this example is meant to give a glimpse. Creating an issue in a local JIRA instance. A few points to note about this example: The input file is denoted by the '--data @filename' syntax. The data is shown separately, and uses the JSON format. Make sure the content type in the request is set to 'application/json', as shown in the example. POST the JSON to JIRA server. In the example, the server is http://localhost:2990/jira/rest/api/2/issue/. The example uses basic authentication, with a username of admin and password of admin. Adding a project to the instance before running is needed, and get the project ID of the project to which needs to be added the issue beforehand. To try a simple REST command with curl, follow these steps: Start by creating the data file that contains the POST data. In command, assume the file is named data.txt. Add the following content: "fields": "project": "id": "10000", "summary": "No REST for the Wicked.", "description": "Creating of an issue using ids for projects and issue types using the REST API", "issuetype": "id": "3" In this example, project ID is 10000. Use a suitable ID of a project in the instance. Also, the issue type is 3, which represents a task. Alternatively, find the api/2/issue resource in the REST API Browser, and paste the text above into the Request Body field to try it out. From the command line enter the following command: curl -u admin:admin -X POST --data @data.txt -H "Content-Type: application/json" http://localhost:2990/jira/rest/api/2/issue/ As before, adjust details for an environment, such as the hostname or port of the JIRA instance. Note that a cloud instance or most public instances would require the use of HTTPS and of course valid credentials for the instance. The response provides the issue ID, issue key, and the URL to the issue (which can then be used to GET additional data, PUT updates, etc). "id":"10009", "key":"test-10", "self":"http://localhost:2990/jira/rest/api/2/issue/10009" [3] CREATING AND UPDATING ISSUES USING REST APIS Arpitha Prasad, Nirmala H. 448

SURVEY ON JIRA INTEGRATION USING REST APIs [3.1] JIRA REST API Example - Create Issue The JIRA Rest API allows to create an issues easily. One can POST a single JSON document. The fields that are available when creating an issue are available via the REST API, e.g. http://localhost:8090/rest/api/2/issue/createmeta This will return all of the create metadata for all issue types across all projects. Most likely want a subset of that information, for example for a specific project and issue type, which can be asked for by specifying the project ids, project names, issue type ids, or issue type names in the URL. For example, to get the create metadata for the Bug issue type in the JRA project: http://localhost:8090/rest/api/2/issue/createmeta?projectkeys=jra&issue typenames=bug&expand=projects.issuetypes.fields [3.2] Examples of creating an issue Creating an issue using project keys and field names. Request: curl -D- -u fred:fred -X POST --data see below -H "Content-Type: application/json" http://localhost:8090/rest/api/2/issue/ Data: "fields": "project": "key": "TEST", "summary": "REST ye merry gentlemen.", "description": "Creating of an issue using project keys and issue type names using the REST API", "issuetype": "name": "Bug" Response: "id":"39000", "key":"test-101", "self":"http://localhost:8090/rest/api/2/issue/39000" [3.3] Updating an Issue via the JIRA REST APIs The simple way to update an issue is to do a GET, update the values inside "fields", and then PUT back. If values are PUT back exactly what values are GOT, then also sending "names", "self", "key", etc. These are ignored. Not needed to send all the fields inside "fields". Just send the fields that want to be updated. Absent fields are left unchanged. For example, to update the summary: "fields": "summary": "new summary" Some fields cannot be updated this way (for example, comments). Instead use explicit-verb updates (see below). If a field cannot be implicitly set by the fact it doesn't have a SET verb. If 449

sending along such un-set-able fields in this manner, they are ignored. This means one can PUT what they GET, but not all of the document is taken into consideration. Operation (verb) based update (explicit verb via "update"). Each field supports a set of operations (verbs) for mutating the field. Retrieve the editable fields and the operations they support using the "editmeta" resource. For example: http://myjira.install.com:8080/rest/api/2/issue/issue-key/editmeta The basic operations are defined below (but custom fields can define their own). The general shape of an update is field, array of verb-value pairs. For example: "update": "field1": [ "verb": value, "verb": value,...], "field2": [ "verb": value, "verb": value,...], SET: Sets the value of the field. The incoming value must be the same shape as the value of the field from a GET. For example, a string for "summary", and array of strings for "labels". CLEAR: (warning) don't need CLEAR, it's the same as SET: []. ADD: Adds an element to a field that is an array. The incoming value must be the same shape as the items of the array in a GET. For example, to add a label: "update": "labels": [ "add": "newlabel" ] REMOVE: Removes an element from a field that is an array. The incoming value must be the same shape as the items of the array in a GET (although can remove parts of the object that are not needed to uniquely identify the object). For example, to remove a label: "update": "labels": ["remove": "test" ] remove a comment (by comment id): "update": "comments": ["remove": "id": 10001 ] EDIT: Edits an element in a field that is an array. The element is indexed/identified by the value itself (usually by id/name/key). edit the text of a particular comment: "update": "comments": ["edit": "id": 10002, "body": "newbody" ] Combining implicit and explicit updates having both "fields" and "update" in the one PUT, but a given field must appear only in one or the other. Validation and errors, if any of the implicit or explicit updates cause a validation error, an error document is returned, detailing the validation errors associated with each field. [4] SYNCHRONIZATION METHODOLGY Sync for JIRA allows to transfer issues from a remote JIRA system to local JIRA application. Create multiple synchronizers to connect to multiple remote JIRA systems. Define JQL statements to filter issues on the remote system. Configure which fields to sync on issues, including system fields and custom fields. Target local JIRA to transfer issues between JIRA projects on the same JIRA. Get informed by e-mail for failed issues. Export & Import settings as XML Arpitha Prasad, Nirmala H. 450

SURVEY ON JIRA INTEGRATION USING REST APIs Solution that would limit returning a large result set from JIRA is to use the POST /rest/api/2/search API method which allows to supply a JQL query along with the fields that needs to return in the result set and the number of results wanted to return. For example: "jql": "project = PROJECTKEY and priority = \"Must Have\"", "maxresults": 1, "fields": ["status"] This will return a JSON object that contains the number of results. Supplying maxresults: 1 will mean that only one result is returned in the issue list. "expand": "names,schema", "startat": 0, "maxresults": 1, "total": 354, "issues": [... ] One can then use the total property for count. Specific example using curl: curl -i -u username:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d '"jql": "project = PROJECTKEY and priority = \"Must Have\"","fields": ["status"], "maxresults": 1' https://jira.url/rest/api/2/search [5] CONCLUSION Unfortunately, there are limitations of this solution; Need to provide the priority as an input (rather than simply having JIRA aggregate the results) 451

Need to make one request per priority in order to retrieve the counts of all known priorities If these limitations aren't acceptable, then one could select all issues for a project and only return the priority field. Need to parse the JSON and aggregate the results. Note however that the results from the API are paged, so it will not be necessary to get all issues returned from a single result. REFERENCES [1] https://en.wikipedia.org/wiki/jira_(software) [2] https://docs.atlassian.com/jira/rest/latest/ [3] https://wiki.almworks.com/display/structure/synchronization [4] https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis [5] http://www.jiratimesheet.com/wiki/restful_endpoint.html Arpitha Prasad, Nirmala H. 452