This document describes the requirements and steps required to get started with the appSolute RTB Automation Toolkit.
Table of Contents
The latest version of the RTB Automation toolkit is 11.5.02
Welcome to the appSolute RTB Automation Toolkit (ARAT). An Extended API and Automation Toolkit for Roundtable TSMS.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction except as noted below, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sub-license, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The Software and/or source code cannot be copied in whole and sold without meaningful modification for a profit.
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The toolkit is not officially supported by Roundtable Technical support or nodeable limited Technical Support.
The toolkit is provided as-is and without any warranty or support of any kind. However, questions, comments, updates and suggestions are very welcome.
Support and Consulting Services
Contact firstname.lastname@example.org or email@example.com for more details on support packages and services for the RTB Automation Toolkit.
The following software is needed:
Roundtable TSMS and OpenEdge
- RTB TSMS 11.5
The latest version of the toolkit has been updated and tested with Roundtable TSMS 11.5 and patch 11.5.02.
There may be dependencies on signatures in the standard APIs and the proxy procedures from RTB 11.5.1 Therefore the toolkit will very likely not work with earlier versions of RTB. The toolkit has not been actively tested with older versions of RTB.
OpenEdge 10.2B or OpenEdge 11.x
Version 11.5.02 of the toolkit has been tested with OpenEdge 11.5 and OpenEdge 11.6.
The latest version of the toolkit has not yet been tested with OpenEdge 10.2B. It is expected to work and testing is underway. As soon as this has been completed, the toolkit and documentation will updated with this info.
The following additional software is recommended for using the toolkit to run outside of OpenEdge and from tools like Jenkins:
Recommend install - Use bundled Apache Ant package
It is highly recommended to use our prepackage Apache Ant bundle to get started. The bundle include Apache Ant with the extra libraries that are needed for the included ANT scripts to work.
The version of Ant included in this bundled in 1.9.4. The bundle have been testet extensivly with ARAT. Java JDK is not part of the bundle, and must be downloaded from oracle.com. Please make sure, you have a running installation of the JAVA JDK before proceeding with ANT/ARAT.
A recent version of a JDK must be available on the system to execute Apache Ant scripts.
|Ant Version||Minimum Java Version|
|1.1 up to 1.5.4||1.1|
|1.6.0 up to 1.6.5||1.2|
|1.7.0 up to 1.7.1||1.3|
|1.8.0 up to 1.8.3||1.4|
|Any 1.9.x release and the git branch 1.9.x||1.5|
|current git master branch||1.8|
Version 1.8.4 or higher. Development and testing has been done using Apache Ant 1.9.6.
Can be downloaded from http://ant.apache.org
The latest release (v202) of the PCT.jar file can be downloaded from https://github.com/jakejustus/pct/releases. Please note PCT requires Ant version 1.8 or higher. However, PCT has only been tested with version 1.9 of Ant.
Automation Toolkit Installation
Alternatively, if the toolkit is to be used as is without customizations, place it in a central directory that can be accessed by all the environments that will be using it. This could be in something like
The toolkit can also be downloaded from BitBucket :
The project is currently available as OpenSource. Feel free to fork and download and submit Pull Requests if for suggestions to fixes and new features.
Fast install - Use bundled Apache Ant package
To make it easier to get started, we have also included a bundled version of Apache Ant with the extra libraries that are needed for the included ant scripts to work (apache-ant-1.9.4.zip). The version of Ant included in this bundled in 1.9.4. After extracting the Apache ANT package, add both PATH and ANT_HOME system variables as described below.
Manual installation of Ant
To ensure all of the available optional tasks are available, it is recommended to run the following update script from the ANT_HOME directory after installing ant:
See http://ant.apache.org/manual/install.html#installing for more details
There are also some extra external libraries needed for the toolkit Ant scripts to work. These are included in the toolkit vendor directory.
Extra libraries can either be added to the Ant and Java CLASSPATH- or simply copied into the ant/lib directory.
Required extras are:
- PCT (see notes further on)
Once ant has been installed, it is recommended to set the system wide environment variable ANT_HOME.
On Windows this could be :
Adding ANT_HOME to PATH environment variable for user convenience. With ANT_HOME added to the PATH value, you can just start ant instead of always typing the/complete/path/to/your/ant/installation/bin/ant.
After adding the above system variables, please verify the installation. A system re-boot may be necessary.
ANT is NOT configured correct.
ANT is properly configured OK (The below error message is not relevant).
See the installation documentation for details on how to install.
In the environment used during the development of this toolkit, the latest official PCT.jar file has been copied directory into the ant/lib directory. This is automatically picked up from the CLASSPATH by ant and is the easiest way to use it.
The Automation toolkit can be included in a simple OpenEdge Project in OpenEdge Developer Studio (OEDS). It is recommended that this is done in a simple OpenEdge project with no special settings for source and build directories. The toolkit should reside in the root directory of the project.
When working with the toolkit from OEDS, the following settings are important to get started:
RTB Root path
Make sure the root path for the version of Roundtable being used with the toolkit is included in the OpenEdge Project PROPATH.
RTB database connection
Make sure there is a database connection for the OE Eclipse project to connect to a database with a logical database name of "rtb" with the schema for RTB 11.5.1.
Eclipse Ant Editor support
To make it easier to open and edit the included Apache Ant scripts, it is recommended that all of the scripts are registered under XML content types for ant scripts.
Window | Preferences | General | Content types | Text | XML | Ant buildfiles.
Each Ant script needs to be registered with the full name, as wild cards cannot be used. The end result could look like this:
Running Ant scripts from Eclipse
Once the ant scripts are registered, the run-time settings for Ant in Eclipse need to be set:
From Window | Preferences | Ant | Runtime, set the following
- ANT HOME:
Under the Classpath tab, select the local installation of Ant which contains PCT (https://github.com/jakejustus/pct) and other libraries e.g. "C:\Ant\apache-ant-1.9.4".
NB: Eclipse comes with a built-in version of Ant, which may be older than the one required for the toolkit.
Set the following properties (actual settings are examples):
The basedir variable is used to pick up the various scripts and programs that make up the toolkit. This should always point to the root directory of the toolkit.
the absolute path to the project
This property defines the name of the JSON properties file that contains the majority of the settings for the toolkit and it's various processes.
Older .props file support
Older .props files are still supported, but not enabled by default in the latest version of the toolkit. If you are using an older version of the toolkit with .props files, it is recommended to convert these to JSON files and udpate the toolkit configuration to use this.
Once this is setup, open up each of the ant scripts, right click on them and select "Run As | Ant Build". This will execute the Ant script and will also automatically create an external tool configuration that can be used later to run the scripts from eclipse. The properties of the configuration can be modified and even saved for others to use if needed.
A sample of JSON properties file called process_windows.json is available in the config directory of the toolkit project.
This can be used to run all of the processes included in the toolkit on Windows. The sample file will need to be adjusted with the correct paths for your Roundtable installation, OpenEdge installation and other directories before it can be used.
Managing the toolkit in Roundtable
If the toolkit is to be used as a standard part of the application life-cycle and maybe even deployed with the application, then it is recommended that it is loaded into Roundtable as an integrated part of your application.
Included in the toolkit directory structure is a config/Jenkins directory. This contains sample jobs for running the Ant scripts from the toolkit in Jenkins. See Jenkins Configuration and the readme.txt file in the config/Jenkins sub-directory for more details.
Automation Toolkit Contents
Details on the APIs and code included in the toolkit are included in Automation Toolkit Contents.