It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Import hierarchical data to JIRA w/JSON

James Mason Nov 14, 2018

Am I to believe that the one web page, entitled "Importing data from JSON", is the entirety of documentation for importing to JIRA via JSON?   Really?


3 answers

3 votes
Andrew Heinzer Atlassian Team Nov 15, 2018

Are you on Jira Server or Jira Cloud?  We do have slightly different versions of the same document for each platform:

Jira Cloud: Importing data from JSON

Jira Server: Importing data from JSON


Could you explain in some more detail what else you are looking for here?   I gather you want to import some data into Jira, I'm just curious to learn the source of that data to see if perhaps there might exist other alternatives to importing such data.

James Mason Nov 16, 2018

We're not supporting our own server, so I suppose that means we're going to be on the cloud.  I suppose I had seen that there were two forms of the document - and while a simple example is highly valuable - I would have expected something more like a grammar to help me generate acceptable JSON.

We're trying to migrate from GNATS.  The data extracted from there has a modest hierarchy - where issues are allowed to have an arbitrary length list of audit trail events.  Events being "State Changed", "Responsible Changed", "Comment Added", "FixForReleaseChanged", "Originator Changed", and some a couple types that relate change in custom issue fields.

I didn't think CSV would be as convenient a way to input hierarchical data - if it's even possible.

I have a python script that successfully loads the GNATS data base, as well as representing the attached list of audit trail items.  I was looking for something to help me emit all that in an acceptable JSON form.

Like # people like this
Andrew Heinzer Atlassian Team Nov 19, 2018

I have not found much in the way of other requests to migrate from GNATS to Jira.  However from the way you have described this hierarchical nature, it sounds much like the way Jira would represent an issue's history.

If you then look at a particular issue in Jira, under the History tab you can see the changes that happened to the issue over time, who made changes, and to which fields, like so:


