Tutorial 04 - PHP Reference Gateway for Airavata - End-User Guide

 Introduction to PHP Reference Gateway

PHP Reference gateway is the interface developed by the Airavata team for demonstration purposes and also for interested science communities to work with. This guide provides step-by-step information on obtaining a complete science gateway experience for science and scholarly communities using Airavata as a middleware platform. Here we also discuss main features and services provided for gateway communities via Airavata.

End of the tutorial you will know;

• How to create and activate user account in the gateway.

• How to create and modify projects

• How to create, execute and monitor, etc... experiments.

• How to communicate your issues, feedback, and request.

For more details on Airavata please visit Airavata site

Test/Demo Environment Details

1. PHP Reference Gateway link;
   https://testdrive.airavata.org/
2. Download application input files from;
   https://cwiki.apache.org/confluence/display/AIRAVATA/XSEDE14+Gateway+Tutorial+Application+Input+Files+and+Parameters 

Tutorial I - Gateway Login

Create Account

1. Create a user account using 'Create Account' on the home page.
   
   1. Account creation page link:https://testdrive.airavata.org/create
      
   2. Please enter required information and submit.
   3. Important;
      1. Username cannot have spaces.
      2. Username cannot be an email address.
      3. Username & password must be longer than 5 characters.
      4. The password is case sensitive.
      5. All the mandatory fields indicated by a star; *.
   
   
2. Account activation;
   1. The user will receive an email upon creating the account to provided email to confirm the creation. Follow the instructions and login to the gateway using the username and password.
   2. Once the account is confirmed gateway admin has to provide gateway access after validating the user account.
   3. The user will be notified gateway access via email.
       

Login to Account

1. Once the account is created successfully and access granted login to the gateway through 'Log In' link in the home page.
   
   1.  Link: https://testdrive.airavata.org/login
      
      

Password Recovery

1. Gateway user can recover the forgotten password using '(Forgot Password? Click here)' link in the login page.
2. When the username is submitted user will receive an email to the email box linked to the username.
3. The email will have instructions on changing the password.

Tutorial II - Create & Search Projects

Create Project

1. 'Projects' in the gateway is simply a grouping of experiments. 
2. Every user will have a pre-created 'Default Project'.
3. To create Projects navigate to ‘Project → Create’ from the main menu. EMandatory fields indicated by star; *.
4. The user is directed to Project Summary page upon successful creation of the project.
   
   

Search Projects

1. To browse existing projects, 'Project → Browse' from the main menu.
2. Search keys are;
   1. Project Name
   2. Project Description
3. After selecting the search key, the user has to give  a value to search using the selected key.
4. All the Projects will be listed with pagination. By clicking ‘View’ at the end of the row user can navigate to ‘Project Summary’ page. 
5. The user can also search using (*) as a wild character. 
6. Using 'View' link i each project user can view all the experiments grouped under the project.From project browse page, the user can 
7. User can click on the experiment ‘Name’ and navigate to ‘Experiment Summary’ page of the selected experiment.

Tutorial III - Create & Launch Experiment

Create Experiment

1. To create an experiment navigate to Experiment → Create from the main menu.
2. Create experiment page is filled in two stages.
   
3. Initially, user needs to enter/select given fields in order to continue.
   1. Experiment Name (Mandatory)
   2. Experiment Description (Optional)
   3. Project (Select from the available LOV)
   4. Application (Select from the available LOV)
   and click ‘Continue’ button. At this point, the user can restart by clicking ‘Reset Values’.
4. Then continue entering Application configuration information.
   1. Experiment application input (Mandatory) - Application input can be in the form of entering data manually or uploading a single or multiple files.
      NOTE: Uploading file content validity is not checked by the gateway. The user has the responsibility of uploading correct files.
   2. Compute Resource (select from the available LOV. If the application is existing in a single resource, it will be the default value)
   3. Queue (a default value will be taken if not changed by the user)
   4. Node Count (If not entered default value will be taken as the input)
   5. Total Core Count (If not entered default value will be taken as the input)
   6. Wall Time Limit (If not entered default value will be taken as the input)
   7. Total Physical Memory (If not entered the default value 0 will be taken as the input)
5. For some compute resources default values in d, e and f will not be correct, in such cases the user needs to change the node count in such cases.
6. While entering application configurations user can start over from the beginning using ‘Start Over’ button.
7. Once saved or saved and launched user will be directed to ‘Experiment Summary’ page; can refresh the page and monitor experiment status changes.
   
   

Launch Experiment

1. The user can launch an experiment in 'Create Experiment' page by selecting 'Save and Launch'. 
2. User can also create and save the experiment to launch later from 'Experiment Summary' Page. 
3. Experiments can be accessed through 'Experiment → Browse' or 'Project →Browse →View Project' pages.
4. If the experiment is not supposed to launch e.g.: a COMPLETED, LAUNCHED experiment, then the launch button will be disabled.

Tutorial IV - Browse Experiments

1. User can search for experiment created by him/her through

1. Experiments → Browse

2. Browse Projects → View Project → View Experiment (by clicking on the status of the experiment) - Please refer Search Projects in Tutorial II above.

2. In Search Experiments search keys are;

1. Experiment Name

2. Experiment Description

3. Application

4. …

3. Browse Experiments Page

Image X - Search Experiments

1. All the experiments of the user will be listed; latest on top. User  can also select the search by key, user has to give  a value to search for using the key. Partial values, complete values, (*) wild card can be used to search.

2. Click on Search once the search key is selected and value is entered. User can also search for experiments by giving the status.

3. All the experiments as per entered Key value pair will be listed.

4. By clicking on the 'Status' user will be navigated to ‘Experiment Summary’ screen of each experiment.

5. In experiment summary users can;

1. Launch experiment - Explained in above Tutorial III

2. Cancel experiment

3. Clone experiment

4. Edit experiment

6. User can edit an experiment by navigating to 'Edit Experiment' page. Edit button next to each experiment name will navigate user to 'Edit Experiment' page of each experiment.

Tutorial V - Modify, Cancel & Clone Experiments

Modify Experiment

1. Modify experiment by clicking on the edit icon (pencil) next to experiment name OR by clicking on ‘Edit’ button in Experiment Summary Page.

2. User can modify all available fields except experiment status, application & experiment ID.  

3. User can update experiments with statuses;

1. CREATED

4. Edit Experiment Page

Image XI - Edit Experiment

Cancel Experiment 

1. Experiments can be canceled by navigating to experiment’s 'Experiment Summary’ screen.
2. Experiment statuses which allow cancellations;
   1. LAUNCHED
   2. EXECUTING
   3. SCHEDULED
3. Click on ‘Cancel’ button and immediately the Experiment status will change to CANCELING.
4. If the job is not already processing in the remote resource (already COMPLETED in the resource) the job will proceed to COMPLETE and upon completing the experiment status will change to CANCELLED. Since the user requested a cancellation generated output will not be provided back to the gateway.
5. If the job was successfully CANCELLED upon changing the job state to CANCELLED experiment status will also change to CANCELED.
6. CANCELED experiments are only available for cloning in the PGA.

Clone Experiment

1. Experiments can be cloned irrespective of the experiment status by clicking ‘Clone’ in ‘Experiment Summary’ page.
2. When clicks ‘Clone’ from experiment summary user will be navigated to ‘Edit Experiment’ page of the new experiment. The new experiment will have exact same information as the earlier existing experiment.   
3. The new experiment will have a new experiment ID and the status will always be CREATED.
   New experiment name = Clone of + Old experiment name
4. User can change existing information (except the Application) in ‘Edit Experiment’ page and save or save & launch.

Tutorial VI - User Assistance

Report Issue

1. Gateway user can report issues faced within the gateway through this page.

2. Page navigation: Help → Report Issue

3. Raise a Bug Page

Image XII - Raise a Bug

Request Feature

1. Gateway allows users to provide feedback as well as request for new applications via Request Feature Page.

2. Page Navigation; Help → Request Feature

3. Got Feedback? Page

Image XIII - Got Feedback?