Overview

No man is an island, wrote John Donne, and this is doubly true of JIRA and almost every other application you may administer. Users want their data to appear in multiple places, administrators want to manage applications from a single place, and anyone may want to run some scripts to make lots of changes at once.

All of these require remote access to JIRA, where remote access is defined loosely as using JIRA without a browser.

This chapter covers a variety of remote access methods for JIRA. The quick summary is that REST is the way that most remote access to JIRA occurs in 2015, with a small amount of SOAP access in older installations. SOAP access was deprecated in JIRA 6.0 and removed in JIRA 7.0.

A good starting place for REST information in the Atlassian documentation is https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis.

Email

Email is one of the simplest ways to use JIRA remotely. Issues can be created and then comments added to them using the standard JIRA mail service and mail handlers. Email is a function commonly already found in many applications.¹ Balanced against the simplicity of email are its limitations:

• Email messages have limited structure. Only the To, Cc, Subject, From fields and any attachments are easily separated from the email body.

• There’s no real guarantee about who most email is from, so authentication is hard.

• Email is asynchronous and unreliable, in the sense that retrying failed messages is slow and limited — so you don’t know if your message reached JIRA. You may not even get any feedback about whether a JIRA server is currently active.

Still, it’s familiar and convenient and a fair number of JIRA users only interact with JIRA via email (see “Further Reading”). Some integrations between different systems use email, but it’s not really a great idea because of the limitations listed above. In addition, standard JIRA has to have a separate mail handler for each JIRA project where issues are created and this does not scale well when there are many projects involved.

SQL

Accessing the underlying database of a JIRA instance is surprisingly common perhaps because, like email, many applications are already accessing their own database and adding one more database is an obvious approach to try. Most access to JIRA’s database is for creating reports using a separate report generating tool.

Reading data from the JIRA database using other systems is usually just fine (and is generally pretty fast) but does have the following strict limitations:

• Access must be read-only. This is because JIRA caches many of the values read from its database and it may not update the caches until the next time it is restarted. If the data is changed in JIRA before that happens, then the updated values will be written back to the database, overwriting any changes that you made there.

• You have to carefully control who can view the different tables in the JIRA database. For instance, if some issues have issue security schemes (see “Issue Security Schemes”) defined so that only certain people can see the issues, the underlying confidential data would end up being visible to the database user running the SQL query. That is, all data in the JIRA database can be viewed by a database user.

• The JIRA database schema is only partially documented because the schema does change between different versions of JIRA. JIRA upgrades handle such changes automatically but Atlassian does not encourage (or support) direct database access. The actual file where the database schema is defined (and not documented) is atlassian-jira/WEB-INF/classes/entitydefs/entitymodel.xml.

If you do decide to take this approach, then a somewhat dated place to start is http://confluence.atlassian.com/display/JIRACOM/Example+SQL+queries+for+JIRA. This page has many SQL queries that other people have found useful. However, most of them don’t have much explanation of why they work the way they do.

REST

The recommended way to access JIRA remotely is REST. REST methods are invoked using a URI, plus arguments passed in after the URI.² The resulting data from JIRA is in the JSON format. The returned data usually also contains further URIs to let you drill down into the data. This means that clients can walk the data and dynamically discover what is currently available.

A good place to start for information about JIRA and REST are the tutorials at https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis/jira-rest-api-tutorials.

If you want to see an example of what JIRA returns with REST for an issue, browse to http://jira.atlassian.com/rest/api/latest/issue/JRA-13036.json. Different browsers will display the resulting JSON data differently. The Pretty JSON extension is helpful for Chrome users.

Alternatively, you can use a command line tool such as curl or wget. Replace userid with your Atlassian username from https://my.atlassian.com and secret with your password and try the following:

curl -u userid:secret 
  http://jira.atlassian.com/rest/api/latest/issue/JRA-13036.json

wget --user=userid --password=secret 
  http://jira.atlassian.com/rest/api/latest/issue/JRA-13036.json

REST access to JIRA is reasonably efficient but requests from the same authenticated user are queued for the same thread so overall access may seem slower sometimes. Updating many issues at once is often only at the rate of a few per second. The performance of many REST requests was improved in JIRA 6.4, particularly searching for issues.

Another excellent way to see what REST resources are available and experiment with them is to install the Atlassian Developer Toolbox add-on which includes the REST API browser tool. This tool lets you choose a set of resources such as Atlassian JIRA - Plugins - REST Plugin, which is the official REST API for JIRA, and explore them. You can also add data and invoke a resource directly from within the page and see the results there.

from jira.client import JIRA

# Note the tuple
jira = JIRA(options={'server': 'http://jira.example.com'},
            basic_auth=('jsmith', 'secret'))

# Get the open issues in the TEST project
jql = 'project = TEST and status != Closed'
      
issues = jira.search_issues(jql)
for issue in issues:
    print issue.key
    

Webhooks

As discussed in “Workflows and Events”, JIRA sends internal events when issues are changed. Webhooks can be configured in JIRA at Administration→System→WebHooks and also in workflow post functions. When a standard event such as Issue Created is sent within JIRA, a webhook can make an HTTP POST call to a remote system. Custom events are not supported but many other events are supported now, making webhooks a useful method to get JIRA to connect to remote systems.

The main Atlassian documentation for webhooks can be found at https://confluence.atlassian.com/display/JIRA/Managing+Webhooks and includes some other restrictions on what webhooks can do. A very useful page with examples of what the POST data looks like is https://developer.atlassian.com/jiradev/jira-architecture/webhooks. Webhooks are implemented by JIRA listeners though this is not visible to administrators.

