20 February 2017

T-Plan Robot Automation Portal

Contents
1. Overview
2. Installation
3. Upgrade

1. Overview

The T-Plan Robot Automation Portal (RAP) is a web application allowing to monitor and manage T-Plan Robot Enterprise driven automation over the TCP/IP network (internet and/or intranet).

RAP features:

Connection to machines running T-Plan Robot Enterprise and monitoring of their status through the Administrate page,

Dashboard with automation result statistics and charts at the Home page,

Tracking of automation results and viewing of automation reports (the Results page),

Extended viewing of the Robot schedule results (the Schedules page),

Management of resources on the remote Robot hosts - start/stop scripts and schedules (the Manage page)

Specification:

Java EE 7 application deployed on a compatible Java EE application server (Oracle GlassFish 4.0 used as a reference server)
MySQL 5.7 backend (contact support to request another DB)

Requirements on the RAP host:

Any OS supported by Java EE 7 and GlassFish 4 (compatibility list)
Java Development Kit (JDK) 7+ installed (JDK 8 recommended)
Minimum hardware requirements are subject to the platform (OS) and the selected Java EE server. For Oracle GlassFish 4.0 refer to the Release Notes.
Disk space requirements: JDK approx. 200 MB, Oracle GlassFish 4.0 approx. 250 MB, RAP application up to 100 MB, total 450 MB.

Requirements on the DB host:

Subject to the selected DB. For MySQL 5.7 see the supported platforms. The hardware requirements are not documented because they are subject to the install type. For RAM calculation use http://www.mysqlcalculator.com.

Requirements on the Robot machines:

T-Plan Robot 4.2.1 or higher is running on the Robot host with the RAP server on. To start the server use either the --rapserver CLI option or the Tools->Enable RAP Server item in the Robot's GUI menu.
The Robot host must be visible over the TCP/IP network and it must allow communication through the RAP port of (no firewall blocking). The port can be eventually changed through the CLI option.

2. Installation

These steps describe installation of RAP and MySQL on a single Windows 10 x64 host. For a different environment adjust accordingly.

MySQL Installation

Use the Windows 32-bit installer (it will install 64-bit version on a 64-bit OS):

http://dev.mysql.com/downloads/windows/installer/5.7.html

Setup Type: "Full" recommended.
Accounts and Roles: set the "root" user password. Do not create any new user at this point.

Post-install steps:

Start the MySQL workbench to create the database and a new user:

Click the "Local Instance" box and connect as root.
The left column contains the "Schema" list of databases. Right click any DB and select "Create schema" from the pop up menu. Create a new one called "tplanrap".

NOTE: The same can be done from the CLI using:

"C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqladmin.exe" -u root -p create tplanrap

Select "Users And Privileges" in the left column and click the "Add Account" button at the bottom
Login tab:

Login Name: tplanrap
Auth: Standard
Limit To Hosts Matching: If MySQL sits on the same machine as GlassFish enter "localhost". This will enable only local access which is more secure than allowing the account from any host ("%"). If MySQL is somewhere else use the name of the GlassFish host.
Click "Apply" and then "Refresh" -> the user must appear in the "User Accounts" table

Select the user and configure more:
"Administrative Roles" tab:

Make sure no global role is selected

"Schema Privileges" tab:

Select "Add Entry" and choose the "tplanrap" database in the "Selected schema" drop down
Select "Apply" -> it will grant full rights to the "tplanrap" database to the user

IMPORTANT: As the RAP schema stores zero TIMESTAMP values the MySQL instance must have the ALLOW_INVALID_DATES mode enabled. This is the default setting for Windows. On other systems such as Ubuntu Linux it must be configured manually or the RAP fails to create the DB correctly. The workaround is to delete all tables, enable the mode and restart the RAP app (the app server domain).

GlassFish 4.0 Installation

Download GlassFish 4.0 from:

http://download.java.net/glassfish/4.0/release/glassfish-4.0-windows.exe

NOTE: Do NOT download release 4.1.1 because it contains a bug which makes any attempt to create the JDBC connection pool to fail with IllegalStateException. The workaround is to create the pool through the "asadmin" CLI utility.

Do NOT install to "C:\Program Files" because the server will have to write to the log file within the install location and thus it will need the file permissions. The best idea is to install it somewhere in the home folder.

Installation Type: Typical
JDK Selection: select the installed JDK if you have multiple ones on your env (use the highest version)
Install Update Tool: off (optional)

Post-install steps:

The installer creates and starts the default domain called "domain1". The steps below show how to start manually. They are referred to in this guide as "start the domain":


        C:\Users\Admin\development\glassfish-4.1.1\glassfish4\bin>
        asadmin start-domain domain1

      Waiting for domain1 to start
        ......................................

      Successfully started
        the domain : domain1

      domain 
        Location:
C:\Users\Robert\development\glassfish-4.1.1\glassfish4\glassfish\domains\domain1

      Log File:
C:\Users\Robert\development\glassfish-4.1.1\glassfish4\glassfish\domains\domain1\logs\server.log

Admin Port: 4848

      Command start-domain
        executed successfully.

Download the MySQL connector from:

https://dev.mysql.com/downloads/connector/j/

Once downloaded extract the mysql-connector-java-xxxx-bin.jarfile and put it to <glassfish>\glassfish\domains\domain1\lib. This will make the domain load the MySQL driver on start up. If the domain is already running restart it:

asadmin stop-domain domain1 asadmin start-domain domain1

Load the Glassfish admin console at:

http://localhost:4848

NOTE: The admin console is just a front end working on top of the "asadmin" tool. Any operation described below can be alternatively performed through the CLI.

Integrate GlassFish with MySQL:

Create a connection pool. It defines a set of shared connections managed through the pool. As creating of a new DB connection for each DB query is costly the connection pool will improve the performance.

Select Resources->JDBC->JDBC Connection Pools in the tree

Select New

Pool Name: tplanpool

Resource Type: javax.sql.ConnectionPoolDataSource

Database Driver Vendor: MySQL

Leave the other settings on defaults

Once created click the pool name in the list of pools and choose "Additional Properties":

Add property "User" with the value of "tplanrap" or the MySQL user name you wish to use.
Add property "Password" with the value of the MySQL password
Add property "URL" = jdbc:mysql://localhost:3306/tplanrap?zeroDateTimeBehavior=convertToNull. If your MySQL DB is on another machine replace 'localhost' with the machine name or IP address accordingly.
Save and select "Ping" -> it must succeed

Create the actual MySQL binding:

Select Resources->JDBC->JDBC Resources in the tree
Select New
Enter "jdbc/tplanrap" for the JNDI name. This is a MUST because this connection identifier is hardcoded in the T-Plan RAP application to identify the database connection.
Pool Name: tplanpool (it will associate the connection with the pool we created)

Restart the domain using "asadmin":

asadmin stop-domain domain1
asadmin start-domain domain1

Deploy the T-Plan RAP application:

Click Applications in the tree
Click Deploy
Select the "Packaged File to Be Uploaded to the Server" option and navigate to the tplanrap.war file (you'll receive it from the T-Plan support)
Leave the settings at defaults and click OK
Once deployed access the T-Plan RAP through the "Launch" link or at http://localhost:8080/tplanrap

NOTE: The app can be also deployed from CLI using the "asadmin" command. See https://glassfish.java.net/docs/4.0/quick-start-guide.pdf for details.

The app will create the tables in the "tplanrap" database on the first start. Once it's done go back to the admin console and perform these steps to allow connection failover (restoring of faled connections):

Select Resources->JDBC->JDBC Connection Pools in the tree
Select the pool you created (jdbc/tplanpool)
Go to Advanced->Connection Validation and configure:

Connection Validation: Required
Validation Method: table
Table Name: DUAL

Optional Steps:

Secure asadmin and the admin console with a password at Common Tasks -> Change Administrator Password
Change the domain port from 8080 to 80 to make RAP accessible at an URL without port (http://localhost/tplanrap):

Select Configurations -> server-config -> HTTP Service -> HTTP Listeners
Find the listener running on port 8080 and change it to 80
Save the changes and restart the domain

Troubleshooting:

RAP shows up in red and says "No database connection. Please make sure that MySQL is running."

- MySQL is either down or the authentication failed. Check if it's running in the system Services. To verify the user and password go to the connection pool in the GlassFish admin console and select the "ping" button. It must succeed.

RAP shows up in red and says "DB error: No database selected"

- This means that RAP can connect to MySQL but it doesn't know which DB to work with. The URL property in the connection pool properties is likely to be wrong.

3. Upgrade

RAP upgrade steps:

Get the new version of tplanrap.war file from the T-Plan support
If the GlassFish domain is not running start it. Then log in to the admin console:

http://localhost:4848

Select Applications, click Redeploy next to the "tplanrap" app and submit the new WAR file.