JIRA 6.1 – This documentation is for the downloadable version of JIRA 6.1.
Not using this? See the [JIRA OnDemand documentation] or earlier versions of the documentation.

Skip to end of metadata
Go to start of metadata

The JSON importer in still in beta and is not yet fully supported. For assistance, please post the problem description on Atlassian Answers with a sample JSON file that doesn't work, ensuring to add the "import" tag to it.

The JIRA Importers plugin, which is bundled with JIRA, allows you to import data from a JavaScript Object Notation (JSON) file.

JSON files are easy to read and are capable of encapsulating more structure and information than CSV files. They can also be used to populate data from other systems.

The JIRA Importers plugin comes with an export option that allows you to export your existing issues to JSON formatted files, which can be used to copy issues between different JIRA servers, or to prepare templates that can be used to populate new projects.

(info) This is an experimental feature so feel free to contact us and share your story or ideas how this feature can help you.

 

You can generate JSON file with JIRA Importers plugin version 4.3 or later.

 

(warning) Please note that the import issue format used by JIRA Importers plugin is a simplified version when compared to the version returned from the JIRA REST API.

On this page:

JSON file example

If you want to prepare the JSON file yourself follow this pattern:

JSON file example

Dates can be represented in SimpleDateFormat "yyyy-MM-dd'T'HH:mm:ss.SSSZ" (example output: "2012-08-31T15:59:02.161+0100") or you can use relative dates like "P-1D" (which means one day ago).

 

Running the JSON Import Wizard

If your JIRA installation has existing data, then before you begin, back up your existing JIRA data.

  1. Log in to JIRA as as a user with the JIRA Administrators global permission.
  2. Select Administration > System > Import & Export > External System Import > Import button associated with the JSON option to open the JSON Import Wizard: Setup page.
    (tick) Keyboard shortcut: g + g + start typing external system import
  3. The importer will display updates as the import progresses, then a success message when the import is complete. You can download the import log if you wish.

Congratulations, you have successfully imported your JSON projects into JIRA! If you have any questions or encounter any problems, please contact Atlassian support.

 

