Entity Member Security

FogBugz entities are special objects in the FogBugz API that correspond to persistent objects in the database, and have special permissions attached to them. In the Plugin API, these objects enforce the permissions of the current user by throwing a FogBugzSecurityException any time an operation is performed and the current user doesn't have sufficient permissions.

Object Permissions

Permissions generally fall into one of three types:

Read Permissions
- Allow the current user to see the properties of an object, but not modify them.
- Typically getting a property requires read permissions, as do certain methods that return information on an object such as CCategory.IconHtml
- Check this permission with IsReadable or IsReadableByPerson
Write Permissions
- Allow the current user to write the properties of an object and commit them to the database.
- Typically setting a property requires write permissions, as do methods that modify properties or save them to the database, such as CBug.Commit or CCategory.Delete
- Check this permission with IsWritable or IsWritableByPerson
(rare) Write-Within Permissions
- Allow the current user to create and modify objects within a section. For example, write-within permissions on a project allow a user to create new cases within that project.
- Currently only projects, wikis, and discussion groups specify write-within permissions
- Check this permission with CProject.CanWriteBugs or CWiki.CanWriteWikiPages

Permissions Example

If a public user accesses a plugin page, and the plugin page attempts to display the title of a bug an exception is thrown:

public string PageDisplay()
{
CBug bug = api.Bug.GetBug(3869);
return bug.sTitle;
}

Result:

FogBugzSecurityException: The user does not have permission to read this object.

A similar exception is thrown if a property is set:

bug.sTitle = "New Title";

Result:

FogBugzSecurityException: The user does not have permission to write this object.

Special Name Fields

Some objects have name fields that have special behavior: if the current user does not have permission to read the object, instead of an exception being thrown a generic name is returned (for example "User 14" for a person object with ixPerson=14). The fields that work this way are:

Area.sArea
Category.sCategory
FixFor.sFixFor
Person.sFullName
Project.sProject
Priority.sPriority
Status.sStatus
Template.sTemplate
Wiki.sWiki
Workflow.sWorkflow

Overriding Permissions

Permissions on an object can be overridden by setting object.IgnorePermissions = true. If IgnorePermissions is true, then all permission checks on that object will be ignored.

It is considered best-practice to set IgnorePermissions before the call that needs to ignore permissions, then immediately set IgnorePermissions to false.

public string PageDisplay()
{
    CBug bug = api.Bug.GetBug(3869);

    bug.IgnorePermissions = true;
    string sTitle = bug.sTitle;
    bug.IgnorePermissions = false;

    return sTitle;
}

Unsafe Methods

Some methods are considered to always be unsafe, because permissions cannot be enforced on them. These methods will always throw a FogBugzSecurityException if IgnorePermissions is not true.

The most common examples of this are the QueryField method and the GetDataSet method, both of which deal with raw records from the database. Because they access raw values, no permissions are enforced, so IgnorePemrissions must be set to true.

Example:

public string PageDisplay()
{
    CPerson person = api.Person.GetCurrentPerson();

    CProjectQuery query = api.Project.NewProjectQuery();

    // load the project owner's name with the project
    query.AddSelect("Person.sFullName AS sFullNameOwner");
    query.AddInnerJoin("Person", "person.ixPerson = project.ixPersonOwner");

    CProject[] rgProject = query.List();
    if (rgProject.Length > 0)
    {
        CProject project = rgProject[0];

        // make sure the current user has permission to see this person
        if (person.CanSee(project.ixPersonOwner))
        {
            project.IgnorePermissions = true;
            return project.QueryField("sFullNameOwner").ToString();
        }
    }

return null;
}

In this example, the name of the project owner is loaded at the same time as the project to avoid unnecessary database queries. If the current user is allowed to see that person, then permission checks are temporarily disabled in order to access the QueryField.

Heartbeat (Maintenance) Permissions

Code that runs during the background maintenance process (the interfaces here) is run as a special user which has permissions to modify anything in FogBugz (like a site admin). To do so, your plugin will need to set IgnorePermissions to true.

Wiki