FogBugz 7.0 Online Help

FogBugz XML API version 7

This document describes XML API version 7, which ships with FogBugz 7.0. The FogBugz XML API is implemented as an ASP page that accepts GET or POST params and returns XML after a user has been authenticated. As of FogBugz 7, the XML API is included with FogBugz and does not need to be installed separately. Sample code that uses the API is included in your FogBugz\Accessories\API folder.

Checking the API Version and location

API clients must first hit the [FogBugz URL]/api.xml.

For example, if the URL is http://www.example.com/fogbugz, hit http://www.example.com/fogbugz/api.xml. Or if your FogBugz On Demand account is https://example.fogbugz.com, hit https://example.fogbugz.com/api.xml.

If this returns an HTTP error (file missing) you can safely assume that either FogBugz is not installed at that location, or else it is installed, but it is a version of FogBugz that does not include the API.

If the FogBugz URL includes an id (e.g. id=xxx for a FogBugz trial or hosted version of FogBugz), you can leave this out for the purpose of downloading api.xml.

api.xml simply tells you what version of the FogBugz API is supported, and gives you the URL for further calls to the API. The file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <version>2</version>
  <minversion>1</minversion>
  <url>api.asp?</url>
</response>

The url field gives you the beginning of the URL you should use for all further calls to the API. This would be "api.asp?" for a typical FogBugz install (FogBugz 7 or later) or "api.php?" for a php install (FogBugz 6.1 or earlier).

The minversion field is used to warn you if the current version of the API is not backwards compatible. For example, if this version is 3, and it is backwards compatible with clients written for version 2 but not backwards compatible with version 1, you'll see:

<version>3</version>
<minversion>2</minversion>

API clients must check minversion and make sure it's less than or equal to the version that was current when they were written.

The private tag can almost always be ignored by non-Fog Creek api clients. It is used by the FogBugz server to indicate to a client that a new version of some API client software is available on the FogBugz server. For example, the following tag might be interpreted by the FogBugz for Visual Studio Add-in to mean that version 3 is now available on the server where it can be downloaded from the URL setup-msvs.exe.

<private id="FogBugz for Visual Studio" version="3" url="setup-msvs.exe" />

Logging On

FogBugz itself supports several methods of logging on, however, the only method supported by the API is by providing an email address (or full name, just like FogBugz sign-in) and password in the logon method:

http://www.example.com/api.asp?cmd=logon&email=xxx@example.com&password=BigMac

Three things can happen.

1) Failed logon - email or password doesn't match:

<response><error code="1">Error Message To Show User</error></response>

2) Successful logon - you get back an opaque string token which you will use for all subsequent requests:

<response><token>24dsg34lok43un23</token></response>

3) Ambiguous logon - there is more than one FogBugz user with that email address.  FogBugz will supply you with a list of full names; you must provide the appropriate full name to log on.

<response><error code="2">Ambiguous Logon</error>
  <people>
    <person>John Hancock</person>
    <person>Fred Astaire</person>
  </people>
</response>

If, for example, you got that response, you would prompt the user with a combo box to choose if they are John Hancock or Fred Astaire. If they're John, you would try logging on again with this URL:

http://www.example.com/api.asp?cmd=logon&email=John%20Hancock&password=BigMac

General rules for API requests

  1. You can use GET or POST.  If you are submitting files however, you must use a enctype="multipart/form-data" POST.
  2. FogBugz is going to be religiously UTF-8.
  3. All API requests will have a cmd argument indicating what you want to do, like cmd=logon in the logon example.
  4. All API requests must have a token argument indicating the logon session except cmd=logon. The token can be used indefinitely, and will only be invalidated by executing a logoff command with that token.
  5. The response is a valid XML file in UTF-8 format containing an outer <response> tag at the root.
  6. If the first child node is <error>, something went wrong.
  7. If the token is not supplied, or if the token does not correspond to a logged-in user, you'll get error code 3:

<response><error code="3">Not logged on</error></response>

Logging Off

To log off, send cmd=logoff. For example:

http://www.example.com/api.asp?cmd=logoff&token=24dsg34lok43un23

Filters

Once logged on, you can get a list of filters available to the current user.

FogBugz has three kinds of filters:

  1. Built-in filters are always present, and include "My Cases" and sometimes the main Inbox if FogBugz is used to read mail

  2. Users can save their own private filters

  3. Administrators can share filters which will be available to all users

To list filters:

cmd=listFilters

The result:

<response>
  <filters>
    <filter type="builtin" sFilter="ez349">My Cases</filter>
    <filter type="saved" sFilter="304">Cases I should have closed months ago</filter>
    <filter type="shared" sFilter="98" status="current">Customer Service Top 10</filter>
  </filters>
</response>

Notes:

type is "builtin", "saved", or "shared". FogBugz users will probably expect to see the three types of filters grouped as they are in FogBugz itself. The list of filters is already in the same order that users are used to seeing it in the FogBugz user interface and should be preserved.