154 Comments

  1. Cool feature. Is there any configuration step to do after choosing the file? (The screenshot is in Polish BTW). Does it handle comments, attachments, and maybe issue history?

    1. There's no configuration possible right now. Maybe will add it in the future.

      Importer handles comments, attachments, and issue history. Unfortunately exporter doesn't handle attachments and issue history.

       

      1. Could you include a complete example of import JSON? Since I can't see the source or export attachments/history, there is no way to know what format to provide them in.

        Edit: Just read in another comment that the importer module is part of the source distro. FYI, I was mislead by the sidebar on the JIM marketplace page. I will go hunting there next but it would still be handy to have this readily available in the docs.

        Edit 2: For those who need JSON samples, they are in the JIRA source under jira-importers-plugin\src\test\resources\sample

        1. I don't see a link in the Marketplace for source code. Where are you getting the source from?

          1. It is in the main JIRA source archive from my.atlassian.com (for licensed users).

            1. I thought I'd looked for the JIM source in those bundles before. Thanks, I'll check again

            2. I could not find the source.  Could you provide the URL to download or view the sample? 

        2. Provided it is complete enough for you, I added the sample JSON file. Tested and proofed. Enjoy!

  2. Does the JSON import handle links between issues (such as 'Duplicate', 'Relates to', etc.)?

  3. Thanks for the JSON file example - it's a very helpful illustration. If it's not too much to ask, could we also see the syntax for custom fields and attachments?

    1. Updated with custom fields example.

      Attachments aren't supported just yet, but you can expect that they are on-line soon. I have them quite high on my list. I will post updates once they are ready.

      1. Pawel's comment (Aug 15, 2012) suggests that exporting attachments is indeed unsupported, but the import should work - is that not correct?

        1. Sorry for suggesting that, attachments for JSON are not supported yet for import or export.

          1. No problem Pawel, thanks for clarifying. Thanks for your great work, guys - this plugin is very useful (and a real time saver) and the example JSON snippet makes it much easier to figure out the right input format.

  4. Anonymous

    Will support for comments be implemented anytime soon?

    Right now we seem to have no way to import tickets WITH comments from an old JIRA instance (4.2) to a newer version (5.1). XML export in 4.2 seems possible and does include the comments, we can convert it to JSON if needed, but right now we don't see a way to include comments in the JSON format supported.

    1. Comments are already supported. Here's a sample json with comments:

       Expand source
      1. Anonymous

        Cool! Thanks Pawel!

  5. Anonymous

    I'm having trouble getting the value of the assignee field to be applied.  I've even tried adding a history element to reassign the new issue.  Anyone else seeing this or know a workaround?

    1. Please post your problem description on http://answers.atlassian.com with a sample JSON file that doesn't work for you. Please add "import" tag to it. assignee need to be an existing username from the destination JIRA. If it doesn't exist you can first refer it in users section in JSON file so it will be created before the import.

  6. Anonymous

    Hi,

    Can we import type of issues with json ?

    Thanks.

    1. Yes, you can with "issueType" : "Bug"

  7. Anonymous

    The export is only running as admin, It should be bossible for any user

    1. Please raise an issue for this at https://studio.atlassian.com/browse/JIM

  8. What format should the dates be in? I assume "P-3D" is a relative format? How would I provide an absolute format with a timezone? 

    1. Good question. This is hard to work out without docs

      1. This format also worked for me "2013-01-22T23:58:16Z"

    2. This SimpleDateFormat worked in my case: "yyyy-MM-dd'T'HH:mm:ss.SSSZ" (example output: "2012-08-31T15:59:02.161+0100").

  9. I tended to use a unix timestamp, e.g.:

    { created: 1234567890 }

  10. Worth noting that lowercase status "open" vs "Open" will result in a mysterious Null Pointer Exception.

  11. How does the JSON importer deal with duplicates?

  12. Just to help dummies like me, to export issues you should enable 2 modules in this plugin.

  13. Anonymous

    where can I get the syntax for custom field types?

    1. You have it in the example: 

      Field Type you can guess from Custom Fields configuration page (investigate the source HTML), field value is something specific to each custom field, you can inspect Edit Issue page's HTML for that.

      Or you can just export issue (having all custom fields set) to JSON and then examine the output. That's also another clue.

      1. Hi Pawel,

        Can we get the list of possible values for the customfieldtypes somewhere in this document? Not sure what you mean by guessing from the custom fields configuration page. Could you give us an example?

        Thank you

        Bhushan

        1. Field typeValue
          Select listcom.atlassian.jira.plugin.system.customfieldtypes:select
          Number fieldcom.atlassian.jira.plugin.system.customfieldtypes:float
          Text fieldcom.atlassian.jira.plugin.system.customfieldtypes:textfield
          Date pickercom.atlassian.jira.plugin.system.customfieldtypes:datepicker
          User pickercom.atlassian.jira.plugin.system.customfieldtypes.userpicker
          Text areacom.atlassian.jira.plugin.system.customfieldtypes:textarea
  14. I prefer this importer greatly above the CSV import, it's far more flexible and you can't import everything with the CSV.

    It could use some more love though:

    • Better feedback instead of a java traceback
    • Better documentation (some fields are a pain)
    • REST call for this (it's a pain todo import attempts, I've automated this with Selenium, but the HTML can ofcourse change (and the OnDemand is different from the offline version))
    • REST call to bulk delete (to revert your last import)
    • Export function in the OnDemand version
    • Better Export function (if you export to json you miss a lot of information you can put in the json)
    • More complete functionality as regards to plugins. Greenhopper related data is impossible to import, and the rest api doesn't allow you to set a completion date
    • The update field sometimes refuses to be set to the real value, and just flips over to "today"

    One hint for people trying to enter estimates in their import:

    1. That's handy, and +1 on the need for better documentation.

    2. Thanks for the feedback Paul. We'll add those to our backlog and prioritise accordingly.

      1. Anonymous

        Nice too hear this is still under improvement!

  15. Some other problems I run into:

    • when you upload bogus json (because you are guessing the format) it fails that import, but repeats the previous upload (Weird?). easiest way to reproduce this: upload valid json, then upload something else (image file or something)
    • When you have a big import (was doing a big (hopefully final import) to Jira, there is a max around 50mb, you get a java heap space error (at least on the on demand), so make code to split your import, and automate the upload with selenium!
  16. Can anyone provide some examples of history import that is NOT status data? For example, when updating the summary or description, what are the fields in the item? I've tried using "fromString" and "toString", but I'm getting errors (NPE) so I'm trying to guess as to what the problem might be.

    1. Please raise an issue at http://ecosystem.atlassian.net/browse/JIM attach your sample JSON, details of the exception (stack trace) and I'll see what's going on. I guess either from and to are also required or your file syntax is broken.

      1. I figured out the issue. The "to" and "from" attributes seem to be required. I have things working for a "summary" update for example if I set "to" and "toString" to the same new value, as well as the "from" and "fromString" to the old value. It seems that for a history item, you need all four item, "to", "toString", "from", and "fromString". If any of those are missing, or any of them are null or empty string, an exception is thrown.

  17. Thanks for the attachment example. But was does "attacher" mean? The name would suggest it is the name of the person that created the attachment, but the data in the example is a relative date. Is that incorrect, or is my understanding of the field's use wrong?

    1. There was an error in the sample, I've corrected it. You're right that "attacher" should be a user name.

  18. Please update your links example - you must use issue-keys to link those together.

    Are Web Links also supported? And if yes - what tag must be used?

    1. Web links are not supported. You can use either issue keys or external ids, but when you use latter the search scope is defined by the projects you listed in the JSON file (so if you don't list any projects no issues are searched for external issue id).

  19. Why Web link is not supported?  It seems relatively simple comparing to issue link.  When will it be supported?  It is an incomplete data migration for us without the web link support.  Thanks

  20. how to import comments for issue?

  21. found after a commentary. please include this example in the doc
    "comments": [
                            {
                                "body": "This is a comment from admin 5 days ago",
                                "author": "admin",
                                "created": "P-5D"
                            },
  22. Is it possible to specify visibility on issues and/or comments using the JSON importer ? I'd want to limit visibility of some comments and issues to specific groups.

    1. No, that's not possible. Please raise an issue at https://ecosystem.atlassian.net/browse/JIM

  23. Is it possible to import worklog entries using JSON importer? If so, what would the syntax be?

    1. Yes, that's possible, put worklogs into issue to set them, like:

      1. When I register worklog-entries as per the above, the registering itself is recorded as of the time the JSON-import is run. How can I record the original (correct) date of the entry? For example, here is the information as recorded in the in the XML-dump of the JIRA instance:

            <Worklog id="10043" issue="10027" author="schXXg" body="Worked my feet off"
        created="2005-09-27 12:17:04.54" updateauthor="scXXng" updated="2005-09-27 12:17:04.54"
        startdate="2005-09-27 12:17:04.54" timeworked="1800"/>
        How would I transfer the updatedcreated, and updateauthor fields via JSON? Thanks!
        1. Unfortunately it's not possible currently. The only supported values of worklogs are "author", "comment", "startDate", "timeSpent". I've created an improvement request  JIM-1221 - Allow users to specify "created" and "updated" values for Worklogs in JSON Importer Open , but I'm not sure if we are going to implement it, because JIRA automatically sets "created" and "updated" to current date.

  24. Hi! Is there any way to ask JIRA to render the externalId not merely as a string, but as a "clickable" one – with the link pointing outside?

    1. No there's no way. When using a different importer there's External System URL field created in addition which supports full URL to the issue. JSON doesn't support that yet.

      But you can do this manually - create a custom field of type url and assign a value for it in each imported issue. There's an example of setting custom field values above.

  25. Must the files for the local attachments (with the scheme of file://.... ) be present on the Jira-server at the time of the JSON-import run?

    1. Yes, they need to be present because they'll be copied inside JIRA directory during the import.

      1. Then it is a bug, I think, that not even a warning is raised, when an attachment listed in the JSON can not be found at import time... Instead, all such attachments are quietly ignored.

        Also, perhaps the above example of JSON can be expanded to show, how a local file is to be referenced – and where exactly these files are expected.

        1. Yes, there's a bug for this. The message will be logged only to atlassian-jira.log unfortunately.

          1. Thanks. I'd just ask you to make sure, the full path of the file, that can not be found during import, be logged – to help figure out the expexted location (smile)

        2. Yes, there's a bug for this. The error message will be logged only to atlassian-jira.log unfortunately.

  26. Can a project's metadata (like associated workflows, schemas, etc.) be specified the same way – via JSON (or, perhaps, via XML)? Thanks!

    1. No, that's not supported by JIRA Importers Plugin, there's no support for schemes (you can associate workflow scheme when importing only).

  27. How would I import a custom field of type com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes ? How do I specify all of the possible values, when defining the field itself and the actual values (a subset of the all, obviously), that a particular issue has?

    1. This is currently unsupported.  JIM-787 - User should be able to import to any custom field type Closed

  28. Anonymous

    So I have a cURL command that updates a comment on an existing ticket in the format 

    curl -D- -u "$jiraUsername":"$jiraPassword" -X POST --data @jiracomment.json -H "Content-Type: application/json" https://jira.local.com/rest/api/2/issue/ticketnum/comment

     

    Can I specify where the jiracomment.json file is located from in the cURL? For example, 

    curl -D- -u "$jiraUsername":"$jiraPassword" -X POST --data /your/homedir/@jiracomment.json -H "Content-Type: application/json" https://jira.local.com/rest/api/2/issue/ticketnum/comment

     

    How do I specify where that file is if I want to create it at a different time and store it in a specific place?

     

    Thanks!

    1. Hi,

      I've noticed that your problem is not connected to JIRA or Rest or JSON Importer, please next time use: https://answers.atlassian.com

      You have misplaced '@' in you second POST request, it should be in the beginning of your file path:

      curl -D- -u "$jiraUsername":"$jiraPassword" -X POST --data @/your/homedir/jiracomment.json -H "Content-Type: application/json" https://jira.local.com/rest/api/2/issue/ticketnum/comment
  29. Anonymous

    Is there a way to perform an import from command-line, rather than through the awkward web-interface? I have shell-access to the box, where JIRA is running? Ideally, I'd like to be able to load multiple projects at a time even, but that's not a requirement... Thanks!

  30. Hi

    i am at the moment testing with the JSON importer.

    Question: Is there a possibility to specify a charset like iso-8859-2 ? the predefined charset does not work with special characters

    1. Please use UTF-8 for you file and you'll be able to import anything.

  31. is it possible to set the Epic Link from JIRA Agile when creating a task?

    I have an epic in the project and what to create a lot of of tasks and also set the epic link for this tasks to the epic, so that the appear under "Issues in epic".

    In my project "epic link" is "customfield_10800" but

    "customfield_10800" : "NW-889" does not work for me (Unrecognized field "customfield_10800")

    1. Sorry but Epic Link custom field type is not currently supported.

  32. Anonymous

    I been playing with this plug-in and it's working great but I need more History samples. Can you please point me to one?

  33. We explicitly create all users via JSON as "inactive":

            {
                "name": "flast",
                "fullname": "First Last",
                "active": false
            }

    However, all such users show up as active in both the GUI and the cwd_users-table in the database. Is this a known problem, or am I doing something wrong? Thanks!

    1. Seems like a bug, the field is ignored internally, please raise an issue at http://ecosystem.atlassian.net/browse/JIM

      1. Ticket JRA-35556 created. Meanwhile, how do we fix the problem? Can I just UPDATE the active field in the cwd_user-table, or is there more to it?

        1. Yes, that should be enough, you may need to restart JIRA thought - users are cached.

          1. When the project being imported attempts to create users, that already exist (in the directory 1), it is not normally a problem – the importer skips such users as expected, without making a fuss.

            However, if those existing users are marked as inactive in the database, as we discussed above in this subthread, the importer chokes with a message about being unable to create the user or some such...

  34. It would appear, the cross-project linking of issues is broken... For example, an issue in our legacy bug-tracking system had links from issues in both its own project and others. The links with issues in the same project got created nicely.

    Attempts to create a link with an issue in a different project, however, fails... Here are the relevant log-entries:

    The issue is first imported – among many others.  HL1723 becomes HLT-1711:

    ...

    2013-11-16 12:52:27,733 INFO - Importing issue: ExternalIssue{externalId=HL1722, summary=..., issueType=Defect}
    2013-11-16 12:52:28,095 INFO - Importing issue: ExternalIssue{externalId=HL1723, summary=..., issueType=New Feature}
    2013-11-16 12:52:29,267 INFO - Importing issue: ExternalIssue{externalId=HL1724, summary=..., issueType=Defect}
    ...

     

    The links from two other issues under HLT are linked to it:

    ...
    2013-11-16 13:00:08,693 INFO - Linking 'HLT-1562' and 'HLT-1711' as relates to
    2013-11-16 13:00:09,022 INFO - Created link 'relates to' between HLT-1562 and HLT-1711
    2013-11-16 13:00:38,577 INFO - Linking 'HLT-1650' and 'HLT-1711' as relates to
    2013-11-16 13:00:38,807 INFO - Created link 'relates to' between HLT-1650 and HLT-1711
    ...

    Finally, the failed attempt to link to the same issue from a different project:

    2013-11-16 14:08:27,351 ERROR - Unable to link issue from RSG2345 to HL1723 with link named 'relates to': Cannot find imported issue key for external id 'HL1723'

    Is this supposed to work? Am I doing something wrong, or is this another evidence of JSON-importer's beta-status?

    Thanks!

    1. Currently JIM cannot link two issues from two different projects if they are not present in the single import (in your case single JSON file). If you would try to import project 'RSG' and 'HL' via single JSON file - everything should be working correctly.

      However, I think it's not correct and intuitive behaviour, so I've created an issue for that: https://ecosystem.atlassian.net/browse/JIM-1094

      1. Some of our projects are so large, I have to split them into multiple uploads already – with 900 issues in each – to stay under the limit on attachment sizes (which we already bumped from the default 10Mb to 20Mb). I wish I could upload the JSON files to the server first – and then run the importer locally from command-line instead of via browser (the browser-method suitable only for small imports).

        Combining multiple projects into one JSON is completely unrealistic for us currently...

        1. As a workaround you can provide JIRA Issue key instead of External ID. E.g:

  35. How does the custom field types work for multi-select fields?

    com.atlassian.jira.plugin.system.customfieldtypes:float

    Could you please let me know, what are the other types available and where is this information available?

  36. We found several problems with the issue-migration – about 20% of the tickets were not imported right due to a programming error. Is there any way to reimport just them – without destroying all the changes done to other tickets in the same project?

    Normally, when I try to load an issue with an externalId, that already exists, that issue is simply skipped. Is there any way to force the issue to be dropped and re-imported instead?

    1. If I understand your question correctly, you would like to update(change) existing issues?

      JIM is not updating issues if they are identified by ExternalId, instead you need to provide a JIRA Issue Key. Example:

      Import file fragment:

      To update this issue you need to remove the externalId declaration and place an Issue Key (I assume that my issue CCC1 was imported as CCC-1)

      When you update an existing issue all specified values will be overwritten with the new values and the rest will stay unchanged. (in my case only description will be changed).

       

      1. So, using "key" instead of "externalId" I can modify existing issues en-masse? That's very good news indeed.

        I suppose, assignee- and wather-lists can be modified the same way?

        What about history of comments and status-transtions? For example, if a comment was recorded to have been made by mikhailt, can this method be used to change the attribution to tmikhail11 – or will the "new" comment be added on top of the old one?

        Likewise, if I attempt to set status of "CCC-1" from "Closed" to something custom like "Verified in QA" – will the status transition be recorded (with a possible exception raised, if the ticket's workflow does not allow such direct transitions), or will it simply replace the current status?

        1.  

          So, using "key" instead of "externalId" I can modify existing issues en-masse?

          Yes, that's correct

          I suppose, assignee- and wather-lists can be modified the same way?

          Yes, all kind of values can be updated, but you need to look out for fields which accepts multiple values e.g. "labels"/"versions" - the entire field value will be overwritten with new values. E.g:

          This will leave issue with only "3.0" fixed version. However this logic only applies for "regular fields" - fields such as "history", "comments", "voters", "watchers", "attachments" currently cannot be updated - another import would just add new values. E.g:

          This would leave issue with three watchers ("bob", "martin", "alice").

           For example, if a comment was recorded to have been made by mikhailt, can this method be used to change the attribution to tmikhail11 – or will the "new" comment be addedon top of the old one?

          As described above, a new comment would be added.

          Likewise, if I attempt to set status of "CCC-1" from "Closed" to something custom like "Verified in QA" – will the status transition be recorded (with a possible exception raised, if the ticket's workflow does not allow such direct transitions), or will it simply replace the current status?

          You can only pick status that exists in your workflow. If status "Verified in QA" exists - change would succeed - even if it's not directly possible due to workflow ("Closed" -> "Verified in QA"). The status change will be noted in "Activity" tab.

  37. Anonymous

    How can I set the project permission scheme from the JSON import?

    1. Sorry, but importing permission scheme is currently not supported.

  38. Anonymous

    Is it possible to set the issue key manually through the JSON import?  For example, if I have a Bugzilla issue with ID 12345 in the ABC project, can I create an issue in JIRA with issue key ABC-12345 via JSON?  I see that I can use the external ID field to store the old Bugzilla ID, but we would like to be able to carry the old IDs into the issue key itself.  It looks like this is possible through the regular CSV import, but, obviously, JSON import offers way more flexibility and other required functionality.

    1. Yes, by specifying "key" you can force JIM to create an issue under specified Issue Key.

      1. Anonymous

        I see "key" as a field under projects, but not under issues.  If I want to specify both the project preface part of the issue key and the actual numerical part of the issue key, is that possible as well?  Or will the number always be assigned as the next available number under the project with that key?

        1. It's not in the example, but issue also has a "key" property. Example:

          This will create for you a project with one issue "SAM-123".

          1. Anonymous

            Excellent!  That's great!  It may be in the comments above, but is there a document that lists all of the possible properties for each section?

            1. Unfortunately, this the only documentation for JSON Importer, pretty much all fields (now with "key") are present in the example - this is still a beta importer, so it may still "evolve".

              If you come across any bug during your import, please contact our support team or open an issue under JIM project (https://ecosystem.atlassian.net/browse/JIM) - we would really appreciate your feedback.

              1. I keep wanting to use the JSON Importer but it's hard without better documentation of what can be done. How long has it been in beta now?

                1. I think it's already a year or two... It's high time to release and document a non-beta version, but it's not planned for any time soon.

                  1. I agree it's high time to release and document. It's not like it's gmail or anything

  39. Anonymous

    What happens if you try to add a link to an external ID that doesn't exist in JIRA yet?  For example, you are importing an issue with dependency links, but you haven't imported the issues that are linked to yet.  Can you still ink to the other issues?  If so, will the links become "live" once the other issues have been imported?

    1. JIM is trying to link issues immediately - if one of the required issues is missing, link will not be saved in any way. If you cannot import all issues in one import, I suggest that you first import all of your issues (in one or many imports) and then do a separated import with links only.

      1. Anonymous

        Sounds good.  Thanks for the quick reply!  If links are done in a separate import, can external IDs still be used or should JIRA issue keys be used?

        Also, does the same go for users?  That is, if I try to set the "reporter" property to "user123" and JIRA doesn't know anything about user123, will that part of the issue be skipped or, worse, will the issue not import at all?  Is it correct that if JIRA already has user123 as a user, I don't need to include that user in the "users" section of the JSON document?  And finally, if JIRA knows that user123 has e-mail address user123@gmail.com and I put "user123@gmail.com" in the "reporter" field for the issue, will JIM be able to link up to the correct user? (Apologies, I'm totally new to JSON as of today!)

        1. If links are done in a separate import, can external IDs still be used or should JIRA issue keys be used?

          You can use either, but please note that we still have a reported bug for importing links by External ID ( JIM-1094 - Allow to link issues from two different imports Open ) - use Issue Keys if possible.

          Also, does the same go for users?  That is, if I try to set the "reporter" property to "user123" and JIRA doesn't know anything about user123, will that part of the issue be skipped or, worse, will the issue not import at all?

          It really depends on field-type. If field is required (e.g."reporter") JIM will pick current logged in user (the one which performs import) if the one specified in JSON file cannot be found. If it's optinal, it would simply be skipped.

           Is it correct that if JIRA already has user123 as a user, I don't need to include that user in the "users" section of the JSON document?

          Yes, that's correct.

           And finally, if JIRA knows that user123 has e-mail address user123@gmail.com and I put "user123@gmail.com" in the "reporter" field for the issue, will JIM be able to link up to the correct user?

          No - this field is only checked with usernames.

          1. Anonymous

            Is "name" in the "users" section the same as the JIRA username?  Is "email" an available property as well?

            1. Yes and yes. Here is a full example of User object:

              1. Anonymous

              2. Can custom project-specific groups be created with the same ease?

                "groups" : {

                ....

                }

                1. There isn't any distinct element for groups. JIM checks is specified group exists during user import - if specified group does not exist, JIM creates it on the spot. Example:

                  After this import, "my-custom-group" will be created if it doesn't exist before.

                  1. All our active users come from Active Directory – not Jira's own directory. But the groups are Jira's only. Can I create such groups without also creating users?

                     

                    1. Unfortunately no - groups are only created during user import. As a workaround you can "import" some mockUser which will belong to all groups that you would like to import. After import you can delete this user and all of his groups will stay in JIRA.

  40. Setting the attachment uri to "C:/attachments/bug.png" results in

    java.io.IOException: The filename, directory name, or volume label syntax is incorrect

    Checked that the file exists. How do I point to a file on the system where JIRA is installed?

    1. JIRA CSV and JSON Importer supports only file import via URIs. That means you can specify attachments in two different ways:

      • HTTP address: e.g. http://my.page.com/attachment.png
      • file protocol e.g: file:///folder/attachment.png - but please note that the specified path must be a subdirectory of$JIRA_HOME/import/attachments due to security reasons (We cannot allow user, even sysadmin, to access any file from the server where JIRA instance is hosted). - In my example I would have to put attachment.png under path: $JIRA_HOME/import/attachments/folder/attachment.png
  41. Anonymous

    Is it possible to provide a description for components like we do for projects?

    1. Anonymous

      In that same vein, what about assigning owners to components?

      1. Components can be specified in JSON file in two different ways: by providing only its name or an object.

        Unfortunately you cannot specify a "Default Assignee" for Component - JIM will always create new Component with "Default Assignee" switched to "Project Default".

  42. Anonymous

    I am trying to import a project definition without any issues, just to test that I'm able to import a basic project.  I've checked and rechecked my import file and it looks ok to me, but I'm getting an error that is causing the importer to stop immediately.  The error looks like this:

     

    2013-12-16 15:04:12,675 ERROR - Unexpected failure occurred. Importer will stop immediately. Data maybe in an unstable state
    java.lang.Exception: Unable to import Project ExternalProject[jiraId=<null>,id=<null>,externalName=<null>,name=Sample Import,key=SAMPLE_IMPORT,url=<null>,lead=jmoszko,description=The Sample Import project,projectCategoryName=<null>,avatarUrl=<null>,assigneeType=3,versions=<null>,components=[com.atlassian.jira.plugins.importer.external.beans.ExternalComponent@5bd2d7[id=<null>,name=comp1,lead=<null>,description=<null>], com.atlassian.jira.plugins.importer.external.beans.ExternalComponent@6f3e29[id=<null>,name=Component 2,lead=<null>,description=<null>], com.atlassian.jira.plugins.importer.external.beans.ExternalComponent@15a003a[id=<null>,name=Component 1/2,lead=<null>,description=<null>]],issues=<null>,workflowSchemeName=<null>]
    	at com.atlassian.jira.plugins.importer.imports.importer.impl.DefaultJiraDataImporter.importProject(DefaultJiraDataImporter.java:699)
    	at com.atlassian.jira.plugins.importer.imports.importer.impl.DefaultJiraDataImporter.doImport(DefaultJiraDataImporter.java:374)
    	at com.atlassian.jira.plugins.importer.imports.importer.impl.ImporterCallable.call(ImporterCallable.java:26)
    	at com.atlassian.jira.plugins.importer.imports.importer.impl.ImporterCallable.call(ImporterCallable.java:15)
    	at com.atlassian.jira.task.TaskManagerImpl$TaskCallableDecorator.call(TaskManagerImpl.java:374)
    	at java.util.concurrent.FutureTask$Sync.innerRun(FutureTask.java:303)
    	at java.util.concurrent.FutureTask.run(FutureTask.java:138)
    	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:441)
    	at java.util.concurrent.FutureTask$Sync.innerRun(FutureTask.java:303)
    	at java.util.concurrent.FutureTask.run(FutureTask.java:138)
    	at com.atlassian.jira.task.ForkedThreadExecutor$ForkedRunnableDecorator.run(ForkedThreadExecutor.java:250)
    	at java.lang.Thread.run(Thread.java:662)
    Caused by: com.atlassian.jira.plugins.importer.external.ExternalException: Unable to create project: ExternalProject[jiraId=<null>,id=<null>,externalName=<null>,name=Sample Import,key=SAMPLE_IMPORT,url=<null>,lead=jmoszko,description=The Sample Import project,projectCategoryName=<null>,avatarUrl=<null>,assigneeType=3,versions=<null>,components=[com.atlassian.jira.plugins.importer.external.beans.ExternalComponent@5bd2d7[id=<null>,name=comp1,lead=<null>,description=<null>], com.atlassian.jira.plugins.importer.external.beans.ExternalComponent@6f3e29[id=<null>,name=Component 2,lead=<null>,description=<null>], com.atlassian.jira.plugins.importer.external.beans.ExternalComponent@15a003a[id=<null>,name=Component 1/2,lead=<null>,description=<null>]],issues=<null>,workflowSchemeName=<null>]
    	at com.atlassian.jira.plugins.importer.managers.CreateProjectManagerImpl.createProject(CreateProjectManagerImpl.java:85)
    	at com.atlassian.jira.plugins.importer.imports.importer.impl.DefaultJiraDataImporter.importProject(DefaultJiraDataImporter.java:682)
    	... 11 more
    Caused by: com.atlassian.jira.exception.CreateException: You must specify a unique project key, at least 2 characters long, containing only uppercase letters.
    	at com.atlassian.jira.plugins.importer.managers.DefaultCreateProjectHandler.createProject(DefaultCreateProjectHandler.java:28)
    	at com.atlassian.jira.plugins.importer.managers.CreateProjectManagerImpl.createProject(CreateProjectManagerImpl.java:70)
    	... 12 more

     

    I'm having trouble making sense of this.  Any ideas?

    1. You have picked an incorrect Project Key ("key" field) - as it's written in your exception:

      You must specify a unique project key, at least 2 characters long, containing only uppercase letters.

      Please remove an underscore '_' character from your project key. (Pick for example "SAMPLE" instead of "SAMPLE_IMPORT")

      1. Anonymous

        Ah, I see.  I was misled into thinking underscores and any length key would work by this page:

        Changing the Project Key Format

        Thanks for the clarification!

  43. Anonymous

    Some of the text I need to import for fields like "summary" and "description" have quotation marks and curly braces.  This seems to be throwing a "Failed to create data bean" error.  Is it possible to get around this and still keep the characters from my original text?

    1. Input needs to be a valid JSON file (http://www.json.org/). You will need to escape quote signs:

  44. How do I set remaining estimate on an issue?

    1. You just need to set some additional values in an issue object. Here is a full example of an issue with Time Tracking related data.

      Values "originalEstimate", "timeSpent", "estimate" needs to be in Period format (Format ISO_8601 - Durations). "startDate" accepts both - DateTime format and Period.

      Please remember to have Time Tracking enabled in JIRA before the import, otherwise this data will be ignored.

  45. Anonymous

    What is the simplest way to import a project (using json) with statuses that are not in the default workflow?

     

    1. If your project does not yet exist you can specify Workflow Scheme Name in project object and then just fill desired status name in issue. Example:

      If you are importing to the existing project than you can skip the "workflowSchemeName" and just specify "status" property in issue object.

      1. Anonymous

        Thank you. It works well (smile)

      2. Anonymous

        Thank you. It works well (smile)

  46. It is my understanding that I can import Agile stories just like JIRA issues but how do I import sprints? Is it possible?

    1. It's possible to assign issue to sprint, but it's currently really limited - You can only assign issue to an existing sprint and only via SprintID ( JIM-1091 - Allow user to import GreenHopper Sprints via CSV Reopened ).

      To do that you need to add additional Custom Field definition in your issue. Example:

  47. Some issues need to have their "environment" set. Is it as simple as adding:

    "environment": "......"

    next to summary and description, etc. or is there more to it?

    1. Yes, it's that simple. Putting "environment" property in issue object is enough.

  48. How can issue-links of the type {{jira_subtask_link}} be created? When I try to create them as usual:

            {
                "name": "jira_subtask_link",
                "sourceId": "XYZ-98",
                "destinationId": "XYZ-102"
            },

    the import works, but all issues with such substasks are then rendered with exceptions, because there are no sequence-numbers – see JRA-34729. Trying to add a sequence value:

     

            {
                "name": "jira_subtask_link",
                "sourceId": "XYZ-98",
                "destinationId": "XYZ-102",
                "sequence": 0
            },

    results in an error during import:

     

    java.lang.RuntimeException: org.codehaus.jackson.map.exc.UnrecognizedPropertyException: Unrecognized field "sequence" (Class com.atlassian.jira.plugins.importer.external.beans.ExternalLink), not marked as ignorable
     at [Source: java.io.StringReader@193fb046; line: 1, column: 96] (through reference chain: com.atlassian.jira.plugins.importer.external.beans.ExternalLink["sequence"])
    	at com.atlassian.jira.plugins.importer.sample.SampleDataImporterImpl.parseSampleData(SampleDataImporterImpl.java:63)
    	at com.atlassian.jira.plugins.importer.imports.json.JsonImporterController.createDataBean(JsonImporterController.java:74)
    	at com.atlassian.jira.plugins.importer.web.ImporterLogsPage.doImport(ImporterLogsPage.java:84)
    	at sun.reflect.GeneratedMethodAccessor3287.invoke(Unknown Source)

    ......

    Perhaps, the importer should simply do its own resequencing? Or allow the desired sequence number to be specified... Please, advise!

    1. I cannot reproduce that on JIRA 6.1+. Both of these links were created correctly:

      Could you share with me your JIM and JIRA version?

      1. As I said – the links are, indeed, created by the importer without a hitch. But, when you then go view the main ticket (which has the newly created subtasks), the page will show a long-winded Java-exception.

        When I searched for that exception online, I found, I was not alone with this problem – bug JRA-34729 has the same details.

        I'm using JIRA-6.1.7 with whatever importer plugin, that comes with that. All our plugins were updated to the latest versions during the recent upgrade of JIRA itself (from 6.0.6 to 6.1.7).

        1. I've investiagted this problem and you are right Mikhail, that's a bug in our JSON Importer. We will fix that and add support for sequence under this issue:  JIM-1039 - Specify Link Sequence for Sub-task on JSON Import Closed

          However, I was able to reproduce this bug only for "jira_subtask_link". If you would change it to "sub-task-link", everything should be working correctly - issue page is rendered correctly.

          But please note that this link works in the other direction! "destinationId" points to Parent Issue and "sourceId" points to Subtask.

          1. Thanks for the confirmation, Przemyslaw. Yes, I can easily rename "jira_subtask_link" into "sub-task-link", when generating the JSON files. But will that still create the same relationship underneath – or will it be subtly different in any way? We are importing from one JIRA-instance to another this time and would like the result to match the original as close as possible...

            Thanks!

            Update... I just tried importing several links this way – renaming the relationship and reversing the source and destination. This failed with the following message:

            • Issue 'EXTRL-11' is not of a sub-task type (Task). It will NOT be a sub-task of the issue 'EXTRL-6'
            • Issue 'EXTRL-12' is not of a sub-task type (Task). It will NOT be a sub-task of the issue 'EXTRL-6'
              .....

            All three of the tickets mentioned above (EXTRL-6, 11, and 12) are all of type "Task".

            If you can think of a way to import the jira_subtask_link relationship cleanly today, please, provide an answer to my question on answer.atlassian.com. Thanks!

  49. Anonymous

    We've completed a large import of issues, but we realized that there are some custom fields we missed in the initial import.  I tried creating a new JSON file that has just the project and key information for these issues along with the new missing custom field, but the importer simply says that all of the issues were skipped because they already exist.  Is there a way to add these custom fields to the existing issues or do I need to delete everything and reimport?

    1. Hi, JIM can identify issues in two ways: Via "externalId" or "key" (Issue Key) and both are working differently. First JIM tries to find issue via "externalId" - if it founds one than he assums that issue already exists and changes nothing. If "externalId" was not specifed or issue with that ID was not found, then JIM tries to match issue by "key". If it found a matching Issue Key, then JIM tries to update issue.

      In other words: If you would like to update issues, you need to specify a matching "key" (Issue Key) in the JSON file for each issue. (I also mentioned that in one of the other comments: Re: Importing Data from JSON (beta release) ).

      If you cannot change your input JSON file (from "externalId" to matching "key"), then you would need to delete everything and do reimport with correct data.

  50. Hello! Although the GHS-6995 - Greenhopper Epic fields cannot be imported to JIRA through CSV Resolved , also known as JIM-988 - Greenhopper Epic fields cannot be imported to JIRA through CSV Closed , is marked as fixed, I still have problems importing Epic-fields:

    WARN - Cannot set value for locked custom field 'Epic Status' in issue 'INS-221' because it is not applicable for issue type 'Task'
    WARN - Cannot set value for locked custom field 'Epic Name' in issue 'INS-221' because it is not applicable for issue type 'Task'
    WARN - Cannot set value for locked custom field 'Epic Colour' in issue 'INS-221' because it is not applicable for issue type 'Task'
    WARN - Cannot set value for locked custom field 'Epic Name' in issue 'INS-957' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Status' in issue 'INS-957' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Colour' in issue 'INS-957' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Name' in issue 'INS-958' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Status' in issue 'INS-958' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Colour' in issue 'INS-958' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Name' in issue 'INS-959' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Status' in issue 'INS-959' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Colour' in issue 'INS-959' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Name' in issue 'INS-960' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Status' in issue 'INS-960' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Colour' in issue 'INS-960' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Name' in issue 'INS-961' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Status' in issue 'INS-961' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Colour' in issue 'INS-961' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Name' in issue 'INS-962' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Status' in issue 'INS-962' because it is not applicable for issue type 'Defect'
    WARN - Cannot set value for locked custom field 'Epic Colour' in issue 'INS-962' because it is not applicable for issue type 'Defect'

    The JIRA-instance where I'm importing from is 6.2 (OnDemand). The target JIRA is 6.1.7 – with whatever JIM, that comes with that. Do I need a newer version of importer? How can I get that – without upgrading the rest of JIRA?

    Thank you!

    1. Hi, Custom Fields "Epic Status", "Epic Name" and "Epic Colour" are only applicable for issue type "Epic". You would need to import those issues as Epics.

      There's an existing bug in JIM / GreenHopper which allows to have some non-Epic issues with those Custom Fields, but it will be fixed in near future.

  51. Importer creates duplicate custom fields. I already have a custom field named "External Issue ID" but every time I import a new project, another field with the same name is created. How do I stop this?

    1. You must reconfigure your projects to use the correct field configuration scheme and that the field exists in this configuration

    2. That's a problem of setting Custom Field context. JIM has currently two rules while handling Custom Fields:

      • JIM creates Custom Fields only with the single-project Context (we don't want to affect any other JIRA projects)
      • JIM never extends the context of exisitng Custom Fields, so it creates a new Custom Field if there's none matching

      To workaround this you need to have a Custom Field with global project context and/or with context that includes the project which you are using for import. This can be done in settings: Issues -> Custom Fields -> click on chosen Custom Field cog -> Configure -> Edit Configuration -> Choose applicable context.

  52. I am attempting to use the JSON importer on a locally installed instance of JIRA.  When I click the submit button to start the import, I end up on a white screen and nothing seems to happen.  I've successfully used the importer on an On Demand instance in the past.

    1. Hi Jessica, it happens for all importers working under JIRA 6.2+ when you are trying to access Importer via a different URL then the one specified under System -> Settings -> Base URL. We have a reported issue for that, which we would like to fix in the next JIM release.  JIM-1251 - Redirecting to unsafe location error on JIM 6.1.1 Closed

      1. Thanks so much!  I was able to change the base url on the installed instance, which let the import go through.

  53. We are having trouble importing attachments.  We moved the files we want to attach into what we believe is $JIRA_home based on our local installation's system information.  Here is a snippet of the JSON we created to do the import:

     

    "attachments" : [
    {
    "name" : "2007-08-24_Answer_Serialization.xml",
    "attacher" : "JonC",
    "created" : "2007-08-31T14:24:27",
    "uri" : "file:///import/attachments/oldBugAttachments/1205.txt",
    "description" : "XML illustrative of Bug 22411"
    }
    ], "comments" : [

     

    The import file, which contains 1 project and 41 issues, seems to go through the import just fine, but we aren't seeing any attachments get through.  There are no warnings or errors and the log doesn't even mention the word "attachment".  Can you tell what we're doing wrong?

    1. Your JSON file seems to be ok. Please try to:

      1. Ensure that Attachments are enabled in you JIRA instance. (System -> Attachments)
      2. Enable logging for Importer: Add DEBUG logging for package "com.atlassian.jira.plugins.importer" under Logging & Profiling page.

      If after trying both hints you are still having troubles with importing your attachments and Importer and JIRA logs are still silent about it, then please open a Support Request under JIM project (https://ecosystem.atlassian.net/browse/JIM), where I would try to help you further.