Hi Hilmar,

After giving some thoughts on how to implement a programmatic access to our web portal,
we think the easiest solution is probably to use the http request->response api model. 
Client sends a POST message to the server with all the information required to kick off the job,
and the server responds with the status of the the submission. One request, one response, no need to
maintain a stateful session. 

I know we've talked about other options before such as SOAP or REST APIs, or XML for request-response
message exchange, but I think we can do without them for simplicity in our case.

Of course, there are still details, APIs to be worked out before any implementation. 
But I'd like to bounce the idea around to see if this is a workable solution for you. 
Attached with this email you will find the proposed request and response message exchange.

I'd love to hear your suggestions or any issue you might see with this approach.  Feel free to
send us any thoughts on this.

1. The client (i.e. the perl program) will POST a multipart message to the web 
   server using some sort of library (maybe HTTP::REQUEST::COMMON ?).  The POST 
   message will consist of the following information:

   a) the name of analysis and tool you want to run;
   b) the file to run the analysis with;
   c) optionally, a xml file which specifies the parameters to run the analysis
      with; (if not provided, the analysis will run with default parameters)
   d) maybe your email address so we can keep track of users who submit
      jobs to our portal.

   Of course, we will provide information on the above (such as list of valid options
   for a), a guideline of what we consider valid nexus file for b), and a schema for c). 

   Therefore, the POST message will look something like this (the multipart
   boundary is for illustration purpose only):

   POST /ws/processreq HTTP 1.1
   Content-Type: multiplart/form-data; boundary=---------------------0a12b03f4
   Host: [name of our web server]
   Content-Length: [this depends on your data you are sending]

   ---------------------0a12b03f4
   Content-Disposition: form-data; name="analysis"
   [name of your analysis]

   ---------------------0a12b03f4
   Content-Disposition: form-data; name="email"
   [your email address]

   ---------------------0a12b03f4
   Content-Disposition: form-data; name="datafile"; filename="[path to your nexus or philip file]"
   Content-Type: text/plain
   [contents of your data file]

   ---------------------0a12b03f4
   Content-Disposition: form-data; name="parameterfile"; filename="[path to your xml parameter file]"
   Content-Type: text/xml
   [contents of your parameter file]


2. The web server will send back the following response message which consists of a
   status and a message field. Currently on the portal when a submission is complete, 
   we send the user by email the URL to retrieve the result files.  Is it sufficient
   to give your the URL in the response message?

   Some of the scerarios I can thinking of right now are:

   a) if web server is up, but backend server (i.e. cluster machine) is down:
      status: SERVICE UNAVAILABLE
      message: [message telling user to try again later]

   b) if required information is missing or empty
      status: INCOMPLETE SUBMISSION
      message: [state which required field is missing or empty]

   c) if the submitted data file failed to be validated by our nexus parser:
      status: INVALID DATA FILE
      message: [error message why it fail]

   d) if the requested analysis is invalid:
      status: INVALID METHOD
      message: [list of valid methods for the submitted data file]

   e) if the email address is invalid
      status: INVALID EMAIL
      message: [message of email address is invalid]

   f) if the submitted xml parameter file is invalid
      status: INVALID PARAMETER FILE
      message: [mesasge why it fails]

   g) if job is submitted successfully:
      status: OK
      message: [URL to retrieve the list of results files]