Issue Tracker Integration API

This article is for developers who want to build an extension for an issue tracking system which is not supported by BugDigger service.

As an alternative, if signing-in to BugDigger via your issue tracker is not essential for your testing process and your issue tracking system can create bug reports from emails, consider setting up a project on BugDigger where bug reports are forwarded to an email address monitored by your issue tracker.

This document describes API for integration of a custom third party web applications with BugDigger, for the purpose of receiving bug reports submitted via BugDigger. This document may be of use to developers interested in writing a BugDigger plugin for their favorite issue tracker or proprietary application.

In order to receive reports from BugDigger, the third party web application is required to provide integration descriptor file and implement logic for handling HTTP requests triggered by BugDigger.

Integration Support Discovery

When BugDigger is given a URL that does not belong to one of the officially supported issue trackers, it will try to fetch an integration descriptor file called “bugdigger-integration.txt” from the server’s root.

For example, if you give BugDigger URL and it fails to recognize issue tracker for the returned page, BugDigger will try to retrieve a file from It’s also possible to use integration descriptor from a sub-directory giving BugDigger full URL to it (enter as a URL to your issue tracker).

Integration Descriptor

File bugdigger-integration.txt tells BugDigger where it can find scripts that it can talk to:

"name": "Name of your site or service",
"bugdigger-api-version": 1,
"plugin-path": "/plugins/bugdigger/",
"logon-path": "logon.php",
"projects-list-path": "projects.php",
"issue-template-path": "form.php",
"issue-post-path": "create.php",
"projects-base-path": "project.php?id=",
"force-https": false,
"contact": "[email protected]"

Descriptor properties:

  • name: Name of the third party web site or service that will be shown to user.

  • bugdigger-api-version: API version, use 1.

  • plugin-path: Base URI to BugDigger integration script(s). If the parameter is missing, the path to the integration descriptor will be used instead. You should use this property if all integration is handled by a single script. If not, you can provide action specific paths (all are optional):

    • logon-path: Authentication script.

    • projects-list-path: Script listing projects available to user.

    • issue-template-path: Path for retrieving bug reporting form.

    • issue-post-path: Script for issue submission.

    • projects-base-path: Path prefix for linking the project in BugDigger’s front end. (This path will not be opened by BugDigger.)

    • projects-base: Project ID will be appended to this URI when linking the project from BugDigger. (This is not currently used.)

  • force-https: Set to true if you want BugDigger to always use HTTPS when accessing your server.

  • contact: Optional contact information in case we need to contact someone regarding the integration.

General rules for API requests

  1. BugDigger uses HTTP POST method to send data to an integrated issue tracker. POST for a bug report submission is “multipart/form-data” encoded.

  2. Form data is UTF-8 encoded.

  3. API requests include cmd parameter as an additional action indicator. (BugDigger allows you to define a separate target URL for each action so this parameter is just for convenience if one URL handles more than one action.)

  4. BugDigger expects JSON object as a response on all requests except when bug reporting form template is requested (in which case (X)HTML is expected, as explained below).

  5. BugDigger maintains an HTTP cookie store per user so your integration script can send a cookie to maintain a session. (Alternatively, you may return a token parameter with successful logon response and the token will be included with all subsequent requests.)

  6. If received JSON object has a property called “error”, it means that something went wrong and the error message (property value) will be passed to user.

Logging On

BugDigger POSTs parameters:

  • cmd with value “logon”

  • username

  • password

For successfully completed authentication return a JSON object containing optional token parameter. For example:

"token": "qwerty123456"

If token is provided, it will be included with all subsequent requests initiated by this user session.

In case of error set an appropriate HTTP response code (not 200) and return an object containing error message:

"error": "Invalid username or password"

Listing Projects

In order to retrieve a list of available projects, BugDigger initiates a request to an URL with path identified by the “projects-list-path” in the integration descriptor (or, if missing, by the plugin path) POST-ing parameters:

  • cmd with value “projects”

  • token (if received on logon)

The result is expected as JSON list of objects containing project names and identifiers:

"name": "Project 1",
"id": "prj1"
"name": "Project 2",
"id": "prj2"

Issue Form Template

When a bug is being reported, BugDigger requests a new issue form template from a path identified by the “issue-template-path” in the integration descriptor (or, if missing, by the plugin path), sending a POST with:

  • cmd (with value “template”)

  • token (if received on logon)

  • project (project ID for which the form is request)

Response to this request should be an (X)HTML containing a FORM element. BugDigger will take the first form element found in received response and use its fields to present bug reporting form. The only fields that must exist in the form are “summary” and “description”. The rest of the form is optional and you can use any additional fields that may be internally used by your issue tracker. For required form fields append asterisk to the label.


<label for="summary">Summary*</label>
<input type="text" name="summary" />
<label for="description">Description</label>
<textarea name="description" ></textarea>
<label for="type">Issue type*</label>
<select name="type">
<option value="bug">Bug</option>
<option value="feature">Feature</option>
<label for="priority">Priority</label>
<select name="priority">
<option value="1">Low</option>
<option value="2" selected="selected">Normal</option>
<option value="3">High</option>

Creating New Issue

BugDigger creates a new issue sending “multipart/form-data” encoded POST to the path specified by the “issue-post-path” in the integration descriptor (or, if missing, by the plugin path). Submitted request includes:

  • form fields specified in issue template

  • cmd (with value “new”)

  • token (if received on logon)

  • project (project ID for which we’re submitting the issue)

  • fileCount (with number of files being uploaded)

  • file1, file2, etc. (attached files)

For successfully created issue BugDigger expects JSON object containing issue ID and URL to it:

"id": "XYZ-12",
"url": ""
comments powered by Disqus