JSON import questions and problems

[Julian Calaby]

I'm trying to import ~1500 tickets from Trac into Jira. Getting the data out of Trac and formatting it into a JSON file is pretty trivial, what I'm expecting to import is:

• All fields and data on tickets (with the exception of a couple of "legacy" fields we never used)
• Comments and field changes ("history")
• Users
• Attachments

I've got a working import for all of that except for some details in the history and will be uploading attachments through the API as I can't see a simple way to do this through the import without making them publicly accessible.

So as I've run into a wall with the history, I'm asking for help.

Is there any complete documentation?

The documentation here: https://support.atlassian.com/jira-cloud-administration/docs/import-data-from-json/ and here: https://confluence.atlassian.com/adminjiraserver/importing-data-from-json-938847609.html does not cover the expected file format in detail, doesn't cover a lot of slightly more obscure areas of the file (e.g. history formatting) and is internally inconsistent, doesn't provide enough information and is out of date with the current state of Jira Cloud.

If it provided detailed logging or even detailed error messages, this would be somewhat mitigated as one could just hack their way to a working file, but there are bugs preventing the logs from being accessed and the error messages displayed in the interface are very unhelpful.

What do you use to identify users in history events?

This ticket: https://jira.atlassian.com/browse/MIG-376 implies that you're supposed to use some internal identifier for users on the cloud platform, otherwise you'll get invalid user references instead. This doesn't match the documentation, which appears to use a username (or maybe a reference to the users in the users section of the file?).

What identifier is supposed to be used here? How do you obtain these identifiers? Are these the "accountId"s returned by the API? What about author / assignee fields, comments, etc. are these supposed to all use the same type of identifier or something different?

How is history data formatted?

Specifically: custom fields and changes to the assignee of the issue. I've found multiple conflicting reports of how custom field changes are supposed to be formatted: is the field type supposed to be "custom" or an actual field type? Neither of which works. Also it appears that assignee changes on a ticket get imported correctly, but I can't tell if the data there is actually correct because, again, there's no documentation.

Is this feature supposed to be Generally Available and is it maintained?

The documentation is both incomplete and out of date, threads like this one and reported bugs seem to be gathering dust. Functionality involved in the import seems to be broken, e.g. user references and importing. (the importer tells you that imported users are inactive, but we still got billed for them) And one of the "solutions" I've found is to spin up an instance of an older version of Jira Server, get the import working there, then migrate that to the cloud. This seems, to me, problematic in the extreme, preparing an import file shouldn't be difficult if it's adequately documented.

[Julian Calaby · Accepted solution]

Resolving this as our issues have mostly been sorted out:

Is there any complete documentation?

No, however Atlassian support has assured me that the documentation will be updated and improved.

What do you use to identify users in history events?

You use internal database IDs which you have to obtain from support as detailed in https://jira.atlassian.com/browse/MIG-376 - the IDs you can obtain through the API or the CSV user export aren't the right ones.

Note that those IDs obtained through the API or CSV user export are used everywhere else that users are identified.

How is history data formatted?

All history data, "from", "to", "fromString" and "toString" are strings or string-alikes, nothing else is accepted. This includes for fields which do not have string data here.

Is this feature supposed to be Generally Available and is it maintained?

Apparently.

How to do attachments?

Not really a question that was initially asked, but the best way I've found is to:

1. Make sure you keep your filenames consistent
2. Upload them through the API after tickets are imported

Jira seems to be smart enough to match everything up afterwards.

Our issues seem to now be resolved, so I'll be performing my migration this weekend.

[Julian Calaby]

I've been discussing this with support and apparently using the IDs in the user export from the admin panel should work, and maybe it did improve some of it, but the history importing is still broken: history action authors aren't specified and the import fails with a useless error message and no logs if I try to import certain history changes.

I'm beginning to believe that there is no up-to-date or complete documentation for this feature, it's completely broken for anything but the most basic use cases, and doing an actual "full" migration of historic data into Jira is not a supported use case.

For smaller organisations Jira is a massive cost and a massive overhead when all you really need is ticket tracking at a level that's a step or two above an inbox or spreadsheet. Issue tracking systems like Trac, Redmine or the ones built-into GitLab or GitHub fill that need quite well: simple tracking of tickets, processes built around direct communication and "just the facts" simplicity.

The problem comes when these organisations grow: when 2-5 employees become 10, when the tickets go from half a dozen open bugs to features and ideas and concepts with forward planning that stretches over months and years.

Jira is the industry leader for a reason, it has it all: all the features, all the agile tools, all the integrations, all the power and flexibility to manage anything. However that transition point when you want to move over to the big-kid toys is where the problems are.

I get that Jira doesn't want to maintain half a dozen random tools that are rarely used, complex, ever-changing, and just barely out of scope, but not providing working alternatives is just insane. How am I supposed to migrate my projects over? How am I supposed to take data that I feel is valuable and slot it into Jira? How am I supposed to grow?

Jira needs to do better, either by providing complete and thorough documentation and keeping that documentation up-to-date, or by providing working tools to do the things that people like me need to do to keep our businesses growing and running.

At this point the only reason why we're not taking our money and business and going somewhere else is that we've already started migrating our documentation to Confluence, and nothing else has the features we need.

[Troy Anderson]

Nailed it

[Claus Schneider (eficode)]

regarding attachment URI ..

I wonder if the https://<username>:<PAT>@<url> would work ?