View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Logical Helion, LLC > Helios >


Annotate this POD



Open  0
View/Report Bugs

NAME ^ - CGI script to receive jobs for Helios via HTTP POST


Besides the built-in Perl job submission API and the command line utility, job can be submitted to Helios via an HTTP POST request by using the CGI program.


The job submission request can be submitted either in a form-encoded request or a simple stream of XML POSTDATA.


You can submit a job through a form-encoded request. There are two form fields:


The job type, ie the service class that will perform the job


The job arguments, ie the actual parameters of the job, in XML format

You can submit requests in this format via a browser using the following HTML form as a guide:

 <form method="post" action="http://host/cgi-bin/">
 <b>Job Type (Service Class)</b> <br />
 <input type="text" name="type" />
 <br />
 <br />
 <b>Job Arguments</b> <br />
 <textarea rows="10" cols="80" name="params"></textarea>
 <br />
 <input type="submit" value="Submit Job" />

The params field should contain the job arguments in XML format, like the following example:


The <arg1>, <id>, etc. tags will be parsed into Perl hash values by Helios when the job is run. Inside the <params> section, the tag names are up to you; though Helios does checks to make sure the job XML is well-formed, there is no DTD that the text is validated against. Thus, you have a certain amount of freedom when deciding what information to pass to Helios as a job argument. However, it is generally a good idea to keep things short and simple.


Instead of encoding your request as a form, you can simply POST a stream of XML text. In this type of request, the job argument XML is in the same format as above, with the addition that the job type is specified as a property of the <job> tag:

 <?xml version="1.0" encoding="UTF-8"?>
 <job type="Helios::TestService">
                <arg1>a job submitted via HTTP</arg1>
                <note>this one was posted as an XML stream</note>

To POST the above XML stream with Perl using LWP::UserAgent, use the following script as an example:

 #!/usr/bin/env perl 
 use strict;
 use warnings;
 use LWP::UserAgent;
 use HTTP::Request::Common;
 my $ua = LWP::UserAgent->new();
 my $jobXML = <<ENDXML;
 <?xml version="1.0" encoding="UTF-8"?>
 <job type="Helios::TestService">
                <arg1>a job submitted via HTTP</arg1>
                <note>this one was posted as an XML stream</note>

 my $r = $ua->request(POST 'http://localhost/cgi-bin/',
                Content_Type => 'text/xml',
                Content => $jobXML
 print $r->as_string;


Regardless of which encoding method you use for your request, if your job was submitted successfully you'll receive a response like the following:

 HTTP/1.1 200 OK
 Connection: close
 Date: Fri, 16 Dec 2011 04:24:30 GMT
 Server: Apache/2.2.14 (Ubuntu)
 Vary: Accept-Encoding
 Content-Type: text/xml; charset=ISO-8859-1
 Client-Date: Fri, 16 Dec 2011 04:24:30 GMT
 Client-Response-Num: 1
 Client-Transfer-Encoding: chunked

 <?xml version="1.0" encoding="UTF-8"?>

If your job was submitted successfully, the <status> section will contain a 0, and the <jobid> section will contain the jobid of the submitted job. If there was an error during the job submission process, a 500 Internal Server Error will be returned.



Given a job type, lookupJobClass() queries the HELIOS_CLASS_MAP table to determine if a Helios service class is associated with that job type. If there is, the function returns that service class. If it isn't, the original type is assumed to be the name of the desired service class, and it is returned to the caller instead.


Given a string of job arguments in XML format, parseArgXMLForType() returns the value of the type attribute of the <job> tag, if specified.

SEE ALSO ^,, Helios::Service, Helios::Job


Andrew Johnson, <lajandy at cpan dot org>


Copyright (C) 2011-2 Andrew Johnson.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.


This software comes with no warranty of any kind.

syntax highlighting: