Skip to end of metadata
Go to start of metadata

This document describes the requirements and steps required to get started with setting up Jenkins to use with the appSolute RTB Automation Toolkit. 

Table of Contents

Jenkins setup

Jenkins should be installed on a server that is compatible with platform requirements for the Roundtable environment to be automated.  This is especially important for compile processes where the compiled code is platform dependent. 

Jenkins can be downloaded from https://jenkins-ci.org/.

Recommended plug-ins

Along built-in core - the following plugins for Jenkins are recommended to be installed and used together with the automation toolkit: 

  • Email Extension plug-in: This plugin allows you to configure every aspect of email notifications. You can customize when an email is sent, who should receive it, and what the email says.

  • Extensible Choice Parameter plug-inThis plugin adds "Extensible Choice" as a build parameter. You can select how to retrieve choices, including the way to share choices among all jobs.

  • Green Balls plug-inChanges Hudson to use green balls instead of blue for successful builds.

  • Slack Notifications plug-inThis plugin allows to post build notifications to a Slack channel.

  • Filesystem trigger Choices plug-inFSTrigger provides polling mechanisms to monitor a file system and trigger a build if a file or a set of files have changed.

  • Files found trigger plug-inBuild trigger that polls one or more directories and starts a build if certain files are found within those directories.

  • URL trigger plug-inURLTrigger plug-in makes it possible to monitor changes of the response got from an URL invocation.

  • Email extension Template plug-inThis plugin allows you to configure templates for email-ext that can be reused across multiple jobs.

  • Build Name Setter plug-inThis plugin sets the display name of a build to something other than #1, #2, #3, so that you can use an identifier that makes more sense in your context.

  • Active Choices plug-inA Jenkins UI plugin for generating and rendering multiple value options for a job parameter.

Make sure that all installed plugins are up to date. Updates to both Jenkins and plugins are released on a regular basis. Jenkins plugins can be installed and updated using Plug-in Manager form Jenkins web client, it can be reachedby following: Manage Jenkins | Manage Plugins.  Further setup instructions will require some of recommended plug-ins installed.

Configuring Jenkins

The following additional software is requires to run ARAT based Jenkins scripts:

  • Apache Ant: Version 1.8.4 or higher. Development and testing have been done using Apache Ant 1.9.6. The latest version of Apache Ant can be downloaded form http://ant.apache.org/Once downloaded, .zip file can be extracted somewhere in the system disk. 

    At least one Ant installation should be added to Jenkins by following: Manage Jenkins | Configure System | Ant | Add Ant:



  • JAVA: A recent version of a JDK must be available on the system to execute Apache Ant scripts. The latest version of Java Development Kit can be downloaded form http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html. Once downloaded can be installed by following installer instructions. 

    At least one JDK installation should be added to Jenkins by following: Manage Jenkins | Configure System | JDK | Add Ant:



  • ARAT Emails: ARAT scripts come with email reports for builds. For emails to work some configuration is required. This is done by setting properties in windows_process.json file, "Mail" object:

    Mail
    "Mail": [
        {
          "HostServer": "smtp.mandrillapp.com",
          "HostPort": "587",
          "User": "jenkins@nodeable.io",
          "UserPassword": "fake*pa55word",
          "FromAddress": "jenkins@nodeable.io",
          "ToAddress": "jenkins@nodeable.io",
          "HostEnableStartTLS": false,
          "UseSSL": false,
        }
      ]
  • HostServer: "smtp.madrillapp.com"
    Email service host server.

    • HostPort: "587"
      Email service host port number.

    • FromAddress: "jenkins@nodeable.io"
      Sender email.

    • ToAdress: "jenkins@nodeable.io"
      Reciever email. 

    • HostEnableStartTLS: false
      When set to true, enables Transport Layer Security encryption protocol.

    • UseSSL: false
      When set to true, enables communication over Secure Sockets Layer.

use the correct settings for your own SMTP email service. 

Installing sample ARAT Jenkins jobs

After completing the Jenkins installation, the contents of the config\Jenkins\jobs.zip file can be extracted to the Jenkins installation root folder. This should place sample scripts into <Jenkins-installation>/jobs folder.

Before running builds, scripts need to be updated for current environment. 

Script configurations

To use ARAT based scripts with Jenkins, some initial configuration is required.

The following is a sample configuration for a Jenkins build using the ARAT workspace compile script:

