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.  

1 2 3 4 $ 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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 { "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

Required / non-null

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

Required / non-null

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).

meta

The meta object has the following fields:

Field

Required / non-null

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

Required / non-null

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.

Additional Help