= Bossa reference manual =

== Creating a Bossa project ==

First, [ServerIntro set up a BOINC server] and [MakeProject create a project].
You'll need PHP 5.2 or later (for JSON functions).
Say your project is called '''test_project''', your BOINC source directory is '''~/boinc''',
and your BOINC projects directory is '''~/projects'''.

Create Bossa's database tables as follows:
{{{
cd ~/boinc/db
mysql test_project < bossa_schema.sql
mysql test_project < bossa_constraints.sql
}}}

Create a Bossa application (see below) as follows:
{{{
cd ~/projects/test_project/html/ops
php bossa_setup_example.php
}}}

bossa_setup_example.php contains:
{{{
$ba = new BossaApp();
$ba->name = 'bossa_test';
$ba->user_friendly_name = 'Simple pattern recognition';
$ba->start_url = 'bossa_example.php';

if ($ba->insert($ba)) {
    echo "Added application '$ba->name'\n";
} else {
    echo "Couldn't add '$ba->name': ", mysql_error(), "\n";
}
}}}
You can edit this to change the application name
and front-end script name, if you like.

== Database tables and PHP structures ==

Until Bossa has good web-based administration tools,
you'll need to examine and modify its MySQL database directly,
using the command-line tool 'mysql'
or a web-based interface such as [http://www.phpmyadmin.net/ phpMyAdmin].

The database tables are as follows:

'''bossa_app''':
|| field name || type || meaning ||
|| id || integer || row ID, assigned by MySQL ||
|| create_time || integer || row creation time ||
|| name || varchar(255) || short name (internal use; no spaces) ||
|| user_friendly_name || varchar(255) || user-visible name (spaces OK) ||
|| long_jobs || tinyint || nonzero if user can have > 1 active job ||
|| start_url || varchar(255) || name (relative to project URL) of start script ||
|| deprecated || tinyint || nonzero if deprecated (don't show) ||
|| info || text || information (typically encoded in JSON) such as the criteria for which users to issue jobs to ||

'''bossa_job''':
|| field name || type || meaning ||
|| id || integer || row ID, assigned by MySQL ||
|| create_time || integer || row creation time ||
|| name || varchar(255) || a unique name for this job ||
|| app_id || integer || ID of bossa_app ||
|| info || text || job-specific info (file names etc.) typically JSON-encoded ||
|| batch || integer || batch number (use to group jobs) ||
|| time_estimate || integer || number of seconds this job is likely to take ||
|| time_limit || integer || give up if not completed after this number of seconds ||
|| more_needed || tinyint || nonzero if more completed instances of this job are needed ||
|| npending || integer || number of pending instances ||
|| nsuccess || integer || number of successfully completed instances ||
|| nsuccess_needed || integer || required number of successfully completed instances ||

'''bossa_job_inst''':
|| field name || type || meaning ||
|| id || integer || row ID, assigned by MySQL ||
|| create_time || integer || row creation time ||
|| job_id || integer || ID of bossa_job ||
|| user_id || integer || ID of user ||
|| finish_time || integer || time when finished, or zero ||
|| info || text || outcome info (usually JSON-encoded) ||

'''bossa_app_user''':
|| app_id || integer || ID of bossa_app ||
|| user_id || integer || ID of user ||
|| info || text || description of the user's skill or ranking at a given app, typically JSON-encoded ||

The Bossa PHP code uses the following classes:

 '''BossaApp, BossaJob, BossaJobInst'''::
  These correspond to the above tables, and have fields corresponding to each database field.  They offer various functions to insert, look up, and modify database rows.
 '''Bossa''':
  Various utility functions.

== Front-end scripts ==

== Adding jobs ==