Sample Jenkins script
<?xml version="1.0" encoding="UTF-8"?>
<project>
	<actions/>
	<description/>
	<keepDependencies>false</keepDependencies>
	<properties/>
	<scm class="hudson.scm.NullSCM"/>
	<canRoam>true</canRoam>
	<disabled>false</disabled>
	<blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
	<blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
	<triggers/>
	<concurrentBuild>false</concurrentBuild>
	<builders>
		<hudson.tasks.Ant plugin="ant@1.2">
			<targets/>
			<antName>apache-ant-1.9.6</antName>
			<buildFile>C:\Development\appsolute_rtb_automation_toolkit\ant\build_rtb_compile.xml</buildFile>
			<properties>basedir=C:\Development\appsolute_rtb_automation_toolkit BuildJsonProps=C:\Development\appsolute_rtb_automation_toolkit\config\process_windows.json</properties>
		</hudson.tasks.Ant>
	</builders>
	<publishers/>
	<buildWrappers/>
</project>

Important things to note when setting up Jenkins builds for your environment:

  • hudson.tasks.Ant plug-in: Ant plugin Jenkins is using, version can be checked/changed in Jenkins web client: Manage Jenkins | Manage Plugins | Installed | Ant Plugin.

  • antName: Currently installed Ant version name.

  • buildFile: Path to Ant script to be processed by Jenkins jobs.

  • basedir: Path to ARAT installation directory.
  • BuildJsonProps: Path to process_windows.json config file. 

Properties can be set by editing config.xml for any specific script. Alternatively scripts can be edited from Jenkins UI, by selecting a build and following: Configure | Invoke Ant | Advanced:

Creating new projects for ARAT builds

Configuring builds

After Jenkins web client restart, scripts should be visible in the item list. Before running builds, scripts need to be set up as parameterized builds. This can be done by selecting one of the scripts and following: Configure | This build is parameterized

Parameters can be added by clicking Add Parameter, selecting parameter type and filling out parameter form:

Properties that are set up be prompted in process_windows.json config file, need to be configured as parameters in Jenkins web client.

In the case of the build_rtb_compile.xml script, the following properties need to be configured as parameters:

  • RtbCompileWspaceId

  • RtbCompileModule

  • RtbCompileCompileObjects

  • RtbCompileForceCompile

process_windows.json
  "RtbCompile": [
    {
      "WspaceId": "prompt",
      "RtbUser": "${RtbUser}",
      "RtbPassword": "${RtbPassword}",
      "Task": "0",
      "Module": "prompt",
      "CompileGroup": "*",
      "ObjectType": "*",
      "CompileObjects": "prompt",
      "ForceCompile": "prompt",
      "CompileListing": false,
      "CompileWithXref": true,
      "TaskRCode": false,
      "FailOnError": false,
      "IgnoreWarnings": true,
      "Platform": "windows",
      "CompileLogFile": "${BuildRootDir}/logs/${RtbWspaceId}_compile_${log.DSTAMP}${log.TSTAMP}.log",
      "ParamFile": "${RtbParamFile}",
      "IniFile": "${basedir}/config/devel.ini",
      "MailResult": "${BuildMailResult}",
    }
  ]

Parameterized build examples

Following parameter setup process requires Active Choices plug-in installed.

To create some of the more complex parameters, depending on needs it could be worthwhile install additional plug-ins. Examples provided are done having installed Active Choices plug-in.

Multiple choices parameter for workspace list:

String parameter with default value:

Boolean parameter for true/false selections:

Jenkins emails

Following email setup process requires Email Extension plug-in installed.

First thing to set is System Admin e-mail adress, by following: Manage Jenkins | Configure System | Jenkins Location:


Jenkins can be configured to send emails when specific events take place. For this to work, email service parameters need to be set by following: Manage Jenkins | Configure System | Extended E-mail notification:


Connection can be tested by checking Test configuration by sending test e-mail and entering recipient email. If all settings are set correctly email should be successfully sent:

 

After this is done email notifications can be added to a specific event. Email notification can be added to a build by selecting a build and following: 

Configure | Post-build Actions | Add post-build action | Editable E-mail notification:

Here various email properties can be set or left as defaults. To set triggers follow: Advanced Settings | Triggers | AddTrigger | Always:

With this setup email is sent every time build is ran to all emails included in recipients list. After running build by clicking Build with Parameters, check additional info in the log and received email:

Log output
BUILD SUCCESSFUL
Total time: 59 seconds

