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, which are used to group jobs.
• Each job has a set of job instances, in progress or completed.
• A user is a person who volunteers to perform jobs.

Each of these is represented by a table in a MySQL database.

Each application has an associated "time estimate" - shown to user - 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; this is 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 an associated app data - a PHP structure whose contents are determined by the project, not by Bossa. These structures are stored in the database.

For jobs, the app 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 app data typically contains the user's response to the job.

For users, the app 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 should keep separate data for each applications.

For some applications it is desirable to group users into discrete levels, with each level performing a variant of the job. The level of a user is represented as an integer in a fixed range.

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

API for job creation

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.

Application 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 app data for an instance.

string user_summary(object $user)

Return a string summarizing the app data for a user.