MoleQueue JSON-RPC Specification

JSON-RPC specification
The JSON-RPC 2.0 specification is here. In a nutshell, the protocol consists of three message types: requests, responses, and notifications. Every request must be met with a reply, and a notification is simply a request object without the id member.

Requests are JSON objects with three name/value pairs:


 * method (String): The method requested.
 * params (Array or Object): A parameters for the requested method.
 * id (Value): A unique identifier.

Each request is met with a reply of the following format:


 * result (Object, Array, or Value): The result of the request. Must not exist if there was an error.
 * error (Error Object): A description of the error. Must not exist if no error occurred.
 * id (Value): Must be the same as the identifier used in the request.

The Error object must contain an integer error code ("code") and a descriptive error string ("message"). An optional "data" object may provide more detailed information.

As mentioned above, notifications follow the same format as requests, but will omit the id name/value pair.

Implementation
Click for details about the MoleQueue JSON-RPC Implementation.

Specifying files
Files may be represented by either referring to a location on a local filesystem or providing a file's contents. The {FileSpec}</tt> object in the following sample messages refers to either of the following forms:

Filesystem path:

or filename and contents:

Supported Messages
The following sections detail the requests, responses, and notifications that MoleQueue recognizes:

List of available Queues/Programs
To obtain a list of the available Queues and the programs supported by them, submit a request for the method "listQueues" with no parameters. MoleQueue will reply with an object containing a dictionary with user-set names identifying each queue, along with an array of the programs supported by each queue.

Client request:

Server response:

Request new job submission
Client request:

Additional (optional) parameters may be used to tweak job behavior further. Default values are provided in parenthesis: and the launch script template is then the job-specific generated launch script will be generated as This option can be used to add custom job-specific functionality for sufficiently advanced clients. Note that some keywords are hardcoded into MoleQueue; these are documented in the "Template Help" dialog of the MoleQueue server GUI. Any unrecognized keywords in the launcher template will be removed.
 * additionalInputFiles</tt>: ([]</tt>) An array of additional {FileSpec}</tt> objects indicating supplemental files needed for the job to run. These are placed in the working directories of the job, but not explicitly called by the executable.
 * cleanRemoteFiles</tt>: (false</tt>) If true, any remote working directories are deleted.
 * retrieveOutput</tt>: (true</tt>) If true, output files are copied back into the local working directory.
 * outputDirectory</tt>: (null</tt>) If not null, this must be a string specifying a path to place completed output files, instead of the local working directory.
 * cleanLocalWorkingDirectory</tt>: (false</tt>) If true, the local temporary working directory will be removed on successful job completion.
 * hideFromGui</tt>: (false</tt>) If true, the job will not be displayed in the MoleQueue GUI by default (useful for automated batch jobs).
 * popupOnStateChange</tt>: (true</tt>) If true, a notification popup will be displayed system tray when the job's state changes.
 * <tt>maxWallTime</tt>: (<tt>-1</tt>) The maximum time limit for a job to run in minutes. If less than or equal to zero, a queue-specific walltime is used instead. This option only has effect on remote queuing systems.
 * <tt>numberOfCores</tt>: (<tt>1</tt>) The number of processor cores to request for this job.
 * <tt>keywords</tt>: (<tt>{}</tt>) A dictionary of string pairs used to populate the launch script template. Dictionary keys identify keywords (enclosed in "$$[keyword]$$") in the launch script template to replace with the associated value. For example, if this member is

Server response:

<tt>moleQueueId</tt> is a identifier that is unique to this instance of MoleQueue.
 * If successful, some identifiers are returned:


 * If unsuccessful, an error is returned:

Cancel submitted job
Client request:

Parameter is the MoleQueue id of the job to cancel:

Server response:

Result is the MoleQueue id of the canceled job:

If the job does not exist or some other error occurs, a JSON-RPC error response is sent with the requested MoleQueue id as the error.data value:

Notification of job state change
When a job changes state, MoleQueue will send a notification to all active connections of the following form:

Valid states are:
 * <tt>None</tt>: Initial state of job, should never be entered.
 * <tt>Accepted</tt>: Job has been received and is being prepared (Writing input files, etc).
 * <tt>QueuedLocal</tt>: Job is being queued locally, either waiting for local execution or remote submission.
 * <tt>Submitted</tt>: Job has been submitted to a remote queuing system.
 * <tt>QueuedRemote</tt>: Job is pending execution on a remote queuing system.
 * <tt>RunningLocal</tt>: Job is running locally.
 * <tt>RunningRemote</tt>: Job is running remotely.
 * <tt>Finished</tt>: Job has completed.
 * <tt>Killed</tt>: Job has been canceled by the user.
 * <tt>Error</tt>: The job has encountered an error.
 * <tt>Unknown</tt>: The job's status is not known or invalid.

Request Job Information
A client can request information about a Job by submitting a lookupJob request and providing a MoleQueue id:

The server will respond with an object describing the Job's state using a similar JSON object as the submission request:

If the lookup fails (i.e. the request MoleQueue id is not known to the server), a simple error reply is sent with the requested MoleQueue id as the error.data value:

Adding File Handlers
Right-clicking on a job entry in MoleQueue will list applications that are able to open files in the job's working/output directories. MoleQueue maintains a collection of file handlers that store an executable along with a set of filename patterns that the application is known to handle. New handlers can be added with the <tt>registerOpenWith</tt> method:

The parameters to this method are:
 * <tt>name</tt>: The name of the application. Must be a non-empty string.
 * <tt>method</tt>: Specification of how to open the file. See <tt>MethodSpec</tt> definition below.
 * <tt>executable</tt>: The name of / path to the executable. If the path is not specified, the executable should be in the user's path.
 * <tt>patterns</tt> (optional): An array of JSON objects that specify filename patterns that may be opened by the executable (see below). There is no limit on the number of patterns that may be specified for a single handler. If no pattern is specified, a single catch-all pattern (<tt>{"wildcard": "*"}</tt>) is used by default.

If the handler is successfully registered with MoleQueue, a JSON-RPC response is sent with the string "<tt>success</tt>" as the result. If a handler with the same name already exists, a JSON-RPC error response is sent with an error code of 1.

Method specification
The <tt>MethodSpec</tt> may either specify an executable or an RPC call. The executable method requires an executable that will be used to open files. If the executable is not in the user's path, the full path to the executable must be specified:

To open files via an RPC call, the server and method must be specified as follows:

MoleQueue will use this information to send a message to a local socket of the form:

The server must send a response to the request. The contents of the response are not important, MoleQueue will only check for a valid JSON-RPC 2.0 reponse. If the MoleQueue does not receive a response within 3 seconds, it will alert the user that the request was not handled.

Pattern specification
Each pattern in the <tt>patterns</tt> array must have a member named "<tt>regexp</tt>" or "<tt>wildcard</tt>". This member specifies a string pattern to match filenames against. "<tt>regexp</tt>" entries are regular expressions that follow the | QRegExp RegExp2 format. The "<tt>wildcard</tt>" matching syntax is specified by the "WildCardUnix" QRegExp format documented on the same page. Both pattern types support an additional "<tt>caseSensitive</tt>" boolean option that can be used to toggle the case-sensitivity of the pattern. If not specified, case-sensitive matching is assumed.

Querying File Handlers
A list of all file handlers can be obtained with the following request:

The result is an array of GUI display names.

Removing File Handlers
A file handler can be removed from MoleQueue by sending the following request, using a name returned by <tt>listOpenWithNames</tt> for the <tt>params</tt> member.

If the file handler is successfully unregistered, the following response is sent.