Access and modify FogBugz entities

FogBugz Plugin API > Access FogBugz Entities

The FogCreek.FogBugz.Plugin.Entity and FogCreek.FogBugz namespaces contains all the objects in FogBugz. These can be accessed via the plugin API. FogBugz objects include ones you know well from your experience as a user:

• CBug
• CPerson
• CWikiPage
• CFilter
• ...

There are also objects which will likely be new to you.

• CNavMenuLink - a link in the various menus of FogBugz (Admin, Options, Extras..)
• CFilterTool - The tools at the top right of the grid view (Save, Columns...)
• CWikiExternalLink - FogBugz keeps track of inbound and outbound links in wikis
• ...

For plugin-specific database data, you can create your own tables and run queries against them, but for FogBugz data, you should use a FogBugz object whenever possible, and only run queries directly if you need for example, special joins for a custom report. Generic queries are not guaranteed to work across database upgrades and are read-only. Using FogBugz entities solves both problems.

If your plugin needs to access FogBugz entities, include the following namespace in your code file:

using FogCreek.FogBugz.Plugins.Entity;

To load an object, use your plugin's instance of the api. The example below load bug number ixBug, sets its FixFor to number 123 and sets the due date to 5 days from now. The case is commited with a(n optional) message. Whenever you use FogBugz entities, make sure to check permissions as described in FogBugz Permissions in Plugins.

CBug bug = api.Bug.GetBug(ixBug);
if (bug.IsWritable)
{
bug.ixFixFor = 123;
bug.dtDue = api.TimeZone.UTCFromSTZ(DateTime.Now.AddDays(5));
bug.Commit("Updated automatically by Plugin");
}

Operations on other entities are similar. The code below loads the current person object, sets the working on to case 123 and commits the person to the database:

CPerson personCurrent = api.Person.GetCurrentPerson();
personCurrent.ixBugWorkingOn = 123;
personCurrent.Commit();

You can also load multiple entity objects via an object query. (make sure to reference the FogCreek.FogBugz.Database.Entity namespace) For example, to load all bugs with greater than 5 hours elapsed:

CBugQuery query = api.Bug.NewBugQuery();
/* if the following line is omitted, only the cases the current
* user can see will be returned. permissions are still enforced
* on each CBug object returned */
query.ExcludeUnreadable = false;
//query.IgnorePermissions = true;
query.AddWhere("Bug.hrsElapsed > 5");
CBug[] rgBug = query.List();

See Generic Database Access for full details on entity queries.

FogBugz will only grant your plugin permissions the current user has unless you explicitly override them. See Entity Member Security for more information. For a example plugins which edit cases, see How To Edit Cases and CVS Commits as BugEvents.