SOAP interface to FBT

About this Document

This document is aimed at developers. It explains the WSDL/SOAP interface to Fast BugTrack (FBT). Using the calls defined in this document, a developer can quickly query, create and update issues within the FBT system.

This document assumes some familiarity with XML and SOAP. You should also be at lease somewhat familiar with FBT, and the data stored within.

Setting up Perl/SOAP-Lite on Windows...

Download and install Perl from ActiveState
Download and install nmake (make utility) from Microsoft
Download and install SOAPLite (There is also a ton of SOAP documentation here!)
Download and install URI Perl module. Other perl modules are recommended on the SOAPLite page, but no other modules are required for communicating with FBT.

Configure FBT to enable SOAP Interface

Admin Menu
SOAP Functions
Click "Enable SOAP" checkbox and submit...

WSDL Explained

WSDL: WSDL stands for Web Service Description Language, and it defines all of the web service requests and responses that can be made to FBT. There are 4 basic opertions that can be performed through the web interface:

Request Name	Description	Read/Write
GetId	This call returns the full bug detail for a single specific issue. It is the equivilant of viewing a bugs details through the web interface.	Read-only
GetBugList	This call allows the caller to define parameters, through which a set of bugs will be returned. It is the equivilant of the filter screen in the web interface.	Read-only
NewBug	Create a new issue within your system using this call.	Write
UpdateBug	Update an existing issue within your system using this call.	Write

Before executing any examples in this document, or using any soap functionality, you must enable SOAP within FBT (it is disabled by default). Enable SOAP from "Admin Menu", "SOAP Functions" and check "Enable SOAP" checkbox and press the submit button.

