Suffering Jira? Creating tickets through its REST API

As exciting as a Product Owner role may seem, dealing with requests is part of the job. There just seems to always be something going wrong, some bug to fix, some report to submit, just even simple user’s questions. These requests often materialized in several ways. Receiving and email was usually the most pleasant, and less common, way. Often, meetings were being disrupted due to supposed ‘urgencies’. Personal interruptions were usual. And on top of that, keeping track of those demands had become a daunting task.

Canalizing and keeping track of this kind of requests between departments had become a need to keep our PO’s sanity.

“Yeah, my developers will take care of it”

In an effort to manage support requests between different teams, we built a simple yet powerful webapp for internal use, just consisting of a form to submit an issue to a specific Jira board.

Our webapp being used by Nick Fury to manage the Avengers

Hated and loved in equal parts, Jira has become the de-facto tool used in Software project management. Quirky as the product itself, its REST API allows for issue creation. I suffered through its sometimes incomplete documentation so you don’t have to. Here’s how to create tickets using Jira REST API.

API authentication

All request to the API must be authenticated through a user’s email and API token. This token can be created here. It is important that this user has full admin rights over the board you want to create tickets in. Otherwise, some requests may fail due to missing privileges, such as setting an issue’s reporter.

The only thing clear in JIRA’s documentation

To avoid incurring in extra costs, our webapp uses the same user credentials to create all issues. This way, there is no need to create extra Jira users, which are paid, so everybody in the organization can use it, whether they have a Jira account or not.

Issue creation

In order to create a JIRA ticket, a POST request must be issued to your corresponding organization Jira URL, which will probably look like this.

https://your-organization.atlassian.net/rest/api/2/issue

In this case, we are using version 2 of this REST API, as the newest version seems to be buggy.

Basic fields

Here’s an example of how to set fields in a Jira POST request body:

{
    "fields": {
        "project": { "key": "SPIDERMAN" },
        "summary": "Pictures",
        "description": "I want pictures of Spiderman!",
        "reporter": { "name": "jonh.jonah.jameson" },
        "assignee": { "name": "peter.parker" },
        "issuetype": { "name": "Task" },
        "priority": { "id": "1" },
        "labels": [ "Superheroes", "Pictures", "Urgent" ],
    }
}

“And I want them in my desk tomorrow first thing in the morning!”

What are we actually filling here?

• Project key indicates Jira which board we want to create this issue in.
• Summary will be the title of our issue.
• Description needs no description. It will apear in the body of your issue.
• To set the issue’s reporter, the only working way is to send it’s name as its email, which can sometimes differ from it’s Jira username. In the following link you can search all your JIRA users and see their email.

https://your-organization.atlassian.net/people/search

For example, if a user named John Jonah Jameson has a registered email as john.jonah.jameson@daily-bugle.com, you will have to send its name to the Jira API as john.jonah.jameson.

• Assignee can be set same way as reporter, by using its email name.
• issueType specifies the kind of issue you want to create, probably a ‘Task’ or ‘Bug’.
• Priority is a tricky one. By default, five levels are available, ranging from 5 being the lowest to 1 being the highest. Obviously, pictures of Spiderman are high priority.
• Issue labels can be specified as an array of strings. Make sure your labels don’t have spaces in them, otherwise the request will fail.

More fields can be set, such as issue transitions or related issue’s epic link. You can find out more here.

Custom fields

Have you defined custom fields in your board issue screens? If so, to be able to fill these fields through your POST request, you must find their id and add a new entry in your request object as follows:

{
    "fields": {
        "project": { "key": "SPIDERMAN" },
        "summary": "Pictures",
        "description": "I want pictures of Spiderman!",
        "reporter": { "name": "jonh.jonah.jameson" },
        "issuetype": { "name": "Task" },
        "priority": { "id": "1" },
        "labels": [ "Superheroes", "Pictures", "Urgent ],
        "customfield_10082": "Cover",
    }
}

In this case, customfield_10082 is a custom field refering to the newspaper page the pictures must appear in. To find its id in Jira, you will need to have administrator privileges:

• Go to Administration / Issues / Custom Fields
• Search for your field and click on configure
• You’ll see your custom field Id in the URL

Jira API will respond with a 200 status code if your request is successful. You fill find the ID of the issue you just created in the response body.

{
    "id": "14294",
    "key": "SPIDERMAN-24",
    "self": "your-organization.atlassian.net/rest/api/2/issue/14294"
}

Adding attachments to your issues

Finally got those pictures of spiderman?

Then attach them to your issues by submitting a POST form-data request to the following URL, where ID is the key of an already existing issue, for example, PICS-56.

your-organization.atlassian.net/rest/api/2/issue/{ID}/attachments

• Attach your pictures of spiderman as a field name ‘file’ to your request.
• Set ‘X-Atlassian-Token’ : ‘nocheck’ in your request headers to avoid your request being blocked due to XSRF.
• Enjoy pictures of Spiderman.

“Finally got you, Spiderman. Thanks Jira”