Issue import and export data format

Repository administrators can import issue data into or export it from Bitbucket. Bitbucket exports and imports data using a ZIP package. For imports, this package must contain a db-2.0.json file, and if the issues had attached files, an optional attachments directory. To extract the package, use the zip command or a GUI utility such as 7-zip.

$ zip -Tv bitbucket-issues.zip 
Archive: bitbucket-issues.zip
 testing: attachments/cow_small.png OK
 testing: db-2.0.json                  OK

When using the issue tracker import/export feature to move issues from one Bitbucket repo to another, the issue IDs remain the same. However, the comment IDs, and therefore the permlinks, change. Comment IDs change because, in contrast to issue IDs, they are not local to the repo.

Certain objects, such as comments, rely on foreign keys. During an import, Bitbucket silently uses NULL to replace any foreign keys that it cannot resolve (for example, a comment that no longer exists on Bitbucket).

Finally, when you export data, Bitbucket does not export issues marked with a spam flag. When importing data from ZIP files created by third-party extensions, the standard Bitbucket spam checking applies.

Example db-2.0.json File

The db-2.0.json file specifies the following objects:

The following is an example db-2.0.json file:

{
    "issues": [
        {
            "assignee": {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
            }
            "component": null, 
            "content": "Some **issue**.", 
            "content_updated_on": "2013-03-21T03:44:04.660869+00:00", 
            "created_on": "2013-01-22T15:55:13.573339+00:00", 
            "edited_on": null, 
            "id": 1, 
            "kind": "bug", 
            "milestone": "M2", 
            "priority": "major", 
            "reporter": {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
            }, 
            "status": "resolved", 
            "title": "Test", 
            "updated_on": "2013-03-21T04:26:26.733922+00:00", 
            "version": null, 
            "watchers": [
                {
                "display_name": "Dylan Etkin",
                "account_id": "<Dylan's Atlassian account id>"
                }
                {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
                }
            ],
 			"voters": [
                {
                "display_name": "Ben Nguyen",
                "account_id": "<Ben's Atlassian account id>"
                }, 
                {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
                }
            ]
        }
    ], 
    "comments": [
        {
            "content": null, 
            "created_on": "2013-01-26T01:00:55.994000+00:00", 
            "id": 388, 
            "issue": 1, 
            "updated_on": null, 
            "user": {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
            }
        }, 
        {
            "content": "This is now fixed with unicode: Erik van Z\u0133st", 
            "created_on": "2013-03-21T04:26:26.749032+00:00", 
            "id": 396, 
            "issue": 1, 
            "updated_on": null, 
            "user": {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
            }
        }
    ], 
    "attachments": [
        {
            "filename": "cow_small.png", 
            "issue": 1, 
            "path": "attachments/cow_small.png", 
            "user": {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
            }
        }
    ], 
    "logs": [
        {
            "changed_from": "/evzijst/bitbucket/issue-attachment/1/evzijst/bitbucket/1359162055.6/1/cow_small.png", 
            "changed_to": "cow_small.png", 
            "comment": 388, 
            "created_on": "2013-01-26T01:00:55.993900+00:00", 
            "field": "attachment", 
            "issue": 1, 
            "user": {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
            }
        }, 
        {
            "changed_from": "new", 
            "changed_to": "resolved", 
            "comment": 396, 
            "created_on": "2013-03-21T04:26:26.814711+00:00", 
            "field": "status", 
            "issue": 1, 
            "user": {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
            }
        }
    ], 
    "meta": {
        "default_assignee": {
                "display_name": "Erik Van Zijst",
                "account_id": "<Erik's Atlassian account id>"
        }, 
        "default_component": "ui", 
        "default_kind": "bug", 
        "default_milestone": null, 
        "default_version": null
    }, 
    "components": [
        {
            "name": "api"
        }, 
        {
            "name": "ui"
        }
    ], 
    "milestones": [
        {
            "name": "M1"
        }, 
        {
            "name": "M2"
        }, 
        {
            "name": "M3"
        }
    ], 
    "versions": [
        {
            "name": "0.9"
        }, 
        {
            "name": "1.0"
        }
    ]
}

Issues

The db-2.0.json file contains an issues array. That array contains one more issue objects each of which has the following fields:

