Issue Import/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 single a db-1.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-1.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 username 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-1.0.json File

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

The following is an example db.json file:

db-1.0.json
{
    "issues": [
        {
            "assignee": "evzijst", 
            "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": "evzijst", 
            "status": "resolved", 
            "title": "Test", 
            "updated_on": "2013-03-21T04:26:26.733922+00:00", 
            "version": null, 
            "watchers": [
                "detkin", 
                "evzijst"
            ],
 			"voters": [
                "bnguyen", 
                "aprentice"
            ]
        }
    ], 
    "comments": [
        {
            "content": null, 
            "created_on": "2013-01-26T01:00:55.994000+00:00", 
            "id": 388, 
            "issue": 1, 
            "updated_on": null, 
            "user": "evzijst"
        }, 
        {
            "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": "evzijst"
        }
    ], 
    "attachments": [
        {
            "filename": "cow_small.png", 
            "issue": 1, 
            "path": "attachments/cow_small.png", 
            "user": "evzijst"
        }
    ], 
    "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": "evzijst"
        }, 
        {
            "changed_from": "new", 
            "changed_to": "resolved", 
            "comment": 396, 
            "created_on": "2013-03-21T04:26:26.814711+00:00", 
            "field": "status", 
            "issue": 1, 
            "user": "evzijst"
        }
    ], 
    "meta": {
        "default_assignee": "evzijst", 
        "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-1.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

Description
assignee   A string value containing the username (for example, "evzijst"). This value can be null.
component   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 content. This value can be null.
content_updated_on (tick) 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 (tick) 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 (tick) A non-null, unique integer representing the issue identifier.
kind (tick)

A non-null string containing one of the following values:

"bug"
"enhancement"
"proposal"
"task"
milestone   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 (tick)

A non-null string containing one of the following values:

"trivial"
"minor"
"major"
"critical"
"blocker"
reporter   A string value containing the username (for example, "evzijst"). This value can be null.
status (tick)

A non-null string containing one of the following values:

"new"
"open"
"resolved"
"on hold"
"invalid"
"duplicate"
"wontfix"

title (tick) A non-null string representing the issue title. This string has a 255 chars limit.
updated_on (tick) 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   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 usernames. This value can be null.
voters   A list of usernames. This value can be null.

comments

The db-1.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

Description
content   A string value containing the comment's content. This value can be null.
created_on (tick) A non-null string in ISO 8601 datetime format (for example, "2013-01-26T01:00:55.994000+00:00")
id (tick) A non-null integer that is unique among the comments array.
issue (tick) 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   A string value containing the username (for example, "evzijst"). This value can be null.

attachments

The db-1.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

Description
filename (tick) A non-null string that is the name of an attachment as it appears on the issue tracker (for example, "cow_small.png").
issue (tick) A non-null, integer representing a foreign key to an existing issue.id in the issues array.
path (tick) A non-null string that contains the location of a file in the ZIP.
user   A string value containing the username (for example, "evzijst"). This value can be null.

components

The db-1.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-1.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-1.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

Description
default_assignee   A string value containing the username (for example, "evzijst"). This value can be null.
default_component   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 (tick)

A non-null string containing one of the following values:

"bug"
"enhancement"
"proposal"
"task"
default_milestone   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   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-1.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

Description
changed_from   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 (tick) 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 (tick) A non-null integer that is a foreign key to a comment.id in the comments section.
created_on (tick) A non-null string in ISO 8601 datetime format (for example "2013-01-22T15:55:13.573339+00:00").
field (tick) A non-null string representing the name of the changed field (for example, "attachment"). This value should not exceed 32 characters.
issue (tick) A non-null, integer representing a foreign key to an existing issue.id in the issues array.
user   A string value containing the username (for example, "evzijst"). This value can be null.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport