Overview:
Each of the following commands accept “ixPersonEditedBy” and “dt” parameters from Site Admins to enable accurate imports with the API. Note that setting ixPersonEditedBy when using the command cmd=new sets who opened the case. For Custom Fields and other plugin fields, see this article.
Audience:
Customer Facing Information.
Step-By-Step Guide:
- To edit a case, send one of this commands: cmd=new and cmd=edit and cmd=assign and cmd=reactivate and cmd=reopen. The possible arguments are described below:
ixBug – omitted for cmd=new – optional
If supplied, the new case is assigned this number. This functionality is provided for importing cases from another system. You must import them in order from lowest to highest case number.
ixBugParent
Make this case a subcase of another case
ixBugEvent – omitted for cmd=new – optional
If supplied, and this is not equal to the latest bug event for the case, you will receive error code 9 back to show that you were working with a “stale” view of the case.
tags
When searching for the tags column via the API, returns a <tags> element with a <tag> for each tag in the case.
sTags
When editing a case, use the sTags column and submit a comma-delimited list of the tags associated with the case. Existing tags omitted from this list will be removed.
sTitle
ixProject (or sProject)
If the user associated with the API Token making the call does not have Modify permissions on the project specified, the case will be opened in the first project on which the user does have Modify permission. If the user does not have Modify on any projects, the return will be Error Code 13: Insufficient Permissions.
ixArea (or sArea)
ixFixFor (or sFixFor – searches project first, then global fixfors)
ixCategory (or sCategory)
ixPersonAssignedTo (or sPersonAssignedTo)
ixPriority (or sPriority)
dtDue
hrsCurrEst
Sets the current estimated time for the case. The first instance of time logged against the case set the most recent current estimate as the original estimate. Future edits with hrsCurrEst will change the current estimate, and the original estimate will remain the same.
hrsElapsedExtra
This sets the additional non-timesheet time on a case. (i.e. if there was an hour long time interval for the case and you set hrsElapsedExtra to 2, then the total hrsElapsed would be 3)
dblStoryPts
Sets the Story Points for a case.
sVersion
sComputer
sCustomerEmail
Case correspondent field
ixMailbox
If you set sCustomerEmail, you’ll want to set this too… otherwise you won’t be able to reply to this case
sScoutDescription – used only with cmd=new
If you set this, and FogBugz finds a case with this sScoutDescription, it will append to that case unless fScoutStopReporting is true for that case, and then it will do nothing.
sScoutMessage
The message you are supposed to display to users for this case
fScoutStopReporting
Set this to 1 if you don’t want FogBugz to record any more of these types of cases
sEvent
Text description of the bug event; or HTML if fRichText is 1
fRichText
If set to 1, then sEvent is interpreted as HTML (only available for FogBugz On Demand or FogBugz On Site)
cols
The columns you want returned about this case. Also includes some columns not available in the UI search
sTicket: The ticket for a case, which can be turned into a public ticket URL
https://<FogBugz site>.fogbugz.com/default.asp?<sTicket>
File1, File2, File3, etc
Upload files to the case, no limit to the number of files (constrained only by the max upload limit on the web server). Use the enctype=”multipart/form-data” form type
nFileCount – Required with File1, File2, etc
Number of file parameters included in the request. If this is absent, only File1 will upload.
- If any fields are omitted, they will not be changed.
- An example of an HTML page which submits to the API to create a new case and upload a file 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.
- Use cmd=resolve as the 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.
- Use cmd=close as the same as cmd=edit. Note: 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).
- Use cmd=email, cmd=reply, and cmd=forward as the same as cmd=edit
-
Can have additional arguments: sFrom (required), sTo (required), ixBug (required), sEvent (required, body of email), sSubject, sCC, sBCC and 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“
-
It is not required, but we recommend making sure the case you email from has sCustomerEmail and ixMailbox set.
-
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, and best practices suggest using a matching ixMailbox value for the case.
See also the full XML API documentation.
Priyanka Bhotika
Comments