Field	Max Length	Description
assignee		An object value containing a Bitbucket display name and the user's Atlassian account_id - for example: `1 2 3 4{ "display_name": "Erik Van Zijst", "account_id": "<Erik's Atlassian account id>" }` This value can be null.
component	128	A string value containing a component name. The value must be declared in a components section (for example, "api"). This value can be null.
content		A string value containing the issue's description. This value can be null. The content is expected to be in Markdown syntax, just like it would be entered when creating/editing an issue. Note that Bitbucket used the Creole markup format before 04 Oct 2012, so if the content_updated_on field is before that date, content is expected to be Creole syntax.
content_updated_on		The timestamp of the most recent change to the issue's description. A non-null string in ISO 8601 datetime format (for example, "2013-03-21T03:44:04.660869+00:00").
created_on		A non-null string in ISO 8601 datetime format (for example "2013-01-22T15:55:13.573339+00:00").
edited_on		The timestamp of the most recent change to the issue's description (deprecated). A string in ISO 8601 datetime format (for example "2013-01-22T15:55:13.573339+00:00"). This value can be null.
id		A non-null, unique positive integer representing the issue identifier.
kind	16	A non-null string containing one of the following values: `1"bug""enhancement""proposal""task"`
milestone	128	A string value containing a milestone name. The value must be declared in a milestones section (for example, "M2"). This value can be null.
priority	16	A non-null string containing one of the following values: "trivial" "minor" "major" "critical" "blocker"
reporter		An object value containing a Bitbucket display name and the user's Atlassian account_id - for example: `1 2 3 4{ "display_name": "Erik Van Zijst", "account_id": "<Erik's Atlassian account id>" }` This value can be null.
status	16	A non-null string containing one of the following values: "new" "open" "resolved" "on hold" "invalid" "duplicate" "wontfix"
title	255	A non-null string representing the issue title. This string has a 255 chars limit.
updated_on		The timestamp of the most recent change to the issue's state. This includes everything from assignee to status. A string in ISO 8601 datetime format (for example, "2013-04-21T03:12:04.660869+00:00"). This string cannot be null.
version	128	A string value containing a version name. The value must be declared in a versions section (for example, "1.0"). This value can be null.
watchers		A list of objects containing display names and account IDs. For example: `1 2 3 4 5 6 7 8 9 10[ { "display_name": "Erik Van Zijst", "account_id": "<Erik's Atlassian account id>" }, { "display_name": "Rani Jaiswal", "account_id": "<Rani's Atlassian account id>" } ]` This list can be empty.
voters		A list of objects containing display names and account IDs. For example: `1 2 3 4 5 6 7 8 9 10[ { "display_name": "Brandon Pearson", "account_id": "<Brandon's Atlassian account id>" }, { "display_name": "Rani Jaiswal", "account_id": "<Rani's Atlassian account id>" } ]` This list can be empty.

comments

The db-2.0.json file contains an comments array. That array contains one more comment objects each of which has the following fields:

Field	Required / non-null	Max Length	Description
content			A string value containing the comment's content. This value can be null. The content is expected to be in Markdown syntax, just like it would be entered when creating a comment. Note that Bitbucket used the Creole markup format before 04 Oct 2012, so if the comment date is before that date, content is expected to be Creole syntax.
created_on			A non-null string in ISO 8601 datetime format (for example, "2013-01-26T01:00:55.994000+00:00")
id			A non-null integer that is unique among the comments array.
issue			A non-null, integer representing a foreign key to an existing issue.id in the issues array.
updated_on			A string in ISO 8601 datetime format (for example, "2013-04-21T03:12:04.660869+00:00"). This string can be null.
user			An object value containing a Bitbucket display name and the user's Atlassian account id_ - for example: `1 2 3 4{ "display_name": "Erik Van Zijst", "account_id": "<Erik's Atlassian account id>" }` This value can be null.

attachments

The db-2.0.json file contains an attachments array. That array contains one more attachment objects each of which has the following fields:

Field	Max Length	Description
filename	255	A non-null string that is the name of an attachment as it appears on the issue tracker (for example, "cow_small.png").
issue		A non-null, integer representing a foreign key to an existing issue.id in the issues array.
path		A non-null string that contains the location of a file in the ZIP.
user		An object value containing a Bitbucket display name and the user's Atlassian account_id - for example: `1 2 3 4{ "display_name": "Erik Van Zijst", "account_id": "<Erik's Atlassian account id>" }` This value can be null.

components

The db-2.0.json file contains an components array. That array contains one or more component objects each of which has a single name field. The name must be a string (max 128 characters) that is unique and non-nullable (for example, api).

milestones

The db-2.0.json file contains an milestones array. That array contains one or more milestone objects each of which has a single name field. The name must be a string (128 characters max) that is unique and non-nullable (for example, M2).

versions

The db-2.0.json file contains an versions array. That array contains one or more version objects each of which has a single name field. The name must be a string (128 characters max) that is unique and non-nullable (for example, 1.0).

Field	Max Length	Description
default_assignee		An object value containing a Bitbucket display name and the user's Atlassian account_id - for example: `1 2 3 4{ "display_name": "Erik Van Zijst", "account_id": "<Erik's Atlassian account id>" }` This value can be null.
default_component	128	A string value containing a component name. The value must be declared in a components section (for example, "api"). This value can be null.
default_kind	16	A non-null string containing one of the following values: `1"bug""enhancement""proposal""task"`
default_milestone	128	A string value containing a milestone name. The value must be declared in a milestones section (for example, "M2"). This value can be null.
default_version	128	A string value containing a version value. The value must be declared in a versions section (for example, "1.0"). This value can be null.

logs

The db-2.0.json file contains an logs array. That array contains one more log objects each of which has the following fields:

Field	Max Length	Description
changed_from	255	A string of 255 chars or less containing the original value (for example, "/evzijst/bitbucket/issue-attachment/1/evzijst/bitbucket/1359162055.6/1/cow_small.png"). This value can be null.
changed_to	255	A string of 255 chars or less containing the new value (for example, "cow_small.png"). This value cannot be null. Instead, an empty string is used to indicate that the field has no value.
comment		A non-null integer that is a foreign key to a comment.id in the comments section.
created_on		A non-null string in ISO 8601 datetime format (for example "2013-01-22T15:55:13.573339+00:00").
field	32	A non-null string representing the name of the changed field (for example, "attachment"). This value should not exceed 32 characters.
issue		A non-null, integer representing a foreign key to an existing issue.id in the issues array.
user		An object value containing a Bitbucket display name and the user's Atlassian account_id - for example: `1 2 3 4{ "display_name": "Erik Van Zijst", "account_id": "<Erik's Atlassian account id>" }` This value can be null.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community