Chapter 2: Configuring Viewpoint - Documentation Index
Transcription
Chapter 2: Configuring Viewpoint - Documentation Index
Viewpoint for Moab HPC Suite 7.1.0 Setup Guide © 2012 Adaptive Computing Enterprises, Inc. All rights reserved. Distribution of this document for commercial purposes in either hard or soft copy form is strictly prohibited without prior written consent from Adaptive Computing Enterprises, Inc. Adaptive Computing, Cluster Resources, Moab, Moab Workload Manager, Moab Viewpoint, Moab Cluster Manager, Moab Cluster Suite, Moab Grid Scheduler, Moab Grid Suite, Moab Access Portal, and other Adaptive Computing products are either registered trademarks or trademarks of Adaptive Computing Enterprises, Inc. The Adaptive Computing logo and the Cluster Resources logo are trademarks of Adaptive Computing Enterprises, Inc. All other company and product names may be trademarks of their respective companies. ii Contents About this guide Chapter 1: Installing/upgrading Viewpoint 1.1 Before installing Viewpoint 1.1.1 Creating the Viewpoint database 1.2 Doing a clean installation of Viewpoint 1.3 Reinstalling Viewpoint 1.4 Upgrading Viewpoint 1.5 Troubleshooting a Viewpoint Installation 1.6 Enhancing Viewpoint performance Chapter 2: Configuring Viewpoint 2.1 Configuring Viewpoint through the interface 2.1.1 Configuring the Moab database via the interface 2.1.2 Configuring the Viewpoint database via the interface 2.1.3 Connecting to Moab Web Services via the interface 2.1.4 Configuring customers via the interface 2.1.5 Connecting to Moab via the interface 2.1.6 Troubleshooting errors 2.2 Manually configuring Viewpoint 2.2.1 Configuring a connection from Viewpoint to Moab 2.2.1.1 Configuring a process Moab connection 2.2.1.2 Configuring a local Moab connection 2.2.1.3 Configuring an SSH password-authenticated Moab connection 2.2.1.4 Configuring an SSH private-key-authenticated Moab connection 2.2.2 Configuring Viewpoint to communicate with your DBMS 2.2.3 Connecting Viewpoint to the Moab Web Services 2.2.4 Configuring Moab Accounting Manager in Viewpoint 2.2.5 Configuring Viewpoint for Quoting 2.3 Configuring Viewpoint Users in Moab 2.4 Configuring security in Viewpoint 2.4.1 Setting <security> permissions 2.4.2 Configuring HTTPS in Tomcat 2.4.2.1 Generating and storing a self-signed certificate 2.4.2.2 Exporting for local keystore import 2.4.2.3 Modifying the Viewpoint web.xml file to enable HTTPS 2.4.3 Integrating with Single-Sign-On (SSO) authentication schemes vii 1 1 4 4 6 7 9 10 13 13 15 17 18 20 21 24 24 25 26 27 27 28 29 37 38 38 39 40 40 41 42 42 43 44 iii 2.4.4 Integrating Viewpoint with LDAP/Active Directory 2.4.5 Configuring role definitions 2.4.6 Configuring the permissions map 2.4.6.1 Setting permissions 2.4.6.2 Filtering navigation with permissions 2.4.7 Setting permissions for the Viewpoint User Management page 2.4.8 Configuring login modules 2.4.8.1 Using ViewpointLoginModule 2.4.9 Configuring the request handler 2.5 Synchronizing job template names Chapter 3: Customizing Viewpoint 3.1 Customizing Viewpoint to specific markets or customers 3.2 Customizing navigation components 3.2.1 Creating links on the Viewpoint menu bar 3.2.2 Adding/editing top links 3.2.3 Adding top link icons 3.2.4 Customizing the header image 3.2.5 Assigning a default Homepage 3.2.6 Customizing the Home icon 3.2.7 Viewpoint page URLs 3.3 Configuring Homepage gadgets 3.3.1 Arranging gadgets on the Homepage 3.3.2 Supported Homepage gadgets 3.4 Configuring the Contact Us page 3.5 Using the Viewpoint queue 3.6 Creating custom dialog windows 3.7 Customizing logging 3.8 Displaying a site maintenance page 3.9 Using generic commands Chapter 4: Configuring jobs 4.1 Configuring the Job Submit form 4.1.1 Configuring the request element for the Job Submit form 4.1.2 Enabling submitting multiple jobs 4.2 Configuring buttons in the Job Management table 4.3 Configuring columns in the Job Management table 4.4 Configuring the Job Details pane 4.5 Configuring streaming job output 4.6 Configuring TORQUE and Moab for streaming job output Chapter 5: Configuring nodes 5.1 Configuring the Node Management table buttons 5.2 Modifying columns in the Node Management table iv 45 49 50 51 54 55 56 57 58 59 61 61 62 63 65 66 67 67 68 68 70 71 72 79 80 81 83 85 86 89 89 90 93 94 97 98 103 104 107 107 109 5.3 Creating a composite column in the Node Management table 5.4 Customizing the Node Detail pane 5.5 Controlling a node's visibility 5.6 Customizing state values in the Node Management table Chapter 6: Creating or configuring forms 6.1 Configuring the <components> element 6.1.1 Configuring an access control list 6.1.2 Configuring a checkbox 6.1.3 Configuring a date box 6.1.4 Configuring a duration spinner 6.1.5 Configuring a duration text box 6.1.6 Configuring an inferred values drop-down list 6.1.7 Configuring a label 6.1.8 Configuring a list box 6.1.9 Configuring a list editor 6.1.10 Configuring a multi-select list box 6.1.11 Configuring a number spinner 6.1.12 Configuring a radio button selector 6.1.13 Configuring a script upload component 6.1.14 Configuring a suggest box 6.1.15 Configuring a table map 6.1.16 Configuring a text box 6.1.17 Configuring an upload file componenet 6.1.18 Setting component rules 6.1.18.1 Changing a component/section's visibility 6.1.18.2 Getting component rule responses dynamically 6.1.18.3 Validating and invalidating components 6.2 Configuring the <pages> element 6.2.1 Configuring the <description> element 6.2.2 Configuring the <sections> element 6.2.3 Configuring a static page layout 6.2.3.1 Configuring validation in static forms 6.2.4 Configuring a dynamic page layout 6.2.4.1 Configuring validation in dynamic forms 6.3 Configuring the <queue> element 6.3.1 Defining what data is stored in the queue 6.3.2 Defining the queue interface 6.3.3 Specifying which queue data is required 6.4 Adding a date decider 6.5 Adding a duration decider 6.6 Adding an integer decider 6.7 Adding a string decider 111 112 114 114 117 118 120 120 121 122 124 126 127 128 129 133 134 135 136 137 139 140 141 142 143 144 146 147 148 149 150 153 154 156 157 158 160 161 162 163 165 166 v 6.7.1 Listing string deciders 6.7.2 Appending strings 6.7.3 Using conditional items in strings 6.7.4 Replacing strings 6.8 Setting a Boolean decider Chapter 7: Configuring reports 7.1 Connecting Viewpoint reporting to the Moab database 7.2 Specifying available reports 7.3 Adding permissions to individual reports 7.4 Configuring Viewpoint to run the Events report 7.5 Querying major events from the Moab event log vi 167 167 168 169 170 173 173 174 176 177 178 About this guide Welcome to the Viewpoint for Moab HPC Suite Setup Guide. This guide explains how to install, configure, customize, and use Viewpoint for Moab HPC Suite. This help is intended for administrators who are responsible for configuring and maintaining Viewpoint for their users. This guide contains these major sections: l l l l l l l Chapter 1: Installing/upgrading Viewpoint on page 1 contains instructions about installing or upgrading to Viewpoint 7.1.0. Chapter 2: Configuring Viewpoint on page 13 describes how to configure Viewpoint connections with Moab Workload Manager, Moab Web Services, the Viewpoint database, and others. Chapter 3: Customizing Viewpoint on page 61 contains information about making personal customizations to your instance of Viewpoint. It describes how to customize navigation, Homepage gadgets, the "Contact Us" page, and dialog windows. It also explains how to customize logs and maintenance pages. Chapter 4: Configuring jobs on page 89 contains information about setting up the Job Submit form and configuring the Job Management table. Chapter 5: Configuring nodes on page 107 contains information about Node Management in Viewpoint. Chapter 6: Creating or configuring forms on page 117 contains information about working with forms in Viewpoint. It includes instructions about configuring different form elements and deciders. Chapter 7: Configuring reports on page 173 contains information about specifying available reports, adding permissions to reports, and other report configuration options. vii Chapter 1: Installing/upgrading Viewpoint Viewpoint must be installed in the right way in order for it to connect with Moab and function correctly. l Before installing Viewpoint on page 1 l Doing a clean installation of Viewpoint on page 4 l Reinstalling Viewpoint on page 6 l Upgrading Viewpoint on page 7 l Troubleshooting a Viewpoint Installation on page 9 l Enhancing Viewpoint performance on page 10 1.1 Before installing Viewpoint To complete prerequisites before installing/upgrading Viewpoint for Moab HPC Suite 7.1.0 1. Verify that you have at least 16 GB of free disk space. 2. Use only components from the following list for the best experience: l Moab Workload Manager 7.1.0 l Moab Web Services 7.1.0 l Oracle Java SE 6.0 Viewpoint requires the Java Runtime Environment from Sun/Oracle version 6.0 or later (running java -version should return a version number of 1.6.0.). Other implementations of the Java Runtime Environment, such as OpenJDK or GIJ, will not run on Viewpoint as expected. l Apache Tomcat 6.0 1.1 Before installing Viewpoint 1 Chapter 1: Installing/upgrading Viewpoint Set the MaxPermSize higher if Moab Web Services and Viewpoint exist in the same Tomcat or to support actions such as running reports. To do so, locate the following line in the /etc/tomcat6/tomcat6.conf. If it is not already present, add it. CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxPermSize=2g" Change each instance of 2g to 4g. CATALINA_OPTS="$CATALINA_OPTS -Xmx4g -XX:MaxPermSize=4g" If you receive a PermGen error while running Viewpoint, gradually increase both the MaxPermSize and Xmx equally (the Xmx should always be at least as much as MaxPermSize). l Database o MySQL 5.1 + o Oracle 10g Express or Enterprise 10.2 + MySQL and Oracle are currently the only supported databases for Viewpoint. However, the use of other databases with Viewpoint is possible. Please contact Adaptive Computing Support for more information. To create the Viewpoint database, see Creating the Viewpoint database on page 4. User, database, and schema created should all be named 'viewpoint'. When you run commands and scripts in the database, you must do so in context. For instance, if you are running a script on a MySQL database, you would include 'viewpoint' before the path, as in the following example: > mysql -u root -p viewpoint < /your/path/script.sql For MySQL, the database/catalog name is viewpoint. l Web Browser o Mozilla Firefox 3.0-4.0 o Internet Explorer 7-8 3. Stop Tomcat. > sudo service tomcat6 stop If you are running other applications in Tomcat, you may need to perform this step later in the process. 4. Create the Viewpoint home directory. 2 1.1 Before installing Viewpoint Chapter 1: Installing/upgrading Viewpoint [root]# mkdir /opt/viewpoint 5. Download the Viewpoint tarball and untar it in the Viewpoint home directory, /opt/viewpoint. > tar -xzvf /tmp/downloads/viewpoint-7.1.0.tgz -C /opt/ > mv /opt/viewpoint-7.1.0 /opt/viewpoint If you want to override the default configuration location of /opt/viewpoint, define the environment variable VIEWPOINT_HOME with a path such as /home/name/viewpoint. The tarball is extracted into a new directory called viewpoint-7.1.0/. It contains the following directories and files that are important to Viewpoint 7.1.0 installation: l moab.war l licenses/ l sql/ o l mysql/, oracle/ o drop_tables.sql o setup_hpc.sql templates/ o setup.properties.mysql o setup.properties.oracle 6. Set up the database by running the setup_hpc.sql script. Remember to run it in context. > mysql -u root -p viewpoint < /tmp/viewpoint/sql/[dbType]/setup_hpc.sql 7. Download the JDBC driver for your database and place it in Tomcat's lib directory. For example, if you are using MySQL, download the MySQL JDBC connector library, untar it, and copy the mysqlconnector-java-x.x.x-bin.jar file to Tomcat's /lib directory (normally $CATALINA_ HOME/lib). > cp mysql-connector-java-5.1.6-bin.jar /usr/share/tomcat6/lib 8. If you are installing Viewpoint for the first time, see Doing a clean installation of Viewpoint on page 4. 9. If you are reinstalling Viewpoint, including retrying an upgrade, see Reinstalling Viewpoint on page 6. 10. If you are upgrading Viewpoint to 7.1.0, see Upgrading Viewpoint on page 7. 11. Configure Viewpoint. See Configuring Viewpoint on page 13. Related topics l Installing/upgrading Viewpoint on page 1 1.1 Before installing Viewpoint 3 Chapter 1: Installing/upgrading Viewpoint 1.1.1 Creating the Viewpoint database MySQL 5.1 is the supported database for Viewpoint. You must create the database and give the user full access to that database. For information on creating databases and granting access with other database vendors, consult the documentation for that vendor. MySQL and Oracle are currently the only supported databases for Viewpoint. However, the use of other databases with Viewpoint is possible. Please contact Adaptive Computing Support for more information. For information on creating databases and granting access with other database vendors, consult the documentation for that vendor. To create the Viewpoint database 1. Run something like the following script. (Remember to run commands in context.) adaptive@viewpointMoab Viewpoint:~$ mysql -u admin –p viewpoint Enter password: mysql> CREATE DATABASE viewpoint; Query OK, 1 row affected (0.08 sec) mysql> GRANT ALL ON viewpoint.* TO viewpoint@localhost IDENTIFIED BY 'p@ssw0rd'; Query OK, 0 rows affected (0.31 sec) mysql> GRANT ALL ON viewpoint.* TO [email protected] IDENTIFIED BY 'p@ssw0rd'; Query OK, 0 rows affected (0.31 sec) FLUSH PRIVILEGES; Query OK, 0 rows affected (0.31 sec) 2. Verify that the script ran correctly by running a third party client such as SQuirrel SQL or by using your database vendor's own client tool (for instance, run mysql -u <username> -p <password>). Related topics l Installing/upgrading Viewpoint on page 1 l Before installing Viewpoint on page 1 1.2 Doing a clean installation of Viewpoint If you are installing Viewpoint for Moab HPC Suite for the first time, complete the instructions found in Before installing Viewpoint on page 1, then perform the following steps. If you have not already done so, create the Viewpoint database. See Creating the Viewpoint database on page 4. To install Viewpoint for Moab HPC Suite for the first time 1. Open the moab.cfg file located in the Moab home directory and verify that Moab 7.0 runs with a Viewpoint user configured as a level 1 administrator and that proxy is enabled. ADMINCFG[1] USERS=root,tomcat6 ADMINCFG[1] ENABLEPROXY=TRUE 4 1.2 Doing a clean installation of Viewpoint Chapter 1: Installing/upgrading Viewpoint For more information, see "ADMINCFG" in "Appendix F: Scheduler Parameters" in the Moab Workload Manager documentation. If Moab and Viewpoint are running on the same machine, that user needs to be named tomcat6 or be the Tomcat user on your system, as in the above addition to the moab.cfg file. 2. Copy moab.war to the Tomcat /webapps directory. Do not run more than one instance of Viewpoint within Tomcat. > cp /opt/viewpoint/moab.war /var/lib/tomcat6/webapps 3. Copy the setup.properties.[dbType] file from /opt/viewpoint/templates/ to the Viewpoint home directory and change its name to setup.properties, removing the .[dbType]. Modify it according to your database's type, host name, port, name, schema, admin username, and admin password. The included template is based on the mysql database type: > vi /opt/viewpoint/setup.properties.sqlserver #dbType=mysql #dbHost=hostName #dbPort=1433 #dbName=viewpoint #dbSchema=viewpoint #dbUser=viewpoint #dbPassword=myPassword 4. If you are installing Moab Accounting Manager, define the MAM URL in the ViewpointConfig.groovy file. mam.url="https://<hostname>/cgi-bin/mam/index.cgi?start=login" 5. Verify that the Tomcat user has read/write privileges to the Viewpoint home directory. For example, you could run the following: chown -R tomcat6:tomcat6 /opt/viewpoint You must grant read privileges for this directory to the Tomcat user. If you do not know the Tomcat user (often tomcat or tomcat6), use the owner of the Tomcat home directory (usually /var/lib/tomcat6). 6. Run the setup_hpc.sql script. This is located in the sql/[dbType] directory. 7. Start the Tomcat service. > service tomcat6 start If you are running Fedora, you must navigate to $CATALINA_HOME/bin/ and run startup.sh as root: [root]> $CATALINA_HOME/bin/startup.sh 8. Configure Viewpoint (see Configuring Viewpoint on page 13). 1.2 Doing a clean installation of Viewpoint 5 Chapter 1: Installing/upgrading Viewpoint If you want reporting in Viewpoint, please contact Adaptive Computing Professional Services. Related topics l Before installing Viewpoint on page 1 l Installing/upgrading Viewpoint on page 1 1.3 Reinstalling Viewpoint If you are reinstalling Viewpoint for Moab HPC Suite, including retrying an upgrade, complete the instructions found in Before installing Viewpoint on page 1, then perform the following steps. To reinstall Viewpoint 1. Optional: back up your Viewpoint home directory and /webapp directories if you want to keep your current Viewpoint settings. > cp -r /opt/viewpoint /tmp/viewpoint/ > cp -r /var/lib/tomcat6/webapps/moab /tmp/viewpoint/ > cp -r /var/lib/tomcat6/webapps/reporting/ /tmp/viewpoint/ 2. Clean out the database by running the drop_tables.sql script. Remember to run the script in context. > mysql -u root -p viewpoint < /tmp/viewpoint/sql/[dbType]/drop_tables.sql 3. Clean out the Viewpoint home directory. Remove the moab.war file (and, if applicable, the reporting.war file) and the /moab and /reporting directories from the Tomcat directory. Remove all Viewpoint-related contents from both the Tomcat /work directories. > rm -rf /opt/viewpoint/* /usr/share/tomcat6/webapps/moab* /usr/share/tomcat6/work/Catalina/localhost/moab*/usr/share/tomcat6/work/Catalina/localhost/reporting* /var/lib/tomcat6/work/Catalina/localhost/moab* /var/lib/tomcat6/work/Catalina/localhost/reporting* 4. Copy moab.war to the Tomcat /webapps directory. Do not run more than one instance of Viewpoint within Tomcat. > cp /tmp/viewpoint/moab.war /var/lib/tomcat6/webapps 5. Copy your working setup.properties file back into the Viewpoint home directory. > cp /opt/viewpoint/bak/setup.properties.[dbType] If you do not have a backed up, working copy, create one from the templates and change its name to setup.properties, removing the .[dbType]. Modify it according to your database's type, host name, port, name, schema, admin username, admin password, and temporary directory. The included template is based on the mysql database type: 6 1.3 Reinstalling Viewpoint Chapter 1: Installing/upgrading Viewpoint > vi /opt/viewpoint/setup.properties #dbType=mysql #dbHost=hostName #dbPort=1433 #dbName=viewpoint #dbSchema=viewpoint #dbUser=viewpoint #dbPassword=myPassword #tempDir=/tmp 6. If you are installing Moab Accounting Manager, define the MAM URL in the ViewpointConfig.groovy file. mam.url="https://<hostname>/cgi-bin/mam/index.cgi?start=login" 7. Verify that the Tomcat user has read/write privileges to the Viewpoint home directory. For example, you could run the following: chown -R tomcat6:tomcat6 /opt/viewpoint You must grant read privileges for this directory to the Tomcat user. If you do not know the Tomcat user (often tomcat or tomcat6), use the owner of the Tomcat home directory (usually /var/lib/tomcat6). 8. Run the setup_hpc.sql script. This is located in the sql/[dbType] directory. 9. Start the Tomcat service. > service tomcat6 start If you are running Fedora, you must navigate to $CATALINA_HOME/bin/ and run startup.sh as root: [root]> $CATALINA_HOME/bin/startup.sh 10. Configure Viewpoint. To do so, see Configuring Viewpoint on page 13. If you want reporting in Viewpoint, please contact Adaptive Computing Professional Services. Related topics l Before installing Viewpoint on page 1 l Installing/upgrading Viewpoint on page 1 1.4 Upgrading Viewpoint If you are upgrading to Viewpoint 7.1.0 from an earlier version than 6.1, you must first upgrade to 6.1. See Upgrading from Viewpoint 2.0 to 6.1 for instructions. To upgrade to Viewpoint for Moab HPC Suite 7.1.0 1.4 Upgrading Viewpoint 7 Chapter 1: Installing/upgrading Viewpoint from 6.1 or 7.0.0, complete the instructions found in Before installing Viewpoint on page 1, then perform the following steps. To upgrade from Viewpoint to 7.1.0 1. Back up the Viewpoint home directory, /webapp directories, and, if you have customized it, message.properties file. Also back up your database. > > > > cp cp cp cp -r -r -r -r /opt/viewpoint /tmp/viewpoint /var/lib/tomcat6/webapps/moab /tmp/viewpoint/ /tomcat/webapps/moab/WEB-INF/grails-app/i18n/message.properties /var/lib/tomcat6/webapps/reporting/ /tmp/viewpoint/ 2. Remove the moab.war file (and, if applicable, reporting.war file) and the /moab and /reporting directories from the Tomcat directory. Remove all Viewpoint-related contents from both the Tomcat /work directories. > rm -rf /usr/share/tomcat6/work/Catalina/localhost/moab* /usr/share/tomcat6/work/Catalina/localhost/reporting* /var/lib/tomcat6/work/Catalina/localhost/moab* /var/lib/tomcat6/work/Catalina/localhost/reporting* 3. Copy moab.war to the Tomcat /webapps directory. Do not run more than one instance of Viewpoint within Tomcat. > cp /tmp/viewpoint/moab.war /var/lib/tomcat6/webapps 4. Move the setup.properties file to the Viewpoint home directory and, if it is not a backed up working copy, change its name to setup.properties, removing the .[dbType]. Modify it according to your database's type, host name, port, name, schema, admin username, admin password, and temporary directory. The included template is based on the mysql database type: > vi /opt/viewpoint/setup.properties.[dbType] #dbType=mysql #dbHost=hostName #dbPort=1433 #dbName=viewpoint #dbSchema=viewpoint #dbUser=viewpoint #dbPassword=myPassword #tempDir=/tmp 5. If you are installing Moab Accounting Manager, define the MAM URL in the ViewpointConfig.groovy file. mam.url="https://<hostname>/cgi-bin/mam/index.cgi?start=login" 6. Verify that the Tomcat user has read/write privileges to the Viewpoint home directory. For example, you could run the following: chown -R tomcat6:tomcat6 /opt/viewpoint You must grant read privileges for this directory to the Tomcat user. If you do not know the Tomcat user (often tomcat or tomcat6), use the owner of the Tomcat home directory (usually /var/lib/tomcat6). 8 1.4 Upgrading Viewpoint Chapter 1: Installing/upgrading Viewpoint 7. Run the setup_hpc.sql script. This is located in the sql/[dbType] directory. 8. Start the Tomcat service. > service tomcat6 start If you are running Fedora, you must navigate to $CATALINA_HOME/bin/ and run startup.sh as root: [root]> $CATALINA_HOME/bin/startup.sh 9. Merge customizations from the backed-up message.properties file and the market.properties file from your backed-up Viewpoint home directory with the same files in your new Viewpoint directories. For information about customizing these files, see Customizing Viewpoint to specific markets or customers on page 61. 10. Configure Viewpoint. To do so, see Configuring Viewpoint on page 13. Viewpoint does not automatically update the navigation to include links to pages that are new to 7.1.0. To update your links, navigate to the webapps/moab/WEB-INF/install/ directory in your Tomcat home (usually var/lib/tomcat6/) open either cloud/ or hpc/, depending on your license. Open the core.xml file and copy any new links to the core.xml file in your Viewpoint home directory. See Creating links on the Viewpoint menu bar on page 63. You must also set the pages' associated permissions in order to view and use them. See Setting permissions on page 51 for a list of all permissions and their related pages. If you want reporting in Viewpoint, please contact Adaptive Computing Professional Services. Related topics l Before installing Viewpoint on page 1 l Installing/upgrading Viewpoint on page 1 1.5 Troubleshooting a Viewpoint Installation The following steps may help you to troubleshoot problems you may encounter while installing Viewpoint 7.1.0. If you are uninstalling Viewpoint starting over, you must run the drop_tables.sql script, located in the sql/[dbType] directory. This script drops the Viewpoint tables, not the Viewpoint database. To troubleshoot a Viewpoint installation 1. Tail the catalina.out file, usually located in the $CATALINA_HOME/logs/ directory, to view information before Viewpoint fully starts. > tail -f $CATALINA_HOME/logs/catalina.out 1.5 Troubleshooting a Viewpoint Installation 9 Chapter 1: Installing/upgrading Viewpoint tail -f $CATALINA_HOME/logs/catalina.out ...Outer Stack Trace... Caused by: pkg.SomeException: Error text here. ...Source Stack Trace... ...End useful logs... SEVERE: Error listenerStart ...top of the 'SEVERE: ' stack SEVERE: Context [/moab] startup failed due to previous errors The most useful information is the Caused by line and the Source Stack Trace, which can be easily found when you search for "SEVERE" and look directly above it. 2. If the error is not in the catalina.out file, search for it in the viewpoint.log file. Related topics l Installing/upgrading Viewpoint on page 1 1.6 Enhancing Viewpoint performance To optimize Viewpoint's performance, perform the following steps that are related to your operating system: To enhance Viewpoint's performance on an Ubuntu Linux operating system 1. Set JAVA_OPTS. /usr/share/tomcat6/bin/setenv.sh #Options for Tomcat server export JAVA_OPTS="-Xmx4g -XX:MaxPermSize=4g" 2. Set MaxThreads. /usr/share/tomcat6/conf/server.xml #Modify the number of threads for the connector <Connector port=#8080" protocol="HTTP/1.1" connectionTimout="20000" URIEncoding="UTF-8" maxThreads="300" redirectPort="8443" /> 3. Increase the number of open file handles to 2048. edit the /etc/init.d/tomcat6 file #Set ulimit, set number of open file handles to 2048 ulimit -n 2048 To enhance Viewpoint's performance on a CentOS or RHEL operating system 1. Set JAVA_OPTS. cd /usr/share/tomcat6/bin/ touch setenv.sh edit setenv.sh #Options for Tomcat server export JAVA_OPTS="-Xmx4g" 10 1.6 Enhancing Viewpoint performance Chapter 1: Installing/upgrading Viewpoint chmod +x setenv.sh chown root:tomcat setenv.sh 2. Set MaxThreads. /etc/tomcat6/server.xml #Modify the number of threads for the connector <Connector port=#8080" protocol="HTTP/1.1" connectionTimout="20000" maxThreads="300" redirectPort="8443" /> 3. Increase the number of open file handles to 2048. edit the /etc/init.d/tomcat6 file #Set ulimit, set number of open file handles to 2048 ulimit -n 2048 Related topics l Installing/upgrading Viewpoint on page 1 1.6 Enhancing Viewpoint performance 11 Chapter 2: Configuring Viewpoint Once you have completed the prerequisites and installed Viewpoint using the instructions in Installing/upgrading Viewpoint on page 1, you must then configure it to work at least with Moab Workload Manager, Moab Web Services, and the Viewpoint database. If you have installed a MySQL database for Moab and reporting, also configure that connection. You may do so manually using the core.xml, ViewpointConfig.groovy, hibernate.cfg.xml, and reporting.xml files respectively (see Manually configuring Viewpoint on page 24), or you can use the interface as demonstrated in the instructions that follow. When you set the Host name on the Viewpoint database, Moab database, Moab, and Moab Web Services configuration pages, type the actual host name to prevent Viewpoint errors. Depending on a server's configuration, setting "localhost" may not work. Configuring Viewpoint via the interface does not include upgrading. To upgrade Viewpoint, you must do so manually. l Configuring Viewpoint through the interface on page 13 l Manually configuring Viewpoint on page 24 l Configuring Viewpoint Users in Moab on page 39 l Configuring a connection from Viewpoint to Moab on page 25 l Configuring Viewpoint to communicate with your DBMS on page 29 l Connecting Viewpoint to the Moab Web Services on page 37 l Configuring security in Viewpoint on page 40 l Synchronizing job template names on page 59 l Configuring Viewpoint to run the Events report on page 177 2.1 Configuring Viewpoint through the interface When you use the interface to configure Viewpoint, Viewpoint automatically writes the necessary code into the configuration files as you submit the forms. Viewpoint also synchronizes the files with the database so that the information can be contained in the application rather than in the configuration files. If a conflict occurs during synchronization, information in the files takes precedence over the information in the database. 2.1 Configuring Viewpoint through the interface 13 Chapter 2: Configuring Viewpoint Configuration through the interface is for clean installations only. Upgrades must be done manually. See Manually configuring Viewpoint on page 24. Whenever Viewpoint writes to the configuration files, you will lose all your comments and formatting. Remember to always back up your configuration files before configuring anything in the interface. You can make changes manually in the configuration files in addition to using configuration in the Viewpoint interface; however, this cannot be done at the same time. The configuration files must not be opened outside of Viewpoint when you are making updates via the user interface. To configure Moab Viewpoint using the user interface 1. Give any desired Viewpoint users access to Moab. See Configuring Viewpoint Users in Moab on page 39. 2. Open Viewpoint in a browser using the following URL: http://[localhost]:8080/moab. Log in with the default User name and Password (admin/admin). For information about changing the default password, see Changing user passwords. 3. Click on the Configuration link on the top navigation bar. The Config Home page contains a list of configuration categories on the right with their current statuses. If an error appears beneath a category, click on the error message to open the corresponding configuration page. You can also navigate to each configuration page using the links on the left as described in steps 4-9. 14 2.1 Configuring Viewpoint through the interface Chapter 2: Configuring Viewpoint 4. Set the license type in the customer configuration section (See step 7 of Configuring customers via the interface on page 20). Viewpoint is automatically configured to work with Cloud. If you are an HPC user, however, you must restart Tomcat after setting the license. 5. Set up the Moab configuration. See Configuring the Moab database via the interface on page 15. 6. Set up the Viewpoint configuration. See Configuring the Viewpoint database via the interface on page 17. 7. Set up the Moab Web Services configuration. See Connecting to Moab Web Services via the interface on page 18. 8. Set up the customer configuration. See Configuring customers via the interface on page 20. 9. Set up the connection to Moab. See Connecting to Moab via the interface on page 21. 10. When you are redirected to Config Home, verify that no errors are present in your configuration. If an error does appear under one of the categories, click the error message to be taken back to the configuration page and make any necessary modifications. 11. To configure different security type from the default (Viewpoint security automatically installs with viewpointLoginModule with a username of admin and a password of admin), see Using ViewpointLoginModule on page 57. 12. (Optional) Configure Moab Accounting Manager to be accessible through Viewpoint. See Configuring Moab Accounting Manager in Viewpoint on page 38. 13. (Optional) Configure Viewpoint to run the VM Lifecycle and Events reports. See Configuring Viewpoint to run the Events report on page 177. Related topics l Configuring Viewpoint on page 13 l Manually configuring Viewpoint on page 24 2.1.1 Configuring the Moab database via the interface The only database that Moab can currently connect to via the interface is a MySQL database. To configure a connection to Moab's database through the Viewpoint interface 1. Open Viewpoint in a browser using the following URL: http://[localhost]:8080/moab. Log in with the default User name and Password (admin/admin). For information about changing the default password, see Changing user passwords in the User Guide. 2. Click the Configuration link in the navigation bar. 3. In the Configuration Objects list, click Moab Config. A configuration form appears on the right. 2.1 Configuring Viewpoint through the interface 15 Chapter 2: Configuring Viewpoint 4. Fill in each field with the requested information. Field Type Description Type of database Moab uses. Currently, the only valid option is mysql. Host Where the database server is running. Name Unique name of the database on the server. User Username used to log in to the database server. Password Password for the username of the database server. Port Port the database server is listening on. 5. Click Update. 6. When you are redirected to Config Home, verify that no errors are present in the Moab configuration. If an error does appear under the Moab header, you can click the error to be taken back to the configuration page and make any necessary modifications. 7. Restart the Tomcat server. > service tomcat6 stop > service tomcat6 start 16 2.1 Configuring Viewpoint through the interface Chapter 2: Configuring Viewpoint Related topics l Configuring Viewpoint through the interface on page 13 2.1.2 Configuring the Viewpoint database via the interface To configure the Viewpoint database through the interface 1. Run the db_setup.sql script to set up the database. > mysql -u <USER> -p < pathToVpInstallationDirectory/db_setup.sql 2. Create the hibernate.cfg.xml file. 3. If you have not already done so, increase Tomcat's memory from its default setting (for more information, see step 1 in Before installing Viewpoint on page 1 ). 4. Open Viewpoint in a browser using the following URL: http://[localhost]:8080/moab. Log in with the default User name and Password (admin/admin). For information about changing the default password, see Changing user passwords in the User Guide. 5. Click the Configuration button in the navigation bar. 6. In the left navigation pane, click Viewpoint Config in the Configuration Objects section. A configuration form appears on the right. 7. Fill in each field with the requested information. 2.1 Configuring Viewpoint through the interface 17 Chapter 2: Configuring Viewpoint Field Type Description Type of database Viewpoint uses. The options are mysql and oracle. Host Location where the database server is running. Name Unique name of the database on the server. User Username used to log in to the database server. Password Password for the username of the database server. Port Port the database server is listening on. 8. Click Update. 9. When you are redirected to Config Home, verify that no errors are present in the Viewpoint database connection. If an error does appear under the Viewpoint header, click the error to be taken back to the configuration page and make any necessary modifications. 10. Restart the Tomcat server. > service tomcat stop > service tomcat start Related topics l Configuring Viewpoint through the interface on page 13 2.1.3 Connecting to Moab Web Services via the interface To connect to Moab Web Services through the Viewpoint interface 1. Open Viewpoint in a browser using the following URL: http://[localhost]:8080/moab. Log in with the default User name and Password (admin/admin). For information about changing the default password, see Changing user passwords in the User Guide. 2. Click the Configuration button in the navigation bar. 3. In the left navigation pane, click MWS connection. A configuration form appears on the right. 18 2.1 Configuring Viewpoint through the interface Chapter 2: Configuring Viewpoint 4. Fill in each field with the information requested. Field Description Host Name of the server hosting Moab Web Services. Username Name of the user that communicates with Moab Web Services. Port Port that Viewpoint will use to communicate with the Moab Web Services. Version Id Version of Moab Web Services that is being used. This field is for display only and is not editable. Build Build number of Moab Web Services. Build Date Date the Moab Web Services build was created. Revision Revision number of Moab Web Services. Password Password being used to communicate with Moab Web Services. 5. Click Update. 2.1 Configuring Viewpoint through the interface 19 Chapter 2: Configuring Viewpoint 6. When you are redirected to Config Home, verify that no errors are present in the Viewpoint configuration. If an error does appear under the MWS header, click the error to be taken back to the configuration page and make any necessary modifications. 7. Restart the Tomcat server. > service tomcat stop > service tomcat start Related topics l Configuring Viewpoint through the interface on page 13 2.1.4 Configuring customers via the interface To configure Viewpoint customers using the Viewpoint interface 1. Open Viewpoint in a browser using the following URL: http://[localhost]:8080/moab. Log in with the default User name and Password (admin/admin). For information about changing the default password, see Changing user passwords in the User Guide. 2. Click the Configuration button in the navigation bar. 3. In the left navigation pane, click Customer Config. A configuration form appears on the right. 4. Fill in each field with the requested information: 20 2.1 Configuring Viewpoint through the interface Chapter 2: Configuring Viewpoint Field Description Software being run by the customer. The options are: License l CLOUD_BASIC (Moab Cloud Suite 7.0) l CLOUD_ENTERPRISE (Moab Cloud Suite 7.0 - HP CSA Edition) l HPC_BASIC (Moab HPC Suite 7.0 - Basic Edition) l HPC_ENTERPRISE (Moab HPC Suite 7.0 - Enterprise Edition) Because there is no difference between Basic and Enterprise editions in Viewpoint, you can safely specify Cloud or HPC in either edition. Name Name of the customer that is running the software. 5. Click Update. 6. When you are redirected to Config Home, verify that no errors are present in the Viewpoint configuration. If an error does appear under the Customer header, click the error to be taken back to the configuration page and make any necessary modifications. 7. Restart the Tomcat server. > service tomcat stop > service tomcat start Related topics l Configuring Viewpoint through the interface on page 13 2.1.5 Connecting to Moab via the interface To connect Viewpoint to Moab using the Viewpoint interface 1. Open Viewpoint in a browser using the following URL: http://[localhost]:8080/moab. Log in with the default User name and Password (admin/admin). For information about changing the default password, see Changing user passwords in the User Guide. 2. Click the Configuration button in the navigation bar. 3. In the left navigation pane, click Moab connection. A configuration form appears on the right. 2.1 Configuring Viewpoint through the interface 21 Chapter 2: Configuring Viewpoint 4. Set the Type, or the type of connection you're using to connect Viewpoint and Moab. Valid connection types are: 22 Connection type Description sshpassword A connection to the Moab server via SSH that requires password authentication. ssh-key A connection to the Moab server via SSH that requires private key authentication. local A local connection to Moab that operates through a shell. process A local connection to Moab that directly invokes commands. This is more secure than local, but disables some features in Viewpoint. 2.1 Configuring Viewpoint through the interface Chapter 2: Configuring Viewpoint 5. Configure the required settings and any desired optional settings based on the type selected. The following table displays which fields are required, optional, and non-applicable for each type: Setting Description Local type SSHpassword type SSHkey type Process Public Key File The path on the Viewpoint server to the public key file used for SSH authentication N/A N/A Required N/A Host The host name of the Moab server N/A Required Required N/A User The username used to connect to the Moab server N/A Required Required N/A Password The password used to authenticate N/A Required N/A N/A Moab Path By default, the $PATH variable will be searched for the Moab client commands. If you are unable to connect to Moab, try finding the client commands in /opt/moab/bin. Optional Optional Optional Optional Key Passphrase The private key passphrase used to authenticate N/A N/A Required N/A Initial Connections The number of Moab connections created when Viewpoint starts. The default is 1. Optional Optional Optional Optional Maximum Connections The maximum number of Moab connections allowed. The default is 10. Optional Optional Optional Optional Port The SSH port used to connect to Moab N/A Optional Optional N/A 6. Click Update. 7. When you are redirected to Config Home, verify that no errors are present in the Viewpoint configuration. If an error does appear under the Moab header, click the error to be taken back to the configuration page and make any necessary modifications. 8. Restart the Tomcat server. > service tomcat stop > service tomcat start 2.1 Configuring Viewpoint through the interface 23 Chapter 2: Configuring Viewpoint Related topics l Configuring Viewpoint through the interface on page 13 2.1.6 Troubleshooting errors If you run into problems while configuring Viewpoint via the interface, try running clean script(s) and reinstalling Viewpoint. > mysql -u <USER> -p < pathToVpInstallationDirectory/db_reset.sql > mysql -u <USER> -p < pathToVpInstallationDirectory/db_setup.sql When you reinstall or recover, verify that the license type is set so that you get the correct defaults. If problems persist, contact Adaptive Computing support using the following instructions. To contact support about your configuration via the Viewpoint interface 1. Place the ViewpointConfig.groovy file in your Viewpoint home directory. Set a logger for com.ace and com.cri each at debug level (see Customizing logging on page 83). 2. Check the catalina.out and viewpoint.log files to verify that everything is logged, not just partial entries. If the entries are truncated, create a logger for whichever package is causing it (it's usually caused by the first, or one of the first, lines in the stack trace, so create the logger for whichever package relates to that). Restart Tomcat and reproduce the problem. 3. Dump the database to Viewpoint home. 4. Zip the Viewpoint home directory with the database snapshot and logs. 5. Email the file to Adaptive Computing. In the body of the email, add all the steps taken prior to failure and the steps already taken to diagnose Viewpoint, including the steps listed previously. Related topics l Configuring Viewpoint through the interface on page 13 2.2 Manually configuring Viewpoint Viewpoint for Moab HPC Suite can be configured automatically in the Viewpoint user interface (see Configuring Viewpoint through the interface on page 13); however, you may want to manually install or modify settings through the core.xml. To configure Viewpoint this way, follow the instructions below. To modify an individual section, see the corresponding page for information. To install Viewpoint for Moab HPC Suite using the core.xml file 1. Verify that you have the correct versions of the software required and install Viewpoint according to the instructions given in Installing/upgrading Viewpoint on page 1. 2. Give any desired Viewpoint users access to Moab. See Configuring Viewpoint Users in Moab on page 39. 24 2.2 Manually configuring Viewpoint Chapter 2: Configuring Viewpoint 3. Create a connection from Viewpoint to Moab. To do so, follow the instructions given in Configuring a connection from Viewpoint to Moab on page 25. Configure your settings based on the connection type: l Configuring a local Moab connection on page 27 l Configuring a process Moab connection on page 26 l Configuring an SSH password-authenticated Moab connection on page 27 l Configuring an SSH private-key-authenticated Moab connection on page 28 4. Create a connection to the database by following the instructions in Configuring Viewpoint to communicate with your DBMS on page 29. 5. Connect Viewpoint to Moab Web Services. See Connecting Viewpoint to the Moab Web Services on page 37. 6. Configure Viewpoint security by following the instructions in Configuring security in Viewpoint on page 40. 7. (Optional) Configure Moab Accounting Manager to be accessible through Viewpoint. See Configuring Moab Accounting Manager in Viewpoint on page 38. 8. (Optional) Configure Viewpoint to run the VM Lifecycle and Events reports. See Configuring Viewpoint to run the Events report on page 177. Related topics l Configuring Viewpoint through the interface on page 13 l Configuring Viewpoint on page 13 2.2.1 Configuring a connection from Viewpoint to Moab In order to function, a Viewpoint client must connect to a Moab server. However, creating a new server connection on demand can be expensive in terms of time and resources. The primary purpose of the connection manager module is to recycle existing connections, thus avoiding the cost of creating new ones. Note that factors such as network latency, resource utilization on the Moab and Viewpoint servers, and the network proximity of the Moab and Viewpoint servers affect application performance and user experience. Take these factors into consideration when fine-tuning for optimal performance. To configure a connection from Viewpoint to Moab In Viewpoint's core.xml file, locate <moab-connection> and set the connection type to one of the following options. Provide the required information and any optional information desired according to the type's instructions: Option Description "local" A local connection to Moab that operates through a shell. See Configuring a local Moab connection on page 27. 2.2 Manually configuring Viewpoint 25 Chapter 2: Configuring Viewpoint Option Description "process" A local connection to Moab that directly invokes commands. This is more secure than local, but disables some features in Viewpoint. See Configuring a process Moab connection on page 26. "sshpassword" A connection to the Moab server via SSH that requires password authentication. See Configuring an SSH password-authenticated Moab connection on page 27. "ssh-key" A connection to the Moab server via SSH that requires private key authentication. See Configuring an SSH private-key-authenticated Moab connection on page 28. This section contains these topics: l Configuring a process Moab connection on page 26 l Configuring a local Moab connection on page 27 l Configuring an SSH password-authenticated Moab connection on page 27 l Configuring an SSH private-key-authenticated Moab connection on page 28 2.2.1.1 Configuring a process Moab connection A process connection is a local connection to Moab that directly invokes commands. This is more secure than a local connection, but it will disable some features in Viewpoint. To configure a process Moab connection 1. Open the core.xml file located in the Viewpoint home directory. 2. Locate the <moab-connection> element and change the type to "process". 3. Set any of the following optional elements: l l l Set <initial-connections> to the number of connections created when the server starts. The default is 1. Set <maximum-connections> to the maximum number of connections allowed. The default is 10. Set <moab-path> to the location of the Moab commands. By default, the operating system path is searched for Moab commands. <moab-connection type="process"> <!-- optional elements --> <initial-connections>5</initial-connections> <maximum-connections>10</maximum-connections> <moab-path>/usr/moab/bin</moab-path> </moab-connection> 26 2.2 Manually configuring Viewpoint Chapter 2: Configuring Viewpoint Related topics l Configuring a connection from Viewpoint to Moab on page 25 l Configuring a local Moab connection on page 27 l Configuring an SSH password-authenticated Moab connection on page 27 l Configuring an SSH private-key-authenticated Moab connection on page 28 2.2.1.2 Configuring a local Moab connection A local connection is a local connection to Moab that operates through a shell. To configure a local Moab connection 1. Open the core.xml file located in the Viewpoint home directory. 2. Locate the <moab-connection> element and change the type to "local". 3. If desired, set the following optional elements: l l l Set <initial-connections> to the number of connections created when the server starts. The default is 1. Set <maximum-connections> to the maximum number of connections allowed. The default is 10. Set <moab-path> to the location of the Moab commands. By default, the operating system path is searched for Moab commands. <moab-connection type="local"> <!-- optional elements --> <initial-connections>5</initial-connections> <maximum-connections>10</maximum-connections> <moab-path>/usr/moab/bin</moab-path> </moab-connection> Related topics l Configuring a connection from Viewpoint to Moab on page 25 l Configuring a process Moab connection on page 26 l Configuring an SSH password-authenticated Moab connection on page 27 l Configuring an SSH private-key-authenticated Moab connection on page 28 2.2.1.3 Configuring an SSH password-authenticated Moab connection A SSH password-authenticated Moab connection is a connection to the Moab server via SSH that requires password authentication. To configure a SSH password-authenticated Moab connection 1. Open the core.xml file located in the Viewpoint home directory. 2. Locate the <moab-connection> element and change the type to "ssh-password". 3. Modify <host> to specify the host name of the Moab server. 2.2 Manually configuring Viewpoint 27 Chapter 2: Configuring Viewpoint 4. Modify <user> to specify the username used to connect via SSH to the Moab server. 5. Modify <password> to specify the password used to authenticate. 6. Configure any of the following optional elements: l l l l Set <initial-connections> to the number of connections created when the server starts. The default is 1. Set <maximum-connections> to the maximum number of connections allowed. The default is 10. Set <moab-path> to the location of the Moab commands. By default, the operating system is searched for Moab commands. Set <port> to the SSH port used to connect to Moab. <moab-connection type="ssh-password"> <!-- required elements --> <host>moab-host</host> <user>moab-host</user> <password>password</password> <!-- optional elements --> <initial-connections>5</initial-connections> <maximum-connections>10</maximum-connections> <moab-path>/usr/moab/bin</moab-path> <port>22</port> </moab-connection> Related topics l Configuring a connection from Viewpoint to Moab on page 25 l Configuring a local Moab connection on page 27 l Configuring a process Moab connection on page 26 l Configuring an SSH private-key-authenticated Moab connection on page 28 2.2.1.4 Configuring an SSH private-key-authenticated Moab connection A SSH private-key-authenticated Moab connection is a connection to the Moab server via SSH that requires private key authentication. To configure a SSH private-key-authenticated Moab connection 1. Open the core.xml file located in the Viewpoint home directory. 2. Locate the <moab-connection> element and change the type to "ssh-key". 28 2.2 Manually configuring Viewpoint Chapter 2: Configuring Viewpoint 3. Set the following required elements for SSH private key authentication: a. Specify <host> as the host name of the Moab server. b. Modify <user> to specify the username used to connect via SSH to the Moab server. c. Modify <public-key-path> to specify the path on the Viewpoint server to the public key file used for SSH authentication. d. Modify <password> to specify the private key passphrase. 4. Set any of the following optional elements: l l l l Set <initial-connections> to the number of connections created when the server starts. The default is 1. Set <maximum-connections> to the maximum number of connections allowed. The default is 10. Set <moab-path> to the location of the Moab commands. By default, the operating system path is searched for Moab commands. Set <port> to the SSH port used to connect to Moab. <moab-connection type="ssh-key"> <!-- required elements --> <host>moab-server</host> <user>moab-user</user> <public-key-path> /home/moab-user/.ssh/id_rsa.pub </public-key-path> <password></password> <!-- optional elements --> <initial-connections>5</initial-connections> <maximum-connections>10</maximum-connections> <moab-path>/usr/moab/bin</moab-path> <port>22</port> </moab-connection> Related topics l Configuring a connection from Viewpoint to Moab on page 25 l Configuring an SSH password-authenticated Moab connection on page 27 l Configuring a local Moab connection on page 27 l Configuring a process Moab connection on page 26 2.2.2 Configuring Viewpoint to communicate with your DBMS Viewpoint uses a database and relies on Hibernate, an Object/Relational Mapping (ORM) tool for Java programs, to communicate with the database. For Viewpoint to recognize and work with your database management system (DBMS), you must configure the hibernate.cfg.xml settings file. Hibernate relies on the JDBC specification. Viewpoint works with the following database management systems: MySQL and Oracle. 2.2 Manually configuring Viewpoint 29 Chapter 2: Configuring Viewpoint To configure Viewpoint to communicate with your DBMS 1. Learn how to do the following steps by consulting the vendor documentation: a. Verify your DBMS is running and that it accepts remote connections. b. Create a database in your DBMS for use with Viewpoint. c. Use the SQL DDL files in the sql folder of your unzipped Viewpoint distribution to set up the tables, foreign key constraints, and so forth that Viewpoint is expecting. If using an unsupported JDBC driver, tailor one of the schema files to fit any DBMS specific syntax you have 2. Open hibernate.cgf.xml located in the Viewpoint home directory. 3. Set the hibernate.dialect property to the appropriate class for your DBMS as listed in the Hibernate Dialects tables that follow. 4. Set the hibernate.connection.driver class to the appropriate class for your DBMS as listed in the Hibernate Dialects tables that follow. 5. Modify the hibernate.connection.url to point to the database location. As each DBMS database driver has slightly different connection URL syntax, you may need to consult the documentation for the JDBC driver for your DBMS. However, they often have the following form: jdbc:<DBMS vendor>://<server>[:<port>]/<database> To help you get started quickly, some sample hibernate.connection.urls are listed in the Hibernate Dialects tables that follow. 6. Specify a username and password in the respective property elements. 7. If using MySQL or Oracle, download the JDBC drivers separately and place them where Viewpoint can find them. l l Download the MySQL driver. The driver will come in a tar.gz or a zip file. The jar file will be inside this tar.gz or zip file and will likely be named something like mysql-connector-java-x.x.xbin.jar. Download the Oracle driver from the Oracle web site. Get the appropriate driver jar file for your Oracle database version. We recommend the drivers in the "JDBC Thin for All Platforms" section of that page. Also note you will need to get an Oracle driver compatible with JDK 1.4 and 1.5. 8. Extract the contents of the database driver file and place the jar file in the tomcat/webapps/moab/WEB-INF/lib directory before you start Viewpoint. SQL Server Hibernate Dialects 30 Dialect org.hibernate.dialect.SQLServerDialect connection.driver_class net.sourceforge.jtds.jdbc.Driver Sample Connection URL jdbc:jtds:sqlserver://localhost:41433/my_database 2.2 Manually configuring Viewpoint Chapter 2: Configuring Viewpoint MySQL Hibernate Dialects Dialect org.hibernate.dialect.MySQLInnoDBDialect connection.driver_class com.mysql.jdbc.Driver Sample Connection URL jdbc:mysql://localhost/my_database PostgreSQL Dialect org.hibernate.dialect.PostgreSQLDialect connection.driver_class org.postgresql.Driver Sample Connection URL jdbc:postgresql://localhost/my_database Oracle Hibernate Dialects Dialect com.cri.poller.hibernate.Oracle10gDialect connection.driver_class org.postgresql.Driver Sample Connection URL jdbc:oracle:thin:moab/moab@localhost:1521/XE The following is an example of a MySQL configuration in the hibernate.cfg.xml file: <property name="hibernate.connection.driver_ class">com.mysql.jdbc.Driver</property> <property name="hibernate.dialect">org.hibernate.dialect.MySQLInnoDBDialect</property> <property name="hibernate.connection.url">jdbc:mysql://localhost/my_ database</property> <property name="hibernate.connection.username">moab</property> <property name="hibernate.connection.password">p@ssw0rd</property> 9. To enable schema namespaces, which is a way of logically grouping table within a single database into separate containers, configure the optional hibernate.default.schema property by performing the following steps: a. Open the hibernate.cfg.xml file located in the Viewpoint home directory and add the following line: <property name="hibernate.default_schema">myschema</property> b. Open the unzipped Viewpoint distribution directory and navigate to the sql directory. 2.2 Manually configuring Viewpoint 31 Chapter 2: Configuring Viewpoint c. Modify the SQL DDL files that set up the tables, foreign key constraints, and so forth that Viewpoint is expecting . To do so, prepend "<schema name>." to the table name for every line in the SQL DDL file that references a table name. An original file might look like the following example: drop table MoabNode_VM; create table MoabNode_VM (MoabNode_nodeID varchar(255) not null, vms_id varchar (255) not null, ... alter table MoabNode_VM add constraint FK_MoabNodeVM_VM_ID foreign key ... The amended lines should appear as follows: drop table myschema.MoabNode_VM; create table myschema.MoabNode_VM (MoabNode_nodeID varchar(255) not null, vms_id varchar(255) not null, ... alter table myschema.MoabNode_VM add constraint FK_MoabNodeVM_VM_ID foreign key ... ADDITIONAL CONNECTION PARAMETERS In addition to the JDBC connection parameters you will notice that the sample hibernate.cfg.xml file has many other properties. You may also notice some mapping elements, like <mapping class="com.cri.cart.server.ShoppingCart" /> Refrain from modifying properties or mappings without talking to support first as modifications may cause problems with the communication between Viewpoint and the database. For more information on what these configuration options do, please refer to the Hibernate documentation. Mapping elements enable Viewpoint to manage database tables for certain features. In particular, Viewpoint will be able to manage tables for the Java class referenced by the class attribute. It is recommended that you not modify these mappings or Viewpoint may not be able communicate properly with the database. Below is an explanation of the other properties in the hibernate.cfg.xml file. hibernate.transaction.auto_close_session Suggested value true (Strongly recommended) Description If enabled, the persistence session is automatically closed after the completion phase of its database transactions. The alternative is to have the application close these sessions manually. In Viewpoint this should be set to true. hibernate.connection.autocommit Suggested value 32 false (Strongly recommended) 2.2 Manually configuring Viewpoint Chapter 2: Configuring Viewpoint hibernate.connection.autocommit When true, this parameter causes autocommit to be enabled for the JDBC connections in the connection pool. It is strongly recommended that this be false. Autocommit mode allows each individual SQL statement to be executed in its own transaction. Starting these extra transactions causes lots of overhead and destroys atomicity and isolation guarantees for operations that should be grouped together in a transaction. Description hibernate.current_session_context_class Suggested value thread (Strongly recommended) Description How the hibernate session should be bound. Although hibernate supports "thread", "jta", and "managed" as legal values for this parameter, in Viewpoint this should be set to "thread". "thread" causes sessions to be bound to threads. "jta" binds sessions to JTA transactions and "managed" causes the responsibility for managing session scope, start, and end to the application. hibernate.show_sql Suggested value false Causes all SQL statements to be printed to the console. Description A better option is to cause SQL to be sent to the log instead of the console. To do this set the log category org.hibernate.SQL to debug in the ViewpointConfig.groovy file. hibernate.format_sql Suggested value true Description Causes the SQL printed to the log and the console to be pretty printed connection.provider_class Suggested value org.hibernate.connection.C3P0ConnectionProvider 2.2 Manually configuring Viewpoint 33 Chapter 2: Configuring Viewpoint connection.provider_class Description Configures the JDBC connection pool which makes communication with the database more efficient. Viewpoint supports only c3p0, or no connection pool. To disable connection pooling. the connection.provider_class property can be commented out. hibernate.c3p0.min_size Suggested value 5 Description Configures the JDBC connection pool which makes communication with the database more efficient. Viewpoint supports only c3p0, or no connection pool. To disable connection pooling. the connection.provider_class property can be commented out. hibernate.c3p0.max_size Suggested value 20 Description Configures the JDBC connection pool which makes communication with the database more efficient. Viewpoint supports only c3p0, or no connection pool. To disable connection pooling. the connection.provider_class property can be commented out. hibernate.c3p0.timeout Suggested value 25000 Description The minimum number of JDBC connections that c3p0 keeps ready at all times. This property is supported with only the c3p0 connection provider. hibernate.c3p0.max_statements 34 Suggested value 0 Description The number of prepared statements that c3p0 will cache. Although prepared statement caching improves performance it has been linked to sporadic race conditions due to bugs in c3p0. For that reason it is recommended to set this to 0 to disable prepared statement caching. This property is supported with only the c3p0 connection provider. 2.2 Manually configuring Viewpoint Chapter 2: Configuring Viewpoint hibernate.c3p0.idle_test_period Suggested value 3000 Description The idle time in seconds before a connection is automatically validated. This causes the connection to be kept alive even when idle so it doesn't get closed by a firewall. This property is supported with only the c3p0 connection provider. OUT-OF-THE-BOX HIBERNATE.CFG.XML SETTINGS The following represents the default hibernate.cfg.xml settings in Viewpoint: <hibernate-configuration> <session-factory> <!-- General properties --> <property name="hibernate.transaction.auto_close_session">true</property> <property name="hibernate.connection.autocommit">false</property> <property name="hibernate.current_session_context_ class">thread</property> <!-- Setting the schema namespace (Optional) --> <!-<property name="hibernate.default_schema">dbo</property> --> <!-- MySQL connections --> <property name="hibernate.connection.driver_ class">com.mysql.jdbc.Driver</property> <property name="hibernate.dialect">org.hibernate.dialect.MySQLInnoDBDialect</property> <property name="hibernate.connection.url">jdbc:mysql://localhost/my_database</property> <property name="hibernate.connection.username">moab</property> <property name="hibernate.connection.password">p@ssw0rd</property> <!-- Postgres connections --> <!-<property name="hibernate.connection.driver_class">org.postgresql.Driver</property> <property 2.2 Manually configuring Viewpoint 35 Chapter 2: Configuring Viewpoint name="hibernate.dialect">org.hibernate.dialect.PostgreSQLDialect</property> <property name="hibernate.connection.url">jdbc:postgresql://localhost/my_ database</property> <property name="hibernate.connection.username">Moab</property> <property name="hibernate.connection.password">p@ssw0rd</property> --> <!-- H2 connections --> <!-<property name="hibernate.connection.driver_class">org.h2.Driver</property> <property name="hibernate.dialect">org.hibernate.dialect.H2Dialect</property> <property name="hibernate.connection.url">jdbc:h2:tcp://localhost/~/my_ database</property> <property name="hibernate.connection.username">sa</property> <property name="hibernate.connection.password">p@ssw0rd</property> --> <!-- Sql Server connections --> <!-<property name="hibernate.connection.driver_class">net.sourceforge.jtds.jdbc.Driver</property> <property name="hibernate.dialect">org.hibernate.dialect.SQLServerDialect</property> <property name="hibernate.connection.url">jdbc:jtds:sqlserver://localhost:41433/my_ database;tds=8.0</property> <property name="hibernate.connection.username">Moab</property> <property name="hibernate.connection.password">p@ssw0rd</property> 36 2.2 Manually configuring Viewpoint Chapter 2: Configuring Viewpoint --> <!-- Use the C3P0 connection pool provider --> <property name="connection.provider_class">org.hibernate.connection.C3P0ConnectionProvider</property> <property name="hibernate.c3p0.min_size">5</property> <property name="hibernate.c3p0.max_size">20</property> <property name="hibernate.c3p0.timeout">40</property> <property name="hibernate.c3p0.max_statements">0</property> <property name="hibernate.c3p0.idle_test_period">3000</property> <!-- Show SQL on stdout --> <property name="hibernate.show_sql">false</property> <property name="hibernate.format_sql">false</property> <!-- Shopping Cart classes --> <mapping class="com.cri.cart.server.ShoppingCart"/> <mapping class="com.cri.cart.server.ShoppingCartLineItem"/> <mapping class="com.cri.cart.server.ShoppingCartItem"/> <!-- Archive classes --> <mapping class="com.cri.archival.server.model.Archive"/> <mapping class="com.cri.archival.server.model.ArchiveObject"/> <!-- VPC user classes --> <mapping class="com.cri.provisioning.environmentmgt.server.model.VpcUser"/> <mapping class="com.cri.component.server.form.persistmodel.FormStatePersistModel"/> <mapping class="com.cri.security.server.SecurityUser"/> </session-factory> </hibernate-configuration> Related topics l Manually configuring Viewpoint on page 24 2.2.3 Connecting Viewpoint to the Moab Web Services Viewpoint must connect to the Moab Web Services in order to communicate with Moab. If you receive bad request (400) errors in Viewpoint, Web Services could be down, unavailable, or incorrectly connected. 2.2 Manually configuring Viewpoint 37 Chapter 2: Configuring Viewpoint To manually connect Viewpoint to the Moab Web Services 1. Open the ViewpointConfig.groovy file, which is located in the Viewpoint home directory. 2. Look for the following entry: mws { baseUrl="http://localhost:8080/mws/rest" username="admin" password="secret" } Modify the content according to your Moab Web Services settings, specifying your host name, username, and password. 3. Save the file and restart Tomcat. Related topics l Manually configuring Viewpoint on page 24 2.2.4 Configuring Moab Accounting Manager in Viewpoint In order to embed Moab Accounting Manager within Viewpoint so that users may use it within the Viewpoint interface, you must define the URL in the ViewpointConfig.groovy file according to the following instructions. The Moab Accounting Manager configuration code is commented out by default. If you configure MAM and no longer wish to use it, comment it out again so that it does not fail in Viewpoint. To configure Moab Accounting Manager in Viewpoint 1. Open the ViewpointConfig.groovy file, located in the Viewpoint home directory. 2. Uncomment the mam.url parameter like the one shown in the following example. Modify it according to your host name. mam.url="https://localhost/cgi-bin/mam/index.cgi?start=login" When users navigate to Moab Accounting Manager using the link in Viewpoint's navigation, they are forwarded to the URL provided. Moab Accounting Manager then becomes embedded in Viewpoint. If opening MAM in Viewpoint fails, check the URL and verify that it is correctly configured. Related topics l Configuring Viewpoint for Quoting on page 38 l Configuring Viewpoint on page 13 2.2.5 Configuring Viewpoint for Quoting Quoting allows you to view the price of a potential service before it is actually submitted to Moab. 38 2.2 Manually configuring Viewpoint Chapter 2: Configuring Viewpoint Viewpoint Quoting is meant to be enabled by our Professional Services team. It is recommended that you contact that department to set up this feature. To configure Viewpoint for quoting 1. Place the following NAMI scripts somewhere on the Viewpoint server: l bank.quote.mam.pl l bank.account.mam.pl 2. Configure the quoting section of the ViewpointConfig.groovy file so that the keys point to the scripts' location. Set quote_enabled to "true". billing { quoting_enabled="true" quote="/opt/moab/tools/mam/bank.quote.mam.pl" accounts="/opt/moab/tools/mam/bank.account.mam.pl" } 3. Configure NAMI in Moab. See "Charging a Workflow" in the Moab Workload Manager documentation for details. Related topics l Manually configuring Viewpoint on page 24 2.3 Configuring Viewpoint Users in Moab To grant Viewpoint users Moab access 1. Open your moab.cfg file located in the Moab home directory. 2. Set the ADMINCFG[1] parameter (admin level 1 group) to include the Viewpoint users that will be granted full administrative rights. Enable proxying. ADMINCFG[1] USERS=<viewpoint-user> ENABLEPROXY=TRUE If you would like to control administrative access via LDAP or SSO, you must give all users ADMINCFG[1] access. LDAP and Viewpoint permission settings will keep normal users from performing administrative functions in Viewpoint. ADMINCFG[1] USERS=root,tomcat,ALL ENABLEPROXY=TRUE 3. Either specify the Moab path (<moab-path>) or include the location of the Moab client commands in the Viewpoint user's $PATH environment variable. 4. Save your updated moab.cfg settings. Related topics l Configuring Viewpoint on page 13 2.3 Configuring Viewpoint Users in Moab 39 Chapter 2: Configuring Viewpoint 2.4 Configuring security in Viewpoint This section contains information about the following security settings in Viewpoint: l Setting <security> permissions on page 40 l Configuring HTTPS in Tomcat on page 41 l Integrating with Single-Sign-On (SSO) authentication schemes on page 44 l Integrating Viewpoint with LDAP/Active Directory on page 45 l Configuring role definitions on page 49 l Configuring the permissions map on page 50 l Configuring login modules on page 56 l Configuring the request handler on page 58 2.4.1 Setting <security> permissions To set <security> permissions 1. Open the core.xml file located in the Viewpoint home directory. Locate the <security> element. 2. Modify the <security> settings according to your preferences: a. Set <permissions-caching> to true to enable permissions to cache in the HttpSession associated with a given user. Set it to false to require users to re-authenticate each time they make a request. A value of false can be useful if a single sign-on system is enabled. b. Set <login-jsp-path> to point to the jsp file that presents the application page. Ensure that the tomcat user has at least read access to this file. The path is relative to the Web application. For example, WEB-INF/login.jsp resolves to (assuming the default location of tomcat and a web application named "sample") /var/lib/tomcat6/webapps/sample/WEB-INF/login.jsp and /WEBINF/login.jsp resolves to /WEB-INF/login.jsp. c. Set <login-servlet-path> to point to the servlet that authenticates a user attempting to get the Viewpoint application. This URL must be visible to the Web browser. By default, this is set to /login d. Set <app-jsp-path> to point to the jsp file that presents the application page. Ensure that the tomcat user has at least read access to this file. e. Set <app-servlet-path> to point to the servlet that serves the Viewpoint application. This URL must be visible to any given Web browser. 40 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint f. Set <logout-parameter> to the HTTP parameter used by the application and login servlets to assess whether the user is attempting to log out. This is used in the navigation configuration to create a Logout link. The URL in this case is /${login-servlet}?${logout-parameter} g. The <username-parameter> element is the HTTP request parameter used by the application to determine the user’s username. Related topics l Configuring security in Viewpoint on page 40 2.4.2 Configuring HTTPS in Tomcat The following instructions for running Viewpoint over HTTPS offer general procedures to accommodate a variety of possible specifications. If you require more specific instruction, consider reviewing the Tomcat documentation. To configure HTTPS in Tomcat 1. Open the server.xml file, usually located in $CATALINA_HOME/conf/ ($CATALINA_HOME represents the directory where Tomcat is installed). 2. Verify the SSL HTTP/1.1 Connector entry is enabled. To do so: a. Locate the SSL HTTP/1.1 Connector entry: <!-<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" /> --> b. Uncomment the Connector element by removing <!-- at the beginning of the entry and --> at the end of the entry. c. Save the file and restart Tomcat. The code above enables SSL access on port 8443. The default for HTTPS is 443, but just as Tomcat uses 8080 instead of 80 to avoid conflicts, 8443 is used instead of 443 here. 3. Verify that folder permissions are owned by the Tomcat user. If you use Tomcat 6, the default user is tomcat6. #change ownership of tomcat directory chown -R tomcat6:tomcat6 /opt/tomcat This section contains these topics: l Generating and storing a self-signed certificate on page 42 l Exporting for local keystore import on page 42 l Modifying the Viewpoint web.xml file to enable HTTPS on page 43 2.4 Configuring security in Viewpoint 41 Chapter 2: Configuring Viewpoint 2.4.2.1 Generating and storing a self-signed certificate Self-signed certificates are useful in cases where you require encryption but do not need to verify the website identity. Using a self-signed certificate instead of one signed by a Certificate Authority (CA), users gaining initial access to the site may get prompted that the site is untrusted and may have to perform several steps to "accept" the certificate before they can access the site. This usually only occurs the first time they access the site. You may prefer to obtain and install a certificate from a Certificate Authority; if so, refer to the Tomcat documentation for installing a certificate from a CA. To generate and store a self-signed certificate 1. Create a .keystore file that contains the self-signed certificate. If it doesn't already exist, you can create it by running the keytool command. The new .keystore file appears in the home directory of the user used to run the keytool command. 2. To specify a different location or filename, add the -keystore parameter followed by the complete pathname to the keystore file, to the keytool. 3. Include the new location in the server.xml configuration file. From a command line, run the keytool command: $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA 4. After running the keytool command, you will be prompted for two passwords: (1) the keystore password and (2) the key password for Tomcat. You must use the same value for both passwords, and the value must be either: l "changeit" (the default Tomcat value) or l a unique value you decide which you must also specify in $CATALINA_HOME/conf/server.xml by adding the following attribute to the SSL HTTP/1.1 Connector entry described earlier: keystorePass="<password value>" 5. You will be prompted for general information about the certificate. For the inquiry, "What is your first and last name?" you must enter the fully qualified hostname of the server running Viewpoint. When the client Web browser examines the certificate it checks this field and verifies that it matches the hostname. If it doesn't, it may prevent access to the site. 6. Give general information such as company, contact name, and so on when prompted. This information is visible to users who attempt to access a secure page in the application, so make sure that the information provided matches user expectations. Related topics l Configuring HTTPS in Tomcat on page 41 2.4.2.2 Exporting for local keystore import After creating the certificate, you must export it to make it ready for importing into the local keystore. 42 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint To export for local keystore import 1. Create the self-signed certificate. See Generating and storing a self-signed certificate on page 42. 2. Export it to make it ready for importing into the local keystore using the following command (assuming the name of your certificate is file.cer): $JAVA_HOME/bin/keytool -export -alias tomcat -file file.cer 3. Import the certificate into the keystore. $JAVA_HOME/bin/keytool -import -alias tomcat -file file.cer -keystore $JAVA_HOME/jre/lib/security/cacerts Related topics l Configuring HTTPS in Tomcat on page 41 2.4.2.3 Modifying the Viewpoint web.xml file to enable HTTPS To enable HTTPS, you must modify the Viewpoint web.xml file. Add a security-constraint section to the $CATALINA_HOME/webapps/Moab/WEB-INF/web.xml file. To modify the Viewpoint web.xml file to enable HTTPS 1. Open the web.xml file usually located in the $CATALINA_HOME/webapps/Moab/WEB-INF/ directory. 2. Add a <security-constraint> section to cause all pages to be hosted with HTTPS. <web-app> ... <security-constraint> <web-resource-collection> <web-resource-name>Viewpoint Secure URLs</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> </web-app> Modify the <url-pattern> text to specify which pages you want protected and which you do not. Related topics l Configuring HTTPS in Tomcat on page 41 2.4 Configuring security in Viewpoint 43 Chapter 2: Configuring Viewpoint 2.4.3 Integrating with Single-Sign-On (SSO) authentication schemes AJP (Apache Jserv Protocol) sets up an Apache server. SSO accesses the Apache server through Port 80, and the Apache server proxies messages to the Viewpoint server through Port 8000 (the only way that Viewpoint may be accessed). SSO inspects requests as they come in. If the user is authenticated, it sends authorization information (groups, username, email, etc.) to Apache for normal routing, which then passes the information to the Viewpoint server. If the user is not authenticated, it redirects to the SSO login. You can configure a parameter list and DN (distinguished name) parameter list to specify which information Viewpoint gathers during authentication. The parameter list takes the group name and applies the HttpHeaderPrincipal, granting access to certain permissions. The DN parameter list applies LdapGroupPrincipals to users as they sign in. Single Sign-On authentication provides more login flexibility and more responsiveness than Tomcat. To integrate with Single-Sign-On (SSO) Authentication Schemes 1. Open the core.xml file located in the Viewpoint home directory. Locate the <login-module> element. 2. Verify that the <login-module> class attribute is "com.cri.security.server.modules.HttpRequestLoginModule" and the flag attribute is "optional". <login-module class="com.cri.security.server.modules.HttpRequestLoginModule" flag="optional"> 3. Configure the parameter list to specify how to assign the HttpHeaderPrincipal to users. To do so, set the <option> child element within <login-module>. Give the name attribute a value of "parameter-list". Set it to the desired parameter. <option name="parameter-list">group</option> When Bob authenticates with the group name of admins, the principal of admins is applied with the HttpHeaderPrincipal and Bob is given associated permissions. More than one parameter may be specified using a comma-separated list with or without spaces. <option name="parameter-list">group,username</option> 4. Configure the DN (Distinguished Name) parameter list to attach LdapGroupPrincipals to each group name to which the user belongs. <option name="dn-parameter-list">dn</option> When the following parameters are received: Dn:"cn=bob,ou=admins,ou=uiteam,dc=example,dc=com" LdapGroupPrincipals of "admins" and "uiteam" are applied. Each instance of ou= refers to a group that will assign LdapGroupPrincipals. 44 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint Related topics l Configuring security in Viewpoint on page 40 2.4.4 Integrating Viewpoint with LDAP/Active Directory Viewpoint is equipped with pluggable security that easily handles integration with LDAP/Active Directory. Configuration for setting up LDAP authentication and authorization requires editing four elements in the core.xml file. When you select LDAP during Viewpoint installation, the core.xml file is automatically generated to include the login module, the permissions map, and a default, functional LDAP configuration; however, if you selected a different security method, you can manually configure Viewpoint to use LDAP/Active directory Several rules apply to configuring LDAP in Viewpoint. The DSA may only have one DIT unless it is specifically configured to allow searching from DSE (as with referrals). Any entry can be either an LDAP or Application user, but they are different: an LDAP user's rights are based on LDIF access to directives or proprietary framework, and an Application user (Viewpoint, email, web application, etc.) uses the entry's attributes or group membership to determine roles and permissions in the application. Security such as SSL/TLS and SASL must be configured outside of Viewpoint, and the Viewpoint server must be configured accordingly. To integrate with LDAP/Active Directory 1. Open the core.xml file located in the Viewpoint home directory and locate the <login-module> element. Specify the class as "com.cri.security.server.modules.LdapLoginModule". Define the LdapLoginModule by inserting the <option> element within <login-module> and applying the name attribute for each of the following: Option Description connectionURL The fully-qualified name of the initial context factory that will be used. The format is <protocol>://<server>:<port>. <protocol> should be 'ldap' or 'ldaps', <server> should be the hostname or IP address, and port is optional if the default is used (389 if the protocol is ldap, and 636 if it's ldaps). Setting the protocol to 'ldaps' overrides the connectionProtocol, forcing its setting to 'ssl'. connectionUsername The distinguished name used by the login module for authentication on the LDAP server. In many cases, this will be the bind user or some other read-only account created specifically for this purpose. Active Directory also accepts the format <user>@<domain>. connectionPassword The credential (password) of the user set in connectionUsername that is used for the login module to authenticate on the LDAP server. 2.4 Configuring security in Viewpoint 45 Chapter 2: Configuring Viewpoint 46 Option Description userBase The distinguished name (baseObject) for the user search. userSearchMatching The criteria (filter) in the search for the user object; for example: (cn=Joe User). Additionally, you can pass a parameter instead of the literal value to the search filter. If you want to parameterize the value of the attribute type (as when inserting the username that the user entered), specify (cn = {0}) for the case where you want to insert the username. userRoleName LDAP attribute type for the user group membership. Different LDAP schemas represent user group membership in different ways. Examples are memberOf, isMemberOf, member, and so forth. For example, if you have: memberOf: cn=admin,ou=groups,dc=foo, specify memberOf as the value for the userRoleName option. roleBase The base distinguished name (baseObject) for the search for the groups of which the user is a member. roleSearchMatching The criteria (filter) to be used to search for the role object. In addition you can pass a parameter instead of the literal value to the search filter; for example: (uniqueMember = {0}) for the case where you want to insert the username. roleName The LDAP attribute type that identifies the group name attribute in the object returned from the group membership query. Note that group membership query is defined by the roleSearchMatching parameter. Often, the group name parameter is cn. authentication The security level to be used. The value must be 'non', 'anonymous', 'simple', or '<saslmechanism>'. Any values besides these are treated as a SASL mechanism like 'EXTERNAL' or 'GSSAPI'. In most cases, 'simple' should be used. 'none' and 'anonymous' have the same effect: they disregard connectionUsername and connectionPassword and attempt an anonymous bind. If not set, the value is determined by the LDAP server. userSearchSubtree This defines the directory search scope for the user. If set to true, directory search scope is SUBTREE, if set to false, directory search scope is ONE-LEVEL. roleSearchSubtree This defines the directory search scope for the role. If set to true, directory search scope is SUBTREE, if set to false, directory search scope is ONE-LEVEL. connectionProtocol The security protocol to be used. This value can be determined by the LDAP server. This can be 'ssl' or 'plain'; however, if another value is used, it is interpreted as 'plain'. followReferrals The aliasDeref for both user and group searches. The default is true (follow). If set to false, it is ignore. 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint Option Description initialContextFactory The fully-qualified name of the initial context factory that will be used. This is always com.sun.jndi.ldap.LdapCtxFactory except for a super-advanced power user. For all searches (userSearchMatching and roleSearchMatching), RFC 2254 filters are allowed. Example 2-1: Active Directory <login-modules> <login-module flag="required" class="com.moab.api.login.MoabLoginModule" /> <login-module class="com.cri.security.server.modules.LdapLoginModule" flag="required" > <!-- Should be set --> <option name="connectionURL">ldap://vp-ldap-ad1:389</option> <option name="connectionUsername">binduser@ldap</option> <option name="connectionPassword">binduser</option> <option name="userBase">cn=Users,dc=ldap,dc=ad</option> <option name="userSearchMatching">(&(sAMAccountName={0}) (objectClass=user))</option> <option name="userRoleName">memberOf</option> <option name="roleBase">cn=Builtin,dc=ldap,dc=ad</option> <option name="roleSearchMatching">(member={0})</option> <option name="roleName">sAMAccountName</option> <!-- Should be defaulted --> <option name="initialContextFactory">com.sun.jndi.ldap.LdapCtxFactory</option> <option name="authentication">simple</option> <option name="userSearchSubtree">true</option> <option name="roleSearchSubtree">true</option> </login-module> </login-modules> Example 2-2: OpenLDAP <login-modules> <login-module flag="required" class="com.moab.api.login.MoabLoginModule" /> <login-module class="com.cri.security.server.modules.LdapLoginModule" flag="required" > <!-- Should be set --> 2.4 Configuring security in Viewpoint 47 Chapter 2: Configuring Viewpoint <option name="connectionURL">ldap://localhost:389</option> <option name="connectionUsername">cn=binduser,cn=Users,dc=example, dc=com</option> <option name="connectionPassword">binduser</option> <option name="userBase">cn=Users,dc=example,dc=com</option> <option name="userSearchMatching">(uid={0})</option> <option name="userRoleName">role</option> <option name="roleBase">cn=Groups,dc=example,dc=com</option> <option name="roleSearchMatching">(member={0})</option> <option name="roleName">role</option> <!-- Should be defaulted --> <option name="initialContextFactory">com.sun.jndi.ldap.LdapCtxFactory</option> <option name="authentication">simple</option> <option name="userSearchSubtree">true</option> <option name="roleSearchSubtree">true</option> </login-module> </login-modules> The MoabLoginModule is required even if you are using LDAP to authenticate. If Viewpoint displays "Welcome, null" at the top right corner of the page after you successfully log in, then you most likely need to add the line to configure MoabLoginModule, as shown above. 2. Find the <role-definitions> element and set the roles, giving each one a unique definition name. If you are already using another login module, the role definitions will probably stay the same. Following an LDAP Viewpoint installation, however, the role definitions will probably need to change. Roles may be user-specific or apply to a group. a. Set the roles' permissions by inserting the <permission> element within definition and giving it a unique name. You may set multiple permissions for each role definition. <role-definitions> <definition name="bob"> <permission name="random.permission" /> <permission name="different.permission" /> </definition> <definition name="admin"> <permission name="admin.permission1" /> <permission name="admin.permission2" /> </definition> </role-definitions> 3. Locate the <permissions-map> section. 48 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint a. Set <principal type="LdapGroupPrincipal"> for each group role. Set <principal type="LdapUserPrincipal"> for each user-specific role. b. Define the principal's role name as the same name used in the role definition section. <permissions-map> <principal type="LdapUserPrincipal" name="userA"> <role name="bob" /> </principal"> <principal type="LdapGroupPrincipal" name="groupA"> <role name="admin" /> </principal> </permissions-map> The userA principal grants the user the permissions given to user bob in role definitions. The groupA principal grants the users the permissions given to group admin in role definitions. A user may have multiple assigned roles. For example, if user bob is assigned the role bob and the role admin, he is granted both a unique set of permissions and the same set of a admin permissions shared by several users. 4. Configure JAAS by adding the appropriate callback parameters to the <request-handler> element. a. Set the <parameter> child element with a callback value of "ProxyUserCallback". Specify the username. b. Set the <parameter> element with a callback value of "NameCallback". Specify the username. c. Set the <parameter> element with the callback value of "PasswordCallback" Specify the password. 5. Restart Tomcat. Related topics l Configuring the request handler on page 58 l Configuring security in Viewpoint on page 40 2.4.5 Configuring role definitions You can recursively specify roles in order to create a role hierarchy. A permission is a domain-like identifier that grants a given entity access to perform some function within Viewpoint (for example, "exit", "setFactory", "print.queueJob"). To configure role definition 1. Open the core.xml file located in the Viewpoint home directory. Locate the <security> element. 2. Use the <role-definition> section to define groups of permissions. 2.4 Configuring security in Viewpoint 49 Chapter 2: Configuring Viewpoint a. Specify the <permission> element. The naming convention follows the hierarchical property naming convention. An asterisk can appear by itself, or if immediately preceded by a "." can appear at the end of the name to signify a wildcard match. For example, "*" and "java.*" are valid, while "*java", "a*b", and "java*" are not valid. b. Set the <permission> name to the name of the permission you wish to grant the user. For a list of Viewpoint permission names, see Setting permissions on page 51. Example 2-1: Role definitions configuration <role-definitions> <definition name="user"> <permission name="archive.create"/> <permission name="archive.read"/> <permission name="archive.restore"/> <permission name="cart.read"/> <permission name="cart.update"/> <permission name="cart.delete"/> </definition> <definition name="admin"> <permission name="user.*"/> <role name="user"/> </definition> </role-definitions> Related topics l Configuring the request handler on page 58 l Configuring login modules on page 56 l Configuring the permissions map on page 50 l Setting permissions on page 51 2.4.6 Configuring the permissions map To configure the permissions map 1. Open the core.xml file located in the Viewpoint home directory. Locate the <security> element. 2. Locate the <permissions-map> section. It specifies how authenticated users are authorized in the Viewpoint framework. For each principal value that should be considered, an arbitrary number of roles and permissions are assigned. 3. Set the <principal> element. a. Set the type attribute to the "simple" class name of the principal. b. Set the name attribute to the value of the principal. If a user is assigned a principal that matches this type and value, the given roles and permissions are assigned to that user. 50 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint c. Set the <role> child element to the role the user is given if they have the given principal. See Configuring role definitions on page 49 for more information. Example 2-1: Permissions map configuration <permissions-map> <principal type="MoabSshUserPrincipal" name="cri"> <role name="user"/> </principal> <principal type="MoabAdminPrincipal" name="ADMIN5"> <role name="user"/> </principal> <principal type="ViewpointRolePrincipal" name="user"> <role name="user"/> </principal> <principal type="ViewpointRolePrincipal" name="admin"> <role name="admin"/> </principal> </permissions-map> Related topics l Configuring the request handler on page 58 l Configuring login modules on page 56 l Configuring role definitions on page 49 l Setting permissions on page 51 2.4.6.1 Setting permissions Links and menu items (see Creating links on the Viewpoint menu bar on page 63) can be filtered according to a user's permissions when they log in. That is, if the user does not have the permission associated with a navigation item, it is not displayed. To set a permission 1. Choose a permission to use: you may either create a custom permission or use a preexisting one from the table below. l Define a permission if you are not using a preexisting one from the table below. To do so: a. Open the core.xml file located in the Viewpoint home directory. b. Find the <role-definition> element and choose or create a role to grant the permission. c. Specify the role with <definition name="role_name"> The role must be defined in the permissions map. See Configuring the permissions map on page 50) d. Create the permission, specifying a unique name for it. Place it inside of the <definition> element. 2.4 Configuring security in Viewpoint 51 Chapter 2: Configuring Viewpoint <permission name=”permission.name” /> l 52 Set one of the following preexisting permissions to grant access to the associated page. Permission Associated page(s) Allowed action(s) cart.delete Cart, Cart Details Lets users delete items from the cart. cart.read Cart, Cart Details Lets users view the cart and Cart Details page. cart.update Cart, Cart Details Lets users add items to the cart and modify items in the cart. dashboard.node.read View Nodes Lets users view the view nodes on the View Nodes page. event.read Event Logs Lets users view the Event Logs page. job.create Submit Job, Job Management Lets users create a job. job.delete Job Management Lets users delete a job job.form.read Submit Job Lets users view a job submission form. job.form.readall Submit Job Lets users view all job submission forms. job.form.create Submit Job Lets users create a new job submission form. job.read Job Management, View Jobs Lets users view their own jobs and job details. job.readall Job Management, View Jobs Lets users view all jobs and job details (HPC Suite only). job.update Job Management Lets users modify their own jobs. job.updateAll Job Management Lets users modify all jobs. mail Contact Us Lets users send mail to administrators from the Contact Us page. nav.admin --- Generic administrator permission. 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint Permission Associated page(s) Allowed action(s) nav.user --- Generic user permission. node.create Node Management Lets users provision nodes. node.delete Node Management Lets users delete nodes. node.modify.power Node Management Lets users power nodes on and off. node.modify.reprovision Node Management Lets users repovision nodes. node.read Node Management Lets users view nodes and node details. node.update Node Management Lets users modify node information. pending-actions.read Requested Actions Lets users view their own requested actions. pending-actions.readall Requested Actions Lets users view all requested actions. policy.node.read Policy Management - Allocation Policy Lets users view the policy settings. policy.node.update Policy Management - Allocation Policy Lets users edit the policy settings. report.read Reports Lets users view the Reports page. report.adaptive.* Reports Lets users view all available reports. reservation.create Create Reservation Lets users create reservations. reservation.delete Reservation Management Lets users cancel reservations. reservation.read Reservation Management, View Reservations Lets users view their own reservations and reservation details. reservation.readall Reservation Management, View Reservations Lets users view all reservations and reservation details. 2.4 Configuring security in Viewpoint 53 Chapter 2: Configuring Viewpoint Permission Associated page(s) Allowed action(s) reservation.update Reservation Management Lets users update reservation information. server.about Configuration Lets users see diagnostics on the Configuration page. user.* User Management Lets users manage Viewpoint users. 2. Assign the permission to a link, page, gadget, report, component, or button using the <permission> element inside of the associated item. For example: <permission name="report.read" /> Related topics l Configuring the permissions map on page 50 l Filtering navigation with permissions on page 54 2.4.6.2 Filtering navigation with permissions To filter navigation with permissions 1. Open the core.xml file located in the Viewpoint home directory. 2. Locate the <nav-menu> section, the desired <menu> sub-section then the link to filter. 3. Use the <permission> element inside <link> to require a permission in order to view the link. <nav-menu> <menu label="Reporting…"> <permission name="reports.read" /> <link href=href="reporting" target="thisWindow" label="Reports"></link> </menu> </nav-menu> Only users with the report.read permission may access reporting. The permission should be specified in the <link> element if the restriction only applies to one specific link in the category. Related topics 54 l Configuring the permissions map on page 50 l Setting permissions on page 51 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint 2.4.7 Setting permissions for the Viewpoint User Management page To set permissions for the Viewpoint User Management page 1. Verify that ViewpointLoginModule is your authentication module (for details, see Configuring login modules on page 56), and not LDAP or SSO. 2. Give the following permissions to any user that should have access to the User Management page (for more information, see Setting permissions on page 51): Permission Reason user.readall Needed to see the User Management page. user.add Needed to add a new user. user.updateall Needed to modify a user or change a user's password. Do not grant any of the user.* permissions to average users. A secure core.xml configuration of user permissions should look like the following example: <config> ... <security> ... <permissions-map> <principal type="ViewpointRolePrincipal" name="user"> <role name="user" /> </principal> <principal type="ViewpointRolePrincipal" name="admin"> <role name="admin" /> </principal> </permissions-map> <role-definitions> <definition name="user"> <permission name="node.create" /> <permission name="node.read" /> <permission name="node.update" /> <permission name="node.delete" /> ... </definition> <definition name="admin"> <permission name="user.*" /> <role name="user" /> </definition> </role-definitions> 2.4 Configuring security in Viewpoint 55 Chapter 2: Configuring Viewpoint ... </security> ... </config> In the above example, the administrator has permission to view, manage, and add users, while an average user has none of those privileges. 3. Require the user.readall permission when creating a menu item for the User Management page in core.xml. 4. Add a link to User Management in an Administration menu by adding the following in core.xml: <nav-menu> ... <menu label="Administration"> ... <link href='page://UserManagement' target='thisWindow' label='User Management'> <permission name="user.readall" /> </link> ... </menu> ... </nav-menu> Related topics l Setting permissions on page 51 l Configuring Viewpoint on page 13 2.4.8 Configuring login modules To configure login modules 1. Open the core.xml file located in the Viewpoint home directory. Locate the <security> element. 2. Use the <login-modules> element to enable extensible security in the Viewpoint framework. This allows a system administrator to specify one or more LoginModules, which are used to authenticate a user across the domains or realms those LoginModules were defined to access. For more information, see the JAAS Reference Guide. a. Set <login-module class="class name">. This sets the LoginModule to be used to authenticate a user. This LoginModule is used to populate the user with "principals" which are then used to authorize the user to take specific actions within the system. b. Set the class attribute to the fully-qualified class name of the LoginModule. 56 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint c. Set the flag attribute to control the overall behavior as authentication proceeds down the stack of LoginModules. The JavaDoc for the Configuration class gives a more detailed specification of the purpose and use of these configurations. Related topics l Configuring the request handler on page 58 l Configuring the permissions map on page 50 l Configuring role definitions on page 49 l Setting permissions on page 51 2.4.8.1 Using ViewpointLoginModule The ViewpointLoginModule is the default login module. When used, the ViewpointLoginModule authenticates users when the hash of a supplied password matches the stored password has in the Viewpoint database. For security reasons, passwords are not explicitly stored in the database. Instead, a base64 encoded SHA512 secure hash consisting of the password and a salt (a random number from a secure random number generator) is stored. To authenticate a user, the input password is combined with the salt (which is retrieved from the database). This combination is base64 encoded and compared with the base64 encoded hash from the database. If the hashes match, the user is authenticated. To use ViewpointLoginModule 1. Open the core.xml file located in the Viewpoint home directory. Locate the <request-handler> element. 2. Insert two <parameter> elements with the callback attribute configured, one with a value of "NameCallback" and the other of "PasswordCallback". Set the element to the login username and password, respectively. <config> ... <security> ... <request-handler> ... <parameter callback="NameCallback">username</parameter> <parameter callback="PasswordCallback">password</parameter> </request-handler> ... </security> </config> 3. Add the ViewpointLoginModule as a required module in the <login-modules> section with the following: <login-modules> <login-module class="com.cri.security.server.modules.ViewpointLoginModule" flag="required" /> </login-modules> 4. Add a ViewpointRolePrincipal that has the same name as each role you define in core.xml: 2.4 Configuring security in Viewpoint 57 Chapter 2: Configuring Viewpoint <permissions-map> ... <principal type="ViewpointRolePrincipal" name="user"> <role name="user" /> </principal> <principal type="ViewpointRolePrincipal" name="admin"> <role name="admin" /> </principal> </permissions-map> ... <role-definitions> <definition name="user"> <permission name="job.read" /> ... </definition> <definition name="admin"> <permission name="user.*" /> <role name="user" /> </definition> </role-definitions> 5. Configure your environment to use an SSL connection, since ViewpointLoginModule allows you to authenticate across a network using passwords. For more information about how to protect a site with SSL, see the Tomcat documentation. Related topics l Setting permissions for the Viewpoint User Management page on page 55 l Setting permissions on page 51 2.4.9 Configuring the request handler To configure request handler 1. Open the core.xml file located in the Viewpoint home directory. Locate the <security> element. 2. Use the <request-handler> configuration to define the set of HTTP parameters to be used during authentication, and the callbacks they serve. More information about what callbacks need to be handled by the callbackhandler can be found in the documentation for your login modules. 3. Map each parameter element directly to an HTTP parameter. Set the callback attribute to the class name of the callback, or the Java Authentication and Authorization Service (JAAS) callback. In cases where callback names conflict, the fully-qualified class name must be used. In addition, an optional required attribute can be specified. The default value is true. <parameter callback="ProxyUserCallback"> 58 2.4 Configuring security in Viewpoint Chapter 2: Configuring Viewpoint Related topics l Configuring login modules on page 56 l Configuring the permissions map on page 50 l Configuring role definitions on page 49 l Setting permissions on page 51 2.5 Synchronizing job template names If you have installed Moab using the Cloud parameter, there will be four default job templates in your moab.cfg file. By default these job templates are named: Job template name Description genericVm Used to allocate a service instance that represents a virtual machine genericPM Used to allocate a service instance that represents a physical machine OSStorage Used to allocate a service instance that represents operating system storage extraStorage Used to allocate a service instance that represents extra storage Viewpoint looks for these job template names, as specified by the default settings of the ViewpointConfig.groovy file: custsvc.vm_template = "genericVM" custsvc.pm_template = "genericPM" custsvc.networkstore_template = "extraStorage" custsvc.osstore_template = "OSStorage" However, it is possible for you to name these job templates in your moab.cfg file anything you want. If you have changed the names of those job templates in moab.cfg, you will need to synch the name in the ViewpointConfig.groovy file so that Viewpoint can identify the job templates. For example, say you have named your job template for VM jobs in the moab.cfg file to be vmTemplate. To map Viewpoint to that template name, you would make this change in your ViewpointConfig.groovy file: custsvc.vm_template = "vmTemplate" You will need to repeat this process and update every job template that is named something different in the moab.cfg file than the default names mentioned above. Related topics l Configuring Viewpoint on page 13 2.5 Synchronizing job template names 59 Chapter 3: Customizing Viewpoint Viewpoint is a highly customizable application that can be modified to suit your organization's needs. In addition to customizing navigation, menu options, and Homepage elements, you can also add and modify your own custom HTML pages to Viewpoint. These custom pages use Viewpoint’s Queue and Summary pages. The pages themselves are created outside of Viewpoint, and are added to the Viewpoint directory structure. This chapter contains information and instructions about customizing your instance of Viewpoint for Moab HPC Suite. It includes these topics: l Customizing Viewpoint to specific markets or customers on page 61 l Customizing navigation components on page 62 l Configuring Homepage gadgets on page 70 l Using the Viewpoint queue on page 80 l Creating custom dialog windows on page 81 l Customizing logging on page 83 l Displaying a site maintenance page on page 85 l Using generic commands on page 86 3.1 Customizing Viewpoint to specific markets or customers Some nomenclature within Viewpoint is configurable. Marketization is the process of defining objects, or in most cases, words, that can be tailored to meet specific market or customer needs. The market.properties and message.properties files contain a dictionary of keys that map to market, or customer-specific, values. The files map to the typical Java properties standard. A sample of a portion of the market.properties file follows: 1Node = Node 2Reservation = Reservation 3Your\ Current\ Request = Your Current Request Content on the left of the equal sign (=) represents current Viewpoint code for content that appears in the user interface. Content on the right replaces content on the left and becomes visible in the user interface. 3.1 Customizing Viewpoint to specific markets or customers 61 Chapter 3: Customizing Viewpoint To tailor semantics to specific markets or customers 1. Open the market.properties file located in the Viewpoint home directory. 2. In the dictionary list, identify the content you want to modify and replace the content on the right of the equation with the new content. For example: Node = Server All instances of "Node" are replaced with "Server" in the user interface. 3. Save the file. 4. Open the message.properties file, typically located in the tomcat/webapps/moab/WEBINF/grails-app/i18n directory. Repeat steps 2-3. 5. Restart the application to allow changes to the files to take effect. When using keys, spaces must be escaped using the backslash (\) character. Also case-sensitivity must be considered; content in the files appears in the user interface exactly as it appears in the dictionary list. Related topics l Customizing Viewpoint on page 61 3.2 Customizing navigation components This section contains instructions for customizing different navigation components of the Viewpoint user interface. It contains these topics: l Creating links on the Viewpoint menu bar on page 63 l Adding/editing top links on page 65 l Adding top link icons on page 66 l Customizing the header image on page 67 l Assigning a default Homepage on page 67 l Customizing the Home icon on page 68 l Viewpoint page URLs on page 68 Related topics l 62 Customizing Viewpoint on page 61 3.2 Customizing navigation components Chapter 3: Customizing Viewpoint 3.2.1 Creating links on the Viewpoint menu bar You can specify the links that appear in the navigation menu bar by using the <nav-menu> element. The <nav-menu> element has the same attributes and values as the <top-link> element (see Adding/editing top links on page 65) and also supports images the same way <top-link> does. To create a drop-down link on the menu bar 1. Open the core.xml file located in the Viewpoint home directory. 2. Scroll to the <nav-menu> element. 3. Insert the <menu> child element. Set the label attribute to the category name to appear in the navigation bar. For example, if you wanted to add a new drop-down menu option named "Reporting": <nav-menu> ... <menu label="Reporting"</menu> </nav-menu> 4. If you want to display an icon with the label, use the <image> child element of <menu>. Specify the image path from the $CATALINA_HOME directory. For example: <nav-menu> ... <menu label="Reporting"> <image>images/reporting_icon.png</image> </menu> </nav-menu> 5. If you want to display only the image for the link, remove the label attribute of <menu>. For example: <nav-menu> ... <menu> <image>images/reporting_icon.png</image> </menu> </nav-menu> 6. Configure the link(s) to reside within the category by inserting a <link> element inside of <menu>. l href – The href component works just like an HTML link. This can be a URL to an external source, or it can link to Viewpoint-specific functionality (for a list of Viewpoint page hrefs, see Viewpoint page URLs on page 68). 3.2 Customizing navigation components 63 Chapter 3: Customizing Viewpoint l l target – The target describes where the link should be opened. The possible values are: Value Description thisWindow Exits the Viewpoint Web application and displays the new page in the same window as the link. newWindow Opens the link in a new window. subFrame Displays the link's contents in the Viewpoint application panel. label – The label attribute is the display name of the menu or item. For example, if you wanted a link named "Reports" to take users to the Viewpoint Reports page, do the following: <nav-menu> ... <menu label="Reporting"> <link href="reporting" target="thisWindow" label="Reports"> </link> </menu> </nav-menu> 7. If you want to give the link an icon, insert an <image> element within <link>. Specify the image path from the $CATALINA_HOME directory. For example: <nav-menu> ... <menu label="Reporting"> <link href="reporting" target="thisWindow" label="Reports"> <image>images/reporting_icon.png</image> </link> </menu> </nav-menu> 8. Restrict who may use the link by setting permissions (for more information, see Filtering navigation with permissions on page 54). For example: <nav-menu> ... <menu label="Reporting"> <link href="reporting" target="thisWindow" label="Reports"> <image>images/reporting_icon.png</image> <permission name="report.read" /> </link> </menu> </nav-menu> 64 3.2 Customizing navigation components Chapter 3: Customizing Viewpoint Related topics l Customizing navigation components on page 62 l Viewpoint page URLs on page 68 l Adding/editing top links on page 65 3.2.2 Adding/editing top links You can specify the links that appear in the upper right corner of the Viewpoint header (for example, "Contact Us" and "Login/Logout"). Additionally, you can associate images with these links (for details, see Adding top link icons on page 66). You can create top links by using the <top-link> element in the core.xml file. <top-links> <top-link href='login?logout=true' target='thisWindow' label='Log out' /> </top-links> Attributes and values for the <top-link> element are: l l l href- The href component works just like an HTML link. This can be a URL to an external source, or it can link to Viewpoint-specific functionality (for a list of Viewpoint page hrefs, see Viewpoint page URLs on page 68). target - The target describes where the link should be opened. The possible values are: Value Description thisWindow Exits the Viewpoint Web application and displays the new page in the same window as the link. newWindow Opens the link in a new window. subFrame Displays the link's contents in the Viewpoint application panel. label - The label attribute is the display name of the menu or item. To add/edit a top link 1. Open the core.xml file located in the Viewpoint home directory. 2. Inside of the <navigation>'s <top-links> child element, insert <top-link>. 3. Set the required href attribute (for a list of Viewpoint page hrefs, see Viewpoint page URLs on page 68). 4. Specify the link's display name by using the label attribute. 3.2 Customizing navigation components 65 Chapter 3: Customizing Viewpoint 5. Specify where the link opens by using the target attribute. It can be set to any of the following: l thisWindow l newWindow l subFrame For example: <top-links> <top-link href="login?logout=true" target="thisWindow" label="Logout" /> </top-links> 6. Restrict who may use the link by setting permissions (for details, see Filtering navigation with permissions on page 54). For example: <top-links> <top-link href="login?logout=true" target="thisWindow" label="Logout"> <permission name="nav.logout" /> </top-link> </top-links> Only users with the support.helpRequest permission can view the Support link, and only users with the manage.VPCs permission can view the Manage page. Related topics l Customizing navigation components on page 62 l Viewpoint page URLs on page 68 l Adding top link icons on page 66 3.2.3 Adding top link icons In addition to being able to specify the links that appear in the upper right corner of the Viewpoint heading (for more information, see Adding/editing top links on page 65), you can also associate images with these links. These steps explain how you can do this. To create a top link icon 1. Create an image that conforms to the required dimensions of 16x16 pixels. Images larger than 16x16 pixels will not fit in the heading. 2. Give the image a descriptive name. For example, logoutIcon.png. 3. Save the image to the ${Viewpoint_webapps_directory}/moab/moab/images directory. 4. Open the core.xml file located in the Viewpoint home directory, and locate the <top-links> element. 5. Insert the <image> element inside of the desired <top-link> element. 6. Specify the location of the image from $CATALINA_HOME. 66 3.2 Customizing navigation components Chapter 3: Customizing Viewpoint Remove the label attribute in the <top-link> element to use the image in place of the link's label (rather than in addition to it). <top-link href="login?logout=true" target="thisWindow"> <image>images/logoutIcon.png</image> <permission name="nav.logout" /> </top-link> Related topics l Customizing navigation components on page 62 l Adding/editing top links on page 65 3.2.4 Customizing the header image In the navigation banner, user interface components that are graphics or icons (with the exception of the menu bar) are configured using the <image> element. However, you can customize the branding image in the header by replacing the original image file (header-custom.png). To customize the header image 1. Create a custom image that conforms to the required dimensions: 401 pixels in width and 100 pixels in height. 2. Save the image as header-custom.png 3. Move the image to ${Viewpoint_webapps_directory}/moab/images/header-custom.png to replace the default header. Related topics l Customizing navigation components on page 62 l Customizing the Home icon on page 68 3.2.5 Assigning a default Homepage You can assign a default Homepage by specifying a URL in the <default-home-page> element of the core.xml file. The URL must adhere to the Viewpoint URL page protocol (for details, see Adding/editing top links on page 65). 3.2 Customizing navigation components 67 Chapter 3: Customizing Viewpoint To assign a default Homepage 1. Open the core.xml file located in the Viewpoint home directory. 2. Locate the <default-home-page> element and replace page://HomePage with the desired Viewpoint URL (for more information, see Adding/editing top links on page 65). For example, if you wanted the default Homepage to be the View Nodes page, you would do the following: <default-home-page>node</default-home-page> For a list of Viewpoint page hrefs, see Viewpoint page URLs on page 68. Related topics l Customizing navigation components on page 62 l Customizing the Home icon on page 68 3.2.6 Customizing the Home icon In the navigation banner, user interface components that are graphics or icons (with the exception of the menu bar) are configured using the <image> element. However, you can customize the Home icon in the menu bar by replacing the original image file (home.png). To customize the Home icon 1. Create a custom image that conforms to the required dimensions: 10x16 pixels. 2. Save the image as home.png 3. Move the image to ${Viewpoint_webapps_directory}/moab/images/home.png to replace the default home icon. Related topics l Customizing navigation components on page 62 l Assigning a default Homepage on page 67 3.2.7 Viewpoint page URLs The following table contains the Viewpoint pages and their specific href values. Page Path href GENERAL Home 68 --- "page://HomePage" 3.2 Customizing navigation components Chapter 3: Customizing Viewpoint Page Path href Login --- "login" Logout --- "login?logout=true" "page://SendMail" Contact Us --- "Contact Us" is off by default. NEW New Job New > Job "page://SubmitJob" New Reservation New > Reservation "reservation/create" VIEW Accounting View > Accounting Manager "mam" View Jobs View > Jobs "job" View Nodes View > Nodes "node/nodeDashboard" View Reservations View > Reservations "viewReservations" HISTORY Event Logs History > Event Logs "page://MoabEvents" Job Management History > Job Management "page://JobManagement" Reports History > Reports "reporting" Requested Actions History > Requested Actions "requestedActions" ADMINISTRATION Configuration Administration > Configuration 3.2 Customizing navigation components "configHome" 69 Chapter 3: Customizing Viewpoint Page Path href Node Management Administration > Node Management "page://NodeManagement" User Management Administration > User Management "page://UserManagement" Related topics l Customizing navigation components on page 62 l Creating links on the Viewpoint menu bar on page 63 l Adding/editing top links on page 65 3.3 Configuring Homepage gadgets You can configure the Viewpoint Homepage to display gadgets (for a list of Viewpoint gadgets, see Supported Homepage gadgets on page 72). The configuration for Homepage gadgets does not follow Google Gadgets API, but you can embed inline frames into the homepage. Because the Google Gadget API permits the use of HTML iframes, Gadgets that are configured for Homepage can be altered to work in any Gadget API-compatible dashboard (such as the WS02 Gadget Server). To configure gadgets on the Homepage 1. Open core.xml in the Viewpoint home directory and locate the <home-page> element. 2. Insert the <module> element for each gadget you wish to add to the page. 3. Insert the <module-prefs> child element to specify the gadget’s title and height in pixels (the width adjusts automatically according to the width of the browser). For example: <module-prefs title="Jobs Needing Attention" height="350" /> 4. Insert the <content> element to provide gadget-loading information. Specify the type (only ‘url’ is currently implemented in Homepage) and the href, setting the value to the location of the gadget’s HTML page. For example: <content type="url" href="jsp/dashboard/tables/jobs_needing_attention.jsp" /> 5. Insert the <positioning> element to specify the location of the gadget on the Homepage (for details, see Arranging gadgets on the Homepage on page 71). 70 3.3 Configuring Homepage gadgets Chapter 3: Customizing Viewpoint 6. Insert the <user-pref> element. Note that ‘url’ gadgets can only have a refresh preference set. a. Give the preference a name. b. Set a default_value for the preference. For refresh, the default value must be an integer specifying the number of seconds between each time the gadget is refreshed. c. Specify the preference’s datatype. For refresh, the datatype must be set to "hidden". d. Indicate whether the preference is required. For refresh, required must be set to "true". For example: <user-pref name="needingAttention" default_value="true" datatype="hidden" required="true" /> 7. Set the <permission> element to restrict who may view the gadget. For a list of permission names, see Setting permissions on page 51. For example: <permission name="nav.homepage" /> In this example, a user must have the nav.homepage permission in order to view the gadget. Related topics l Arranging gadgets on the Homepage on page 71 l Supported Homepage gadgets on page 72 3.3.1 Arranging gadgets on the Homepage You can manually configure the Viewpoint Homepage. The Homepage GUI is generally composed of three columns of gadgets. (Gadgets are simple HTML and JavaScript applications that can be embedded in Web pages and other applications. For more information, see Supported Homepage gadgets on page 72). Each gadget sizes horizontally according to the width of the browser while the height can be manually configured. There are several configuration options, including the height, position, title, and permission of each gadget. To arrange gadgets on the homepage 1. Open the core.xml file in the Viewpoint home directory. 2. Scroll to the <home-page> element and locate the <module> section of the gadget to be moved. 3.3 Configuring Homepage gadgets 71 Chapter 3: Customizing Viewpoint 3. Modify the <positioning> child element the following ways: a. Set the column attribute to the number of the column in which the gadget will be: Value Position "1" Left column "2" Center column "3" Right column b. Set the priority attribute to the number of the row in which the gadget will be. For example, to place the gadget in the top row, set the priority to "1"; in the second row, set the priority to "2", and so on. You can create any number of rows by assigning gadgets to the corresponding number. For example: <module> <module-prefs title="My Workload" height="350" /> <content type="url" href="jsp/dashboard/charts/workload_table.jsp" /> <positioning column="5" priority="4" /> <user-pref name="needingAttention" default_value="false" datatype="hidden" required="true" /> <permission name="nav.homepage" /> </module> Related topics l Configuring Homepage gadgets on page 70 l Supported Homepage gadgets on page 72 3.3.2 Supported Homepage gadgets Viewpoint Homepage supports Viewpoint gadgets and user-created gadgets. These are the current Viewpoint gadgets: 72 l My Workload on page 73 l Jobs Needing Attention on page 74 l Troubled Resources on page 75 l System Events on page 76 l Resource Utilization on page 77 l Resource Utilization History on page 78 3.3 Configuring Homepage gadgets Chapter 3: Customizing Viewpoint MY WORKLOAD The My Workload gadget displays all your jobs and the jobs' Jobid, State, Size, and Wclimit attributes. <module> <module-prefs title="My Workload" height="350" /> <content type="url" href="jsp/dashboard/tables/workload_ table.jsp" /> <positioning column="1" priority="4" /> <user-pref name="myWorkload" default_value="false" datatype="hidden" required="true" /> <permission name="nav.homepage" /> </module> 3.3 Configuring Homepage gadgets 73 Chapter 3: Customizing Viewpoint JOBS NEEDING ATTENTION The Jobs Needing Attention gadget displays jobs with special state values of interest. This gadget shows the same job attributes as the My Workload gadget. The possible job state values of interest are: Lost, None, Suspended, System Hold, Unknown, Deferred, and Batch Hold. <module> <module-prefs title="Jobs Needing Attention" height="350" /> <content type="url" href="jsp/dashboard/tables/jobs_needing_ attention.jsp" /> <positioning column="2" priority="4" /> <user-pref name="needingAttention" default_value="true" datatype="hidden" required="true" /> <permission name="nav.homepage" /> </module> 74 3.3 Configuring Homepage gadgets Chapter 3: Customizing Viewpoint TROUBLED RESOURCES The Troubled Resources gadget displays nodes and VMs with a status of "down", and all nodes and VMs with G-Events on them. The gadget also provides drill-through capability to drill down to the node or VM in the Viewpoint Node Management page. <module> <module-prefs title="Troubled Resources" height="400"/> <content type="url" href="../tables/troubled_resources_ table.jsp"/> <positioning column="2" priority="1"/> <permission>root</permission> </module> 3.3 Configuring Homepage gadgets 75 Chapter 3: Customizing Viewpoint SYSTEM EVENTS The System Events gadget displays nodes and VMs with G-Events on them. The severity (1-Info, 2-Warning, 3-Alert, 4-Fatal), event, and timestamp of the event are displayed. The gadget also provides drill-through capability to drill down to the node or VM in the Viewpoint Node Management page. System Events is configured for Moab HPC Suite by default. For it to work for Moab Cloud Suite, however, you must configure Moab to report generic events on nodes, then uncomment the gadget's entry in the core.xml file. See "Enabling Generic Events" in the Moab Administrator Guide for details. 76 3.3 Configuring Homepage gadgets Chapter 3: Customizing Viewpoint RESOURCE UTILIZATION The Resource Utilization gadget displays state information for all servers. These are the possible states: State Description Down The node is not available for workload. Idle The node is available for workload but is not running anything. Busy The node is running workload and cannot accept more. Running The node is running workload and can accept more. Drained The node has been sent the drain request and has no workload on it. Draining The node has been sent the drain request, but still has workload on it. Flush The node is being reprovisioned. Reserved The node is being reserved. This is an internal Moab state. 3.3 Configuring Homepage gadgets 77 Chapter 3: Customizing Viewpoint State Description Unknown The state of the node is unknown. Up The node is up, but the usage is being determined. All All Servers. The gadget also provides drill-through capability to drill down to the node and the appropriate status in the Viewpoint Node Management page. <module> <module-prefs title="Resource Utilization" height="350"/> <content type="url" href="../charts/resource_utilization_ chart.jsp"/> <positioning column="1" priority="3"/> <user-pref name="refresh" default_value="30" datatype="hidden" required="true"/> <permission>root</permission> </module> A JavaScript version of the Resource Utilization gadget that does not require Flash can be configured by replacing ../charts/resource_utilization_chart.jsp with ../charts/resource_utilization_history_chart_raphael.jsp in the XML sample above. RESOURCE UTILIZATION HISTORY A Resource Utilization History gadget displays the same information as the Resource Utilization gadget, but records the percent of resource usage over time in the form of a line chart. Like Resource Utilization, this gadget allows drilling down to the node and the status in the Viewpoint Management page. <module> <module-prefs title="Resource Utilization - History" height="350" /> <content type="url" href="homePageGadget/resourceUtilizationHistory" /> <positioning column="2" priority="10" /> <permission name="nav.admin" /> </module> Related topics 78 l Arranging gadgets on the Homepage on page 71 l Configuring Homepage gadgets on page 70 3.3 Configuring Homepage gadgets Chapter 3: Customizing Viewpoint 3.4 Configuring the Contact Us page The Viewpoint Web framework provides email configuration options. Sending email is primarily an end-user function for submitting issue notification or requesting support. To allow users to send messages, configure the mail settings according to required specifications. By default, the "Contact Us" page is turned off. To modify the Contact Us page 1. Open the core.xml file located in the Viewpoint home directory. 2. Locate the <mail> element and modify the authentication information the following way: a. Set <smpt-server> to reflect your host name, such as smtp.gmail.com. b. Set <port> to reflect the port that the SMTP server uses to receive email requests. c. Insert the <username> and <password> used to authenticate with the SMTP server. d. Specify whether to use encryption by setting <ssl-enabled> to true or false. <mail> <smtp-server>smtp.gmail.com</smtp-server> <port>25</port> <username>[email protected]</username> <password>password</password> <ssl-enabled>true</ssl-enabled> … </mail> 3. Specify recipient(s) to receive the email using the <recipients> element and its <recipient> child element. Set the field attribute of the <recipient> element to specify whether to send messages directly to a recipient ("to"), as a correspondent copy ("cc"), or as a blind correspondent copy ("bcc"). Specify multiple recipients by separating them with commas. <mail> … <recipients> <recipient field="to"> [email protected] </recipient> <recipient field="cc"> [email protected] </recipient> <recipient field="bcc"> [email protected],[email protected],[email protected] </recipient> </recipients> </mail> 3.4 Configuring the Contact Us page 79 Chapter 3: Customizing Viewpoint Related topics l Creating links on the Viewpoint menu bar on page 63 3.5 Using the Viewpoint queue In order to use Viewpoint's built-in queue system, a page may call the setQueue JavaScript method or specify a queue URL parameter when querying for the page. Each queue must have a unique ID, and pages that share a queue should share this ID. When the page uses Viewpoint's queue, two major changes happen: l l The layout of the page changes to allow for a summary panel to be displayed on the right-hand side outside of the iframe. Various other JavaScript functions are available to interact with the queue. Each queue has a unique ID associated with it to allow for each page (or set of pages) to interact with its own queue. This configuration will allow each queue page or set of pages to operate independently. At any given moment, the user may have many queue objects in memory, but only the queue the page deals with will be shown at a time. As of Viewpoint 6.1, the queue is stored in the browser cache on the local user's machine, but it disappears after the user navigates away from Viewpoint. To utilize Viewpoint's queue 1. Use the setQueue(string) method to specify the ID of a queue for the page. 2. Use the addQueueItem(JavaScript) method to accept a JavaScript object that will be parsed and added to Viewpoint's queue for that object. The JavaScript object (JSO) should have three child objects: Object Description Defines how the queue items should be displayed and contains two child objects: l summary – Any string that will be interpreted as HTML to be displayed in the queue summary panel displayed on each form page. This should be a shorted, summary view of the item. l description – Any string that will be interpreted as HTML to be displayed in the queue table that can (optionally) be displayed on the last page of the request. This contains more detailed information about the queue item. display >values Contains a mapping of key, value pairs for the data stored on a single queue item. qty (Optional) Since each item in the queue may have an associated quantity, this attribute defines the quantity for this queue item. If not specified, the default value of 1 is used. var display = new Object(); display.description = "Image: " + image + " vCPU: " + procs + " RAM: " + mem + " GB Disk: " + disk + " GB"; 80 3.5 Using the Viewpoint queue Chapter 3: Customizing Viewpoint display.summary = image + ": " + procs + " vCPU, " + mem + " GB RAM, " + disk + " GB HD"; var myObject = new Object(); myObject.values = { "image" : image, "procs" : procs, "mem" : mem, "disk" : disk }; myObject.display = display; top.addQueueItem(myObject); 3. Use the getQueueItems() method to return a list of all items in the queue, as well as their quantities. It returns a JavaScript array, where each item in the array follows the same syntax and structure explained above. This method is necessary since the Viewpoint framework allows users to remove items and update quantities outside of the form page. Therefore it is recommended to let Viewpoint keep track of the queue completely, and your page should only query for the information when it is ready to perform the action. 4. Use the clearQueue() method to remove all the items from Viewpoint's queue. No URL changes are made. Typically, this method should also take the user back to the first page of the form (if there are multiple pages). Therefore it is typically a good idea to use a changePlace request with this method (unless there is only a single page that makes up the view) 5. Show the queue table by making a URL change with the showTable parameter set to "true". top.changePlace("Local;page=custom/your_form;queue=vc;showTable=true"); The buttons takes the user to the request table page. Related topics l Customizing Viewpoint on page 61 3.6 Creating custom dialog windows To create a custom dialog window 1. Open the XML file corresponding with the management page in which you want to create the dialog window. These files are located in the Viewpoint home directory. For example, to add the dialog window to Nodes Management, open the nodes.xml file. 2. Set the required frame-url attribute to the URL of the page to be shown in the popup window. 3. Insert any desired field references of the current object, preceded by $, that will be replaced by the field's value. See the option's Management Table fields for a complete list of options (Modifying columns in the Node Management table on page 109, etc.). 3.6 Creating custom dialog windows 81 Chapter 3: Customizing Viewpoint <controls> <open-dialog frameurl="customizations/vms/reprovision.gsp;vmId=$id"></open-dialog> </controls> The $id variable in the URL will be replaced by the actual VM name. 4. Insert the required <header> element to define the text displayed in the dialog window's header. a. Insert any desired field references to the current object, preceded by $, that will be replaced by the field's value. See the option's management table fields for a complete list of options. b. Set the image attribute within <open-dialog> to place a custom image to the left of the header's text. Set the value to the image's location from the $CATALINA_HOME directory. For example: <header image="images/reprovisions.png">Reprovision VM $id</header> 5. Set the <requirement> child element and specify a condition to disable the dialog window for certain records. The condition can be any Boolean decider value (for details, see Setting a Boolean decider on page 170) and all keywords corresponding to applicable fields for the record. In this example, a VM must run Linux to access the dialog window: <open-dialog frame-url="customizations/vms/reprovision.gsp;vmId=$id"> … <requirement comparison="equals"> <first> <component id="variable[vm_os]" /> </first> <second>linux</second> </requirement> </open-dialog> 6. Customize dialog window’s button using the tooltip, image-url, and label optional attributes in the <open-dialog> element. a. Set the tooltip attribute to the explanatory text that will be displayed by the button on mouse-over. b. Set the image-url attribute to the path of the icon that will be used to display the button. c. Set the label to the display text of the button. For example: 82 3.6 Creating custom dialog windows Chapter 3: Customizing Viewpoint <open-dialog frame-url="customizations/vms/reprovision.gsp;vmId=$id" tooltip="Reprovision this VM" image-url="images/button.png" label="Reprovision"> Related topics Customizing Viewpoint on page 61 l 3.7 Customizing logging By default, Viewpoint sends log files to the Viewpoint home directory. However, you can modify where the logs are sent, and you can change the logging verbosity by following these instructions. Viewpoint uses Grails logging. For information, see http://grails.org/doc/latest/guide/single.html#logging. To customize logging in Viewpoint 1. Copy and paste the following into the log4jConfig.groovy file in the Viewpoint home directory: log4j = { //ORDER MATTERS, PUT APPENDERS AT THE BEGINNING appenders { // (EXAMPLE) Set logging to the console. //console name: 'stdout', threshold: org.apache.log4j.Level.INFO, layout: pattern(conversionPattern: '%d{dd MMM yyyy HH:mm:ss,SSS} %5p %c{1}:%L - %m%n') // Setup rolling log files and set the location of the log. rollingFile name: 'vpLog', file: "/opt/viewpoint/ViewpointLog.log", maxFileSize: '500KB' } //ORDER MATTERS, PUT LOGGERS NEXT error 'org.codehaus.groovy.grails.web.servlet', // controllers 'org.codehaus.groovy.grails.web.pages', // GSP 'org.codehaus.groovy.grails.web.sitemesh', // layouts 'org.codehaus.groovy.grails.web.mapping.filter', // URL mapping 'org.codehaus.groovy.grails.web.mapping', // URL mapping 'org.codehaus.groovy.grails.commons', // core / classloading 'org.codehaus.groovy.grails.plugins', // plugins 'org.codehaus.groovy.grails.orm.hibernate', // hibernate integration 'org.springframework', 'org.hibernate', 'net.sf.ehcache.hibernate' warn 'org.mortbay.log', 'grails.app' // info 'grails.app.com.ace.viewpoint' //ORDER MATTERS, PUT ROOT CLOSURE AT THE END //set the overall level here (fatal, error, warn, info, debug, trace) root { error 'vpLog' // , 'stdout' //DON'T USE MULTIPLE LINES IN HERE, PUT EVERYTHING ON ONE LINE ABOVE } } 2. Customize the settings to meet your specifications. For information on how to customize, see 3.7 Customizing logging 83 Chapter 3: Customizing Viewpoint http://grails.org/doc/latest/guide/single.html#logging. As part of your logging customization, you can specify the following Viewpoint packages: 84 Value Description com.cri This is the general package for all Viewpoint server code. This will log all server interaction with the Viewpoint Web server. com.cri.security This is the logger for all security packages. This is important for authentication and authorization testing. com.ace This is the logger for external Java API classes. This includes Java code that has been validated for external customer consumption. Classes include MoabJob, MoabNode, Reservation, and so forth. See the Moab Java API for more information. com.Moab This is the logger for internal Java API classes. Classes include VPCs, low-level Moab consumption, etc. This is the logger that shows what Moab commands are sent and the associated output. org.codehaus.groovy.grails.web.servlet This is the logger for controllers. org.codehaus.groovy.grails.web.pages This is the logger for GSP. org.codehaus.groovy.grails.web.sitemesh This is the logger for layouts. org.codehaus.groovy.grails.web.mapping.filter This is the logger for URL mapping. org.codehaus.groovy.grails.web.mapping This is the logger for URL mapping. org.codehaus.groovy.grails.commons This is the logger for classloading. org.codehaus.groovy.grails.plugins This is the logger for plugins. org.codehaus.groovy.grails.orm.hibernate This is the logger for hibernate integration. 3.7 Customizing logging Chapter 3: Customizing Viewpoint Value Description org.springframework --- org.hibernate --- net.sf.ehcache.hibernate --- 3. Save your changes to the logj4Config.groovy file. Related topics l Customizing Viewpoint on page 61 3.8 Displaying a site maintenance page Occasionally, you will need to shut down your site for maintenance. To display a site maintenance page 1. Open the core.xml file located in the Viewpoint home directory. 2. Find the <properties> element and add the <maintenance-path> element to display a "Site is under maintenance" page. <maintenance-path /> You can also specify the relative path of a custom site maintenance page. <maintenance-path>pages/maintenancePage.jsp</maintenance-path> Users who do not have the maintenance.user permission will not be able to access the site. 3. Give users the maintenance.user permission (<permission name="maintenance.user" />) if you want them to be able to access the site. For more information, see Setting permissions on page 51. The server will not need to be restarted. Users currently logged in will not be logged out and will continue to have access to the site. Once the application is in use, any user that does not have the correct permissions will be denied access to the site. Related topics l Setting permissions on page 51 l Customizing Viewpoint on page 61 3.8 Displaying a site maintenance page 85 Chapter 3: Customizing Viewpoint 3.9 Using generic commands A generic command is a way to perform any administrator-configured action on the Web server. Administrators set up generic commands to perform functions that are not part of Viewpoint's built-in commands. For example, canceling a job is one of Viewpoint's built-in commands but editing a job's variable is not. To edit a variable on a job, an administrator can create a generic command that defines the action. Generic commands are represented as additional controls in the various management pages within Viewpoint. When a user clicks on a generic action, a popup window opens allowing the user to input values and submit the form. All generic commands are configured in an XML configuration file. For generic commands dealing with jobs, the XML is added to the jobs.xml file. Generic commands dealing with reservationss are configured in reservations.xml, etc. Generic commands are configured in the same sections where other commands are configured. All configurable management pages allow for buttons at the top of a page to perform actions on a record without having to double-click on a record in the table. Also, most management pages allow for controls on the details section after double-clicking on a record. To perform a function that is not part of Viewpoint’s built-in commands 1. Open the xml file corresponding to the page in which the generic command will exist. These are typically found in the Viewpoint home directory. 2. Locate the <controls> element and insert the <generic-command> child element. 3. Inside of <generic-command>,add the id attribute and give the command a unique name. Insert the label attribute to specify the text that users will see for the generic action performed. 4. Optional: Use the tooltip attribute to specify the text that is displayed on the control when the mouse hovers over it. Specify the image-url attribute to specify the path to the icon that will be used to display the control. 5. Inside of the <generic-command> element, set the <header> element to describe the header of the dialog box that is created. a. Optional: Set the image attribute within <header> to the location of an image on the Web server. b. Optional: Include field references, or keywords, that will be replaced with the value of the field of the current object being viewed. Allowable fields are the same as the allowable fields for the table and details sections. <header image="image.png">Edit variable of $id!</header> $id will be replaced with the ID of the object being modified. If this was the job management configuration and the user selected "job.15", then clicked the button created for the generic action Modify, the header would be "Edit variable of job.15". 6. Insert the <components> element within <generic-command> to describe the components that will be placed on the dialog box. (For more information, see Configuring the <components> element on page 118.) 86 3.9 Using generic commands Chapter 3: Customizing Viewpoint The <components> element works as it does when creating forms; however, as a part of a generic command, it allows you to specify a component's source using the optional <source> element with the property attribute. For example: <component id="textbox1" <description>Textbox auto=populated with OS</description> <source property="os" /> <text-value /> </component> 7. Insert the <command> element within <generic-command> to describe the command that will run on the Web server. a. Insert the <value> child element. This is the command that will run on the server. It can be any string value decider (for more information, see Adding a string decider on page 166). For each command, there are certain keywords that an be used to get the values of objects that are being changed. For more information, see the specific action you are modifying. b. Optional: Insert the <rule> element within <command>. It must be evaluated to true in order to execute. If <rule> is not set, the command will always run when the specific action takes place. This value can be any boolean decider (for more information, see Setting a Boolean decider on page 170). Similar to the <value> element, there are certain keywords for each action that can be used to get the values of the objects being changed. For more information, see the specific action you are modifying. 8. (Optional) Set the <requirement> child element within <generic-command> to a boolean value decider that determines if a record is valid for the action. Not all actions are applicable for all records. For example, the administrator may wish to only allow a node with a certain feature to have the ability to change IP address. In order to disable the generic action for some records, then re-enable the action for others, administrators should use the <requirement> element. This accepts any boolean value decider, and any keyword corresponding to the applicable columns for the record in question. For example, the value decider can use "account", "id", "memory", and "link" to job fields for generic commands dealing with job records. It also accepts the "username" variable, which displays the user's Moab username when the generic command is run. <generic-command id="mycoolNodecmd" tooltip="This will allow you to edit the location of the reservation" label="Edit Location"> <header image="editLocation.png">Edit location of $id!</header> <requirement comparison="equals"> <first> <component id="variable[vm_os]" /> </first> <second>linux</second> </requirement> <components> <component id="textbox1"> <description>What is the desired location</description> 3.9 Using generic commands 87 Chapter 3: Customizing Viewpoint <source property="variable[vm_os]" /> <text-value /> </component> <component id="textbox2"> <description>Textbox autopopulated with ip addr</description> <source property="variable[ip-address]" /> <text-value /> </component> </components> <command> <value>/home/user/tools/change_location $id</value> </command> </generic-command> This example changes a reservation's location using a generic command. This command will only be enabled for reservations with a Linux operating system. Related topics l 88 Customizing Viewpoint on page 61 3.9 Using generic commands Chapter 4: Configuring jobs This chapter contains information about configuring jobs. It includes these sections: l Configuring the Job Submit form on page 89 l Configuring buttons in the Job Management table on page 94 l Configuring columns in the Job Management table on page 97 l Configuring the Job Details pane on page 98 l Configuring streaming job output on page 103 l Configuring TORQUE and Moab for streaming job output on page 104 4.1 Configuring the Job Submit form You can customize the user interface and Job Submit logic by configuring the Job Submit form: l l user interface – You can fully customize the components that are displayed on the page, as well as other display options like the CSS and images shown to the end user. logic – You can map UI components to attribute values that should be submitted via the Moab msub command. See the Moab Workload Manager documentation. Building the Job Submit form is similar to building all other Viewpoint forms, all sharing the common requirement of modification to the <pages>, <components>, and <queue> elements. To configure the job submit form 1. Open the jobs.xml file located in the Viewpoint home directory. 2. Give users permission to save and load form values on the job submit page. See Setting permissions on page 51. If the user has the appropriate permissions, the Save and Load links appear automatically on the Submit Job page. a. Give users the job.form.create permission to allow them to save form values. b. Give users the job.form.read permission to allow them to load form values. c. Give users the job.form.readall permission to allow them to read all job forms. 3. Configure the Job Submit request element. See Configuring the request element for the Job Submit form on page 90. 4. Configure the Job Submit page to allow for multiple job submission. See Enabling submitting multiple jobs on page 93. 4.1 Configuring the Job Submit form 89 Chapter 4: Configuring jobs Related topics l Configuring the request element for the Job Submit form on page 90 l Enabling submitting multiple jobs on page 93 l Creating or configuring forms on page 117 l Configuring the <pages> element on page 147 l Configuring the <queue> element on page 157 l Configuring the <components> element on page 118 4.1.1 Configuring the request element for the Job Submit form Viewpoint allows you to customize and configure the msub command to match the needs and requirements specific to your site. See the Moab Workload Manager documentation. To configure the Job Submit request element 1. Open the jobs.xml file located in the Viewpoint home directory. Locate the <request> element. 2. Add any of the following child elements: l l l l l l l 90 <account> – This field corresponds to the Account attribute and is the name of account associated with job (It accepts any string value decider. See Adding a string decider on page 166.). <additional-attributes> – Any additional command line arguments to be appended to the end of the 'msub' request. Each argument should be defined using a <attribute> element. Each child <attribute> element has two parts: o <value> (required) – The value of the command line argument (It accepts any string value decider. See Adding a string decider on page 166.). o <condition> (optional) – If this is specified, Viewpoint includes the argument only if the condition evaluates to true (It accepts any Boolean decider. See Setting a Boolean decider on page 170.). <apply-hold> – This field corresponds to the Hold attribute and specifies that a user hold be applied to the job at submission time (It accepts any Boolean value decider. See Setting a Boolean decider on page 170.). <class> – This field corresponds to the Destination Queue (Class) attribute and defines the destination of the job. Moab uses the term Destination Queue for class (It accepts any string value decider. See Adding a string decider on page 166.). <error-path> – This field corresponds to the Error Path attribute and defines the path to be used for the standard error stream of the batch job (It accepts any string value decider. See Adding a string decider on page 166.). <execution-dir> – This field corresponds to the Execution Directory attribute and is the directory in which the job should execute (It accepts any string value decider. See Adding a string decider on page 166.). <generic-resources> – This field corresponds to the generic resources attribute. This works only with the table-map component. Here is an example: 4.1 Configuring the Job Submit form Chapter 4: Configuring jobs <generic-resource> <component id="generic_resource_table_map" /> </generic-resource> l l l <gpu-count> – This field corresponds to the Resource List attribute and is the number of GPUs per node requested (It accepts any integer value decider. See Adding an integer decider on page 165.). <job-name> – This field corresponds to the Name attribute and is the user-specified job name (It accepts any string value decider. See Adding a string decider on page 166.). <job-script> – This field corresponds to the Job Script attribute(It accepts any string value decider. See Adding a string decider on page 166.). Typically, this value is determined from an upload-script component or a write-script component, however, you can hard code the value or determine the value from other means. Here is an example where the job script is determined from either an upload-script component or a write-script component, depending on which option the user had selected: <job-script> <calculate operation="conditional"> <option> <value> <component id="upload-script" /> </value> <condition comparison="equal"> <first> <component id="script-chooser" /> </first> <second>Upload</second> </condition> </option> <option> <value> <component id="write-script" /> </value> <condition comparison="equal"> <first> <component id="script-chooser" /> </first> <second>Create New</second> </condition> </option> </calculate> </job-script> l l <memory> – This field corresponds to the Resource List attribute and is the maximum amount of physical memory used by the job (It accepts any integer value decider. See Adding an integer decider on page 165.). <node-count> – This field corresponds to the Resource List attribute and is the number of nodes to be reserved for exclusive use by the job (It accepts any integer value decider. See Adding an integer decider on page 165.). 4.1 Configuring the Job Submit form 91 Chapter 4: Configuring jobs l l l l l l l l l l l l 92 <node-features> – The list of node features the job requires (It accepts any string list value decider. See Adding a string decider on page 166.). <operating-system> – The administrator defined operating system (It accepts any string value decider. See Adding a string decider on page 166.). <output-path> – This field corresponds to the Output Path attribute and defines the path to be used for the standard output stream of the batch job (It accepts any string value decider. See Adding a string decider on page 166.). <partition> – The required partition (It accepts any string value decider. See Adding a string decider on page 166.). <preemptible> – The job is a preemptee and therefore can be preempted by other jobs (It accepts any Boolean value decider. See Setting a Boolean decider on page 170.). <priority> – This is the priority of the job (It accepts any integer value decider. See Adding an integer decider on page 165.). Normally, this is between -1024 and 0. <proc-count> – This field corresponds to the Resource List attribute and is the number of processors per node requested (It accepts any integer value decider. See Adding an integer decider on page 165.). <qos> – The Quality of Service associated with job (It accepts any string value decider. See Adding a string decider on page 166.). <restartable> – This field corresponds to the Rerunable attribute and declares whether the job is rerunable (It accepts any Boolean value decider. See Setting a Boolean decider on page 170.). <swap> – The maximum amount of virtual memory used by all concurrent processes in the job in MB which is the amount of swap disk required by job (It accepts any integer value decider. See Adding an integer decider on page 165.). <variables> – A collection of variables to be set on the job. This can have one or more <variable> child elements. Each child <variable> element has a minimum of two parts: o <key> (required) – The name of the variable (It accepts any string decider. See Adding a string decider on page 166.). o <value> (required) – The value of the variable (It accepts any string decider. See Adding a string decider on page 166.). o <rule> (optional) – If this is specified, Viewpoint includes the variable only if the rule evaluates to true (It accepts any Boolean value decider. See Setting a Boolean decider on page 170.). <vm-usage> – The environment in which the job will be run. This value must be one of the following: o requirepm – The job runs on a physical machine. o prefpm – The job runs on a physical machine, if possible; if not, it runs on a virtual machine. o createvm – The job creates a virtual machine on which to run. The newly-created VM is o createpersistentvm – The job creates a virtual machine on which to run, but the newly- 4.1 Configuring the Job Submit form Chapter 4: Configuring jobs created VM persists after job completion. l o requirevm – The job does not run until a virtual machine is available on which it can run. o prefvm – The job runs on a virtual machine, if possible; if not, it runs on a physical machine. <wall-time> – This field corresponds to the Resource List attribute and is the maximum amount of real time during which the job can be in the running state in seconds (It accepts any string integer decider. See Adding an integer decider on page 165.). Related topics l Configuring the Job Submit form on page 89 l Enabling submitting multiple jobs on page 93 l Creating or configuring forms on page 117 l Setting a Boolean decider on page 170 l Adding an integer decider on page 165 l Adding a string decider on page 166 4.1.2 Enabling submitting multiple jobs You can configure the Job Submit page to allow for multiple jobs to be submitted on each submit request. To enable submitting multiple jobs 1. Open the jobs.xml file located in the Viewpoint home directory. 2. Configure the <queue> element. See Configuring the <queue> element on page 157. The <queue> element stores all components on the form, because the <request> element does not support different requirements. You do not need to specify a <requirement-data> element. See Configuring the <queue> element on page 157. Example 4-1: Enabling multiple job submit <queue name="Your Job Request"> <queue-item> <title> <description>Job:</description> <component id="job-name" /> </title> <row order="1" required="true"> <description>Resources</description> <calculate operation="append-in-order"> <value order="1"> <component id="nodeCount" /> </value> <value order="2"> Nodes, </value> <value order="3"> 4.1 Configuring the Job Submit form 93 Chapter 4: Configuring jobs <component id="procCount" /> </value> <value order="4"> PPN</value> </calculate> </row> <row order="2" type="dynamic" source="storage-list"> <description>Storage:</description> <component id="storage-list" /> </row> </queue-item> </queue> Related topics l Configuring the Job Submit form on page 89 l Creating or configuring forms on page 117 l Setting a Boolean decider on page 170 l Adding an integer decider on page 165 l Adding a string decider on page 166 4.2 Configuring buttons in the Job Management table The <controls> element lets you configure which buttons are available, and what actions the user can perform on jobs in the table. To add/remove/modify buttons in the Job Management table 1. Open the jobs.xml file located in the Viewpoint home directory. Locate the <controls> element. 2. Create any drop-down menu buttons to contain related links. 3. For example, you might create a Job Actions button to contain Cancel, Hold, Release, Requeue, Suspend, and Resume. To do so, use the <menu> element inside of <controls>. Give it a descriptive label - Job Actions, in this case - and insert the related buttons as its child elements with descriptive labels. <menu label="Job Actions"> <cancel label="Cancel" /> <hold label="Hold" /> <release label="Release" /> <requeue label="Requeue" /> <suspend label="Suspend" /> <resume label="Resume" /> </menu> This is what it would look like in the UI: 94 4.2 Configuring buttons in the Job Management table Chapter 4: Configuring jobs Buttons may stand on their own as child elements of <controls> as demonstrated in this step; they are not required to be contained in a menu button. 4. Set any of the following child elements to configure the corresponding button: Table 4-1: Buttons Element Description <cancel> Cancels selected job <checkpoint> Checkpoints selected job <download-stderr> Downloads the standard error file of a completed job <download-stdout> Downloads the standard output file of a completed job <get-output> Loads the job output page where streaming job output can be viewed <hold> Adds user hold to selected job <refresh> Refreshes page <release> Releases selected job <requeue> Requeues selected job <suspend> Suspends selected job <unhold> Removes user hold from selected job 4.2 Configuring buttons in the Job Management table 95 Chapter 4: Configuring jobs 5. In the core.xml file, set the job.updateAll permission in the desired groups to allow users to perform actions on all jobs (for details, see Setting permissions on page 51). By default, users can only perform actions on their own jobs (even administrators). Any user with the job.updateAll permission must also have the appropriate administrator level set in the Moab configuration file for Moab to report all existing jobs to the user. 6. Modify the appearance of the button according to your preferences. l l l Set the tooltip attribute of the button's corresponding element to the text to be displayed on the button when the mouse hovers over it. Set the label attribute of the button's corresponding element to the text to be displayed either on the button or, if an image is specified, to its right side. Set the image-url attribute of the button's corresponding element to the path to an icon that will be used to display the button. <controls> <refresh /> <menu label="Job Actions"> <hold label="Hold" tooltip="Request that Moab hold this job" /> <release label="Release" /> <requeue label="Requeue" /> <suspend label="Suspend" /> <resume label="Resume" image-url="../images/job_icon.png" /> </menu> <checkpoint label="Checkpoint" /> </controls> Related topics 96 l Configuring columns in the Job Management table on page 97 l Configuring the Job Details pane on page 98 4.2 Configuring buttons in the Job Management table Chapter 4: Configuring jobs 4.3 Configuring columns in the Job Management table To add/remove/modify the columns in the Job Management table 1. Open the jobs.xml file located in the Viewpoint home directory. Locate the <fields> element. 2. Configure any desired buttons by inserting the corresponding element. The available buttons are: l <account> l <drmjid> l <expected-state> l <flags> l <holds> l <gpu-count> l <group> l <id> l <name> l <node-count> l <memory> l <proc-count> l <qos> l <run-priority> l <start-priority> l <user> l <variable> o Set the required name attribute to represent the name of the variable to be displayed in the column. l <vm-usage-policy> l <wallclock-requested> 3. Set at least one field as the primary key by setting the primary attribute of the column name to "true" (The default is "false"). It is strongly suggested that you create an <id /> field as the sole primary key field. You can make this field invisible if you do not want users to see it. For example: 4.3 Configuring columns in the Job Management table 97 Chapter 4: Configuring jobs <id primary="true" visible="false"> 4. Set the visible attribute to specify whether the column should be displayed or hidden. The default is "true". 5. Set the width attribute to specify the width, in pixels, of the column. 6. Insert the <title> child element in any field type and specify the text to be displayed to the user as the name of the column. Related topics l Configuring buttons in the Job Management table on page 94 l Configuring the Job Details pane on page 98 4.4 Configuring the Job Details pane The Job management page contains a panel for displaying a job in detail. These panels currently allow one to configure a title, a set of controls, and a list of sections to display information in. To configure the job details pane 1. Open the jobs.xml file located in the Viewpoint home directory. Find the <details> element within the <job-management> section. 2. Customize the title of the details pane by inserting the <title> element within <details>. The <title> can include field references that are replaced with the value of the field of the current object being viewed. Any scalar field types are allowed. Fields are specified by prefixing a field name with a dollar sign ($) and optionally wrapping it in curly brackets, such as $id, ${name}, or $expected-state. Job variables can also appear in the title by using a map variable syntax, which suffixes the field name with a key enclosed in square brackets. For example, the reference $variable[aitId] would be substituted with the value of the job variable "aitId" in the title. 3. Configure any desired buttons in the details pane by using the <controls> element. This accepts the same child elements as the <controls> element for the Job Management table (for details, see Buttons on page 95). 4. Create drop-down buttons to contain buttons that relate to one another by setting the <menu> child element, creating a descriptive label, and setting the buttons as its child elements. For example: <controls> <menu label="Job Actions"> <cancel /> <hold /> <suspend label="Suspend Job" tooltip="Request that Moab suspend this job" /> </menu> 98 4.4 Configuring the Job Details pane Chapter 4: Configuring jobs <requeue /> </controls> 5. Set <menu>'s vertical attribute to false to switch the menu's layout direction from its default vertical orientation. For example: <controls> <menu label="Job Actions" vertical="false"> <cancel /> <hold /> <suspend label="Suspend Job" tooltip="Request that Moab suspend this job" /> </menu> <requeue /> </controls> 6. Customize the sections using the <sections> element. Specify a <section> for each collapsible section in the Job Details pane. 7. For each <section>, set the <title> that will separate the section in the pane. 8. Set the <fields> element as a child of <section>. This element will hold the field details. 9. Within the <fields> element, set any of the table field types (for details, see Configuring columns in the Job Management table on page 97). You may also set any of the following child elements: 4.4 Configuring the Job Details pane 99 Chapter 4: Configuring jobs Element Description <variables> Displays a list of all the current job variables <messages> Displays a list of all messages currently associated with the job <header> Adds a line of header text to be used as a sub-header inside a details section or to separate groups of values in a details section. <downloadstdout> Provides a link to download the standard output of a completed job <downloadstderr> Provides a link to download the standard error of a completed job 10. Give any desired fields the editable="true" attribute to specify that it can be edited in the Job Details pane by clicking the edit icon. The following field types are editable: l <account> l <class> l <group> l <name> l <qos> l <wallclock-requested> l <variable> l <variables> For example: 11. <fields> <name editable="true"> <title>Apple's Name</title> </name> </fields> 100 4.4 Configuring the Job Details pane Chapter 4: Configuring jobs If at least one field is marked as editable, the job details section displays a Save button. <details> <title>Job ${name}($id) Details</title> <controls> <cancel /> <hold /> <suspend label="Suspend Job" tooltip="Request that Moab suspend this job" /> <requeue /> </controls> <sections> <section> <title>Apple</title> <fields> <name> <title>Apple's Name</title> </name> <state> <title>State of the Apple</title> </state> </fields> </section> <section> <title>Grape</title> <fields> <user> <title>Grape Users</title> </user> <group> <title>Grape Groups</title> </group> <account> <title>Grape Accounts</title> </account> </fields> </section> <section> <title>Peach</title> <fields> <wallclock-requested> <title>Requested Peach Walltime</title> </wallclock-requested> 4.4 Configuring the Job Details pane 101 Chapter 4: Configuring jobs <proc-count> <title>Peach Processor Count</title> </proc-count> <memory> <title>Peach's Memory in GB</title> </memory> <submit-date> <title>Date Peach Was Submitted</title> </submit-date> </fields> </section> <section> <title>Orange</title> <fields> <variable name="aitId"> <title>AIT ID</title> </variable> </fields> </section> <section> <title>Mango</title> <fields> <variables /> </fields> </section> </sections> </details> 102 4.4 Configuring the Job Details pane Chapter 4: Configuring jobs Related topics l Configuring buttons in the Job Management table on page 94 l Configuring columns in the Job Management table on page 97 4.5 Configuring streaming job output The job output page allows a user to view the standard output and standard error files for a job as the job is running and after the job completes. The page is accessible via the get-output button in the Configuring Job Management Buttons page (for details, see Configuring buttons in the Job Management table on page 94). To configure streaming job output 1. Open the jobs.xml file located in the Viewpoint home directory and locate the <job-management> element. 2. Insert the <spool-dir> element to enable streaming job output. Point it to the directory where Viewpoint can read the job output files. 4.5 Configuring streaming job output 103 Chapter 4: Configuring jobs <spool-dir>/var/spool/torque/spool</spool-dir> Since Viewpoint assumes the job output files are contained in the specified directory both while the job is running and after it is completed, you must configure the file system where the spool directory is located. 3. Configure the resource manager that runs the jobs. Set the resource manager to place job output files in the specified directory and keep them there after the job completes. If Viewpoint and any of the MOM daemons are running on different machines (which is the typical scenario), the spool directory must be configured as a shared network directory to which all MOMs and Viewpoint share access. 4. Configure the <stdout-format> element to describe the file format of the job’s stdout stream. This element allows for string interpolation in the same way as the <title> element for job management. By default, these parameters are configured to use the format TORQUE uses when $spool_as_final_name is configured and a directory is specified via the -o and -e flags for qsub. The format is $name.o$id for stdout and $name.e$id for stderr. (For more information, see the TORQUE Administrator Guide.) <stdout-format>$name.o$id</stdout-format> 5. Configure the <stderr-format> element to describe the file format of the job’s stderr stream in the same way that the <stdout-format> element is configured. <config> ... <job-management> <spool-dir>/var/spool/torque/spool</spool-dir> <stdout-format>$name.o$id</stdout-format> <stderr-format>$name.e$id</stderr-format> ... </job-management> </config> Related topics l Configuring the Job Submit form on page 89 l Configuring TORQUE and Moab for streaming job output on page 104 4.6 Configuring TORQUE and Moab for streaming job output The only resource manager for which streaming output is supported is TORQUE 2.4 and later. 104 4.6 Configuring TORQUE and Moab for streaming job output Chapter 4: Configuring jobs To configure TORQUE and Moab for streaming job output 1. Configure all pbs_mom daemons in TORQUE with the $spool_as_final_name parameter set to true. This causes the MOM daemons to not move the job output files to another location after the jobs finish running. 2. Use submit filters to force all job output to go to the directory configured in Viewpoint. If both msub and qsub are used by users, a filter must be supplied for both. The following example demonstrates a submit filter for the msub command that forces all job output to go to /var/spool/torque/spool. The script relies on Ruby, RubyGems, the libxml-ruby gem, and the availability of native libxml2 libraries that libxml-ruby needs. #!/usr/bin/env ruby require 'rubygems' require 'libxml' include LibXML::XML SpoolDir = '/var/spool/torque/spool/' ScriptStartRe = %r{^\s*\START} ScriptDirectiveRe = %r{#{ScriptStartRe}\23!.+?\0a} job = Parser.io($stdin).parse e = job.find_first('/job/SubmitString') output_directives = "#PBS -o #{SpoolDir} #PBS -e #{SpoolDir} " { " " => "\\20", " " => "\\0a", "#" => "\\23" }.each do |a, b| output_directives.gsub!(a, b) end if e.content =~ ScriptDirectiveRe || e.content =~ ScriptStartRe e.content.insert($~.size, output_directives) else raise "Failed to recognize start of job submit string" end puts job 3. Create job output files with file permissions such that the OS user Viewpoint runs under can read the files. Use the $job_output_file_unmask parameter to configure all MOM daemons to produce job output files that are world-readable. Specifically, the following line causes job output files to be created with read privileges for all users: $job_output_file_umask 022 4. Verify the steps have been completed successfully. Once the following 4 criteria have been met, the job output Viewpoint feature and the "get-output" job control should function properly: a. TORQUE MOM daemons are configured to use the same location for job output while the job is running and after it is completed. b. Submit filters force all job output to a single directory. c. The job output umask is configured so that the Viewpoint user can read the job output files. d. Viewpoint is properly configured to look inside this directory for job output, the job output Viewpoint feature and the "get-output" job control should function properly. 4.6 Configuring TORQUE and Moab for streaming job output 105 Chapter 4: Configuring jobs Related topics 106 l Configuring the Job Submit form on page 89 l Configuring streaming job output on page 103 4.6 Configuring TORQUE and Moab for streaming job output Chapter 5: Configuring nodes This chapter contains information about configuring nodes. It includes these sections: l Configuring the Node Management table buttons on page 107 l Modifying columns in the Node Management table on page 109 l Creating a composite column in the Node Management table on page 111 l Customizing the Node Detail pane on page 112 l Controlling a node's visibility on page 114 l Customizing state values in the Node Management table on page 114 5.1 Configuring the Node Management table buttons The above-table controls perform actions based on items like the currently selected table records. The above-table buttons are configured in the <controls> child element of <node-management>. Supported elements are listed below. Note that some buttons are only valid for a particular record type (node or VM). Buttons disable themselves when their surrounding context is invalid such as if the button requires a selected record but no table record is selected, or if the type of the selected record doesn't apply to the button. To configure a button's icon, label, or tooltip 1. Open the nodes.xml file located in your Viewpoint home directory. Locate the <controls> element within <node-management>. Several above-table buttons have already been configured. The buttons you may configure are: Button Description <power-off> Powers off selected nodes <power-on> Powers on selected nodes <refresh> Refreshes the table and any open details panel 5.1 Configuring the Node Management table buttons 107 Chapter 5: Configuring nodes Button Description < reprovision> Reprovisions all selected nodes <showpendingactions> Redirects to the pending actions page for the currently-selected node <modifyhostreservations > Displays a popup listing all host-based reservations that include the selected node in their host expression. Users can then remove reservations from the node by either shrinking them or by deleting them if they exist only on the selected node. <removeadminreservations > Removes all host-based user reservations from the selected nodes. If these reservations would then become empty, they are deleted instead. You may also insert any other desired buttons that area not already configured. 2. Customize the buttons by doing the following: a. Use the image-url attribute to specify the path to an icon that will be used to display the button. b. Use the label attribute to change the button's display text. If an image has been specified, this text will appear to its right side. c. Use the tooltip attribute to display a short explanation of what the button does when the cursor hovers over it. d. You may set a permission for each button with the <permissions> child element (for details, see Setting permissions on page 51). e. It might contain a sequence of <permission> elements that specify a Viewpoint permission a user needs in order to see and use the button. For example: <power-off> <permissions> <permission name="node.update" /> </permissions> </power-off> In this example, a user can use the power-off button only if she/he has the node.update permissions. Related topics 108 l Setting permissions on page 51 l Configuring columns in the Job Management table on page 97 5.1 Configuring the Node Management table buttons Chapter 5: Configuring nodes l Creating a composite column in the Node Management table on page 111 l Controlling a node's visibility on page 114 l Customizing the Node Detail pane on page 112 l Customizing state values in the Node Management table on page 114 l Creating custom dialog windows on page 81 5.2 Modifying columns in the Node Management table The Node Management table can be configured at the column-level to show different attributes for nodes. The relevant XML section for configuring the table is nodes > node-management > table > fields. Each child element of the fields element corresponds to a single column, and the columns will appear in the same order that the child elements are specified. The name of each element corresponds to the type of the column. This type knows how to extract a piece of information from a table record to display in the column, and also contains sensible defaults for display options of the column. To add/remove/modify columns in the Node Management Table 1. Open the nodes.xml file located in the Viewpoint home directory. 2. Scroll to the <node-management> section and locate the <table> element. 3. To remove a column, either delete the associated <field> element or comment it out using the <!-and --> brackets. 4. Modify existing columns according to your preferences: a. Set the width attribute for the associated element. The width is specified in pixels. b. Set the visible attribute for the associated element to specify whether the column should be displayed or hidden. This is set to true by default. c. Use the <title> child element to change the column’s display name. 5. To add a new column, insert the corresponding child element from the list below into the <field> element. They may contain any of the attributes or the element described in step 4. l <access-policy> l <alias> l <architecture> l <disk-available> l <disk-total> l <disk-utilized> l <features> l <id> 5.2 Modifying columns in the Node Management table 109 Chapter 5: Configuring nodes l <ip-address> l <link-id> l <load> l <memory-available> l <memory-total> l <memory-utilized> l <os> l <pending-actions> l <power> l <power-policy> l <priority> l <processors-available> l <processors-total> l <processors-utilized> l <state> l <status> l <substate> l <type> 6. Verify that at least one field to be a primary key field. To do so, set the primary attribute to true. It is strongly suggested that you create an <id /> field as the sole primary key field. You can make this field invisible if you do not want users to see it. Related topics 110 l Creating a composite column in the Node Management table on page 111 l Controlling a node's visibility on page 114 l Customizing the Node Detail pane on page 112 l Configuring the Node Management table buttons on page 107 l Customizing state values in the Node Management table on page 114 5.2 Modifying columns in the Node Management table Chapter 5: Configuring nodes 5.3 Creating a composite column in the Node Management table The <table> element supports a special kind of column named "composite". The composite column allows you to display a value based on the basic fields listed above by using the value decider framework. Each field can be accessed with <component> elements. To create a composite column in the Node Management table 1. Open the nodes.xml file located in the Viewpoint home directory. 2. Use the <component> element inside the <fields> element. This will display a value based on the basic fields in this Node Management table (see Modifying columns in the Node Management table on page 109). 3. Specify a width and a <title> for the <component>. 4. Set the <value> element to include the value decider portion that determines the form of the column values. The basic structure of a <composite> element is below: 5. <composite width="100"> <title>Column title</title> <value> ... </value> </composite> As an example, you might create a composite value to display both the available disk space and the total configured disk space on nodes and VMs in gigabytes. Disk values are reported directly as given by Moab. If Moab is reporting disk values in megabytes, you could configure the composite value as shown in the example below. This example displays a column value of the form <disk available in GB> / <disk total in GB>. <composite width="75"> <title>Disk (GB)</title> <value> <calculate operation="append-in-order"> <value order="1"> <calculate operation="double-to-string" format="#.#"> <calculate binary-operation="multiply"> <first> <component id="disk-available"/> </first> <second>.0001</second> </calculate> </calculate> </value> 5.3 Creating a composite column in the Node Management table 111 Chapter 5: Configuring nodes <value order="2"> / </value> <value order="3"> <calculate operation="double-to-string" format="#.#"> <calculate binary-operation="multiply"> <first> <component id="disk-total"/> </first> <second>.0001</second> </calculate> </calculate> </value> </calculate> </value> </composite> Related topics l Configuring nodes on page 107 l Modifying columns in the Node Management table on page 109 5.4 Customizing the Node Detail pane Each details panel section specified in XML corresponds to a collapsible section in the details panel. A section itself consists of a title (with no variable interpolation) and a <fields> element that contains a list of fields. These fields have names that correspond directly to the table fields described previously in the fields section. To customize the Node Detail page 1. Open the nodes.xml file located in the Viewpoint home directory. Locate the <details> element within the <node-management> section. 2. Customize the details panel collapsible sections. a. Specify a title (with no variable interpolation) for the section. <details> … <sections> <section> <title>General</title> <fields> <id> <title>Name</title> </id> 112 5.4 Customizing the Node Detail pane Chapter 5: Configuring nodes … </fields> </section> … </sections> </details> b. Within the <fields> element, insert any of the table fields listed here or any of the following additional fields: l <classes> - A collection l <generic-events> - A table l <generic-metrics> - A table l <generic-resources> - A table l <header> - This is used to add a line of header text meant to be a sub-header inside a details section or to separate groups of values in a details section. l <jobs> - A collection l <os-options> - A collection l <reservations> - A collection l <resource managers> - A collection l <variables> - A table Several fields actually display a collection or list of scalar values. By default, these values are printed as a label of comma-separated values. However, if the field is given the attribute multiline="true", the field is displayed as a multi-select box with each individual collection value displayed on its own line. The fields that currently have this feature are labeled as collection fields. 3. Give the field a <title> as demonstrated in the 2a example. 4. Configure any desired buttons inside the <controls> element. You may use any of the above-table button elements, or the elements from the following list: l <toggle-node-power> o Set the <on-button> and <off-button> child elements with the image-url attribute to configure a custom button look for when the button can turn off a node, and another button look for when the button can turn a node on. <toggle-node-power> <on-button image-url="images/power-green.png" tooltip="Power on server" /> <off-button image-url="images/power-red.png" tooltip="Power off server" /> </toggle-node-power> l <remove-node> 5.4 Customizing the Node Detail pane 113 Chapter 5: Configuring nodes Related topics l Modifying columns in the Node Management table on page 109 l Creating a composite column in the Node Management table on page 111 l Controlling a node's visibility on page 114 l Customizing state values in the Node Management table on page 114 l Configuring the Node Management table buttons on page 107 5.5 Controlling a node's visibility You can control the way nodes are displayed using Moab. To control a node's visibility 1. Use the variable VP_IS_VISIBLE=false to control a node's visibility to all users. Run the mnodectl command (see "mnodectl" in the Moab Workload Management Administrator Guide) on the node to set the Moab variable. If the variable is set to anything other than false, or if the variable is not present on a node, the node will be displayed normally, which is the default. mnodectl node01 -m variable=VP_IS_VISIBLE=false 2. Use the VP_VIEW_PRINCIPALS variable to control a node's visibility based on users' principals. a. Verify that the user role has the node.read permission so that the user can access nodes. b. Configure the VP_VIEW_PRINCIPALS variable and set the value to a set of user principals, delimited by the | character, necessary to access the node. To do so, run the following command: mnodectl node01 -m variable=VP_VIEW_PRINCIPALS=admin|poweruser|operator A user must have any of the specified principals to view the node. Related topics l Configuring nodes on page 107 5.6 Customizing state values in the Node Management table The values reported by the state, substate, and status fields can be customized using the localization framework (see Customizing Viewpoint to specific markets or customers on page 61.). To customize state values in the Node Management table 1. Open the market.properties configuration file located in the Viewpoint home directory. 2. Add the value to be replaced, followed by a '=', and then the value that will replace it. 114 5.5 Controlling a node's visibility Chapter 5: Configuring nodes Drained = Admin Down "Admin Down" appears in the Node Management table if the status of a node is reported as "Drained". Related topics l Customizing Viewpoint to specific markets or customers on page 61 l Modifying columns in the Node Management table on page 109 l Creating a composite column in the Node Management table on page 111 l Controlling a node's visibility on page 114 l Customizing the Node Detail pane on page 112 l Configuring the Node Management table buttons on page 107 5.6 Customizing state values in the Node Management table 115 Chapter 6: Creating or configuring forms A form is a series of pages with input components such as select boxes, check boxes, and so forth. Users input various values into the components and submit the form to the server. The server then reads the values the user entered and performs an action such as submit a job. You can create or customize forms using XML. Administrators can define certain aspects of the user interface (UI) as well as business rules and logic associated with a form. Forms that you can configure include the following: l Configuring the Job Submit form on page 89 explains how to modify the jobs.xml file. Each of the configurable XML files (reservations.xml, nodes.xml, jobs.xml) have elements in common. Common elements include the <pages>, <components>, and <queue> elements. For detailed information on configuring these elements, see the following: l Configuring the <components> element on page 118 l Configuring the <pages> element on page 147 l Configuring the <queue> element on page 157 It is very important to note, though, that not all elements share the same attributes. In such cases, where there are unique configuration requirements, they are noted in the help page associated with configuring the specific file. For example, specific requirements for configuring the <queue> element in the jobs.xml file are available through Configuring the Job Submit form on page 89. Each of the configurable XML files have unique requirements for configuring the <request> element. Instructions for configuring the <request> element for each file are available in the help page for each form. Additionally, other such unique instruction is available in the help page for each form. This chapter contains these topics: l Configuring the <components> element on page 118 l Configuring the <pages> element on page 147 l Configuring the <queue> element on page 157 l Adding a date decider on page 162 l Adding a duration decider on page 163 l Adding an integer decider on page 165 l Adding a string decider on page 166 l Setting a Boolean decider on page 170 117 Chapter 6: Creating or configuring forms 6.1 Configuring the <components> element To configure the components element 1. In the configurable XML file corresponding to the form you are creating, usually in the Viewpoint home directory, locate the <components> element. 2. For each input, insert a <component> element inside <components>. Assign the inserted component a unique id such as "priority". For example: <components> ... <component id="priority">...</component> ... </components> 3. Apply the description attribute of <component> to any string you want to use as a label in the user interface for the component. The default is an empty string. 4. Use the required attribute of <component> to specify whether the component is required. (The user must enter data to pass page validation.) The default is "false". The <label> component does not support the required attribute. 5. Use the editable attribute of <component> to specify whether the component is editable by the user. The default is "true". The <label> component does not support the editable attribute. 6. Use the permission attribute of <component> to specify which permissions are required to view the component. The value can be any permission. See Setting permissions on page 51. <component id="priority" required="false" permission="power-user"> <description>Priority</description> <number-value type="int"> <default>0</default> <minimum inclusive="true">-10000</minimum> <maximum inclusive="true">10000</maximum> <step>1</step> </number-value> </component> The user must have the "power-user" permission to see the priority component. 7. Configure any of the following components: l 118 ACL (Access Control List) Editor (Configuring an access control list on page 120) 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms l Help Text l Check Box (Configuring a checkbox on page 120) l Date Box (Configuring a date box on page 121) l Duration Components o Duration Text Box (Configuring a duration text box on page 124) o Duration Spinners (Configuring a duration spinner on page 122) l File Upload (Configuring an upload file componenet on page 141) l Inferred Value (Configuring an inferred values drop-down list on page 126) l Label (Configuring a label on page 127) l List Box (drop-down, single selection) (Configuring a list box on page 128) l List Editor (Configuring a list editor on page 129) o List Editor Text Box (Configuring a list editor on page 129) Add Bookmark o List Editor Select Box (Configuring a list editor on page 129) Add Bookmark o List Editor Suggest Box (Configuring a list editor on page 129) Add Bookmark o List Editor with Inferred Values (Configuring a list editor on page 129) Add Bookmark o List Editor Using Other Components (Configuring a list editor on page 129) Add Bookmark l Multi-select List Box (Configuring a multi-select list box on page 133) l Number Spinner (Configuring a number spinner on page 134) l Radio Button Selector (Configuring a radio button selector on page 135) l Script Upload (Configuring a script upload component on page 136) l Suggest Box (Configuring a suggest box on page 137) l Table Map (Configuring a table map on page 139) l Text Box (Configuring a text box on page 140) o Password Text Box (Configuring a text box on page 140) Add Bookmark 8. Set any desired component rules. See Setting component rules on page 142. Related topics l Creating or configuring forms on page 117 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 l Setting permissions on page 51 6.1 Configuring the <components> element 119 Chapter 6: Creating or configuring forms 6.1.1 Configuring an access control list An ACL editor is a component that can be used to create or modify any access control list. An access control list is a list of credentials that have or will have access to the base object. There are two input areas for any ACL editor: (1) the credential type and (2) the credential name. The credential types are User, Account, Class, Group, or QoS. After selecting the type, enter the credential name in the text area to the right. As text is entered, suggestions for credential names, that match the type specified, appear. Add credentials by pressing ENTER on the keyboard. To add/delete/modify an access control list 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Insert the following: <component id="aclEditor"> <description>Access Control List</description> <acl-editor /> </component> An ACL editor is inserted into the form. The user selects the credential type from the left drop-down list, and specifies the credential name in the text area on the right . The multi-select component is invalid when less than two or more than three items are selected. Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.2 Configuring a checkbox A user clicks a checkbox to toggle true or false values. Use a <boolean-value> element to specify a checkbox. To add/delete/modify a checkbox 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Set the <boolean-value /> element within <component>. 120 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms 4. Set the <default> if you would like it to be “true”. If unset, Viewpoint automatically assumes "false". <component id="isDevelopment" required="true"> <description>Development</description> <boolean-value /> <default>true</default> </component> Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.3 Configuring a date box A date box allows users to input a date value. Restrictions can be placed on the date box to define what are valid dates. As with other components, the default date can be specified by using the <default> element. To add/delete/modify a date box 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Set the <date-value> element within <component>. 6.1 Configuring the <components> element 121 Chapter 6: Creating or configuring forms 4. Set restrictions to define which dates are valid. To do so: a. Insert the <earliest-date> element within <date-value> to specify the earliest date that a user can input. This is assumed to be an absolute date, but to set it as a relative date, add the relative attribute, and set it to "false". b. Set the date by inserting any of all of the following elements: <years>, <months>, <days>, <hours>, <minutes>, and <seconds>. The text in each of these elements must be an integer value. Any value not set is assumed to be 0. Users may specify values above the theoretical maximum and they will be converted. For example, 25 hours would correspond to +1 day and 1 hour. c. Insert the <latest-date> element within <date-value> to specify the latest date that a user can input. This is assumed to be an absolute date, but to set it as a relative date, add the relative attribute and set it to "true". Set the date according to the instructions in step 4b. <component id="birthday" required="true"> <description>Birthday</description> <date-value> <earliest-date relative="false"> <years>1776</years> <months>7</months> <days>4</days> </earliest-date> <latest-date relative="true" /> </date-value> </component> The user must input a date after July 4, 1776 and before today. Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.4 Configuring a duration spinner You can configure the <duration-value> component to display number spinners. You can specify how many spinners should be available for entering time information. 122 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms To add/delete/modify a duration spinner 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <duration-value> child element with the type attribute set to “spinner”. 4. Set the <default> element within <duration-value> to define a default value for each period type. 5. Set the <minimum> element within <duration-value> to specify the minimum allowable value for each period type. 6. Set the <maximum> element within <duration-value> to specify the maximum allowable value for each period type. 7. Set the <display> element within <duration-value> to specify which number displays for each period type. 8. Set <time-period> within each of the child elements described in steps 4-6 and specify a time by setting the following elements inside of <time-period>: <years>, <months>, <days>, <hours>, <minutes>, and <seconds>. The text in each of these elements must be an integer value. Any value not set is assumed to be 0. Users may specify values above the theoretical maximum and they will be converted. For example, 25 hours would correspond to +1 day and 1 hour. <duration-value type="spinner"> -> <default> <!-> <time-period> <!-> <days>14</days> <!-> <hours>6</hours> <!-> </time-period> <!-> </default> <minimum> <!-> <time-period> <!-> <hours>4</hours> </time-period> </minimum> <maximum> <time-period> <years>2</years> </time-period> </maximum> <display> <!-- 6.1 Configuring the <components> element <!-- Type should be "text" or "spinner". - You can specify a default value for any -- period type listed above. -- Here, a default value of 14 is displayed -- to the user for the 'days' entry and '6' is -displayed for the 'hours' entry. -- Minimum and maximum values can be specified -for each period type. -- This works for only the "spinner" duration -- 123 Chapter 6: Creating or configuring forms > <time-period> <!-- type. Using this element creates a spinner -- <months>1</months> <!-- for each time period that you specify. A -- <days>1</days> <!-- time period with a value of '1' displays a -- <hours>1</hours> <!-- number spinner for that time period type on -- > > > > </time-period> <!-- the GUI. -- > </display> </duration-value> Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.5 Configuring a duration text box The duration text box component is the default duration component and can be specified with type="text". To add/delete/modify a duration text box 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <duration-value> child element with the type attribute set to “text”. 4. Set the <default> element within <duration-value> to define a default value for each period type. The default value is displayed to the user. 5. Set the <minimum> element within <duration-value> to specify the minimum allowable value for each period type. 6. Set the <maximum> element within <duration-value> to specify the maximum allowable value for each period type. 7. Set <time-period> within each of the child elements described in steps 4-6 and specify a time by setting the following elements inside of <time-period>: <years>, <months>, <days>, <hours>, <minutes>, <seconds>. The text in each of these elements must be an integer value. Any value not set is assumed to be 0. Users may specify values above the theoretical maximum and they will be converted. For example, 25 hours would correspond to +1 day and 1 hour. 124 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms <duration-value type="text"> <default> <time-period> <years>1</years> <months>1</months> <days>0</days> <hours>0</hours> <minutes>0</minutes> <seconds>0</seconds> </time-period> </default> <minimum> <time-period> <years>0</years> <months>0</months> <days>0</days> <hours>0</hours> <minutes>0</minutes> <seconds>0</seconds> </time-period> </minimum> <maximum> <time-period> <years>100</years> <months>100</months> <days>365</days> <hours>24</hours> <minutes>60</minutes> <seconds>60</seconds> </time-period> </maximum> </duration-value> Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1 Configuring the <components> element 125 Chapter 6: Creating or configuring forms 6.1.6 Configuring an inferred values drop-down list The inferred values component enables you to have a drop-down menu that is generated at the time the page is loaded, instead of when the configuration file is read. This enables you to configure a component that has dynamic values that change depending on the current state of your environment. There are two ways to source the values that populate the dynamic drop-down menu: You can use a URL to read in an external script or XML file. You can retrieve values from Moab. To add/delete/modify an inferred values drop-down list 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Determine whether to populate the dynamic drop-down menu using a suggest box or from a URL. l Configure a suggest box to use inferred values. a. Set the <inferred-value> child element inside the component. b. Set the component attribute to "suggest". <inferred-value source="Moab" type="node-name" component="suggest" /> The user is presented with a text box with suggestions populated as the user types. l Configure a URL to read in an external script or XML file. a. Insert the <inferred-value> element inside the component. b. Set the cardinality attribute if the inferred value that is read is in a <select-value>. c. Set the value to "one" or "many" to indicate whether a single or multiple items can be selected at once. d. Set the source attribute to indicate that the inferred values come from a file, not Moab. Set the value to "exec" if the file is an executable or to "file" if the file is an XML file. e. Insert the <url> child element, and set the value attribute to the file’s location. <component id="node_selection" required="false"> <description>List of nodes available</description> <inferred-value cardinality="one" source="file"> <url value="file:///availableNodes.xml" /> </inferred-value> </component> Both file system-based URL types (i.e., flat text file or executable script) use the file protocol. 126 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms Because the <inferred-value> element is already wrapped in the <component> element, all that needs to be read-in from the script or file is the component details. Two valid returns to the <inferred-value> element are: <select-values> <select-value api-value="a" display-value="Value A" /> <select-value api-value="b" display-value="Value B" /> </select-values> <number-value type="int"> <default>1</default> <minimum>2</minimum> <maximum>8</maximum> <step>1</step> </number-value> Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.7 Configuring a label The label component allows you to display unmodifiable text. To add/delete/modify a label 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <label-value> element within <component> to display text that cannot be modified. <label-value>Operating System Information</label-value> Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1 Configuring the <components> element 127 Chapter 6: Creating or configuring forms 6.1.8 Configuring a list box To add/delete/modify a list box 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <select-values> element and set the cardinality attribute to "one". A <select-values> element with cardinality="many" uses the (multi-select) List Box. 4. Set the <select-value> element to specify what items should appear in the list that can be selected. Set the api-value to specify how the value is interpreted and display-value to determine what is displayed in the list. 5. Optional: Set the <default> element within <select-values> to select a value other than the first one in the list as the default. 6. Optional: Set the sort attribute of <select-values> to "true" to sort the values alphabetically by their <display-value> rather than by the order they are listed in the XML. <component id=”os” required=”true”> <description>Operating Systems</description> <select-values cardinality="one" sort=”true”> <select-value api-value="RhelAS4u6x86_64" display-value="RedHat AS 4.6 64bit" /> <select-value api-value="RhelAS4u6x86" display-value="RedHat AS 4.6 32bit" /> <select-value api-value="RhelES5u1x86_64" display-value="RedHat ES 5.1 64bit" /> <default api-value="RhelAS4u6x86" display-value="RedHat AS 4.6 32bit" /> <select-value api-value="Win2003EEr2x86" display-value="Win 2003 Ent 32bit" /> 128 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms <select-value api-value="Win2003EEr2x86_64" displayvalue="Win 2003 Ent 64bit" /> <select-value api-value="RhelES5u1x86" display-value="RedHat ES 5.1 32bit" /> </select-values> </component> All validation and rule descriptors use the api-value attribute when getting the value of a single select list box. Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.9 Configuring a list editor A list editor is a component that allows users to add strings to a list. It is configured using the <listeditor> element. This component has an input area that allows a user to input a string value and buttons on the side for adding or removing items in the list. To add a value to the list box, the user enters a value into the input component and clicks the "+" button. A user removes a value from the list by selecting one or more items on the list and clicking the "-" button. The list editor widget currently supports default values and enforces a minimum and maximum number of items in the list. Unlike other components, there may be more than one <default> element. Each default element will add another item to the list. To add/delete/modify a list box 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <list-editor> element within <component>. 6.1 Configuring the <components> element 129 Chapter 6: Creating or configuring forms 4. Determine which widget to use for input to the list editor. l Specify a text box as the list editor input. This is the default and is used if no input area is configured in the XML. a. Use the <default> child element any number of times to add default items to the list. b. Set the <minimum> child element to specify the minimum items users may add to the list. c. Set the <maximum> child element to specify the maximum items users may add to the list. d. Optional: Specify a regular expression using the <regex> child element. <component id="zip_code_list"> <description>List of ZIP Codes</description> <list-editor> <default>84043</default> <default>30052</default> <minimum>1</minimum> <maximum>5</maximum> <regex>^\d{5}$</regex> </list-editor> </component> l Specify a select box as the list editor input. a. Use the <select-value> element to preset default options in the list editor. <component id="licenses"> <description>Software Licenses</description> <list-editor> <select-value>Matlab</select-value> <select-value>NetSuite</select-value> <select-value>Tomcat</select-value> <select-value>Windows Server 2008</select-value> <select-value>Microsoft Office 2010</select-value> <select-value>Adobe Acrobat 9</select-value> </list-editor> </component> 130 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms l Specify a suggest box as the list editor input. a. Use the <suggest-box> element. See Configuring a suggest box on page 137. l Specify the list editor input as inferred values. a. Insert the <inferred-value> element. b. Set the source attribute to "moab", the type attribute to "node-name", and the component attribute to "suggest" l Specify the list editor input as a composite list. a. Insert the <composite-list-editor> element. b. Set the <display-value> element to determine how any new item in the list should be displayed. c. Set the <api-value> element to determine the internal, hidden value of any new item. d. Optional: Set the <add-text> element to specify the desired text of the “Add” button. e. Optional: Set the <remove-text> element to specify the desired text of the “Remove” button. <component id="storage-list"> <composite-list-editor> <add-text>Add Storage</add-text> <api-value> <calculate operation="append-in-order"> <value order="1"> <component id="storage-amount" /> </value> <value order="2">:</value> <value order="3"> <component id="storage-type" /> </value> <value order="4">@</value> <value order="5"> <component id="storage-location" /> </value> </calculate> </api-value> <display-value> <calculate operation="append-in-order"> 6.1 Configuring the <components> element 131 Chapter 6: Creating or configuring forms <value order="1"> <component id="storage-amount" /> </value> <value order="2"> units of type </value> <value order="3"> <component id="storage-type" /> </value> <value order="4"> at </value> <value order="5"> <component id="storage-location" /> </value> </calculate> </display-value> </composite-list-editor> </component> A description is not required for this component. However, if one is specified, it will be placed in the upper left section of the widget: 132 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.10 Configuring a multi-select list box A multi-select list box component allows users to select one or more items in a list. The CTRL key is used to select multiple items. To use the multi-select list box, specify a <select-values> element with a cardinality attribute that has a value of "many". To add/delete/modify a multi-select list box 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <select-values> element and set the cardinality attribute to "many". A <select-values> element with cardinality=”one” uses the (single select) List Box. 4. Set the <default> element within <select-values> to specify what the initial selection should be. 5. Set the <maximum> element within <select-values> to specify how many items must be selected at maximum. 6.1 Configuring the <components> element 133 Chapter 6: Creating or configuring forms 6. Set the <minimum> element within <select-values> to specify the minimum number of items that can be selected. 7. Set the <select-value> element to specify what items should appear in the list that can be selected. Set the api-value to specify how the value is interpreted and display-value to determine what is displayed in the list. <select-values cardinality="many"> <maximum>3</maximum> <minimum>2</minimum> <default api-value="RhelAS4u6x86" display-value="RedHat AS 4.6 32bit" /> <default api-value="RhelAS4u6x86_64" display-value="RedHat AS 4.6 64bit" /> <select-value api-value="RhelAS4u6x86" display-value="RedHat AS 4.6 32bit" /> <select-value api-value="RhelAS4u6x86_64" display-value="RedHat AS 4.6 64bit" /> <select-value api-value="RhelES5u1x86" display-value="RedHat ES 5.1 32bit" />" <select-value api-value="RhelES5u1x86_64" display-value="RedHat ES 5.1 64bit" /> <select-value api-value="Win2003EEr2x86" display-value="Win 2003 Ent 32bit" /> <select-value api-value="Win2003EEr2x86_64" display-value="Win 2003 Ent 64bit" /> </select-values> The multi-select component is invalid when less than two or more than three items are selected. Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.11 Configuring a number spinner The number spinner is a text box that allows only numbers with up and down buttons on the side. As the user clicks on either the up or down arrows, the value inside the spinner increments or decrements, depending on which button is clicked. 134 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms To add/remove/modify a number spinner 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <number-value> element and set its type to "int" for integers or "double" for decimal values. 4. Set the <minimum> element to specify the minimum value, setting a number as the text. Use the inclusive attribute to specify whether the value inside should be inclusive or exclusive. Set the value to "true" or "false". The default is "true". If it is set to "false", the user will not be able to select that value. 5. Set the <maximum> element to specify the maximum value. Use the inclusive attribute to specify whether the value inside should be inclusive or exclusive. Set the value to "true" or "false". The default is "true". If it is set to "false", the user will not be able to select that value. 6. Set the <default> element to specify the default value, which is a number within the minimum and maximum ranges. <component id="duration" required="true"> <description>Duration in months</description> <number-value type="int"> <default>1</default> <minimum inclusive="true">1</minimum> <maximum inclusive="true">12</maximum> </number-value> </component> The number spinner ranges from 1 to 12 inclusive with a default value of 1. Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.12 Configuring a radio button selector A radio button selector is a panel that contains multiple radio buttons along with some descriptive text. Users can choose one of the items by clicking on the radio button for the item they wish to select. The value of a radio button selector panel is the text of the currently selected value (or empty if none is selected). To add/delete/remove a radio button selector 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 6.1 Configuring the <components> element 135 Chapter 6: Creating or configuring forms 3. Insert the <radio-select> element and set the display-value to the text the user will see with the radio button. 4. Set the horizontal-layout attribute to "true" or "false". If set to "true", the radio buttons are placed on the panel horizontally instead of vertically. The default is "false". Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.13 Configuring a script upload component The script upload component allows user created scripts to be uploaded from the Web browser to the cluster head. The component exists as an active link on a page that, when clicked, loads a dialog window like the one that follows. Image 6-1: Create Script window 136 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms To add/delete/modify a script upload component 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <script-upload> element and set the following three child elements: a. Set <server-path> to specify a temporary path on the server where the file should be uploaded. This must be a fully qualified path. b. Set <Cloud-path> to specify the final destination path of the file on the Cloud head. This must be a fully qualified path. c. Optional: Set <form-submit> to specify an alternative Servlet or other form action URL. The server and Cloud paths must be different if you are using an SSH connection to the localhost for Moab; otherwise the file will be deleted. <script-upload> <server-path>/tmp</server-path> <Cloud-path>/var/tmp</Cloud-path> <form-submit>/fileupload/script</form-submit> </script-upload> Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.14 Configuring a suggest box A suggest box is a text box or text area that displays a preconfigured set of selections that match the user's input. Suggest boxes are useful when there are too many choices to present to the user—so many that a select box would be unreasonable. It is also appropriate when the user can use an arbitrary string, but you want helpful suggestions to be available. 6.1 Configuring the <components> element 137 Chapter 6: Creating or configuring forms To add/delete/modify a suggest box 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <suggest-box> element. 4. Select whether to create a static suggest box in which all suggestions are determined when the page is loaded, or a dynamic suggest box in which the logic to determine the suggestions is executed on an external script. Inferred values incorporate well with suggest boxes. If you are using an inferred value script, have the script return the <suggest-box> root element and all its children. l Create a static suggest box by inserting the <suggestion> element for each suggestion. Viewpoint uses its built-in intelligence engine to determine how many options are sent to the client when the form is created. If there are too many suggestions to send to the client, Viewpoint caches the suggestions on the server and passes more to the client when necessary. <component id="manager-names" required="false"> <description>Select Team Lead</description> <suggest-box> <suggestion>Kelly Michaelis</suggestion> <suggestion>Larry Craig</suggestion> <suggestion>Elliott Johnson</suggestion> <suggestion>Harrison Carodine</suggestion> <suggestion>Bradley Kadanson</suggestion> </suggest-box> </component> l Create a dynamic suggest box by setting the <suggest-box> dynamic attribute to "true" and the source to "exec". Insert the <url> child element’s value attribute to the location of the script. <component id="dynamic-names" required="false"> <description>Dynamic</description> <suggest-box dynamic="true" source="exec"> <url value="file:///home/user/tools/suggestions.pl" /> </suggest-box> </component> The script outputs suggestions based on submitted outputs. The single argument to the script is the value of the current text. If "Jane" is submitted as input, it gets passed to suggestions.pl. Related topics 138 l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.15 Configuring a table map A table map is a component that allows users to add an arbitrary amount of key-value pairs. It is configured using the <table-map> element. This component consists of a table with three columns and an Add button at the bottom for adding more rows to the table. The first column is an icon to remove existing rows from the table. The component in the second column is the "key" component. All key components must have a unique value for the table map to be considered valid. The component in the last column is the "value" component. To add a new key-value pair to the table, the user clicks Add. This adds a new row to the table with the three columns explained earlier. The user can then fill in the values for these components as desired. A user who wants to remove the key and its corresponding value from the table, clicks the Remove icon to remove that row. To add/delete/modify a table map 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <table-map> element. 4. Configure the key component by inserting <key-component> within <table-map>. Give the component a unique id and set it up as you would if the component stood alone. The table accepts any component except components that contain lists or are tables themselves. For example, a table map cannot contain a key component of a table map. 5. Configure the value component by inserting <value-component> within <table-map>. Give the component a unique id and set it up as you would if the component stood alone. The table accepts any component except components that contain lists or are tables themselves. For example, a table map cannot contain a key component of a table map. <component id="genericResources" required="false"> <description>Generic Resources</description> <table-map> <key-component id="genericResourcesKey"> <select-values> <select-value api-value="fastio" display-value="Fast I/O" /> <select-value api-value="san" display-value="Extra Storage" /> 6.1 Configuring the <components> element 139 Chapter 6: Creating or configuring forms <select-value api-value="matlab" display-value="MATLAB Licenses" /> <select-value api-value="matlab" display-value="MATLAB Licenses" /> <select-value api-value="bandwidth" display-value="Bandwidth" /> </select-values> </key-component> <value-component id="genericResourcesValue"> <number-value type="int"> <default>0</default> <minimum inclusive="true">0</minimum> <maximum inclusive="true">10000</maximum> <step>1</step> </number-value> </value-component> </table-map> </component> The key is a list of generic resources and the value is the amount requested for each resource. Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.16 Configuring a text box A text box allows users to input any string data into a field. Restrictions can be placed on the text box to define what the valid inputs are. To add/delete/modify a text box 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <text-value> element. 4. (Optional) Set restrictions on the text using the <regex> child element. The expression is used to validate the input as defined by regular expression pattern matching. If it is not set, all inputs are considered valid. Regular expressions must use the JavaScript regular expression syntax. 5. (Optional) Set a default using the <default> element. 6. (Optional) Set the <error-msg> element to clarify the purpose of an error in a message should the regex validation fail. 140 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms <component id="zip" required="true"> <description>Zip Code</description> <text-value> <default>84043</default> <regex>^\d{5}$</regex> <error-msg>Zip code must be exactly 5 digits</error-msg> </text-value> </component> The text must match /^d{5}$/ (5-digit zip code) with a default value of 84043. 7. (Optional) Set the text box to mask the text to protect passwords. To do so, set the <text-value> type to "password". Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.17 Configuring an upload file componenet A file upload component allows users to upload files from their local computer to the cluster head. To add/delete/modify an upload file component 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <components> element. 2. Create the <component> with a unique id. 3. Insert the <file-upload> element. 4. Use any of the four optional child elements desired: l l Set <server-path> to specify a temporary path on the server where the file should be uploaded. The path must be fully qualified. Set <cluster-path> to specify the final destination path of the file on the cluster head. The path must be fully qualified. l Set <max-file-size> to specify the maximum allowable file size (in bytes) users can upload. l Set <form-submit> to specify an alternative Servlet or other form action URL. The server and cluster paths must be different if you are using an SSH connection to the localhost for Moab; otherwise the file will be deleted. <file-upload> <server-path>/tmp</server-path> 6.1 Configuring the <components> element 141 Chapter 6: Creating or configuring forms <cluster-path>/var/tmp</cluster-path> <max-file-size>10000000</max-file-size> <form-submit>/fileupload/file</form-submit> </file-upload > Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.18 Setting component rules This class represents a way to add requirements and rules to components. A component rule consists of two parts: <requirement> - What must be evaluated to determine if a response should occur. The requirement can be any Boolean decider. It is evaluated when any of the components change. <response> - What happens if the requirement is evaluated to true. The response can do one of the following operations: change the selectable values in a single select list box, change a component's (or a section's) visibility, validate or invalidate individual components, or get a dynamic component response. To set a component rule 1. Inside the component, set the <component-rule> element. 2. Place the <requirement> element within <component-rule> and configure a Boolean value decider to be evaluated when any of the components change. See Setting a Boolean decider on page 170. 3. Within <component-rule>, configure the <response> element to perform one of the following operations: l Change the selectable values in a single-select list box. See Configuring a list box on page 128. <component-rule> <requirement comparison="equals"> <first> <component id="procs" /> </first> <second>1</second> </requirement> <response> <component id="memory"> <select-values> <select-value api-value="1" display-value="1 GB" /> <select-value api-value="2" display-value="2 GB" /> <select-value api-value="4" display-value="4 GB" /> 142 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms </select-values> </component> </response> </component-rule> If the user selects "1" as the value for the "procs" component, the options available for the "memory" component become "1 GB", "2 GB", and "4 GB". l l l Change a component's (or a section's) visibility. See Changing a component/section's visibility on page 143. Validate or invalidate individual components. See Validating and invalidating components on page 146. Get a dynamic component response. See Getting component rule responses dynamically on page 144. Related topics l Configuring the <components> element on page 118 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 l Setting permissions on page 51 6.1.18.1 Changing a component/section's visibility When you create component rules, you must set a requirement and a response (see Setting component rules on page 142). Once you configure the desired requirement, use the following instructions to configure the <response> element to change a component or section's visibility. To change a component's or section's visibility 1. Within the <response> element, place the <component> element. Specify which component's or section's visibility will change using the id attribute. <component id="ip-address" /> 2. Specify the new visibility of the component using the <display> child element. <display> is either true (visible) or false (invisible). COMPONENT VISIBILITY EXAMPLE <component-rule> <requirement comparison="equals"> <first> <component id="script-chooser" /> </first> <second>Write New</second> </requirement> 6.1 Configuring the <components> element 143 Chapter 6: Creating or configuring forms <response> <component id="upload-script"> <display>false</display> </component> <component id="write-script"> <display>true</display> </component> </response> </component-rule> The "upload-script" component is made invisible when a value of "Write New" is set. SECTION VISIBILITY EXAMPLE <component-rule> <requirement comparison="equals"> <first> <component id="script-chooser" /> </first> <second>Write New</second> </requirement> <response> <component id="scriptsection"> <display>true</display> </component> </response> </component-rule> "scriptsection" is only visible if the value of the "script-chooser" component is true. Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Validating and invalidating components on page 146 6.1.18.2 Getting component rule responses dynamically Viewpoint can make a remote procedure call (RPC) that executes a script on the Web server to determine a component's response. In such a case, when the component rule is evaluated to true, the script specified in the XML configuration executes. Upon completion, that script returns XML describing another type of component response, which then runs on the client. This makes it possible to perform more complex operations to change the user interface state dynamically. 144 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms To get a component rule's response dynamically 1. When setting rules for a component (see Setting component rules on page 142), insert the <response> element inside of the <component-rule> element. 2. Set the source attribute to either "file" or "exec". Attribute Description "file" Viewpoint reads the contents of the file and attempts to parse it to any other component response. The file's contents should be in XML format, as defined in all other component response options. "exec" Viewpoint executes the file on the Web server and parses the STDOUT of the file into one of the component response options. 3. If the source of the dynamic component response is a script (source="exec"), specify required input parameters using the <input> element. 4. Set one or more <component id="X"> elements, configuring id to correspond to the component required. <component-rule> <requirement> <component id="enable-firewall-checkbox" /> </requirement> <response source="exec"> <url value="file:///home/user/tools/getFirewallOptions.py" /> <input> <component id="ip-address" /> </input> </response> </component-rule> The getFirewallOptions.py script requires the value of the "ip address" component. When the user clicks the appropriate checkbox, the script is called in the following manner (assuming the ip address is 192.168.99.120): /home/user/tools/getFirewallOptions.py xml='<components> <component id="ip-address"> <value>192.168.99.120"</value> </component> </components> The script returns XML respresenting a component response like the following: <response> <component id="LAN-options"> <display>true</display> </component> <component id="WAN-options"> <display>false</display> </component> </response> 6.1 Configuring the <components> element 145 Chapter 6: Creating or configuring forms Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Changing a component/section's visibility on page 143 l Validating and invalidating components on page 146 6.1.18.3 Validating and invalidating components Through component responses, individual components may become valid or invalid by using the <validate> element. When a component is invalidated through a component response, only another component response may re-validate the component. To validate and invalidate a component 1. When setting rules for a component, insert the <invalidate-components> element within the <response> section of the <component-rule> element. l Optional: If you want to restrict the user from proceeding until the component is re-validated, set the strict attribute to "true". <response> <invalidate-components strict="true"> <message>These are not valid values</message> <component id="ip-address" /> <component id="firewall" /> </invalidate-components> </response> If the rule is met, the "ip-address" and "firewall" components are invalidated, and the user is shown the message "These are not valid values" and is prevented from proceeding. 2. Create a rule (See Setting component rules on page 142). Set the <validate-components> element within the rule's <response> to re-validate the component(s). l Optional: If you want to restrict the user from proceeding unless the components are validated, set the strict attribute to "true". <response> <validate-components strict="true"> <component id="ip-address" /> <component id="firewall" /> </validate-components> </response> If the rule is met, the "ip-address" and "firewall" components are re-validated, and the user is allowed to proceed. Because component rules can be dynamic, meaning they can be returned from the server, you may prefer to use them as opposed to existing validation framework. For example, you could have an external script verify that a username is valid, possibly invalidating the username component. 146 6.1 Configuring the <components> element Chapter 6: Creating or configuring forms Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Getting component rule responses dynamically on page 144 l Changing a component/section's visibility on page 143 l Setting permissions on page 51 6.2 Configuring the <pages> element The <pages> element allows you to define the layout of the user interface. The layout can be either static or dynamic. To configure the pages element 1. Open the configurable XML file corresponding to the form you want to edit. These are usually located in the Viewpoint home directory. Find the <pages> element. 2. To create a page, add a child <page> element within <pages> and give it a unique id. <pages> ... <page id="page01"> ... </page> ... </pages> 3. Verify that at least one configured page has the first attribute set to "true". <page id="page01" first="true"> 4. Locate the <sections> element, which contains a list of sections to display on the page, and configure it according to your needs (for more information, see Configuring the <sections> element on page 149). 5. Configure the <navigation> element within a page to specify either a dynamic page layout or a static page layout. 6. If you are using multiple pages in a dynamic layout, specify which page(s) to load next by adding more <page> elements. 7. Configure the <description> element within a page to describe it (for more information, see Configuring the <description> element on page 148). 8. Configure the <validation> element within the <page>. This will determine if the values on the page are valid before submission. 9. Set permissions for pages for which you wish to restrict visibility. To do so, add the permission attribute to the <page> element and set the value to what permission is needed. If the user does not have the specified permission, the page is not displayed. 6.2 Configuring the <pages> element 147 Chapter 6: Creating or configuring forms <pages ui-type="dynamic"> <page id="page01" first="true"></page> <page id="page02"></page> <page id="page03" permission="advancevpc"></page> </pages> "page03" is viewable only by users with the "advancedvpc" permission. This section contains these topics: l Configuring the <description> element on page 148 l Configuring the <sections> element on page 149 l Configuring a static page layout on page 150 l Configuring a dynamic page layout on page 154 6.2.1 Configuring the <description> element Use the optional <description> element to describe the page. The description is not displayed to the user. To configure the description element 1. Open the desired xml file located in the Viewpoint home directory. Locate the <pages> element and then the desired <page>. 2. Set the optional <description> element to describe the page for administrator reference. Users will be unable to view the description. <pages> <page id="page1" first="true"> <description>First page. Shows the environment options.</description> ... </page> <page id="page2"></page> <page id="page3"></page> </pages> Related topics 148 l Configuring the <pages> element on page 147 l Configuring the <sections> element on page 149 l Configuring a static page layout on page 150 l Configuring a dynamic page layout on page 154 l Configuring validation in static forms on page 153 l Configuring validation in dynamic forms on page 156 l Creating or configuring forms on page 117 6.2 Configuring the <pages> element Chapter 6: Creating or configuring forms 6.2.2 Configuring the <sections> element Every page must have a <sections> element. The <sections> element has one or more child <section> elements. Each section contains a description visible to the user and an ordered list of components that are defined in the <components> element. To configure the sections element 1. Open the desired xml file located in the Viewpoint home directory. Locate the <sections> element. 2. Place at least one <section> within it. Give the section a unique id and set a permission if desired. <section id="section1" permission="advancedvpc"> The "section1" section is viewable only by users with the "advancedvpc" permission. 3. Use the <description> child element to specify the section title displayed to the user in the Viewpoint interface. 4. Set at least one <component> element per section to designate options for the user. Specify a unique id for each component. <page> <sections> <section id="s1" permission="advancedvpc"> <description>Environment Options</description> <component id="starttime" order="1" /> <component id="duration" order="2" /> <component id="securityZone" order="3" permission="advanced-user-2" /> </section> </sections> </page> 5. Set any desired optional attributes of <component> to meet your needs. l l l l Set description to give a label to the component in the interface. Any string is a valid description. Set required to specify whether the component must enter data into this field to pass page validation. The default is "false". Set editable to specify whether the user can edit the component. The default is "true". Set permission to specify which permissions are required to view the component. This is supported by all components in Viewpoint 1.1 and later. See Setting permissions on page 51. 6. Optional: Set the child element <help-text> to specify the text to appear immediately beneath the component. This is only valid in Viewpoint 2.0 and later. <component id="class" required="false"> <description>Class</description> <help-text>This is the help text</help-text> <text-value /> </component> 6.2 Configuring the <pages> element 149 Chapter 6: Creating or configuring forms HTML tags are accepted within the help-text tag, but must be wrapped in a CDATA tag, as in the example below: <component id="class" required="false"> <description>Class</description> <help-text> <![CDATA[Desired <a href="http://www.desired-web-page.com">Web Page</a>]]> </help-text> <text-value /> </component> Related topics l Configuring the <pages> element on page 147 l Configuring the <description> element on page 148 l Configuring a static page layout on page 150 l Configuring a dynamic page layout on page 154 l Configuring validation in static forms on page 153 l Configuring validation in dynamic forms on page 156 l Creating or configuring forms on page 117 6.2.3 Configuring a static page layout A static layout is recommended for more advanced users or users that may only need to change a few components when submitting the form. In this layout, the user is presented with all pages at the same time. Users are shown the list of pages on the left side (the context area) and can skip to any page at any time. To configure a static page layout 1. Open the desired xml file located in the Viewpoint home directory. Locate the <pages> element. 2. Set the ui-type attribute to "static". <pages ui-type="static"> 3. Set the hide-context attribute to "true" to hide navigation on the left side of the form that shows currently-selected tab. <pages ui-type="static" hide-context="true"> 150 6.2 Configuring the <pages> element Chapter 6: Creating or configuring forms Example 6-1: Submit job form without hide-context="true" 6.2 Configuring the <pages> element 151 Chapter 6: Creating or configuring forms Example 6-2: Submit job form with hide-context="true" The navigational tags on the left side of the page disappear, and the user navigates the form using the links on the bottom of each page. 4. If you wish to verify that the inputs on the page are valid before form submission, set the <validation> element as a child of <components> (for more information, see Configuring validation in static forms on page 153). A static layout is recommended for more advanced users or users that may only need to change a few components when submitting the form. It allows users to see the list of pages on the left side and skip to any page at any time. Related topics 152 l Configuring the <pages> element on page 147 l Configuring the <components> element on page 118 l Configuring the <description> element on page 148 l Configuring the <sections> element on page 149 l Configuring a dynamic page layout on page 154 l Configuring validation in static forms on page 153 6.2 Configuring the <pages> element Chapter 6: Creating or configuring forms l Configuring validation in dynamic forms on page 156 l Creating or configuring forms on page 117 6.2.3.1 Configuring validation in static forms With the <validation> element, you can set rules to check if the inputs on a page are valid. A user cannot proceed to the next page until inputs are valid values. After the user tries to proceed to the next page, the validation is checked and the response is fired. Once this occurs the validation is continuously checked on the page. As soon as the user enters a valid value, the warning messages go away and the Next button is reenabled. This differs from the individual component validation which is constantly being checked as soon as the user starts entering data. To configure validation in static forms 1. Open the desired xml file located in the Viewpoint home directory. Locate the <pages> element. 2. Set <validation> as a child of <component>. 3. Insert <requirement> within <validation> to define the conditions of the field(s). 4. Place the <response> element inside of <validation> to describe the behavior of the Viewpoint interface when <requirement> evaluates to false. It specifies which components will be invalidated. 5. Insert the <message> element within <response> and create a warning message for the user. 6. Insert any of the invalidated <component> elements you would like included with the message. <validation> <requirement logical-operation="and"> <rule comparison="lessthan"> <first> <variable binary-operation="add"> <first> <component id="linuxVMCount" /> </first> <second> <component id="windowsVMCount" /> </second> </variable> </first> <second> <value>10</value> </second> </rule> </requirement> <response> <message>You cannot create more than a total of 10 VMs</message> <component id="linuxVMCount" /> <component id="windowsVMCount" /> </response> </validation> Users are prevented from creating more than ten reservations of any type. 6.2 Configuring the <pages> element 153 Chapter 6: Creating or configuring forms Related topics l Configuring validation in dynamic forms on page 156 l Configuring the <pages> element on page 147 l Configuring the <description> element on page 148 l Configuring the <sections> element on page 149 l Configuring a static page layout on page 150 l Configuring a dynamic page layout on page 154 l Creating or configuring forms on page 117 6.2.4 Configuring a dynamic page layout A dynamic layout is useful when dealing with complex tasks or when it is helpful to guide users through an unfamiliar process. With a dynamic layout, it is possible to use navigation branching, which means what appears on, and the ability to proceed to, the next page depends on input to previous pages and the values in the current page. To configure a dynamic page layout 1. Open the desired xml file located in the Viewpoint home directory. Locate the <pages> element. 2. Set the ui-type attribute to "dynamic". <pages ui-type="dynamic"> 3. Verify that each <page> element has a unique id. <page id="myPage"> 4. Specify which page comes first in the sequence by setting the attribute first="true". <page id="myPage" first="true"> 5. If the interface contains more than one page, insert the <navigation> element within <page>. <navigation> is only valid for dynamic layouts. Specify which page comes next in the sequence by adding the <next-page> child element to <navigation> . Set the set-next attribute to the ID of the next page. <pages ui-type="dynamic"> <page id="page1" first="true"> <description>First page. Shows the environment options.</description> <navigation> <next-page set-next="page2" /> </navigation> ... </page> <page id="page2">...</page> 154 6.2 Configuring the <pages> element Chapter 6: Creating or configuring forms <page id="page3">...</page> </pages> When the user clicks Next, the flow goes from "page1" to "page2". 6. (Optional) If you wish to verify that the inputs on the page are valid, set the <validation> element as a child of each <page> element (for more information, see Configuring validation in dynamic forms on page 156). The <validation> element is configured differently for static and dynamic layouts. See Configuring a static page layout on page 150. 7. (Optional) Set up conditional branching by inserting the <rule> child element within <next-page>. The rule is a Boolean value decider that, if evaluated to true, directs users to the specified page. See Setting a Boolean decider on page 170. If no rule is specified, the default next page is what is specified by the set-next attribute. If there are multiple <next-page> elements with rules, the user is directed to the first one that is evaluated to true. <page id="firstPage"> <description>First Page asks if they are new or not</description> <sections>...</sections> <navigation> <next-page set-next="newUserPage"> <rule comparison="equals"> <first> <component id="newOrExistingUser" /> </first> <second> <value>New user</value> </second> </rule> </next-page> <next-page set-next="existingUserPage" /> <next-page set-next="newUserPage" /> </navigation> </page> The component asks if the user has an account or if the user is new. If the user selects the 'New user' value for the "newOrExistingUser" component, they are directed to the "newUserPage". If the user indicates that they have an existing account, the requirement operation evaluates to false and the following <next-page> element ("existingUserPage") is evaluated to true. The default value is "newUserPage" and is placed only as a safeguard to verify the next page is specified. Related topics l Configuring the <pages> element on page 147 l Configuring the <description> element on page 148 l Configuring the <sections> element on page 149 l Configuring a static page layout on page 150 6.2 Configuring the <pages> element 155 Chapter 6: Creating or configuring forms l Configuring validation in static forms on page 153 l Configuring validation in dynamic forms on page 156 l Creating or configuring forms on page 117 6.2.4.1 Configuring validation in dynamic forms With the <validation> element, you can set rules to check if the inputs on a page are valid. A user cannot proceed to the next page until inputs are valid values. After the user tries to proceed to the next page, the validation is checked and the response is fired. Once this occurs the validation is continuously checked on the page. As soon as the user enters a valid value, the warning messages go away and the Next button is reenabled. This differs from the individual component validation which is constantly being checked as soon as the user starts entering data. To configure validation in dynamic forms 1. Open the desired xml file located in the Viewpoint home directory. Find the <pages> element. 2. Choose a <page> to validate. Set <validation> as a child of the corresponding <page> element. 3. Insert <requirement>within <validation> to specify the conditions of the field(s). See Setting component rules on page 142. 4. Place <response> inside of <validation> to describe the behavior of the Viewpoint interface when <requirement> evaluates to false. It defines which components to invalidate. a. Insert the <message> element within <response> to create a warning message for the user. b. Insert any <component> elements that are invalidated to be included with the message. <validation> <requirement logical-operation="and"> <rule comparison="lessthan"> <first> <variable binary-operation="add"> <first> <component id="linuxVMCount" /> </first> <second> <component id="windowsVMCount" /> </second> </variable> </first> <second> <value>10</value> </second> </rule> </requirement> <response> <message>You cannot create more than a total of 10 VMs</message> <component id="linuxVMCount" /> <component id="windowsVMCount" /> 156 6.2 Configuring the <pages> element Chapter 6: Creating or configuring forms </response> </validation> Users are prevented from creating more than ten reservations of any type. Related topics l Configuring validation in static forms on page 153 l Configuring the <pages> element on page 147 l Configuring the <description> element on page 148 l Configuring the <sections> element on page 149 l Configuring a static page layout on page 150 l Configuring a dynamic page layout on page 154 l Creating or configuring forms on page 117 6.3 Configuring the <queue> element Many forms may have a queue, or a client-side request queue to store unsubmitted data. For example with Create VPC, the request queue would contain a collection of reservations the user wishes to create. For submit job, the queue may contain a collection of jobs that will be submitted upon page submission. The queue element defines what data is stored in the queue and the interface for the request queue, which is the list of items generated when a user clicks Add To Request. The following image is an example of how the queue might look in the create VPC page if the user wants two reservations in their desired VPC: To configure the queue element 1. Open the configurable XML file corresponding to the form you want to edit, usually located in the Viewpoint home directory. Locate the <queue> element. 2. Add the name attribute to specify the text displayed at the top of the queue. 6.3 Configuring the <queue> element 157 Chapter 6: Creating or configuring forms The preceding example was configured with the following XML as the top line: <queue name="Your Current Request"> 3. Specify what queue data is stored. See Defining what data is stored in the queue on page 158. 4. Define the queue interface. See Defining the queue interface on page 160. 5. Define what data is required. See Specifying which queue data is required on page 161. Related topics l Creating or configuring forms on page 117 l Configuring the <pages> element on page 147 l Configuring the <components> element on page 118 6.3.1 Defining what data is stored in the queue The parent <queue> element contains one or more child <queue-item> elements. For most requests, there will only be one queue item definition. However, if you want to support heterogeneous queue items, you may specify more than one item. To define what data is stored in the queue 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <queue> element. Modify the name if desired. 2. Add the <queueItem> element inside of <queue>. 3. Set the <condition> element within <queueItem> to specify that Viewpoint should determine whether the queue item should be added. a. Set <condition> to any boolean value decider. <queue name="Your Current VPC Request"> <queueItem> <condition comparison="equals"> <first> <component id = "vmtype" /> </first> <second>local</second> </condition> <title required="false"> <description>Description</description> <component id="sysdescription" /> </title> <row order="1" required="true"> <description>Procs:</description> <component id="procs" /> </row> 158 6.3 Configuring the <queue> element Chapter 6: Creating or configuring forms <!-- ... --> <requirement-data id="rsvRequirement"> <component id="sysdescription" /> <component id="vmtype" /> <component id="procs" /> </requirement-data> </queueItem> <queueItem> <condition comparison="equals"> <first> <component id = "vmtype" /> </first> <second>ec2</second> </condition> <title required="false"> <description>Description</description> <component id="sysdescription" /> </title> <row order="1" required="true"> <description>Type:</description> <component id="ami" /> </row> <row order="2" required="true"> <description>key:</description> <component id="key_name" /> </row> <requirement-data id="EC2Requirement"> <component id="sysdescription" /> <component id="vmtype" /> <component id="ami" /> <component id="key_name" /> </requirement-data> </queueItem> </queue> Each time the user clicks Finish or Add to Queue, each queue item is evaluated to determine whether the item should be added to the list. The item is not added if either the condition evaluates to false or there is no data that is saved in the queue item. Related topics l Configuring the <queue> element on page 157 l Setting a Boolean decider on page 170 l Creating or configuring forms on page 117 l Defining the queue interface on page 160 l Configuring the <pages> element on page 147 l Configuring the <components> element on page 118 6.3 Configuring the <queue> element 159 Chapter 6: Creating or configuring forms 6.3.2 Defining the queue interface You can configure the way a queue item is displayed to the user. To define the queue interface 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <queue> element. Modify the name if desired. 2. Locate the <title> element and set the <description> text to whatever explanatory text you would like displayed before the value. Ensure that the title contains the desired component. The <title> element is optional. 3. Modify the <row> element. a. Set the order attribute to the number order which the indicated line should be displayed on the page. For example, to place a row at the top, set order to "1". b. Set the required attribute to either true or false, depending on whether the row should display even if the value is empty or zero. 4. Make a row dynamic so that the exact number of rows is dependent on the components in the form. a. Set the type attribute of <row> to "dynamic". b. Set the source attribute of <row> to any component that contains a list of values. For example, you might use a list edit component. <row order="2" type="dynamic" source="storage-list"> <description>Storage:</description> <component id="storage-list" /> </row> The second row in the queue item creates however many items are in the "storage-list" component. 160 6.3 Configuring the <queue> element Chapter 6: Creating or configuring forms 5. Modify the CSS to customize the view for individual components. a. Open the utility-hosting.css file. b. Modify the CSS styles according to the following: l l l l Modify the ace-DynamicQueueItem-titleDescription style to customize the style of the title's description, assuming the description is not empty. Modify the ace-DynamicQueueItem-titleValue to customize the style of the title's value, assuming the value is not empty. Modify the ace-DynamicQueueItem-rowDescription to customize the style of the row's description, assuming the description is not empty. Modify the ace-DynamicQueueItem-rowValue to customize the style of the row's value, assuming the value is not empty. Related topics l Creating or configuring forms on page 117 l Configuring the <queue> element on page 157 l Specifying which queue data is required on page 161 l Configuring the <pages> element on page 147 l Configuring the <components> element on page 118 6.3.3 Specifying which queue data is required For forms where there may be multiple requirements (such as the Create VPC page), you may specify what data gets saved for which requirements. A single queue item may contain data about one or more requirements. The stored data is later passed to Moab. For details about the requirement specifications, see the administrator configuration for the page you are configuring. Typically, all components dealing with an individual queue item should be stored as part of the queue item's requirement data; such individual queue item components might include processor count, amount of memory, and so forth. Components that are global to the entire request (like the start time and the duration for the Create VPC page), do not need to be stored in the <requirement-data> element. To specify which queue data to store 1. Open the appropriate XML file located in the Viewpoint home directory. Locate the <queue> element. 2. Set the <requirement-data> element within <queue-item> to define the data that is stored from each component each time a user adds a new item to the request queue. 3. Insert the <component> element for each component to require. Set the id attribute to the exact name of the component to include. <queue name="Your Current VPC Request"> ... <requirement-data id="rsvRequirement"> <component id="os" /> 6.3 Configuring the <queue> element 161 Chapter 6: Creating or configuring forms <component id="procs" /> <component id="memory" /> <component id="disk" /> </requirement-data> ... </queue> The operating system, number of processors, RAM, and disk space are stored then passed to Moab through the mshow -a command, configured using the <request> element. See the Moab Workload Manager Administrator Guide for more information about the mshow -a command. Related topics l Configuring the <queue> element on page 157 l Creating or configuring forms on page 117 l Defining the queue interface on page 160 l Configuring the <pages> element on page 147 l Configuring the <components> element on page 118 6.4 Adding a date decider Specifying a relative date is very similar to specifying a duration decider. However, a duration has no meaning until it is applied to a date. For example, a duration of one month differs depending on if it is currently February or March. A relative date is always applied to the current time at run time. To add a date decider 1. Open the .xml file where a date decider (rather than a concrete date) is allowed. These files are usually located in the Viewpoint home directory. 2. Set a date component inside the parent element. <component id="nameOfDatebox" /> 3. Determine whether the date should be absolute or relative, or evaluated by Viewpoint in relation to the current date. To configure an absolute date, set the relative attribute to "false". To configure a relative date, set the relative attribute to "true". 4. Set the following date child elements to specify an absolute date or a date relative to the current date, depending on which option you chose in the previous step. 162 l <years> l <months> l <days> l <hours> l <minutes> l <seconds> 6.4 Adding a date decider Chapter 6: Creating or configuring forms The children in each element must be an integer decider. Any value not set is assumed to be 0. Values specified above the theoretical maximum are converted (25 hours corresponds to +1 day and 1 hour). 5. Specify the <calculate> element if you’d like to add a duration to a date. Set the binary-operation attribute to "add". l l Set the <first> child element and add a duration value decider using any or all of the tags listed in step 4. Set the <second> child element to any date decider. <calculate binary-operation="add"> <first> <months>1</months> </first> <second> <component id="starttime" /> </second> </calculate> Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Validating and invalidating components on page 146 l Creating or configuring forms on page 117 6.5 Adding a duration decider Specifying a duration decider is very similar to specifying a relative date. However, a duration has no meaning until it is applied to a date. For example, a duration of one month differs depending on if it is currently February or March. A relative date is always applied to the current time at run time. To add a duration decider 1. Open the .xml file where a duration decider (rather than a concrete duration) is allowed. These files are located in the Viewpoint home directory. 2. Set a duration component inside the parent element. <component id="nameOfDurationTextbox" /> 6.5 Adding a duration decider 163 Chapter 6: Creating or configuring forms 3. Set a duration by specifying an integer value for the following child elements: l <years> l <months> l <days> l <hours> l <minutes> l <seconds> Any value not set is assumed to be 0. 4. Configure the binary calculation by setting the <calculate> element’s binary-operation attribute. l Set the value to "between-dates" to specify the duration between date deciders. 1. Define the <first> child element, which can be a decider itself. 2. Define the <second> child element, which can be a decider itself. l Set the value to "shortest" to set two duration deciders and have Viewpoint choose the shortest duration. <calculate binary-operation="shortest"> <first> <months> <component id="duration" /> </months> </first> <second> <calculate binary-operation="between-dates"> <first> <component id="starttime" /> </first> <second relative="false"> <years>2010</years> <months>8</months> </second> </calculate> </second> </calculate> The user inputs an integer for duration and a date for "starttime". The duration is compared to the duration from the "starttime" component to September 1st. The chosen duration is the one that is shortest. Related topics 164 l Creating or configuring forms on page 117 l Setting component rules on page 142 6.5 Adding a duration decider Chapter 6: Creating or configuring forms l Validating and invalidating components on page 146 l Configuring the <components> element on page 118 6.6 Adding an integer decider Whenever the XML allows an integer decider (instead of a concrete integer), these are the valid options: l A binary operation calculation l Other operations l A concrete integer To add an integer decider 1. Locate the UI component that holds an integer (such as a number spinner). Determine which operation to use. 2. Configure a binary operation. a. Set the <calculate> element with the binary-operation attribute set to the operation to be performed ("add" or "multiply"). b. Set the <first> and <second> elements to components, integers, etc. These themselves could be deciders. <calculate binary-operation="add"> <first> <component id="disk" /> </first> <second>60</second> </calculate> 60 is added to the "disk" component. If the binary-operation were "multiply", the result would be the product of 60 and "disk". 3. Configure other operations. a. Set the <calculate> element with the operation attribute set to "string-to-int". b. Set a child string decider for Viewpoint to evaluate and parse into an integer. See Adding a string decider on page 166. Related topics l Configuring the <components> element on page 118 l Setting component rules on page 142 l Validating and invalidating components on page 146 l Creating or configuring forms on page 117 6.6 Adding an integer decider 165 Chapter 6: Creating or configuring forms 6.7 Adding a string decider Whenever the XML allows a string decider (instead of a concrete string), these are the valid options: l l l A binary operation using the binary-operation attribute. Specify this attribute inside a <calculate> element. Other supported operations (that are not binary) using the operation attribute. Specify this attribute inside a <calculate> element. A concrete string value consisting of any text inside the parent element. To add a string decider 1. Locate the UI component that holds a string (such as a text box or select box). Determine which operation to use. 2. Configure a binary operation. a. Set the <calculate> element with the binary-operation attribute set to "substring". b. Set the <first> element to a string decider and the <second> element to an integer. <calculate binary-operation="substring"> <first> <component id="payment-value" /> </first> <second>3</second> </calculate> 3. Configure another operation. a. Set the <calculate> element with the binary-operation attribute set to one of the following: l l "int-to-string" – Evaluates the integer and takes the string value. Requires a child integer decider. "double-to-string" – Evaluates a double decider and takes the string value. It requires a double decider. Optionally, you can use the precision attribute to specify how many decimal places to use in the result. b. (Optional) Use any of the following keywords to get specific strings: l "empty-string" – Returns an empty string l "space" – Returns a space Related topics 166 l Configuring the <components> element on page 118 l Setting component rules on page 142 l Validating and invalidating components on page 146 l Creating or configuring forms on page 117 6.7 Adding a string decider Chapter 6: Creating or configuring forms 6.7.1 Listing string deciders Whenever the XML allows users to specify a list strings decider (instead of a concrete list), the following are valid inputs: l A comma-separated list of values. Viewpoint parses the comma-separated string to a list of values. l A calculate element to convert a string to a list. A string to list decider takes a single string and parses the string into a list of strings using a delimiter. To add a string to a list decider 1. Locate the UI component that holds a string (such as a text box or select box). 2. Set the <calculate operation="string-to-list"> tag. Insert one child element, which is any string value decider (such as a component or another <calculate> element). 3. (Optional) Set the delimiter attribute to specify how the list is delimited. If a delimiter is not specified, Viewpoint uses a comma to tokenize the string. <calculate operation="string-to-list" delimiter=","> <component id="hostListTextbox" /> </calculate> The "hostListTextbox" component contains a comma-separated list of values that will be converted to a list. This allows you to pass a string into components that accept lists for their input. Related topics l Adding a string decider on page 166 l Configuring the <components> element on page 118 l Setting component rules on page 142 l Validating and invalidating components on page 146 l Creating or configuring forms on page 117 6.7.2 Appending strings You can pull the value of a component to be displayed within a page's text. To append strings 1. Locate the UI component that holds a string (such as a text box or select box). 2. Set the <calculate> element with the operation attribute set to "append-in-order". 3. Set at least two children string deciders and the component which contains the value that will be displayed. a. Specify the order of the strings and the component's information by setting <value>'s order attribute. The value should correspond with the phrase's placement in the text. 6.7 Adding a string decider 167 Chapter 6: Creating or configuring forms <calculate operation="append-in-order"> <value order="1">Add a new reservation with</value> <value order="2"> <component id="procs" /> </value> <value order="3"> Processor(s)</value> </calculate> The page containing this example displays the text "Add a new reservation with <number of procs> Processor(s)" Related topics l Adding a string decider on page 166 l Configuring the <components> element on page 118 l Setting component rules on page 142 l Validating and invalidating components on page 146 l Creating or configuring forms on page 117 6.7.3 Using conditional items in strings To use conditional items in strings 1. Locate the UI component to hold the conditional decider. 2. Set the <conditional> element. 3. Set the <if> element to a Boolean decider to be evaluated first. 4. Insert the <then> element within <if>. It is the value of the evaluation condition if the if decider evaluates to true. 5. (Optional) Set the <else-if> element to a Boolean decider. If set, specify another <then> element as the value of the evaluated condition if the previous conditions evaluated to false. There may be zero or more <else-if> statements. 6. (Recommended) Set the <else> element to the value of the conditional if the other <if> and <else-if> statements evaluated to false. Although optional, it is always recommended to include the <else> element to verify that the decider always returns a value. <conditional> <if comparison="equal"> <first> <component id="script-chooser" /> </first> <second>Upload</second> <then> <component id="upload-script" type="upload" /> </then> </if> <else-if comparison="equal"> 168 6.7 Adding a string decider Chapter 6: Creating or configuring forms <first> <component id="script-chooser" /> </first> <second>NONE</second> <then>NO_VALUE</then> </else-if> <else> <component id="write-script" type="upload" /> </else> </conditional> In the preceding example, if the "script-chooser" component was "upload", then the value is the value of the "upload-script" component. Else if the "script-chooser" component was "NONE", then the value would be "NO_VALUE". If neither of these conditions are true, then the value would be the value of the "write-script" component. Related topics l Adding a string decider on page 166 l Configuring the <components> element on page 118 l Setting component rules on page 142 l Validating and invalidating components on page 146 l Creating or configuring forms on page 117 6.7.4 Replacing strings The string replace decider is where the decider replaces all instances of the first string with the second string. To replace a string 1. Locate the UI component to hold replace string decider. 2. Set the <calculate> element with the operation attribute set to "string-replace". 3. Set the <regex> child element within <calculate> to a regular expression to be matched. 4. Set the <replacement> child element within <calculate> to the string that replaces the matched expression. 5. Set the <value> child element within <calculate> to the original string that is evaluated. The regular expression checks this string. <calculate operation="string-replace"> <regex>\.</regex> <replacement>_</replacement> <value>Name.Of.File</value> </calculate> 6.7 Adding a string decider 169 Chapter 6: Creating or configuring forms Related topics l Adding a string decider on page 166 l Configuring the <components> element on page 118 l Setting component rules on page 142 l Validating and invalidating components on page 146 l Creating or configuring forms on page 117 6.8 Setting a Boolean decider Whenever the XML allows a Boolean decider (instead of a concrete Boolean), these are the valid options: l A comparison operation between two values l A logical operation (OR or AND) l A concrete boolean value (either true or false) inside the parent element To set a Boolean comparison operation to compare dates or strings 1. Locate the UI component to hold the comparison operation. 2. Set the <requirement> element with the comparison attribute set to one of the following: Option Description "equal" Evaluates to true only if the first and second values are equal "lessthan" Evaluates to true only if the first is less than the second "greaterthan" Evaluates to true only if the first is greater than the second "not" Evaluates to true only if the first is NOT equal to the second 3. Specify whether this is a string or a date by setting the type attribute of <comparison> to either "string" or "date". Not setting type causes Viewpoint to assume "string". 4. Set the <first> and <second> elements within <requirement> to the values to be compared. These can be deciders themselves. l If the type is set to "string", the values should be string deciders. l If the type is set to "date", the values should be date deciders. <requirement comparison="equals"> <first> <component id="procs" /> </first> 170 6.8 Setting a Boolean decider Chapter 6: Creating or configuring forms <second>1</second> </requirement> The requirement evaluates to true if the value in the "procs" component is equal to 1. To set a boolean decider to perform a logical operation 1. Locate the UI component to hold the comparison operation. 2. Set the <requirement> element with the logical-operation attribute set to one of the following: l l "or" – Performs a logical OR operation. If any child element evaluates to true, the operation evaluates to true. "and" – Performs a logical AND operation. If all child elements evaluate to true, the operation evaluates to true. <requirement logical-operation="or"> <value> <component id="test_vlan" /> </value> <value> <component id="dev_vlan" /> </value> </requirement> The requirement is evaluated to true if either the "test_vlan" or "dev_vlan" components are true. Related topics l Creating or configuring forms on page 117 6.8 Setting a Boolean decider 171 Chapter 7: Configuring reports This chapter contains information about how to configure reporting in Viewpoint. It describes how to set up a connection to the Moab database and how to add user permissions to individual reports. This chapter includes these sections: l Connecting Viewpoint reporting to the Moab database on page 173 l Specifying available reports on page 174 l Adding permissions to individual reports on page 176 l Configuring Viewpoint to run the Events report on page 177 l Querying major events from the Moab event log on page 178 7.1 Connecting Viewpoint reporting to the Moab database To connect Viewpoint reporting to the Moab database 1. Open the reporting.xml file, located in the Viewpoint home directory. 2. Configure the MySQL database connection in Moab by modifying the <database-connection> element in the reporting.xml file. a. Set the <url> to the JDBC database connection URL to either your own database or Moab's ODBC database. b. Set the <username> and <password> elements to the username and password to the Moab ODBC database. c. Set <driver> to the MySQL JDBC driver that you’re using. Place the driver in the Viewpoint application WEB-INF/lib directory. <database-connection type="mysql-jdbc"> <url>jdbc:mysql://localhost/Moab</url> <username>root</username> <password>root</password> <driver>com.mysql.jdbc.Driver</driver> </database-connection> Related topics l Specifying available reports on page 174 l Adding permissions to individual reports on page 176 7.1 Connecting Viewpoint reporting to the Moab database 173 Chapter 7: Configuring reports l Configuring Viewpoint to run the Events report on page 177 l Configuring Viewpoint to communicate with your DBMS on page 29 l Configuring reports on page 173 7.2 Specifying available reports You can specify whether a user can generate reports. On the Reporting page, users choose from a list of available options, which report(s) to run. 1. Open the reporting.xml file located in the Viewpoint home directory. 2. Comment out any reports you do not want available using the <!-- and --> tags. Reports that are available by default to all users with the report.read permission are the following: 174 Report Description Events A report showing historical event information in the form of a table, pie chart, or bar chart Job and Processor Hours by Credential A list report of processor hours and jobs by credential. The data is displayed in table format by year, then by month. Job and Processor Hours by Month A bar chart of the chosen year with total processor hours and jobs for each month Jobs and Processor Hours by Quarter and Year Bar Chart A bar chart of totals for jobs and processor hours by quarter and year Jobs Submitted A report presenting the jobs submitted by credentials (user, group, account, and quality of service) for the supplied time in table format with name and total of jobs Jobs Submitted and Completed Line Chart A line chart showing number of jobs over the specified time and for the specified credential with the option of showing completed jobs Total Active Processor Count Line chart showing the number of active processors over the specified credential and credential name Total Allocated Node Count Displays the number of total allocated nodes over time in a line chart for the given start and end time by credential and credential name 7.2 Specifying available reports Chapter 7: Configuring reports Report Description Total Queue Time A table and pie chart view of queue hours over the specified time and for the specified credential Used Wallclock Time A table and pie chart view of used wallclock hour for the specified time and for the specified credential 3. Give reports individual permissions so that only certain users may access them (for details, see Adding permissions to individual reports on page 176). 4. Once the permission is created, add it to the users’ permissions for them to view it. To do so: a. Open the core.xml file in the Viewpoint home directory and scroll to the <definition name="role-name"> that will receive the permission. b. Insert the new permission name within that element. To grant a group access to all reports within a certain category, insert an asterisk rather than the report name: <permission name="report.jobs.*" /> Similarly, to give permission to all reports, grant the following role: <permission name="report.*" /> 5. Create a custom category. To do so, create a directory for each category to hold its corresponding reports. For example, you could create the jobs directory to place all the job-related reports, such as Jobs Submitted. This will be located in the Tomcat webapps/reporting/report directory. a. Change the <category> element to the directory name so that Viewpoint can locate it. b. Modify the <display-category> to update the display name for the category. As an example, see this configuration for the Jobs Submitted report: <reports> <report> <display-name>Jobs Submitted</display-name> <report-design>jobs_submitted.rptdesign</report-design> <display-category>Jobs</display-category> <category>jobs</category> <description>Presents the Jobs submitted by credential (user, group, account and quality of service) for the supplied time in table format with name and total of jobs</description> <permission name="report.jobs.jobs_submitted" /> </report> </reports> Viewpoint looks in the jobs directory to locate the report. A user with the report.job.jobs_submitted permission may view the report on the Reporting page. The Reporting page will show that the report is in the Jobs category. 7.2 Specifying available reports 175 Chapter 7: Configuring reports 6. Change the report name that users will see by modifying the <display-name> element within <report>. 7. Change the viewable report category on the Viewpoint Reporting page by modifying the text in the <display-category> element. 8. Alter the description of the report viewable in the Viewpoint Reporting page by modifying the text in the <description> element. Related topics l Configuring reports on page 173 7.3 Adding permissions to individual reports To add permission to view individual reports to the users' permissions 1. Open the reporting.xml file located in the Viewpoint home directory. 2. Give reports a unique permission. a. Locate the <report> element of the report that will require the permission. Insert the <permission> element and give it a name. It is recommended that you name permissions in the following way: <permission name="report.[category].[report_name]" /> The category should correspond with the directory where the report exists. By default, all reports are displayed in the Adaptive category and located in the adaptive directory. 3. Add the permission to the users' permissions. a. Open the core.xml file located in the Viewpoint home directory and scroll to the <definition name="role-name"/> that will receive the permission. b. Insert the new permission within the element. To grant a group access to all reports within a certain category, insert an asterisk rather than the report name: <permission name="report.jobs.*" /> Similarly, to grant permission to access all reports, grant the role the following permission: <permission name="report.*" /> 4. Create a directory to hold reports if you specified a custom category. The directory name must correspond with the category name. For example, you could create the jobs directory to place all the job-related reports, such as Jobs Submitted. This will be located in the Tomcat webapps/reporting/report directory. 5. Change the <category> element to the directory name so that Viewpoint can locate it. 176 7.3 Adding permissions to individual reports Chapter 7: Configuring reports 6. Modify the <display-category> to update the display name for the category. As an example, see this configuration for the Jobs Submitted report: <reports> <report> <display-name>Jobs Submitted</display-name> <report-design>jobs_submitted.rptdesign</report-design> <display-category>Jobs</display-category> <category>jobs</category> <description>Presents the Jobs submitted by credential (user, group, account and quality of service) for the supplied time in table format with name and total of jobs</description> <permission name="report.jobs.jobs_submitted" /> </report> </reports> Viewpoint looks in the jobs directory to locate the report. A user with the report.job.jobs_submitted permission may view the report on the Reporting page and run it. The Reporting page will show that it is the jobs category. Related topics l Setting permissions on page 51 l Configuring reports on page 173 7.4 Configuring Viewpoint to run the Events report The Events report (including the data for the Event Logs page) requires a script to convert data from the Moab event files. The Event Logs page will not work until you follow these instructions for installing the script. To install the script required to run the Events report 1. Run the script. To do so: a. Log in to the Moab server as the root user or a user with appropriate permissions. b. Navigate to the unzipped Moab distribution and locate the contrib directory. For example: # cd /usr/moab-dist/contrib/events c. Make the script executable. # chmod u+x events2db.pl d. Run the script with the -m (manual) argument for the full documentation. # ./events2db.pl -m 7.4 Configuring Viewpoint to run the Events report 177 Chapter 7: Configuring reports Read the entire document. There is information in the manual not included here. e. Run the script with the correct arguments. # ./events2db.pl --dbname=Moab --dbuser=bob --dbpassword=p@ssw0rd --createschema /opt/moab/stats Running the script could take a good deal of time depending on how many events you have, but the script must complete successfully before you set up the crontab schedule. 2. Set up the script as a cron job: a. Still working as the root user or a user with appropriate permissions, edit the crontab. b. Create a new entry for the script. The syntax can be customized based on how often you want the script to run. For real-time reports, 1-5 minutes is the ideal setting. For less overhead on the server, every few hours or even once daily is a better option. The following runs hourly: 0 * * * * /usr/moab-dist/contrib/events/events2db.pl --dbname=Moab -dbuser=bob --dbpassword=p@ssw0rd /opt/moab/stats This runs without the --create-schema option. 3. See the contab man page for more information on crontab. # man crontab 4. Add the reports to Viewpoint by removing the comment tags from the desired report(s) in the reporting.xml file, located in the Viewpoint home directory. For more information, see Specifying Available Reports. Related topics l Configuring reports on page 173 7.5 Querying major events from the Moab event log The Viewpoint Moab Events page allows you to query major events that have been reported to the Moab event log. These events include JOBSTART, JOBEND, and JOBMODIFY. By default, the event log is maintained in the statistics directory and rolls on a daily basis. 178 7.5 Querying major events from the Moab event log Chapter 7: Configuring reports To query major events that have been reported to the Moab event log 1. Verify that your Moab database is a MySQL database. 2. Specify which events Moab should record in the Moab configuration file (moab.cfg) using the RECORDEVENTLIST parameter. For more information on configuring moab.cfg, see "Initial Moab Configuration" in the Moab Workload Manager Administrator Guide. 3. Configure Moab to report its events to a database instead of to files in the statistics directory. To configure Moab to report events to the database, see Configuring Viewpoint to communicate with your DBMS on page 29. 4. Verify Viewpoint, Moab, and the Moab database run on machines that are in the same time zone and that they react the same way to Daylight Savings Time changes. The web browser can be located anywhere, but the time stamp on the Moab Events page will display the time zone where Viewpoint is located. If you choose to have Viewpoint and the database run in different time zones, event queries that involve date or time will not be accurate. 5. To create a Moab Events filter, which allows you to quickly retrieve saved filters without having to fill in the form each time, click Reports > Events. a. You can create a filter which will allow you to query data by: l Date l Time l Event l Object l Name b. The list of events returned as listed by: l Date l Time l Event l Object l Name l Description 6. If the filter is already saved, click Manage Filters and select the filter. 7. Click the minus sign. Select a data item, an operator, and a criterion. The date is set to the current date. If you want to change the date, click the Calendar icon. 8. Click the plus sign to add another line to the filter. Complete the line. 9. Click Match All to connect lines of the filter using the AND operator, or click Match Any to connect them using the OR operator. 10. Click Run to run the filter, or click Save to save it. Type a name for the filter and click Save. 7.5 Querying major events from the Moab event log 179 Chapter 7: Configuring reports 11. To rename or delete a filter, select Manage Filters from the Moab Events page. To close this dialog, click Close or press the Escape key. Databases with more than 5,000,00 entries may result in unresponsive queries. You should use extra caution when utilizing the Match Any filter setting on a large system, because the number of entries can grow quickly enough to slow or stall the events page. To ensure responsiveness, it is strongly recommended that queries refine searches on larger systems through the use of a date parameter. Related topics 180 l Configuring Viewpoint to communicate with your DBMS on page 29 l Configuring a connection from Viewpoint to Moab on page 25 l Configuring reports on page 173 7.5 Querying major events from the Moab event log