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">(&amp;(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