NOTE: FBT will dynamically generate a custom .wsdl file based on how your instance of FBT is configured (ie. If you have custom fields, they will be added to your wsdl file. All of our examples in this document assume the stock FBT installation. You can view the .wsdl file by going to http://localhost:10000/FastBugTrack.wsdl (assuming you are on the same machine as FBT is running on... Replace localhost with the name of the machine running FBT.

General Conventions

Field names within FBT are prefixed with "m", and "camelcase" is used for field naming conventions (capitalize the beginning of each word). Example: the Id field is mId, the Date Last Modified field is mDateLastModified. Viewing the source HTML of pages such as the ViewBug and Filter pages allows you to look up a specific field name.

All of the examples provided are using Perl and SOAP::Lite (a Perl module). We're using this for our examples because: Perl and SOAP::Lite are available for just about every operating system, and they're free. While we're using Perl, most modern programming languages have web service modules / libraries that should work fine with FBT. Customers with any questions about compatibility and/or would like examples for platforms can email bugtrack@alceatech.com for additional information.

getId

Description

This function is similar to the filter function - returning the data that you would see on the MainMenu.

Sample Perl Code

The following Perl code retrieves the details of bug 10 from the system. We turn full debug on, to display both the raw data that we send to FBT, and display the raw data received in response.

#!/usr/bin/perl

use SOAP::Lite;
print SOAP::Lite
  ->service("http://localhost:10000/FastBugTrack.wsdl")
  -> on_debug(sub{print@_}) 
  -> getId(SOAP::Data->name("mId" => "10"));

Input

We can see that the following SOAP message is sent to FBT:

POST http://localhost:10000
Accept: text/xml
Accept: multipart/*
Content-Length: 448
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://localhost:10000/getId"

<?xml version="1.0" encoding="UTF-8"?>
  <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"      
     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
     xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
     xmlns:xsd="http://www.w3.org/1999/XMLSchema">
  <SOAP-ENV:Body>
    <getId xmlns="">
      <mId xsi:type="xsd:int">10</mId>
    </getId>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Output

The details of the bug are returned. The contents are contained in a bugStruct element, which in turn contains all of the current (non-history) fields, plus bugEntry structures for each update to the bug. Each bugEntry contains the values that were provided in those updates.

Sample output from the perl call:


HTTP/1.1 200 OK
Content-Length: 1919
Content-Type: text/xml; charset=utf-8
Client-Date: Tue, 21 Oct 2003 02:38:11 GMT
Client-Peer: 127.0.0.1:10000
Client-Response-Num: 1

<?xml version="1.0"?>

<SOAP-ENV:Envelope
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/1999/XMLSchema"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
      <bugStruct>
        <mId>10</mId>
        <mSubject>performance @ Aktiom ... Server timing ...</mSubject>
        <mDateEntered>Tue Sep 16 00:13:23 EDT 2003</mDateEntered>
        <mCurrentStatus>Closed</mCurrentStatus>
        <mCurrentAssignedTo>cjustus</mCurrentAssignedTo>
        <mLastModifiedBy>cjustus</mLastModifiedBy>
        <mDateLastModified>Mon Sep 22 21:55:12 EDT 2003</mDateLastModified>
        <mEnteredBy>cjustus</mEnteredBy>
        <mPriority>3</mPriority>
        <mProject>Aktiom</mProject>
        <mArea>area</mArea>
        <mVersion></mVersion>
        <mEnvironment></mEnvironment>
        <mParent>0</mParent>
        <mRequestedDueDate>null</mRequestedDueDate>
        <mActualCompletionDate>null</mActualCompletionDate>
        <mEstimatedHours>0.0</mEstimatedHours>
        <mActualHours>0.0</mActualHours>
        <mPercentComplete>0.0</mPercentComplete>
        <bugHistory>
          <bugEntry>
            <mAssignedTo>cjustus</mAssignedTo>
            <mWho>cjustus</mWho>
            <mStatus>Open</mStatus>
            <mWhen>Tue Sep 16 00:13:23 EDT 2003</mWhen>
            <mDescription></mDescription>
          </bugEntry>
          <bugEntry>
            <mAssignedTo>cjustus</mAssignedTo>
            <mWho>cjustus</mWho>
            <mStatus>Closed</mStatus>
            <mWhen>Mon Sep 22 21:55:12 EDT 2003</mWhen>
            <mDescription>istop issue...</mDescription>
          </bugEntry>
        </bugHistory>
      </bugStruct>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

getBugList

Description

This function is the SOAP call equivalent to running a filter. Critera submitted via the soap call will return a filtered list of bugs.

Sample Perl Code

The following Perl code shows how to enter filter criteria with SOAP. Take note of the method in which custom fields are entered. The custom field ID numbers can be found on the Admin Menu -> Custom Field page.

#!/usr/bin/perl

use SOAP::Lite;
print SOAP::Lite
  ->service("http://localhost:10000/FastBugTrack.wsdl")
  -> on_debug(sub{print@_}) 
  -> getBugList(SOAP::Data->name("mPriority" => "1"),
         SOAP::Data->name("mPriorityOp" => "="),
         SOAP::Data->name("mPriorityAndOr" => "OR"),
         SOAP::Data->name("mPriority2" => "2"),
         SOAP::Data->name("mPriority2Op" => "="));
         SOAP::Data->name("filterCustomFields" =>
         \SOAP::Data->value(SOAP::Data->name("filterCustomField" =>
           \SOAP::Data->value(SOAP::Data->name("Id" => "5"),
                              SOAP::Data->name("Op" => ">="),
                              SOAP::Data->name("Value" => "2005/05/5"),
                              SOAP::Data->name("AndOr" => "and"),
                              SOAP::Data->name("Op2" => "<="),
                              SOAP::Data->name("Value2" => "2005/05/15"))))));

Input

We can see that the following SOAP message is sent to FBT:

POST http://localhost:10000
Accept: text/xml
Accept: multipart/*
Content-Length: 766
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://localhost:10000/newBug"

<?xml version="1.0" encoding="UTF-8"?>
  <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"      
     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
     xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
     xmlns:xsd="http://www.w3.org/1999/XMLSchema">
  <SOAP-ENV:Body>
  <getBugList xmlns="">
    <mPriority xsi:type="xsd:int">1</mPriority>
    <mPriorityOp xsi:type="xsd:string">=</mPriorityOp>
    <mPriorityAndOr xsi:type="xsd:string">OR</mPriorityAndOr>
    <mPriority2 xsi:type="xsd:int">2</mPriority2>
    <mPriority2Op xsi:type="xsd:string">=</mPriority2Op>
    <filterCustomFields>
      <filterCustomField>
        <Id xsi:type="xsd:int">5</Id>
        <Op xsi:type="xsd:string">>=</Op>
        <Value xsi:type="xsd:string">2005/05/5</Value>
        <AndOr xsi:type="xsd:string">and</AndOr>
        <Op2 xsi:type="xsd:string"><=</Op2>
        <Value2 xsi:type="xsd:string">2005/05/15</Value2>
      </filterCustomField>
    </filterCustomFields>
  </getBugList>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Output

A list of filtered bugs are returned. The results are a set of bugStruct elements contained in a bugList element.

Sample output from the perl call:

HTTP/1.1 200 OK
Content-Length: 1919
Content-Type: text/xml; charset=utf-8
Client-Date: Tue, 21 Oct 2003 02:38:11 GMT
Client-Peer: 127.0.0.1:10000
Client-Response-Num: 1

<?xml version="1.0"?>

<SOAP-ENV:Envelope
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/1999/XMLSchema"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
      <bugList>
        <bugStruct>
          <mId>13</mId>
          <mSubject>test</mSubject>
          <mCurrentAssignedTo>birdman</mCurrentAssignedTo>
          <mDateLastModified>Fri May 13 16:10:00 EDT 2005</mDateLastModified>
          <mCurrentStatus>Open</mCurrentStatus>
          <mPriority>1</mPriority>
          <mDateEntered>Fri May 13 16:10:00 EDT 2005</mDateEntered>
          <mEnteredBy>jsimpson</mEnteredBy>
          <mProject>SYSTEM</mProject>
          <mArea></mArea>
          <mVersion></mVersion>
          <mEnvironment></mEnvironment>
          <mRequestedDueDate></mRequestedDueDate>
          <mActualCompletionDate></mActualCompletionDate>
          <mEstimatedHours>0.0</mEstimatedHours>
          <mActualHours>0.0</mActualHours>
          <mPercentComplete>0.0</mPercentComplete>
          <mParent>0</mParent>
          <mLastModifiedBy>jsimpson</mLastModifiedBy>
          <mElapsedTime>0</mElapsedTime>
          <mNotifyList></mNotifyList>
          <mRejectedCount>0</mRejectedCount>
          <mRankCache>0.0</mRankCache>
          <bugHistory>
            <bugEntry>
              <mAssignedTo>birdman</mAssignedTo>
              <mWho>jsimpson</mWho>
              <mStatus>Open</mStatus>
              <mWhen>Fri May 13 16:10:00 EDT 2005</mWhen>
              <mDescription>Test bug</mDescription>
            </bugEntry>
          </bugHistory>
        </bugStruct>
      </bugList>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

newBug

Description

This function mirrors the functionality of the New Bug screen. A new bug will be created using the data from any field values submitted via the SOAP call. The new bug's ID is returned.

Sample Perl Code

The following Perl code shows how to enter a new bug with SOAP. Fields that are not included will be set to empty in the newly created bug. Take note of the method in which custom fields are entered. The custom field ID numbers can be found on the Admin Menu -> Custom Field page.

#!/usr/bin/perl

use SOAP::Lite;
print SOAP::Lite
  ->service("http://localhost:10000/FastBugTrack.wsdl")
  -> on_debug(sub{print@_}) 
  -> newBug(SOAP::Data->name("mSubject" => "Testing SOAP: newBug call"),
       SOAP::Data->name("mDescription" => "This will enter a new bug into the system."),
       SOAP::Data->name("mAssignedTo" => "admin"),
       SOAP::Data->name("customFields" =>
         \SOAP::Data->value(SOAP::Data->name("customField" =>
           \SOAP::Data->value(SOAP::Data->name("Id" => "3"),
                               SOAP::Data->name("Value" => "SOAP UPDATE")))),
         SOAP::Data->value(SOAP::Data->name("customField" =>
           \SOAP::Data->value(SOAP::Data->name("Id" => "4"),
                             SOAP::Data->name("Value" => "SOAP UPDATE"))))));

Input

We can see that the following SOAP message is sent to FBT:

POST http://localhost:10000
Accept: text/xml
Accept: multipart/*
Content-Length: 766
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://localhost:10000/newBug"

<?xml version="1.0" encoding="UTF-8"?>
  <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"      
     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
     xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
     xmlns:xsd="http://www.w3.org/1999/XMLSchema">
  <SOAP-ENV:Body>
    <newBug xmlns="">
      <mSubject xsi:type="xsd:string">Testing SOAP: newBug call</mSubject>
      <mDescription xsi:type="xsd:string">This will enter a new bug into the system.</mDescription>
      <mAssignedTo xsi:type="xsd:string">admin</mAssignedTo>
      <customFields>
        <customField>
          <Id xsi:type="xsd:int">3</Id>
          <Value xsi:type="xsd:string">SOAP UPDATE</Value>
        </customField>
        <customField>
          <Id xsi:type="xsd:int">4</Id>
          <Value xsi:type="xsd:string">SOAP UPDATE</Value>
        </customField>
      </customFields>
    </newBug>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Output

The new bug's ID is returned in a FBTMessage element.

Sample output from the perl call:

HTTP/1.1 200 OK
Content-Length: 1919
Content-Type: text/xml; charset=utf-8
Client-Date: Tue, 21 Oct 2003 02:38:11 GMT
Client-Peer: 127.0.0.1:10000
Client-Response-Num: 1

<?xml version="1.0"?>

<SOAP-ENV:Envelope
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/1999/XMLSchema"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <FBTmessage>Bug 13 has been created.</FBTmessage>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

updateBug

Description

This function works the same as the newBug call. In addition to other fields, the mId field is set to the ID of the bug that will be updated. Fields that are not set in the SOAP call will remain unchanged.