MoleQueue JSON-RPC Specification

JSON-RPC specification

This is the proposed communication protocol, it is neither final nor implemented!

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.

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:

{
  "jsonrpc": "2.0",
  "method": "listQueues",
  "id": "XXX"
}

Server response:

{
  "jsonrpc": "2.0",
  "result": {
    "Big cluster SGE" : {
      "programs" : [ "GAMESS",
                     "MOPAC",
                     "Gaussian",
                     "NWChem"
                   ]
    },
    "Remote cluster PBS" : {
      "programs" : [ "GAMESS",
                     "MOPAC",
                     "Gaussian",
                     "NWChem"
                   ]
    },
    "Local" : {
      "programs" : [ "GAMESS",
                     "MOPAC",
                     "Gaussian",
                     "NWChem"
                   ]
    }
  },
  "id": "XXX"
}

Request new job submission

Client request:

Two supported forms:

• Input file provided as a single string

{
  "jsonrpc": "2.0",
  "method": "submitJob",
  "params": {
    "queue": "Remote cluster PBS",
    "program": "MOPAC",
    "description": "PM6 H2 optimization",
    "inputAsString": "PM6\n\nH 0.0 0.0 0.0\nH 1.0 0.0 0.0\n"
  },
  "id": "XXX"
}

• Input file provided as a path

{
  "jsonrpc": "2.0",
  "method": "submitJob",
  "params": {
    "queue": "Remote cluster PBS",
    "program": "MOPAC",
    "description": "PM6 H2 optimization",
    "inputAsPath": "/path/to/local/input/file/named/h2.mop"
  },
  "id": "XXX"
}

Additional (optional) parameters may be used to tweak job behavior further. Default values are provided in parenthesis:

• cleanRemoteFiles: (false) If true, any remote working directories are deleted.
• retrieveOutput: (true) If true, output files are copied back into the local working directory.
• outputDirectory: (null) If not null, this must be a string specifying a path to place completed output files, instead of the local working directory.
• cleanLocalWorkingDirectory: (false) If true, the local temporary working directory will be removed on successful job completion.
• hideFromQueue: (false) If true, the job will not be displayed in the MoleQueue GUI by default (useful for automated batch jobs).
• popupOnStateChange: (true) If true, a notification popup will be displayed system tray when the job's state changes.

Server response:

• If successful, some identifiers are returned:

{
  "jsonrpc": "2.0",
  "result": {
    "moleQueueJobId": 17,
    "queueJobId": 123456,
    "workingDirectory": "/tmp/MoleQueue/17/"
  },
  "id": "XXX"
}

moleQueueJobId is a identifier that is unique to this instance of MoleQueue, while queueJobId is unique to the queue (Either a DRMS job id or a local process id).

• If unsuccessful, an error is returned:

{
  "jsonrpc": "2.0",
  "error": {
    "code": 32,
    "message": "Cannot write to local directory \"/tmp/MoleQueue/17/\". Permission denied.",
  }
  "id": "XXX"
}

Cancel submitted job

Client request:

Parameter is the MoleQueue id of the job to cancel:

{
  "jsonrpc": "2.0",
  "method": "cancelJob",
  "params": {"moleQueueJobId" : 17},
  "id": "XXX"
}

Server response:

Result is the MoleQueue id of the cancel job:

{
  "jsonrpc": "2.0",
  "result": 17,
  "id": "XXX"
}

Notification of job state change

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

{
  "jsonrpc": "2.0",
  "method": "jobStateChanged",
  "params": {
    "moleQueueJobId": 17,
    "oldState": "RemoteQueued",
    "newState": "Running"
  }
}

Valid states are:

• None: Initial state of job, should never be entered.
• Accepted: Job has been received and is being prepared (Writing input files, etc).
• LocalQueued: Job is being queued locally, either waiting for local execution or remote submission.
• Submitted: Job has been submitted to a remote queuing system.
• RemoteQueued: Job is pending execution on a remote queuing system.
• Running: Job is running, either remotely or locally.
• Finished: Job has completed.