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. The name of a job is batch_ID_N where ID is the batch ID and N is the number of the job.

Input:

<query_job>
   <authenticator>X</authenticator>
   <name>X</name>
</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