[[PageOutline]]
= Web services for remote job submission =

This document describes remote interfaces for remotely submitting jobs and batches of jobs
to a BOINC server.
The APIs are accessed by sending a POST request,
using HTTPS, to PROJECT_URL/job_control.php

The inputs and outputs of each API 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>
   [<command_line>C</command_line>]
   [<input_file>URL or path</input_file>]
   ... other input files
</job>
}}}

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

A batch of jobs is described by:
{{{
<batch>
   <app>appname</app>
   [<input_template>x</input_template>]
   [<output_template>x</output_template>]
   <job>...</job>
   ... more jobs
</batch>
}}}

The names of the input and output template files may be specified;
otherwise the defaults '''appname_in''' and '''appname_out''' are used.

== Batch runtime estimation ==

Estimates the completion time of a batch.
Input:
{{{
<batch_estimate>
   <authenticator>X</authenticator>
   <batch> ... </batch>
   [<priority>N</priority>]
</batch_estimate>
}}}

'''Priority''', if specified, is relative to other batches submitted by this user.

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

== Submitting a batch ==

Input:
{{{
<batch_submit>
   <authenticator>X</authenticator>
   <batch> ... </batch>
   [<priority>N</priority>]
</batch_submit>
}}}

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

== Querying jobs ==

The jobs in a batch are numbered starting from 0.

Input:
{{{
<query_job>
   <authenticator>X</authenticator>
   <batch_id>N</batch_id>
   <job_num>M</job_num>
</query_job>
}}}

Output:
{{{
<job_status>
   <aborted/>
   or
   <instance>
      <unsent/>
      or
      <hostid>N</hostid>
      <userid>M</userid>
      <runtime>X</runtime>
      <fraction_done>X</fraction_done>
   </instance>
   ... other instances
</job_status>
}}}

== Querying batches ==

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

Output:
{{{
<batch_status>
   <fraction_done>X</fraction_done>
   <jobs_completed>N</jobs_completed>
   <remaining_time>X</remaining_time>
</batch_status>
}}}

== Aborting jobs ==

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

Output:
{{{
<aborted/>
}}}

== Access control ==

Users can submit jobs only if they have been
given access (via a web interface) by project administrators.

In addition, project admins can allow users to submit jobs for any app,
or can designate which apps they can submit jobs to.

== Example usage ==
PHP:

{{{
$ch = curl_init("https://project.edu/job_control.php");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "request=
   <batch_estimate>
      <batch>
         <app>myappname</app>
         <job>
             <command_line>--t ALPHA</command_line>
         </job>
      </batch>
   </batch_estimate>
");
$reply = curl_exec($ch);
if (!$reply) die("HTTP op failed\n");
$r = simplexml_load_string($reply);
if (!$r) die("bad reply: $reply\n");
$name = $r->getName();
if ($name == 'estimate') {
    echo "estimate: ".(string)$r->seconds."\n";
} else if ($name == 'error') {
    foreach ($r->message as $msg) {
        echo "$msg\n";
    }
} else {
    die("bad reply\n");
}
}}}

== 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
}}}