[[PageOutline]]
= APIs for remote job submission =

This document describes APIs for remotely submitting jobs
to a BOINC server.
The APIs support the submission of large '''batches''' of jobs,
such as parameter sweeps.
The APIs can be used, for example, to create web interfaces for job submission,
such as might be found in a science portal web site:

[[Image(submit.png)]]

BOINC provides a PHP library that implements the API.
The underlying web services are implemented as HTTP/XML RPCs,
and it is easy to create bindings in other languages.

This system is coupled with new
[MultiUser multi-user project features].
In particuler, users can submit jobs only if they have been given access
(via a web interface) by project administrators,
and admins can restrict the apps for which
each user is allowed to submit jobs.

== PHP interface ==

The following functions are provided in the file
[/trac/browser/trunk/boinc/html/inc/submit.inc submit.inc],
which is independent of other BOINC code and can be used in the Portal web code.

=== boinc_estimate_batch() ===

This function returns an estimate of the elapsed time
required to complete a given batch.

Arguments: a "request object" whose fields include
 * '''project''': the project URL
 * '''authenticator''': the user's authenticator
 * '''app_name''': the name of the application for which jobs are being submitted
 * '''jobs''': an array of job descriptors (see example)

Return value: a 2-element array containing
 * The estimate, in seconds
 * An error message (null if success)

Example usage:
{{{
$req->project = "http://foo.bar.edu/test/";
$req->authenticator = "xxx";
$req->app_name = "uppercase";
$req->jobs = array();

$f->source = "http://foo.bar.edu/index.php";
$f->name = "in";
$job->input_files = array($f);

for ($i=10; $i<20; $i++) {
	$job->rsc_fpops_est = $i*1e9;
	$job->command_line = "--t $i";
	$req->jobs[] = $job;
}

list($e, $errmsg) = boinc_estimate_batch($req);
if ($errmsg) {
	echo "Error: $errmsg\n";
} else {
	echo "The batch will take about $e seconds to complete\n";
}
}}}

=== boinc_submit_batch() ===

Similar to '''boinc_estimate_batch()''', but submits the batch.

Result: a 2-element array containing
 * The batch ID
 * An error message (null if success)

=== boinc_query_batches() ===

Returns a list of this user's batches, both in progress and complete.

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above.

Result: a 2-element array.
The first element is an array of objects describing batches,
with the following fields:
 * '''batch_id''': batch ID
 * '''fraction_done''': a number 0..1 giving the fraction of the batch that has been completed
 * '''create_time''': when the batch was submitted
 * '''est_completion_time''': an updated estimate of completion time
 * '''njobs''': the number of jobs in the batch

=== boinc_query_batch() ===

Gets batch details.

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above
 * '''batch_id''': specifies a batch.

Result: a 2-element array.
The first element is an array of objects describing jobs
within the batch, with the following fields:

 * '''job_id''': the job ID
 * '''canonical_instance_id''':
  if the job has been completed and validated, the ID of a valid instance
 * '''n_outfiles''': the number of output files

=== boinc_query_job() ===

Gets job details.

Argument: a request object with elements:
 * '''project''' and '''authenticator''': as above
 * '''job_id''': specifies a job.

Result: a 2-element array.
The first element is an object with the following fields:
 * '''instances''': an array of job instance descriptors

Each job instances descriptor is an object with the following fields:
 * '''name''': the instance's name
 * '''id''': the ID of the corresponding result record

=== boinc_abort_batch() ===

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above,
 * '''batch_id''': specifies a batch.

Result: an error message, null if successful

=== boinc_get_output_file() ===

Get a URL for a particular output file.

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above,
 * '''instance_name''': specifies a job instance,
 * '''file_num''': the ordinal number of one of the output files.

Result: a URL from which the output file can be downloaded.

=== boinc_get_output_files() ===

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above,
 * '''batch_id''': specifies a batch.

Result: a URL from which a zipped archive of all
output files from the batch can be downloaded
(only the outputs of "canonical" instances are included).

=== boinc_cleanup_batch() ===

Delete server storage (files, DB records) associated with a batch.

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above,
 * '''batch_id''': specifies a batch.

Result: an error message, null if successful

== HTTPS/XML interface ==

At a lower level, the APIs are accessed by sending a POST request,
using HTTPS, to PROJECT_URL/submit.php.
Bindings of these RPCs can be implemented in languages other than PHP.

The inputs and outputs of each function are XML documents.
If an operation fails, the output is of the form
{{{
<error>
   <message>X</message>
</error>
}}}
where X is an error message.

All operations include the authenticator of the user making the request.
This user must be marked as a "job submitter" in the BOINC database.

=== Describing a batch ===

A job is described by
{{{
<job>
   <rsc_fpops_est>X</rsc_fpops_est>
   [<command_line>C</command_line>]
   [<input_file>
      <source>URL or path</source>
      <name>physical_name</name>
   </input_file>]
   ... other input files
</job>
}}}

Each input file is specified either by a URL accessible to the server,
or by a path on the server.

A batch of jobs is described by:
{{{
<batch>
   <app_name>appname</app_name>
   <job>
      ...
   </job>
   ... more jobs
</batch>
}}}

=== Batch runtime estimation ===

This function estimates the completion time of a batch.
Input:
{{{
<batch_estimate>
   <authenticator>X</authenticator>
   <batch> ... </batch>
</batch_estimate>
}}}

Output:
{{{
<estimate>
   <seconds>X</seconds>
</estimate>
}}}

=== Submitting a batch ===

Input:
{{{
<batch_submit>
   <authenticator>X</authenticator>
   <batch> ... </batch>
</batch_submit>
}}}

Output:
{{{
<batch_id>N</batch_id>
}}}

=== Querying batches ===

Input:
{{{
<query_batches>
   <authenticator>X</authenticator>
</query_batches>
}}}

Output:
{{{
<batches>
   <batch>
      <id>N</id>
      <completed>0|1</completed>
      [<fraction_done>X</fraction_done>]
      {<completed_time>X</completed_time>]
   </batch>
   ...
</batches>
}}}

=== Querying a batch ===

Input:
{{{
<query_batch>
   <authenticator>X</authenticator>
   <batch_id>N</batch_id>
</query_batch>
}}}

Output:
{{{
<batch>
   <job>
      <id>N</id>
      <canonical_resultid>N</canonical_resultid>
      [<outfile>name</outfile>]
      ...
   </job>
</batch>
}}}

=== Aborting a batch ===

Input:

{{{
<abort_batch>
   <authenticator>X</authenticator>
   <batch_id>N</batch_id>
</query_batch>
}}}

== Implementation notes ==

New tables

{{{
batch
  id
  create_time
  logical_start_time
  logical_end_time
  estimated_completion_time
  njobs

user_submit
  user_id
  quota
  logical_start_time
  bool all_apps

user_app
  user_id
  app_id
}}}