sFilter is an opaque string that can be passed back to cmd=setCurrentFilter. The meaning is internal to FogBugz.

Zero or one of the filters may have the status="current" attribute indicating that this is the users' current filter. (If none of these filters has status="current", the user is probably looking at an ad-hoc filter which hasn't been saved.)

Currently the builtin filters won't be listed as "current" even if you are currently looking at one.


To change the current filter (pass in the sFilter attribute from the listFilters cmd):

cmd=setCurrentFilter&sFilter=402

The result is purposefully empty.

<response></response>

Listing and Viewing Cases

The API differs from the web interface in that, rather than listing cases in one action and viewing specific cases in another, you can return both a list of cases and the exact information you want about them all at the same time using the cols parameter.

cmd=search

Arguments:

q - the query term you are searching for.  Can be a string, a case number, a comma separated list of case numbers without spaces, e.g. 12,25,556 .  Note, to search for the number 123 and not the case 123, enclose your search in quotes.  This search acts exactly the same way the search box in FogBugz operates, so you can use that to debug.

If q is not present, returns the cases in your current filter.  If the current filter matches a saved or built-in filter, the sFilter is also returned.

cols - the information you would like returned with each case in the list.  The parameter should be a comma-separated list of column names (e.g., cols=sTitle,sStatus).  Available columns are listed here in the case xml output.  Additional columns: if you include events, you will also receive all the events for that case.  Include latestEvent to just get the latest event.

ix columns can be empty or 0 if they are not set.  All valid ix columns (ixPersonClosedBy for example) will be > 0 if there is a valid person who closed this case.

max - the max number of bugs you want returned.  Leave off if you want them all.

Editing Cases

Each of the following commands accept "ixPersonEditedBy" and "dt" parameters from admins to enable accurate imports with the API.

cmd=new and cmd=edit and cmd=assign and cmd=reactivate and cmd=reopen

Arguments:

If any fields are omitted, they will not be changed.

You can also upload an unlimited number of files (constrained only by the max upload limit on the web server).

File1, File2, File3, etc.
To upload files, use the enctype="multipart/form-data" form type and you will need an additional argument nFileCount which contains the number of files (otherwise only the first one will upload).

For example, an html page which submits to the api to create a new case would look like this:

<html>
<form method="post" action="http://localhost/fb/api.asp" enctype="multipart/form-data" >
<input type=hidden name=cmd value=new />
<input type=hidden name=token value="CCECOGMBRTPJLFUVFUAAGZCEIEYAC2" />
<input type=file name=File1 />
<input type="submit">
</form>
</html>

You can read more about this encoding type in the RFC.

cmd=resolve

Same as cmd=edit, with the addition of the ixStatus field.  Note: the UI does not let you change the project, area, assigned to, and category on resolve.  The API does.

cmd=close

Same as cmd=editNote: the UI does not let you change any fields on close.  The API does.  However, ixPersonAssignedTo will always be set to 1 (the CLOSED user).

cmd=email and cmd=reply and cmd=forward

Additional arguments: sSubject, sFrom, sTo, sCC, sBCC, ixBugEventAttachment (this is the ixBugEvent if you want to include any attachments from a previous email, for example when you want to do a "forward")

Note: You can supply any address for the sFrom field, although the UI restricts you to email addresses that FogBugz is actively checking (so that when a user replies to your email, it will actually go back into FogBugz).  The sFrom field you supply here should be one of the values returned from the cmd=listMailboxes command.

Same as cmd=edit.

Lists

