Quick Start Guide

All you need to get started working with the FogBugz XML API is an HTTP library and an XML parsing library. We're going to use Python. If you've never used Python before, that's OK. We'll show you everything you need to know to get started.

Install Python and FogBugzPy

Quick installation steps:

1. Install Python 2.7.10 or Python 3.5.2. On Windows, we recommend the Windows MSI Installer.
   1. Add Python to your system path.
2. Install FogBugzPy.
   1. pip install fogbugz
   2. If you prefer to install from source, on Mac, Unix, Linux: Clone and install FogBugzPy

See Installing Python and FogBugzPy for more detailed instructions.

Python Interpreter Example

Go to the command line, type python, and press Enter. This will bring up the Python interpreter. Type the following code into the interpreter, replacing string values where appropriate to correspond to your FogBugz installation.

First, let's tell Python that we want to use the FogBugz library and create an instance of FogBugz called fb:

1:
2:

>>> from fogbugz import FogBugz
>>> fb = FogBugz('https://example.fogbugz.com/')

Next, log on using your username and password (you can also use an API token):

1:

>>> fb.logon('logon@example.com','password')

Let's do a basic search and print the result to the screen. Because we're not specifying any criteria to search, the API is just going to return the cases in our currently active filter. The prettify method makes the XML response easier to read.

1:

>>> print fb.search().prettify()

What if I want to see all cases assigned to me? Use the q parameter to specify a FogBugz search. You can use any search axis that you would normally use in FogBugz: 

1:

>>> print fb.search(q='assignedto:"me"').prettify()

When I return a list of something, I usually want to do something with each item in the list. This time, we'll use the cols parameter to specify which columns we want returned with our filter.  Note that resp.cases.childGenerator() is one way to return a list of elements.

1:
2:
3:
4:

>>> resp = fb.search(q='assignedto:"me"',cols='ixBug,sTitle')
>>> for case in resp.cases.childGenerator():
...     print case['ixBug'] + ':' + case.sTitle.string
...

Here's another example of iterating through a list of cases, this time using resp.findAll('case')

1:
2:
3:

>>> for case in resp.findAll('case'):
...    print case['operations']
...

Let's make an edit to a case. We'll use the FogBugz edit method. Note how we use the ixBug parameter to specify which bug we want to edit and the sEvent parameter to specify what text to include in the edit to the case.

1:

>>> fb.edit(ixBug=1,sEvent='This is an edit from the API!')

Python Script Example

In the above example, we explored the FogBugz XML API using the interactive Python interpreter from the command line. This example will show how to save a script to a file and execute it from the command line.

Create a file called example.py. Copy the code below into that file, replacing the values at the top of the file to match your installation.

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:

#This script will print a list of all overdue cases assigned to me

from fogbugz import FogBugz
from datetime import datetime, timedelta

# Fill in the following values as appropriate to your installation
S_FOGBUGZ_URL   = 'https://example.fogbugz.com/'
S_EMAIL         = 'logon@example.com'
S_PASSWORD      = 'password'

fb = FogBugz(S_FOGBUGZ_URL)
fb.logon(S_EMAIL, S_PASSWORD)

#Get all cases assigned to me
resp = fb.search(q='assignedto:"me"',cols='ixBug,sTitle,dtDue')

print 'The following cases are overdue:'

for case in resp.cases.childGenerator():
    #Check to see if we have a due date
    if case.dtDue.string: 
        #All dates returned are UTC, so parse the due date
        #into a datetime object.
        dtDueUtc = datetime.strptime(case.dtdue.string,'%Y-%m-%dT%H:%M:%SZ')
        fOverdue = dtDueUtc <= datetime.utcnow()
        if fOverdue:
            tdDays = (datetime.utcnow() - dtDueUtc).days
            sTitle = case.sTitle.string
            print "%s: %s (%s days)" % (case['ixBug'], sTitle, tdDays)

From the command line (in the directory that contains example.py), type the following to run the script:

1:

> python example.py

Python Resources

Are you interested in learning more about Python? Start here:

• Python 2.7.10 documentation - the official documentation for Python 2.7.10
• Learn Python The Hard Way - a free online book (PDF and print versions also available) to get started programming in Python. Although it's called "the hard way," following along is very easy, requiring you to type out the code for each exercise. We highly recommend it if you're new to Python or programming in general.