This is something that you can define in JSON that Jira could handle.  The guide does cite at least one example of this in

                    "history" : [
                            "author" : "alice",
                            "created": "2012-08-31T15:59:02.161+0100",
                            "items": [
                                    "fieldType" : "jira",
                                    "field" : "status",
                                    "from" : "1",
                                    "fromString" : "Open",
                                    "to" : "5",
                                    "toString" : "Resolved"

In this example, it's a single historical change made by user Alice, at that specific time where the status is being changed from open to resolved.

But I would agree that using the CSV importer in Jira does not really appear to offer the same level of data that could be imported as JSON.   I don't believe that the CSV import in Jira is really intended to import such historical changes on an issue.


Does this help?  Forgive me if I have misunderstood the hierarchy you are referring to in GNATs is not historical information.  I admit that I have not used this particular system before.

James Mason Nov 20, 2018

Your understanding of my thinking and why I'm interested in JSON is essentially correct.  But please do not focus on the fact that I'm coming from GNATS.   As I noted previously - I've solved the problem of extracting GNATS data.  I can turn what I have into a structured file of almost any sort rather easily.

I need specific information on the JSON format for import to JIRA.

Interestingly, my question appears to have been asked in May of 2013 - "JSON Format for JIRA Import".   The Atlassian team member responding at that time explained that only an example was offered because things were incomplete/preliminary/etc.  I'll quote the frustrated user from May of '13:

I can't emphasize enough that the documentation -- including the data schema -- needs to be better.


Are you really expecting customers to successfully build JSON import data for JIRA - on the basis of the cloud/server documentation pages noted above?

Like # people like this
Andrew Heinzer Atlassian Team Nov 27, 2018

The short answer is, Yes.   I expect it is possible to build this import format with the examples in those documents.


The much longer answer is, I don't expect this to be quick and easy to achieve as other import methods that use predefined templates to migrate issue data from other trackers.  I would not be surprised to find this would take a lot of time to build the import format correctly.   However if you find there are problems with formatting this, that is what support is here for, either here on Community, or via our portal page. 

James Mason Dec 10, 2018

This doesn't need to be hard.   But it probably will be - precisely because Atlassian has not provided the detailed reference that someone creating this content needs.

Mind you - I'm not talking about a reference for specifics of "general" JSON (what a string looks like, a number, a list, a dictionary, etc.).  I'm writing python code and I'm emitting JSON using Python's "json" extension module.  So the "well formed JSON" part is easy.

The problem is that Atlassian hasn't provided specific semantics on THEIR side of what field names in what structures.   What values they're allowed/required to have exactly.   What values they'll get if not specified - or if incorrectly specified.   Etc., etc.

Like # people like this
David Johle Jan 03, 2019 • edited Jan 14, 2019

This is exactly the struggle I am facing right now.

The example in the JSON import article is good overall, but it is a bit lacking on some of the finer points.  Yet these details are the things required for successful import.

For example, the links->name values...I found another doc that said they have to match the Names used in the Issue Linking admin page.  Well, that only defines 4 of them, which does not include the sub-task-link used in the example!

Okay, so for sub task links, maybe it's the Sub-tasks admin page names?  Nope.  Doesn't match that one either.  So where did sub-task-link even come from?

On to the ->issues->history fields, fromString and toString are pretty self explanatory, but then there is this from and to as well, which seem to have some magic numbers in them.  Huh?



Yeah, I know, it says contact Atlassian suppor for help.  Well, I am just an evaluation license, no support included.  And I did contact their "product specialist" that contacted me during the evaluation (well, I think it was just an automated message, really) and got no response.

I really want to switch away from my old system with quite a lot of data (9 years of usage).  However, if I can't import everything, it's simply not worth it (money, user frustrations, and lack of historical data) to change.

It seems that Atlassian does not grasp just how much a good data import process relates to acquiring new customers, and thus doesn't give it the attention it deserves.




Update (Jan 14): FWIW I am now communicating with someone in support and they are being helpful towards my JSON import issues.

Like # people like this
Kye Russell Jan 18, 2019 • edited

For what it's worth, I 100% agree with you OP.

@Andrew Heinzer: With all due respect, your response is about as subpar as the reference document. Please admit some fault, or don't respond, but your ignorance to the poor quality of the document is just an indication that this hasn't been thought through at all from a customer's perspective.

The JSON format documentation leaves a lot to the imagination, and more closely resembles draft internal documentation or something you'd find in an open-source project, rather than the reality - public documentation pertaining to customer onboarding to the flagship product of a ~$21bn (market cap) publicly traded software company.

The issue is not the complexities of pulling data out of an existing bug tracking / project management solution. The issue is not the complexities transforming this data into some sort of JSON. I'm a developer, and I'm sure that most other people reading this are too. It's our job, we can gauge how hard that'll be. The issue is the JSON format we're meant to be writing to is extremely poorly defined by Atlassian.

We need to know: for each possible key, what is/are the expected format/s of the value? What's each allowed value? what precisely does it mean? If it's dependent upon our Jira installation / configuration, what part/s?

This is poor quality work for a large company with whom money is being transferred.

Like # people like this
0 votes
James Mason Thursday

Still no success at this effort.  But I think I've learned a few new details that aren't part of any explicit documentation for creating JSON input:

  • Projects must specify a "type" - in my case and probably many others "software" is the right answer.
  • Issues are required to have a defined "summary".  A "description" field apparently won't cut it.
  • Project keys are required to be upper case only
  • I'm assuming that your JSON has to name an existing project, but not as sure of that.
  • I'm also assuming that your issue "itemType" has to be among the default values - such as "Bug", "Improvement" or "Documentation".  Not sure if this is a requirement, but it probably wouldn't be good if it accepted random issue types on a load.  Maybe you could use others if they were defined with the project.

Hoping for support on this from Atlassian.  Got an initial response from Gabriel Senna, who helpfully noted that I should consult the documentation that is the subject of this entire thread.  Perhaps that would have been more understandable, had I not observed in the support request that, "For the record, I am the author of....".

James Mason yesterday

Further discovery - contrary to what I said above - no, your JSON doesn't have to name an existing project.  A project will be rolled up as needed.

0 votes
jcddesign I'm New Here Monday

This doesn't seem overly complicated for Atlassian to remedy - am I missing something?

Suggest an answer

Log in or Sign up to answer
This widget could not be displayed.
This widget could not be displayed.
Community showcase
Published in Next-gen

Introducing subtasks for breaking down work in next-gen projects

Teams break work down in order to help simplify complex tasks. This is often done iteratively, with tasks being broken down into smaller tasks and so on until the work is accurately captured in well-...

12,530 views 61 59
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you