cmd=listProjects  - list all undeleted projects (Arguments: fWrite=1 -- optional, do you want a list of projects you can write to? If this is left off, then the API assumes you are looking for projects that you can at least read. ixProject -- optional, if included will always list at least this project even if it is deleted)
cmd=listAreas - list all undeleted areas (Arguments: fWrite=1 -- optional, do you want a list of areas you can write to? If this is left off, then the API assumes you are looking for areas that you can at least read. ixProject -- list areas from this project, ixArea -- optional, if included will always list at least this area even if it is deleted)
cmd=listCategories - list all categories
cmd=listPriorities - list all priorities
cmd=listPeople - list people in the corresponding categories (Arguments: fIncludeNormal=1, fIncludeCommunity=1, fIncludeVirtual=1 -- if you don't supply any arguments, the API assumes you mean fIncludeNormal=1)
cmd=listStatuses - list status for a particular category (Arguments: ixCategory - optional, will list all if left off, fResolved=1 -- if fResolved = 1 then only resolved statuses are listed)
cmd=listFixFors - list milestones ( Arguments: ixProject - only list milestones for this project, if omitted will list all milestones, ixFixFor - if listing all milestones will include this milestone even if it's unassignable (i.e. inactive), fIncludeDeleted=1 - include inactive milestones (i.e. those that are marked unassignable), fIncludeReallyDeleted=1 - include completely deleted milestones (i.e. no longer viewable or assignable)
cmd=listMailboxes - get a list of mailboxes that you have access to -- note the sTemplate field here will have placeholders you will need to replace ( such as {case} {subject} {ticketurl} etc).  See the Mailboxes edit screen in FogBugz for more info.

Creating

cmd=newProject

Arguments: sProject (sProject is the title of the new project), ixPersonPrimaryContact, fAllowPublicSubmit, ixGroup, fInbox (default=1)

Returns: ixProject of the new project
cmd=newArea

Arguments: ixProject, sArea (sArea is the title of the new area), ixPersonPrimaryContact (if ixPersonPrimaryContact is -1, use project's primary)

Returns: ixArea of the new area
cmd=newPerson

Arguments: required: sEmail, sFullname optional:nType (default=0), fActive (default=1), sPassword (default=random), sLocale, sLanguage, sTimeZoneKey, sSnippetKey, fNotify, sPhone, sHomepage
(nType is 0 for a normal user, 1 for an administrator, 2 for a community user, and 3 for a virtual user)

Returns: ixPerson of the new person
cmd=newFixFor

Creates a new milestone.

Arguments: required: ixProject (set ixProject to -1 to create a global milestone), sFixFor (sFixFor is the title of the new milestone) optional:dtRelease, dtStart, sStartNote, fAssignable

Returns: ixFixFor of the new milestone

Views

cmd=viewProject - display info about a particular project

Arguments: ixProject OR sProject

cmd=viewArea - display info about a particular area
Arguments: ixArea OR (sArea,ixProject)
cmd=viewPerson - display info about a particular person
Arguments: ixPerson OR sEmail (Optional: if this is left off the user currently logged in is returned)
cmd=viewFixFor - display info about a particular milestone
Arguments: ixFixFor OR (sFixFor,ixProject) )
cmd=viewCategory - display info about a particular category
Arguments: ixCategory
cmd=viewPriority - display info about a particular priority
Arguments: ixPriority
cmd=viewStatus - display info about a particular status
Arguments: ixStatus OR (sStatus, ixCategory)
cmd=viewMailbox - display info about a particular mailbox
Arguments: ixMailbox

Milestone Dependencies

cmd=addFixForDependency- Arguments: ixFixFor, ixFixForDependsOn - create a dependency of one milestone upon another.

cmd=deleteFixForDependency- Arguments: ixFixFor, ixFixForDependsOn - remove a dependency of one milestone upon another.

Working Schedule

cmd=listWorkingSchedule - list working schedule for a particular person
Arguments: ixPerson - If ixPerson is omitted, list the working schedule for the logged on user. If ixPerson is set to 1, list the site working schedule.

Returns <workingschedule> (see sample xml)

cmd=wsDateFromHours - Allows you to add hrs (in working hours time) to dt respecting the working hours.  For example, if you work 9-5 Monday to Friday, and it's Friday at 4pm and you want to know what date to set a case to that should be due in 8 working hours, it would return the next Monday at 3pm.  If it was Monday at 3pm and you wanted to know what the date would be for something due in 5 hours, it would give you back the next day, Tuesday at 12 noon.

Arguments
  • ixPerson - If omitted, use the working schedule for the logged on user.
  • hrs - the number of hours you want to add to the date
  • dt - the UTC date you want to start at.

Returns <dt>2007-05-07T16:30:00Z</dt>  -- a UTC date

cmd=listProjectPercentTime - list Per-Project Percent Time
Arguments
  • ixPerson - If ixPerson is omitted, list Per-Project Percent Times for the logged on user.

Returns per-project percent times and nPercentTimeAllOtherProjects

cmd=addProjectPercentTime - Protect a project
Arguments
  • ixProject - The project to protect
  • nPercent - How much time will be spent on this project (between 0 and 100)

Returns the new per-project percent time information

cmd=editProjectPercentTime - edit Per-Project Percent Time
Arguments
  • ixProjectPercentTime - The ProjectPercentTime to modify
  • nPercent - How much time will nowbe spent on the project (between 0 and 100)

Returns the modified per-project percent time information

cmd=deleteProjectPercentTime - Unprotect a project
Arguments
  • ixProjectPercentTime - The ProjectPercentTime to delete

Time Tracking

cmd=startWork - start working on this case and charge time to it (start the stopwatch)

Arguments:  ixBug - the case you want to start working on

cmd=stopWork - stop working on everything (stop the stopwatch)

No arguments

cmd=newInterval - import a time interval that already happened

Arguments: ixBug, dtStart, dtEnd

cmd=listIntervals - returns all TimeIntervals for a user. Any of the optional arguments serve to filter the results.

Arguments
  • ixPerson (optional) - Specifies which user's intervals should be returned. If omitted, list intervals for the logged on user. If set to 1, list intervals for all users.
  • ixBug (optional) - Specifies that only intervals associated with this bug should be returned.
  • dtStart, dtEnd (optional) - If dtStart and/or dtEnd are supplied, listIntervals will return intervals whose start date falls between dtStart and dtEnd.

Source Control

cmd=newCheckin - associate a new checkin with a given FogBugz case
Arguments:
  • ixBug - the case with which to associate the checkin
  • sFile - the name of the file being checked in
  • sPrev - the pre-checkin revision number
  • sNew - the post-checkin revision number
  • sRepo (optional) - the source control repository in which this file is located
cmd=listCheckins - list all of the checkins that have been associated with the specified case
Arguments: ixBug

Release Notes

You can reproduce the current behavior of getting release notes for a particular release using the following syntax:

cmd=search&q=fixfor:undecided&cols=ixBug,sCategory,sTitle,sReleaseNotes


Wikis

cmd=newWiki
Arguments: s, sTagLineHTML (s is the title of the new wiki)
cmd=editWiki
Arguments: ixWiki, s (optional), sTagLineHTML (optional), ixDictionary (optional), ixTemplate (optional)
cmd=deleteWiki
Arguments: ixWiki
cmd=newArticle
Arguments: ixWiki, sHeadline, sBody, cols, dt, ixPersonEditedBy, sTags
cmd=editArticle
Arguments: ixWikiPage, sHeadline, sBody, sComment, cols, dt, ixPersonEditedBy, sTags
cmd=listWikis
Arguments: (none)
cmd=listArticles
Arguments: ixWiki
cmd=listRevisions
Arguments: ixWikiPage
cmd=viewArticle
Arguments: ixWikiPage, nRevision (optional)
cmd=listTemplates
Arguments: (none)
cmd=listTemplateRevisions
Arguments: ixTemplate
cmd=viewTemplate
Arguments: ixTemplate, nRevision (optional)
cmd=deleteTemplate
Arguments: ixTemplate
cmd=newTemplate
Arguments: sTemplate, sBodyHTML, sBodyCSS, sComment
cmd=editTemplate
Arguments: ixTemplate, sTemplate (optional), sBodyHTML (optional), sBodyCSS (optional), sComment (optional)
cmd=wikiFileUpload
Arguments: ixWiki, File1 (multipart/form-data)


Discussion Groups

cmd=listDiscussGroups - list all readable discussion groups

cmd=listDiscussion Arguments: ixDiscussGroup, fFull (if you want every post fFull=1, just main topics fFull=2), m (month, omit for curent), y (year, omit for current)... i.e. ixDiscussGroup=1&fFull=1&m=2&y=2007 - all posts in discussion group 1 for February 2007.

cmd=listDiscussTopic Arguments: ixDiscussTopic

BugzScout

BugzScout cases can be handled directly by the API now.

cmd=listScoutCase Arguments: sScoutDescription - empty if no case is found -- limited to 255 chars.

To record a case, simply add the column sScoutDescription when executing a cmd=new

To edit scout info, simply add the columns sScoutMessage and/or fScoutStopReporting when you edit a case. 

Subscriptions

cmd=subscribe - Arguments: ixBug or ixWikiPage

cmd=unsubscribe - Arguments: ixBug or ixWikiPage

To check if you are subscribed to a case, use cmd=search&q=xxx&cols=fSubscribed (where xxx is the case number)

Mark as viewed

Cases marked as "viewed" will appear to be visited links in the FogBugz UI.

cmd=view

Arguments:
ixBug - must be a case number
ixBugEvent - If supplied will only mark case as being "viewed" up until this bugevent.  If omitted, will mark case as being viewed up to the latest bugevent.

Settings

cmd=viewSettings - get back info on this person such as their timezone offset, preferred columns, etc.

 

Evidence-Based Scheduling

cmd=viewUserTimelineReport - View the complete set of EBS milestone work simulations for all users required to complete this milestone and all of its dependencies. This is the same data that is displayed in the Per-User Timeline Report.
Arguments: ixFixFor, ixPriority
cmd=viewUserShipDateReport - Like viewUserTimelineReport, but only including the simulation of the final milestone to be completed by each user. This is the same data that is show in the Per-User Ship Date report.
Arguments: ixFixFor, ixPriority
cmd=viewShipDateReport - View the distribution of overall completion dates for this milestone at this Priority. This is the same data that is shown in the Ship Date report.
Arguments: ixFixFor, ixPriority
cmd=viewHoursRemainingReport - View the distribution of projected overall hours remaining to complete this milesone at this Priority. This is the data that is aggregated over time in the Burn Down Chart. Including fThisFixForOnly=1 gives the data that is aggregated in the Burn Down Chart (this milestone only).
Arguments: required: ixFixFor, ixPriority optional: fThisFixForOnly (defaults to false)
cmd=listShipDate - List the historical nightly ship date calculations for this milestone at this Priority from the time when the milestone was created until now.
Arguments: ixFixFor, ixPriority
cmd=viewEstimator - View the distributions of actual/estimated ratios in this person's estimate history.
Arguments: ixPerson

Sample XML Payloads

Cases:

<cases count="1"> -- count is included in the cases attribute
<case ixBug="123" operations="edit,assign,resolve,reactivate,close,reopen,reply,forward,email,move,spam,remind">
-- note: currently move, spam, and remind are not supported actions. Older version of the API which call
-- the deprecated cmd=list (instead of cmd=search&q=) will not see reply, forward, or email operations
-- in the case listing

<ixBug>123</ixBug> -- case number
<ixBugParent>234</ixBugParent> -- parent case number
<ixBugChildren>456,876</ixBugChildren> -- subcase numbers
<tags> -- tags
  <tag><![CDATA[first]]></tag>
  <tag><![CDATA[second]]></tag>
  <tag><![CDATA[third]]></tag>
</tags>
<fOpen>true</fOpen> -- true if open, false if closed
<sTitle>Duck, Duck... but No Goose!</sTitle> -- title
<sLatestTextSummary>I searched the docs, but no goose!</sLatestTextSummary> -- short string with case's latest comment
<ixBugEventLatestText>1151</ixBugEventLatestText> -- ixBugEvent for latest event with actual text comment
<ixProject>22</ixProject> -- project id
<sProject>The Farm</sProject> -- project name
<ixArea>35</ixArea> -- area id
<sArea>Pond</sArea> -- area name
<ixGroup>6</ixGroup> -- group id
<ixPersonAssignedTo>1</ixPersonAssignedTo> -- person case is assigned to (id)
<sPersonAssignedTo>Old MacDonald</sPersonAssignedTo> -- person case is assigned to (name)
<sEmailAssignedTo>grandpa@oldmacdonald.com</sEmailAssignedTo> -- email of person case is assigned to
<ixPersonOpenedBy>2</ixPersonOpenedBy> -- person case was opened by (id)
<ixPersonResolvedBy>2</ixPersonResolvedBy> -- person case was resolved by (id)
<ixPersonClosedBy></ixPersonClosedBy> -- person case was closed by (id)
<ixPersonLastEditedBy>0</ixPersonLastEditedBy> -- person case was last edited by (id)
<ixStatus>2</ixStatus> -- status (id)
<sStatus>Geschlossen (Fixed)</sStatus> -- status (name)
<ixPriority>3</ixPriority> -- priority (id)
<sPriority>Must Fix</sPriority> -- priority (name)
<ixFixFor>3</ixFixFor> -- fixfor (id)
<sFixFor>Test</sFixFor> -- fixfor (name)
<dtFixFor>2007-05-06T22:47:59Z</dtFixFor> -- date of fixfor (date)
<sVersion></sVersion> -- version field (custom field #1)
<sComputer></sComputer> -- computer field (custom field #2)
<hrsOrigEst>0</hrsOrigEst> -- hours of original estimate (0 if no estimate)
<hrsCurrEst>0</hrsCurrEst> -- hours of current estimate
<hrsElapsed>0</hrsElapsed> -- total elapsed hours -- includes all time from time intervals PLUS hrsElapsedExtra time
<c>0</c> -- number of occurrences (minus 1) of this bug (increased via bugzscout)
-- to display the actual number of occurrences, add 1 to this number
<sCustomerEmail></sCustomerEmail> -- if there is a customer contact for this case, this is their email
<ixMailbox>0</ixMailbox> -- if this case came in via dispatcho, the mailbox it came in on
<ixCategory>1</ixCategory> -- category (id)
<sCategory>Feature</sCategory> -- category (name)
<dtOpened>2007-05-06T22:47:59Z</dtOpened> -- date case was opened
<dtResolved>2007-05-06T22:47:59Z</dtResolved> -- date case was resolved
<dtClosed>2007-05-06T22:47:59Z</dtClosed> -- date case was closed
<ixBugEventLatest>1151</ixBugEventLatest> -- latest bugevent
<dtLastUpdated>2007-05-06T22:47:59Z</dtLastUpdated> -- the date when this case was last updated
<fReplied>false</fReplied> -- has this case been replied to?
<fForwarded>false</fForwarded> -- has this case been forwarded?
<sTicket></sTicket> -- id for customer to view bug (bug number + 8 letters e.g. 4003_XFLFFFCS)
<ixDiscussTopic>0</ixDiscussTopic> -- id of discussion topic if case is related
<dtDue></dtDue> -- date this case is due (empty if no due date)
<sReleaseNotes></sReleaseNotes> -- release notes
<ixBugEventLastView>1151</ixBugEventLastView> -- the ixBugEventLatest when you last viewed this case
<dtLastView>2007-05-06T22:47:59Z</dtLastView> -- the date when you last viewed this case
<ixRelatedBugs>345,267,2920</ixRelatedBugs> -- comma separated list of other related case numbers
<sScoutDescription>Main.cpp:165</sScoutDescription> -- if this case is a Scout case, this ID is the unique identifier
<sScoutMessage>Please contact us or visit our knowledge base to resolve.</sScoutMessage> -- this is the message
-- displayed to users when they submit a case that matches this sScoutDescription
<fScoutStopReporting>false</fScoutStopReporting> -- whether we are still recording occurrences of this crash or not
<fSubscribed>true</fSubscribed> -- true if you are subscribed to this case, otherwise false

</case>
</cases>
 

BugEvents:

<events>
<event ixBugEvent="174" ixBug="13">

<ixBugEvent>174</ixBugEvent> -- Identity field in the database for this event
<evt>4</evt> -- Number for type of event, see event codes
<sVerb>Assigned to Captain Caveman</sVerb> -- Description of event in English always
<ixPerson>3</ixPerson> -- Identity field of the person who made this event happen
<sPerson>Mikey</sPerson> -- Person's full name
<dt>2007-05-06T22:47:59Z</dt> -- Date event happened (in RFC822 UTC format)
<s>Up up and away!</s> -- The text of the event (if this is an email, this is a simple view of the message)
<fEmail>false</fEmail> -- True if it is an email event
<bExternal>false</bExternal> -- True if this case was created via an incoming email, discussion topic, or BugzScout
<sChanges>Project changed from 'Inbox' to 'Cave'.</sChanges> -- Description of changes to the case during this event
<evtDescription>Captain Caveman von Mikey zugewiesen</evtDescription> -- Description of event in YOUR language (in this case German)

<rgAttachments>
<attachment>
<sFileName>Test Word.doc</sFileName> -- name of the attached file
<sURL>default.asp?pg=pgDownload&amp;pgType=pgAttachment&amp;ixBugEvent=756&amp;sPart=2&amp;sTicket=&amp;sFileName=Test%20Word.doc</sURL> -- url to hit to get the contents of the attached file (add on token=<yourtoken>)
</attachment>
</rgAttachments>

-- if the event is an email (fEmail == true) then there are additional fields --

<sFrom>"JJ Walker" <jj@dynomite.org></sFrom> -- the from header from the message
<sTo>good@times.org</sTo> -- the to header from the message
<sCC></sCC> -- the cc header from the message
<sBCC></sBCC> -- the bcc header from the message (if readable)
<sReplyTo></sReplyTo> -- the replyto header from the message
<sSubject></sSubject> -- the subject header from the message
<sDate>5 Jun 07 21:07:54 GMT</sDate> -- the date header from the message (exactly as it appears usually rfc822 date)
<sBodyText></sBodyText> -- the body plaintext from the message
<sBodyHTML></sBodyHTML> -- the message formatted in html

</event>
</events>

Projects:

<projects>
  <project>
    <ixProject>68</ixProject> -- project id
    <sProject>The Farm</sProject> -- project name
    <ixPersonOwner>6</ixPersonOwner> -- person who is the default owner for this project (id)
    <sPersonOwner>Old MacDonald</sPersonOwner> -- name of owner
    <sEmail>grandpa@oldmacdonald.com</sEmail> -- email of owner
    <sPhone>555-294-4778</sPhone> -- phone of owner
    <fInbox>false</fInbox> -- true if this is the Inbox project
    <iType>1</iType> -- type of group this project is part of (1 = client / 2 = dept)
    <ixGroup>1</ixGroup> -- group (id) this project is part of
    <sGroup>Internal</sGroup> -- name of group this project is part of
  </project>
</projects>

Areas:

<areas>
  <area>
    <ixArea>53</ixArea> -- area id
    <sArea>Bug</sArea> -- area name
    <ixProject>23</ixProject> -- project (id) this area belongs to
    <sProject>Antioch, CA</sProject> -- project (name) this area belongs to
    <ixPersonOwner></ixPersonOwner> -- default owner of this area. if empty then use project owner
    <sPersonOwner></sPersonOwner> -- name of owner of this area. if empty then use project owner
    <nType>0</nType> -- type of area: 0 = normal, 1 = Not Spam, 2 = Undecided, 3 = Spam (Inbox areas only)
    <cDoc>0</cDoc> -- number of documents trained into area (autosorted areas only)
  </area>
</areas>

FixFors:

<fixfors>
  <fixfor>
    <ixFixFor>1</ixFixFor>
    <sFixFor>Undecided</sFixFor>
    <fDeleted>0</fDeleted>
    <dt/>
    <dtStart/>
    <sStartNote/>
    <setixFixForDependency/>
    <ixProject/>
    <sProject/>
  </fixfor>
  <fixfor>
    <ixFixFor>2</ixFixFor>
    <sFixFor>2005.1</sFixFor>
    <fDeleted>0</fDeleted>
    <dt>2005-12-05T00:00:00Z</dt>
    <dtStart>2005-10-01T00:00:00Z</dtStart>
    <sStartNote>Can't start work until the hardware arrives.</sStartNote>
    <setixFixForDependency><ixFixFor>3</ixFixFor></setixFixForDependency>
    <ixProject>5</ixProject>
    <sProject>New York City</sProject>
  </fixfor>
</fixfors>

Priorities:

<priorities>

<priority>
<ixPriority>1</ixPriority> -- priority id
<sPriority>Very Urgent</sPriority> -- priority name
</priority>
<priority>
<ixPriority>2</ixPriority>
<sPriority>Urgent</sPriority>
</priority>
...

</priorities>

Categories:

<categories>
  <category>
    <ixCategory>1</ixCategory> -- category id
    <sCategory>Bug</sCategory> -- category name
    <sPlural>Bugs</sPlural> -- category plural name
    <ixStatusDefault>2</ixStatusDefault> -- when a case of this category type is resolved, the status id of the default (selected) status
    <fIsScheduleItem>false</fIsScheduleItem> -- true if this is a schedule item category
  </category>
  <category>
    <ixCategory>2</ixCategory>
    <sCategory>Feature</sCategory>
    <sPlural>Features</sPlural>
    <ixStatusDefault>8</ixStatusDefault>
    <fIsScheduleItem>false</fIsScheduleItem>
  </category>
</categories>
 

Working Schedule:

<workingSchedule>
    <ixPerson>2</ixPerson> -- person owner (id) of this schedule
    <nHoursPerDay>8</nHoursPerDay> -- hrs of day that are actually devoted to work 
    <nWorkdayStarts>9</nWorkdayStarts> -- military hour that workday starts 9am = 9 / 5pm = 17
    <nWorkdayEnds>17</nWorkdayEnds> -- military hour that workday ends 9am = 9 / 5pm = 17
    <fHasLunch>true</fHasLunch> -- whether there is time off for lunch
    <nLunchStarts>12</nLunchStarts> -- military hour that lunch starts
    <hrsLunchLength>0.5</hrsLunchLength> -- hours long that lunch lasts
    <dtLastUpdated>2007-05-06T22:39:31Z</dtLastUpdated> -- the date these values were last changed
    <rgWorkDays> -- if value is true, then it is considered a workday
        <sunday>false</sunday>
        <monday>true</monday>
        <tuesday>true</tuesday>
        <wednesday>true</wednesday>
        <thursday>true</thursday>
        <friday>true</friday>
        <saturday>false</saturday>
    </rgWorkDays>
</workingSchedule>

Intervals:

<intervals>
  <interval>
    <ixBug>2</ixBug> -- case id for this interval
    <ixInterval>8</ixInterval> -- interval (id) 
    <dtStart>9</dtStart> -- start time of interval
    <dtEnd>17</dtEnd> -- end time of interval
    <sTitle>1</sTitle> -- title of case
    <ixPerson>12</ixPerson> -- person this interval applies to
  </interval>
</intervals>

People:

<people>
  <person>
    <ixPerson>11</ixPerson> -- person (id)
    <sFullName>Old MacDonald</sFullName> -- person name
    <sEmail>grandpa@oldmacdonald.com</sEmail> -- person email
    <sPhone></sPhone> -- person phone
    <fAdministrator>false</fAdministrator> -- true if user is a site admin
    <fCommunity>false</fCommunity> -- true if user is a community user
    <fVirtual>false</fVirtual> -- true if user is a virtual user
    <fDeleted>false</fDeleted> -- true if account is inactive
    <fNotify>true</fNotify> -- true if user receives email notifications
    <sHomepage></sHomepage> -- homepage url
    <sLocale>en-us</sLocale> -- The locale code for the date/number language (i.e., "en-us") ( "*" means use browser format )
    <sLanguage>en-us</sLanguage> -- The locale code for the UI language (i.e., "en-us") ( "*" means use browser format )
    <sTimeZoneKey>Eastern Standard Time</sTimeZoneKey> -- A key that defines the time zone setting for this person's account 
    (i.e., "Eastern Standard Time"). The values for this setting are operating system dependent.
    ( "*" means use fogbugz default )

    <fExpert>false</fExpert> -- No longer used
  </person>
</people>

Discussion Thread

<topic>
  <post>
    <ixDiscussTopic>2</ixDiscussTopic>
    <ixDiscussTopicParent>0</ixDiscussTopicParent>
    <sHeadline>test headline</sHeadline>
    <sFullName>fogtest</sFullName>
    <sURL/>
    <dt>2007-06-25T20:24:50Z</dt>
    <sPost>message</sPost>
    <fModerator>true</fModerator>
    <fAuthorized>true</fAuthorized>
  </post>
  <post>
    <ixDiscussTopic>3</ixDiscussTopic>
    <ixDiscussTopicParent>2</ixDiscussTopicParent>
    <sHeadline>test headline</sHeadline>
    <sFullName>fogtest</sFullName>
    <sURL/>
    <dt>2007-06-25T20:39:30Z</dt>
    <sPost>another message</sPost>
    <fModerator>true</fModerator>
    <fAuthorized>true</fAuthorized>
  </post>
</topic>

Discussion (includes topics)

<discussion>
  <sFullName>test</sFullName>
  <sURL>http://localhost/fb/?test</sURL>
  <sTagLineHTML>test</sTagLineHTML>
  <topic>
    <post>
      <ixDiscussTopic>4</ixDiscussTopic>
      <ixDiscussTopicParent>0</ixDiscussTopicParent>
      <sHeadline>a second topic</sHeadline>
      <sFullName>fogtest</sFullName>
      <sURL/>
      <dt>2007-06-25T20:39:47Z</dt>
      <sPost>new topic message</sPost>
      <fModerator>true</fModerator>
      <fAuthorized>true</fAuthorized>
    </post>
  </topic>
  <topic>
    <post>
     ...
    </post>
  </topic>
</discussion>

Discussion Group (without topics)

<discussions>
  <discussion>
    <sFullName>test</sFullName>
    <sURL>http://localhost/fb/?test</sURL>
    <sTagLineHTML>test</sTagLineHTML>
    <ixDiscussGroup>1</ixDiscussGroup>
  </discussion>
</discussions>

Checkins

<checkins>
  <checkin>
    <ixCVS>28444</ixCVS>
    <ixBug>403416</ixBug>
    <sFile>trunk/fogcreek/FogBugz/Website/snippet.js</sFile>
    <sPrev>0</sPrev>
    <sNew>22878</sNew>
<sRepo/>
  </checkin>
</checkins>

Mailboxes

<mailboxes>
  <mailbox>
    <ixMailbox>1</ixMailbox>
    <sEmail>"customer support" &lt;customer@company.com&gt;</sEmail> -- the email address from mailbox settings
    <sEmailUser>"Jonas Jalopy" &lt;customer@company.com&gt;</sEmailUser> -- the "personal" email address with your name
    <sTemplate>-- Sincerely, Customer Service</sTemplate> -- the automatic message reply text or "signature"
  </mailbox>
</mailboxes>

Settings

<settings>
  <sTimeZoneKey>Eastern Standard Time</sTimeZoneKey> -- this user's time zone
  <nTimeZoneOffset>-14400</nTimeZoneOffset> -- offset in seconds from UTC for this user
  <sServerTime>2007-10-05T11:34:14Z</sServerTime> -- current time on the FogBugz server
  <cols>sCategory,ixBug,sLatestTextSummary,sStatus,ixPersonOpenedBy,sPriority</cols> -- an approximation of the columns in the user's current filter
</settings>

Evidence-Based Scheduling

<shipDate>
  <ixShipDate>704843</ixShipDate>
  <ixFixFor>281</ixFixFor>
  <ixPriority>7</ixPriority>
  <dtCalc>2008-12-06T06:01:58Z</dtCalc> -- The date and time when this calculation was performed.
  -- The 5, 50, and 95% confidence completion dates calculated --
  <dtLow>2009-01-26T22:26:46Z</dtLow>
  <dtMid>2009-02-18T19:23:12Z</dtMid>
  <dtHigh>2009-03-10T20:52:10Z</dtHigh>
  -- The 5, 50, and 95% confidence sums of projected hours remaining to complete in this FixFor and all preceding FixFors in its project. --
  <hrsLow>0</hrsLow>
  <hrsMid>0</hrsMid>
  <hrsHigh>0</hrsHigh>
  -- The 5, 50, and 95% confidence sums of projected hours remaining to complete in ths FixFor only. --
  <hrsLowThis>0</hrsLowThis>
  <hrsMidThis>0</hrsMidThis>
  <hrsHighThis>0</hrsHighThis>
  <dtOfficial>2009-02-27T05:00:00Z</dtOfficial>-- The user-supplied official ship date fo this FixFor at the time of calculation.
  <fCompleted>false</fCompleted>
</shipDate>

<estimator>
  <ixPerson>29</ixPerson>
  <rgdblRatioSmall>
    <array>
      <item>0</item>
      <item>0.0599074074074074</item>
      <item>0.0616666666666667</item>
      <item>0.08</item>
      <item>0.108333333333333</item>
      <item>0.122222222222222</item>
      ...
    </array>
  </rgdblRatioSmall>
  <rgdblRatioBig>
    <array>
      <item>0</item>
      <item>0</item>
      <item>0.256732026143791</item>
      <item>0.333586805555556</item>
      <item>0.434944444444444</item>
      <item>0.466884531590414</item>
      ...
    </array>
  </rgdblRatioBig>
</estimator>

 

Error Codes

Event Codes