appForm (Application Form)
Purpose of appForm
A variety of general-purpose and discipline-specific applications run on the clusters comprising the grid. Users can submit batch jobs through the Job Services tab of the Grid Portal to submit jobs that run these applications. Without appForm, a user must create an input file or files specific to the application he/she will use. Often this requires a great deal of familiarity and expertise with the application.
appForm is a Grid based application (part of UGP) that uses AJAX technologies to create an application-specific HTML web page form for user input. It processes the user input into a valid input file for the application which it submits to the application executable on the Grid.
With appForm, the user can fill in a form to generate the input for an application instead of providing the input file him/herself. This is especially useful for applications that require complex or esoteric input files, or that do not have their own GUI interfaces.
appForm provides a standard method of input that both:
- simplifies the creation of application input files by providing an easy to use HTML form that can display appropriate labels and descriptions and provide easy-to-use input methods, such as pull down menus, in a GUI interface and
- automatically submits input files created by appForm to the corresponding program executable on the grid.
appForm allows the process of input file creation and job submission on the grid to be integrated in one place.
To add a new application to appForm, the grid administer must first write two XML files (app_job.xml and app_form.xml) that create the forms for job submission and application input, respectively, and an XSLT file (app_form_input.xsl) that processes the user's input and creates the corresponding program input file. This is a one time only task. Once these three files have been created, any user of the Grid Portal may use appForm by interacting with the form for the specific application.
appForm Job Parameters and Input Generator Tabs
appForm produces a pop-up web page with two tabs:
- Job Parameters
- Input Generator
Job Parameters is a customizable form that provides the options necessary for Job Submission to the Grid. Input Generator is a customizable form that users can fill in to generate the input file for a specific application. Together, they form an integrated module that can be used to easily create a job input file and submit it to the Grid.
You can use a customized Job Parameters tab even if you don't have an Input Generator for that program.
Setup for Customized Job Parameters and/or appForm
UGP maintains a database of applications. Each entry has a unique key of the form:
- is the name of an application. This is defined in the "Display Name" field of the Application table (located on the UCLA Grid Portal under the Grid Admin tab)
- is the name of the cluster.
With appForm or a customized Job Parameters tab, the database entry for an application points to an xml file, which is used instead of the information in the database Application table.
There are three files that you could create:
- to create the pop-up page and customize the Job Parameters tab
- to define the contents of the Input Generator tab (optional)
- to translate the user input from the Input Generator tab into a valid program input file (required if and only if you have an app_form.xml)
In all cases, replace app with the "Display Name" of the application used in UGP's Application table. For the example given above, this would be "Q-Chem".
If you have an application that is hosted on multiple clusters, you will need to define a job.xml for each cluster. However, you may make one form.xml file that is used by the application on all clusters.
The setup of appForm involves files in two directories:
- The operational directory (appform_dir) where appForm actually runs from
- A temporary directory (temp_dir) where a separate copy of all appForm files are kept and edited. Files in temp_dir are deployed to appform_dir using the deployappForm script. All appForm files should be edited in temp_dir, then deployed to appform_dir (if this is not conformed to, appForm files may be inadvertently overwritten).
The location of appform_dir and temp_dir should be defined by each grid admin, however sample locations are shown below:
- appform_dir: UCPortal/apache-tomcat-5.5.17/webapps/UCLAGridPortal/jsp/job/appForm/uclaAppForm
- temp_dir: UCLAGridPortal/Portal/webapp/jsp/job/appForm/uclaAppForm
Once these directories are created, complete the following steps to setup appForm:
- Modify the line containing "appform.dir=" in UCLAGridPortal/Portal/config/ugp.properties to point to appform_dir.
- Create the app_job.xml and possibly the app_form.xml and app_form_input.xsl files in temp_dir.
- In temp_dir, execute the deployappForm Script (should be included with your release)
- Login to the grid portal as an administrator.
- Go to Application under the Grid Admin tab.
- Select the application you wish to modify and click Load.
- Ensure that the name of your three files (only the app prefix) matches the "Display Name" field
- Fill in the "Customized.xml" field with the name of your app_job.xml file.
How appForm Works
When the user selects the application, UGP calls combine.jsp which:
- applies the translator rsl.xsl to the user-created app_job.xml for this application. This produces the html for the Job Paramaters tab.
- applies the translator trans.xsl to the user-created app_form.xml for this application. This produces the html for the Input Generator tab.
- combines these two pages as two tabs of the same page (using YUI TabView), which it then displays to the user in a pop-up window.
When the user presses the Save button, appForm:
- saves whatever the user has filled into the form in an xml file. If the user wants to run another job later with input that is similar to this input, he/she can load this xml file to repopulate the form and then make changes to that.
- applies the user-created translator app_form_input.xsl to the xml file to create a program input file.
- fills in the input file name on the Job Parameters page.