Bossa reference manual

Abstractions

• A Bossa project has one or more applications.
• A application has a dynamic set of jobs.
• An application has a dynamic set of batches (groups of jobs).
• Each job has a set of job instances.
• A user is a person who volunteers to perform jobs.

Each has a corresponding table in a MySQL database.

Each application has an associated "time estimate" and "time limit"; if an instance is not completed within the time limit, is is considered "timed out".

Jobs may be marked as calibration jobs. These are jobs for which the answer is known in advance; their purpose is to estimate the accuracy of each user. Each application has a calibration job fraction: the probability with which calibration jobs are assigned.

Each job has a state, one of:

BOSSA_JOB_EMBARGOED: the job is not yet eligible to be issued.

BOSSA_JOB_IN_PROGRESS: the job is eligible to be issued.

BOSSA_JOB_DONE: the job has been finished successfully.

BOSSA_JOB_INCONCLUSIVE: the job has finished unsuccessfully (typically because a consensus was not reached).

Each job has a floating-point priority. Jobs are assigned to users in order of decreasing priority.

Each job, job instance, and user has associated opaque data - a PHP structure whose contents are determined by the project, not by Bossa. These structures are stored in the database.

For jobs, the opaque data typically contains the information needed to display the job to a user - e.g., the name of an image file. For calibration jobs, it would also contain the correct answer.

For instances, the opaque data typically contains the user's response to the job.

For users, the opaque data typically contains a representation of the user's "skill", possibly including:

• their score on a training course
• their performance on calibration tasks
• their performance based on validation

If a project has multiple applications, it could contain separate data for each application.

For some applications it is desirable to group users into levels (0, 1, ...). For example, level 0 might be average users, and level 1, expert users.

When levels are used, each job has a vector of priorities, one per level. Jobs are assigned to a particular user in order of decreasing priority for that user's level.

Job creation API

int bossa_app_lookup(string $app_name)

Returns the ID of the application with the given short name.

int bossa_batch_create(int $appid, string name, bool $calibration)

Creates a batch with the given name and returns its ID.

bool bossa_job_create(int $appid, int $batchid, mixed $app_data, bool $calibration)

Creates a job with the given app data. Initial priorities are one. Returns true on success.

Callback functions

Each application must define a set of functions, listed below. These are stored in a file project/html/inc/APPNAME.inc, where APPNAME is the application's short name.

bool job_show(object $job, object $instance, object $user)

Display the given job instance to the given user. Return true on success.

A job may consist of a single web page or a sequence of web pages. In either case the "done" action on the final page must go to the URL bossa_job_finished.php, passing it a GET argument bji consisting of the ID of the job instance.

job_issued(object $job, object $inst, object $user)

Called when the given instance has timed out.

job_finished(object $job, object $inst, object $user)

Called when the given instance has finished.

job_timed_out(object $job, object $inst, object $user)

Called when the given instance has timed out.

string job_summary(object $job)

Return a short string describing the job, for use in administrative pages. For example, this might return an image name hyperlinked to the image.

string instance_summary(object $info)

Return a string summarizing the opaque data for an instance.

string user_summary(object $user)

Return a string summarizing the opaque data for a user.

Bossa API

The interface of "job" objects is

mixed get_opaque_data()
array get_instances()
   // return array of all instances
array get_finished_instances()
   // return array of finished instances
bool set_priority(float $priority [int $level]}
   // set priority for the given level (default level is zero)
bool set_state(int $state)

The interface of "instance" objects is:

bool set_opaque_data(mixed $data)
mixed get_opaque_data()
object get_user()
   // return user to whom this instance was issued

"User" objects are accessed by first obtaining an object $user->bossa. The interface of the resulting object is:

mixed get_opaque_data()
bool set_opaque_data(mixed $data)
bool set_level(int $level)

Utility functions from bossa.inc:

bool bossa_lookup_job(int $instid, object &$job, object &$inst, object &$user)
   // Given an instance ID, look up the instance, its job, and its user

Some utility functions from html/inc/util.inc:

string get_str(string $name, bool $optional=false)
   // return a GET form variable, and undo the effects of PHP "magic quotes"
void page_head(string $title)
   // display the project's banner (as defined in html/project/project.inc)
void page_tail()
   // display the project's footer