Email was triggered for: Always
Sending email for trigger: Always
Sending email to: a.gluodas@gmail.com
Finished: SUCCESS
Email body
Workspace-Compile - Build # 27 - Successful:

Check console output at http://localhost:8080/job/Workspace-Compile/27/ to view the results.

 

Running a build

After all parameters are setup, a build can be run by clicking Build with Parameters from the dashboard:

Build results example

Below are the results of compilation script build:

Output
Buildfile: C:\Development\appsolute_rtb_automation_toolkit\ant\build_rtb_compile.xml
 
start:

JsonProperties:
     [echo] Loading C:\Development\appsolute_rtb_automation_toolkit\config\process_windows.json properties file from JSON

readJSonProps:
     [echo] Reading JSON properties file: C:\Development\appsolute_rtb_automation_toolkit\config\process_windows.json
     [echo] JSON properties loaded

setLogFilename:

startlogging:
     [echo] Log (info) being written to: D:\rtb115\buildlogs\build_rtbcompile_Devel_20160119_103534.log

default:
     [echo] Buildfile     : C:\Development\appsolute_rtb_automation_toolkit\ant\build_rtb_compile.xml
     [echo] Basedir       : C:\Development\appsolute_rtb_automation_toolkit\
     [echo] Build root dir: D:\rtb115

RTBCompilePrompts:
     [echo] Checking RTB workspace to compile

RTBUserPrompt:
     [echo] Checking RTB username and password

checkRTBProps:

checkCompileProps:

selectiveCompile:

selectiveCompileWindows:
     [echo] Launching windows-based compile... 
     [echo] RTB database port : 11500
     [echo] Compiling with networked connection to RTB database
   [PCTRun] Unable to find INI file D:\rtb115\config\devel.ini - Skipping attribute
   [PCTRun] Starting Roundtable API for user : sysop...
   [PCTRun] Logging into Roundtable API...
   [PCTRun] Session ID : 940
   [PCTRun] Setting paths in RTB API...
   [PCTRun] Mode: Client only (940)...
   [PCTRun] 
   [PCTRun]   Processing workspace: production...
   [PCTRun]   /*****************************************/
   [PCTRun]    Setting workspace in RTB session to 'production'...
   [PCTRun]    Compile settings 
   [PCTRun]    =================
   [PCTRun]    Workspace       : production
   [PCTRun]    Task number     : 000000000
   [PCTRun]    Module          : *
   [PCTRun]    Group           : *
   [PCTRun]    Object type     : *
   [PCTRun]    Object(s)       : *
   [PCTRun]    Force compile   : yes
   [PCTRun]    Listings        : no
   [PCTRun]    Xref            : yes
   [PCTRun]    Ignore warnings : yes
   [PCTRun]    Stop on error   : no
   [PCTRun]    Starting custom selective compiler: 
   [PCTRun]     C:\Development\appsolute_rtb_automation_toolkit\scm\custom\rtb\p\rtbcust_compiler.p
   [PCTRun]    Performing selective compile for workspace: production

   [PCTRun]    Selective compile complete.
   [PCTRun]    Compile log copied to : D:\rtb115\Logs\Compiles\production\production_CompileReport_20160119_103535.txt
   [PCTRun] Logging out of RTB API...
     [echo] 
     [echo] Compiler log contents:
     [echo] Object: bbin.w - OK
     [echo]   Pmod: GUI
     [echo]   Path: D:\rtb115\rtbws\production\gui\bbin.w
     [echo] 
     [echo] Object: bcust.w - OK
     [echo]   Pmod: GUI
     [echo]   Path: D:\rtb115\rtbws\production\gui\bcust.w
     [echo] 
     [echo] Object: binvtrans.w - OK
     [echo]   Pmod: GUI
     [echo]   Path: D:\rtb115\rtbws\production\gui\binvtrans.w
		
		..........
 
     [echo] 
     [echo] Object: wsupplier.w - OK
     [echo]   Pmod: GUI
     [echo]   Path: D:\rtb115\rtbws\production\gui\wsupplier.w
     [echo] 
     [mail] Sending email: Compile results: production

     [mail] Sent email with 1 attachment

BUILD SUCCESSFUL
Total time: 58 seconds

Finished: SUCCESS

 

Automation Toolkit Contents

Details on the APIs and code included in the toolkit are included in Automation Toolkit Contents.

This document describes the requirements and steps required to get started with setting up Jenkins to use with the appSolute RTB Automation Toolkit. 

 

  • No labels
Write a comment…