XML and RSS

Retrieving an XML file with the details of just one issue is easy with a URL such as http://jira.atlassian.com/si/jira.issueviews:issue-xml/JRA-13036/JRA-13036.xml. The XML that’s returned is formatted as an RSS feed item, but since it is structured data, it can be processed by clients for integrating other systems with JIRA.

You can also retrieve the results of a search as an XML file using the link under the Export menu in the Issues→Search for issues screen (also known as the Issue Navigator screen). The XML link is the same one that is used for integrating JIRA with Confluence. JIRA provides similar RSS feeds for the activity of individual users and projects as well. Following a JIRA project’s activities with an RSS reader application is more efficient than reading email in some ways.

Authentication is probably the hardest part of using RSS feeds for integration. A username and password can be passed in the URL or a user can be prompted for a password, but neither method is particularly robust.

More information can be found in the documentation at http://confluence.atlassian.com/display/JIRA/Displaying+Search+Results+in+XML.

CLI (Command Line Interface)

You may just want is a way to interact with JIRA from a command line or with a shell script. For example, you might want to have an automated build system add a new version in JIRA when a new release occurs. Or you might want to make it easier for an IT team to create new internal users in JIRA by providing a small script for them to run.

The main CLI available for JIRA is JIRA CLI, a commercial add-on by Bob Swift, now part of Appfire. This is written entirely in Java, can be invoked from a shell script, and is part of a suite of CLI tools for all of the Atlassian products. Bob’s CLI is well-maintained and very well-tested. It uses both REST and direct HTML access internally, but this is unseen by the user.

The jira-python library mentioned in “REST” also provides a jirashell interactive shell for examining data from JIRA

Remote Issue Links

Remote Issue Links make linking JIRA issues to the URLs of objects in other systems much easier. They can also be used to create links to JIRA issues on another JIRA system. The choices are seen by a user when adding a link to a JIRA issue, but remote issue links can also be created and updated using the REST API.

There is also the unsupported JIRA to JIRA Issue Copy add-on from Atlassian, which allows users to copy JIRA issues from one JIRA server to another.

Issue Collectors

Up until a few years ago JIRA supported creating issues and other actions using a fixed URL (https://confluence.atlassian.com/display/JIRA051/Creating+Issues+via+direct+HTML+links). This was convenient for embedding a Report a Bug link in web pages to create JIRA issues in a specific JIRA project. However it was never easy to authenticate the reporter so as of JIRA 5.2 this approach is deprecated. As of JIRA 6.4 it still works for presetting the project and issue type only.

The alternative is Issue Collectors. These are little snippets of JavaScript automatically generated for each project and issue type. These snippets can be added to a web page to provide a form where details for a new issue can be entered. There is also an administration page that shows which issue collectors have recently been used to create issues.

Basic issue collectors are relatively straight-forward to configure and use. Setting default field values and some other customizations are possible using more customized JavaScript as described in the Advanced Use of the JIRA Issue Collector documentation.

Integrating with Other Applications

Whichever method is used for integrating other applications with JIRA, there are a few things are that worth bearing in mind.

Networking outages will inevitably occur and so your integration has to survive them without inconsistent or corrupted data. This means that any synchronous approach such as REST has to be able to retry later on or warn users that something went wrong. Other than changing issues, most JIRA operations are not strictly transactional, which makes integrations harder.

JIRA provides services, custom tasks that are periodically executed as frequently as once per minute. This is one way to have an integration be able to recover from errors. Such services may also run when JIRA is started, which could mean a large load on another system if JIRA has been down for a while. In this case, limiting the amount of work that is done in a single run of the service can help.

Synchronizing two systems in only one direction is much simpler than doing it in both directions. If you really do have to do it in both directions, consider very carefully how you’re going to avoid infinite loops and which application will maintain the synchronization state (don’t try storing it in both). JIRA issues have an Updated date field that can help with that if the systems’ clocks are synchronized. You can also use the internal records of everything that has changed.

There is a useful book titled Enterprise Integration Patterns, by Gregor Hohpe and Bobby Woolf (Addison-Wesley) that covers these kinds of issues. And if you haven’t already read it, then The Twelve Networking Truths [RFC 1925] is brief and applies to many integrations just as well as it does to networking design.

Further Reading

The process of using JIRA via email is documented at http://confluence.atlassian.com/display/JIRA/Creating+Issues+and+Comments+from+Email. The most commonly used add-on to do more with this is The Plugin People and Andy Brook’s Enterprise Mail Handler for JIRA (JEMH). This commercial add-on has an amazing number of features and is well maintained.

The main page for information about the JIRA database schema is https://developer.atlassian.com/jiradev/jira-architecture/database-schema. Enabling logging of all SQL queries is described at https://developer.atlassian.com/display/jiradev/Logging+JIRA+SQL+Queries.

One good place to look for more general information about REST is http://en.wikipedia.org/wiki/REST. More information about JSON and an example of what that format looks like can be found at http://en.wikipedia.org/wiki/JSON.

Finally, the whole of the quote from John Donne:

No man is an Iland, intire of it selfe; every man is a peece of the Continent, a part of the maine; if a Clod bee washed away by the Sea, Europe is the lesse, as well as if a Promontorie were, as well as if a Mannor of thy friends or of thine owne were; any mans death diminishes me, because I am involved in Mankinde; And therefore never send to know for whom the bell tolls; It tolls for thee.

Devotion XVII (Meditation XVII), John Donne, 1624