Child pages
  • Using the appSolute RTB Automation Toolkit
Skip to end of metadata
Go to start of metadata

eThis document describes how the appSolute RTB Automation toolkit can be used. 

Table of contents

BuildJsonProps Property files

The installation of the toolkit includes a sample properties files that can be used to execute all of the supported automation processes. This file is called :

config/process_windows.json

It has been mentioned in the appSolute RTB Automation Toolkit Installation Guide in connection with setting up the toolkit to work in Eclipse. 

The properties files has a number of base settings that apply to all of the environments, as well as sections that are specific to each of the automation processes. 

Here are the main properties used for all of the automation processes: 

RTB Automation base properties
"Properties": {
      "basedir": "D:/Users/thomas/automation_toolkit_115",
      "ProductName": "appSolute Automation Toolkit",
      "CustomerName": "appSolutions",
      "BuildLoglevel": "info",
      "ProgressDLC": "D:/OpenEdge115",
      "ProgressCpStream": "iso8859-1",
      "BuildRootDir": "D:/Users/thomas/rtbdemo115",
      "BuildScriptDir": "${basedir}/ant",
      "BuildMailResult": true,
	  "BuildMailResult": true,
      "BuildVerbose": false,
      "BuildDebug": false,
      "RtbUser": "sysop",
      "RtbPassword": "",
  "Rtb": [
    {
      "RtbDbName": "rtb",
      "RtbLgDbName": "rtb",
      "RtbDbHostName": "localhost",
      "RtbDbPort": 15000,
      "RtbInstallPath": "D:/Users/thomas/rtbdemo115",
      "RtbCustomPath": "${basedir}:${basedir}/scm/custom",
      "RtbWspaceId": "Devel",
      "RtbDbSingleUser": false,
      "RtbUseAppServer": false,
      "RtbAppServerConnection": "AppServer://localhost:5171/thomas_rtbdemo115",
      "RtbParamFile": "${basedir}/config/rtb_automation.pf",
      "RtbReportBaseDir": "${BuildRootDir}/Logs",
      "RtbDeploymentBaseDir": "${BuildRootDir}/Deployments",
	  "RtbMaxWorkspaces": 8
    }
  ]
  • basedir: "D:/Users/thomas/automation_toolkit_115"

    ARAT installation root directory.

  • BuildLogLevel: "info"

    Default logging level for builds.

  • ProgressDLC: "D:/OpenEdge115"

    OE installation root directory. 

  • ProgressCpStream: "iso8859-1"
    Specifies the character set used for operating system file I/O. Can be set to 'ibm850' or 'iso8859-1'

  • BuildRootDir: "D:/Users/thomas/rtbdemo115"
    RTB TSMS installation root directory.

  • BuildScriptDir: "${basedir}/ant"
    ARAT directory with ant scripts. 

  • BuildMailResult: true
    If set to true, automation process log is built as an attachment to an email. 

  • BuildMailResultDetail: true
    If set to true, automation process log is built as an attachment to an email, in addition to that log content is added to email body. 

  • BuildVerbose: false
    If set to true, logging level set to verbose - very detailed.

  • BuildDebug: false
    If set to true, enables debugging.  

  • RtbDbName: "rtb"
    RTB repository database physical name. 

  • RtbDbLgName: "rtb"
    RTB repository database logical name. 

  • RtbDbHostName: "localhost"
    RTB repository database host name. 

  • RtbDbPort: 15000
    RTB repository database port number.

  • RtbInstallPath: "D:/Users/thomas/rtbdemo115"
    RTB TSMS installation directory. 

  • RtbCustomPath: "${basedir}:${basedir}/scm/custom"
    Parameter you can use to add extra paths to your PROPATH when the OE sessions are running in the toolkit

  • RtbWspaceId: "Devel"
    Default name for rtb workspace.

  • RtbDbSingleUser: false
    If set to true, RTB repository database is used in single user mode.

  • RtbUseAppServer: false
    Is set to true, connection to RTB repository database established via appserver.

  • RtbAppServerConnection: "AppServer://localhost:5171/thomas_rtbdemo115"
    RTB appserver connection string. 

  • RtbParamFile"${basedir}/config/rtb_automation.pf"
    Path to ARAT startup parameter file.

  • RtbReportBaseDir: "${BuildRootDir}/Logs"
    Root log directory for automation processes.

  • RtbDeploymentBaseDir: "${BuildRootDir}/Deployments"
    Root directory for deploy sites.

  • RtbMaxWorkspaces: 8
    Maximum number of workspaces for single automation process can be ran against.

 

Make sure the locations of the OpenEdge installation, Roundtable TSMS installation being used, RTB repository ports etc are set to match your environment.  

If strange directories, like ${BuildRootDir} are created testing the automation processes, then the properties are not set correctly.

 

Windows scripts

The installation of the toolkit includes a number of sample scripts for running the automation processes from a command prompt in Windows. These scripts set the base properties and the location of the configuration file to use and then executes the ant script. Standart ARAT installation includes these cmd scripts:

  • workspace-compile.cmd: compiles workspace using specified parameters.

  • workspace-deploy.cmd: creates workspace deployment using specified parameters.

  • workspace-import.cmd: imports products between workspaces using specified parameters. 

  • workspace-integrity-check.cmd: checks if workspace is in sync with file system using specified parameters.

  • workspace-release.cmd: creates workspace release using specified parameters.

  • workspace-schema.cmd: updates workspace schema using specified parameters. 

In addition to performing RTb processes, scripts can log action results and forward them as an atachment to an email.

Before using windows scripts some initial changes are required. In a case of wokspace-compile.cmd edit parameters as shown:

@call ant -buildfile D:/oeworkspaces/aivaras/115/appsolute_rtb_automation_toolkit/ant/build_rtb_compile.xml -DBuildJsonProps=D:/oeworkspaces/aivaras/115/appsolute_rtb_automation_toolkit/config/process_windows.json -Dbasedir=D:/oeworkspaces/aivaras/115/appsolute_rtb_automation_toolkit

pause
  • -buildfile: path to corresponding ant script.

  • -DbuildJsonProps: path to process_windows.json file.

  • -Dbasedir: path to ARAT root folder. 

The Automation processes

This section includes some details on the various automation processes that are included in the toolkit. 

Each of the processes have a section in the configuration files, that sets the standard properties for the process. 

Each process also has one or more extended APIs and scripts to execute them associated with them. Depending on how the processes are being used, they can either be triggered from command line scripts, shell scripts, Jenkins jobs or other CI tools that are able to execute ant scripts. 

Compiling workspaces

Compile properties

The following properties are relevant for compile processing: 

"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}",
    }
  ]
  • WspaceId: "prompt"
    When set to "prompt" the user will be prompted for the workspace(s) to be processed during compilation. This can also be set to a specific workspace.  
    Another option is to set the RtbCompileWspaceId property when the automation task is run (i.e. as a property set with the command executing the script). Properties that are set with the command take precedence and override the contents of the properties file.  

  • RtbUser: "${RtbUser}"
    Setting is usually inherited from the base property settings. 

  • RtbPassword: "${RtbPassword}"
    Setting is usually inherited from the base property settings. 

  • Task: "0"
    If specified, only objects belonging to this task will be included into compilation process. 

  • Module: "prompt"
    When set to "prompt" the user will be prompted for the module(s) to be processed during compilation. This can also be set to a specific module.  
    Another option is to set the RtbCompileModule property when the automation task is run (i.e. as a property set with the command executing the script). 

  • CompileGroup: "*"
    Object group(s) to be processed during compilation. 

  • ObjectType: "*"
    Object type(s) to be processed during compilation. 

  • CompileObjects: "prompt"
    When set to "prompt" the user will be prompted for the object(s) to be processed during compilation. This can also be set to a specific object.  
    Another option is to set the RtbCompileObject property when the automation task is run (i.e. as a property set with the command executing the script). 

  • ForceCompile: "prompt"
    When set to "prompt" the user will be prompted whether to force compilation even if Roundtable thinks that specified objects don't need it. This can also be set to 'true' or 'false'.  

  • CompileListing: false
    If set to true, fully expanded code is included into compilation log files. 

  • CompileWithXref: true
    If set to true, compilation is executed using cross references. 

  • TaskRCode: false
    If set to true, during compilation r-code is created for compiled objects. 

  • FailOnError: false
    If set to true, compilation process is stopped whenever one of the specified obhects generate a compiation error.

  • IgnoreWarnings: true
    If set to true, any generated compilation warnings are disregarded during the process. 

  • Platform: "windows"
    Specifies on what platform compilation process is ran on, so that proper r-code is generated. This can be set to 'windows' or 'unix'. 

  • CompileLogFile: "${BuildRootDir}/logs/${RtbWspaceId}_compile_${log.DSTAMP}${log.TSTAMP}.log"
    Compilation log file path.

  • ParamFile: "${RtbParamFile}"
    Path to ARAT parameter file 'rtb_automation.pf', usually inherited from the base property settings.

  • IniFile: "${basedir}/config/devel.ini"
    Path to ARAT startup parameter file.

  • MailResult: "${BuildMailResult}"
    Setting is usually inherited from the base property settings. Alternatively can be set to 'true' or 'false'. If set to true, the log results from the import will be sent as an attachment to an email. 

Running compiles

Before the compilation process can be used, some initial setup is required. In the example of the devel workspace - when doing compiles on Windows - the file referenced in the *IniFile* property (e.g. ${basedir}/config/devel.ini) needs to be setup. Important things to set are:

  • DLC: OpenEgde install directory

  • PROPATH: Should include current directory, RTB install directory, ARAT install directory, devel workspace working directory, path to adecomm procedure library and OE root, gui, src, bin directories.

[Startup]
V6Display=no
;ImmediateDisplay=yes
;MultitaskingInterval=100
DefaultFont=MS Sans Serif, size=8
DefaultFixedFont=Courier New, size=8
DLC=D:\OpenEdge115
Use-3D-Size=Yes
Keep3DFillinBorder=yes 			
AllowDesignMode=yes				
PROPATH=.,D:\Users\thomas\rtbdemo115,D:\Users\thomas\automation_toolkit_115,D:\Users\thomas\rtbdemo115\quickstart\demodata\devel,D:\OpenEdge115\gui\adecomm.pl,D:\OpenEdge115\gui,D:\OpenEdge115\src,D:\OpenEdge115,D:\OpenEdge115\bin
EditorConfigPath=D:\Development\Work

Depending on the property settings in the BuildJsonProps config file, the user can be prompted for information about the workspaces to compile and the filters to use during compilation. 

A sample output of the compile process looks like this: 

Object: wmain.w - OK
  Pmod: GUI
  Path: D:/Users/aivaras/rtb115demoinstall/rtbws/test/gui/wmain.w

Object: wsupplier.w - OK
  Pmod: GUI
  Path: D:/Users/aivaras/rtb115demoinstall/rtbws/test/gui/wsupplier.w

Object: simple_proc.p
  Pmod  : GUI
  Path  : D:/Users/aivaras/rtb115demoinstall/rtbws/test/gui/simple_proc.p
  Error : ** "gui\simple_include.i" was not found. (293)
  ** D:\Users\aivaras\rtb115demoinstall\rtbws\test\gui\simple_proc.p Could not understand line 1. (193)

If emails are enabled, then an email will also be sent with the processing log file and a compile log file attached.

The process can also be run as part of a Jenkins project or be run by the user directly from an Eclipse session. 

Checking workspace integrity

Integrity check properties

The following properties are relevant for integrity check process: 

 "RtbWsCheck": [
    {
      "WspaceId": "prompt",
      "RtbUser": "${RtbUser}",
      "RtbPassword": "${RtbPassword}",
      "ObjectFilter": "*",
      "DisplayWIPObjects": false
    }
  ]
  • WspaceId: "prompt"
    When set to "prompt" the user will be prompted for the workspace(s) to be processed during compilation. This can also be set to a specific workspace.  
    Another option is to set the RtbCompileWspaceId property when the automation task is run (i.e. as a property set with the command executing the script). Properties that are set with the command take precedence and override the contents of the properties file.  

  • RtbUser: "${RtbUser}"
    Setting is usually inherited from the base property settings. 

  • RtbPassword: "${RtbPassword}"
    Setting is usually inherited from the base property settings. 

  • ObjectFilter: "*"
    Object(s) to be processed during integrity check.

  • DisplayWIPObjects: false
    If set to true, objects with status WIP are excluded from integrity check porcess.

Creating releases

Release properties

The following properties are relevant for creating workspace releases: 

 "RtbRelease": [
    {
      "WspaceId": "prompt",
      "RtbUser": "${RtbUser}",
      "RtbPassword": "${RtbPassword}",
      "ReleaseNote": "Ant Auto Release ${start.DSTAMP} ${start.TSTAMP}",
      "OnlyWhenNeeded": true,
      "CreateReport": true,
      "MailResult": "${BuildMailResult}",
      "MailResultDetail": "${BuildMailResultDetail}"
    }
  ]
  • WspaceId: "prompt"
    When set to "prompt" the user will be prompted for the workspace(s) to be processed during compilation. This can also be set to a specific workspace.  
    Another option is to set the RtbCompileWspaceId property when the automation task is run (i.e. as a property set with the command executing the script). Properties that are set with the command take precedence and override the contents of the properties file.  

  • RtbUser: "${RtbUser}"
    Setting is usually inherited from the base property settings. 

  • RtbPassword: "${RtbPassword}"
    Setting is usually inherited from the base property settings. 

  • ReleaseNote: "Ant Auto Release ${start.DSTAMP} ${start.TSTAMP}"
    A description attached to the release.

  • OnlyWhenNeeded: true
    If set to true, release only created if there has been changes since the last release. 

  • CreateReport: true
    if set to true, a report is created after the creation of release.

  • MailResult: "${BuildMailResult}"
    If set to true, the log results from the import will be sent as an attachment to an email. 

  • MailResultDetail: "${BuildMailResultDetail}"
    If set to true, the log results from the import will be sent as an attachment to an email, in addition to that log content is added to email body. 

Importing between workspaces

Import properties

The following properties are relevant for import processing: 

"RtbImport": [
    {
      "WspaceId": "prompt",
      "RtbUser": "${RtbUser}",
      "RtbPassword": "${RtbPassword}",
      "BuildImport": true,
      "SourceWorkspaces": "devel",
      "Pmods": "*",
      "TaskList": "prompt",
      "ReleaseNum": "0",
      "HigherVerOnly": false,
      "CurrReleaseOnly": true,
      "CompleteTasksOnly": true,
      "IncludeAll": true,
      "ApplyImport": true,
      "ReportAfterBuild": false,
      "ReportAfterApply": true,
      "DeleteAfterApply": true,
      "MailResult": true,
	  "MailResultDetail": "${BuildMailResultDetail}",
      "DeleteExistingImportTable": true,
      "CompileAfterImport": true,
      "CreateTaskForImport": true,
      "CompleteImportTask": true,
      "MaxWorkspaces": "${RtbMaxWorkspaces}",
      "ProcessImportTableTasks": true
    }
  ]

 

  • WspaceId: "prompt"
    When set to "prompt" the user will be prompted for the workspace(s) to be processed during deployment. This can also be set to a specific workspace.  
    Another option is to set the RtbImportWspaceId property when the automation task is run (i.e. as a property set with the command executing the script). Properties that are set with the command take precedence and override the contents of the properties file.  

  • RtbUser: "${RtbUser}"
    Setting is usually inherited from the base property settings. 

  • RtbPassword: "${RtbPassword}"
    Setting is usually inherited from the base property settings. 

  • BuildImport: true
    If set to true, an import table is built otherwise looking for existing import table.

  • SourceWorkspaces: "devel"
    Default source workspace for imports.

  • Pmods: "*"
    Product module(s) to be processed during import.

  • TaskList: "prompt"
    When set to "prompt" the user will be prompted for the task(s) from specified wokspace to be processed during import. This can also be set to a specific workspace. Another option is to set the RtbImportTaskList property when the automation task is run (i.e. as a property set with the command executing the script).

  • ReleaseNum: "0"
    Release from source workspace to be processed during import. If nothing is specified in the "task" prompt - newest release from source workspace is used. 

  • HigherVerOnly: false
    If set to true, objects from import table are processed only if they have version higher than current.

  • CurrReleaseOnly: true
    If set to true, creates an incremental import table containing only object changes since the previous release(s) in the source workspace(s).

  • CompleteTasksOnly: true
    If set to true, only objects from completed tasks are concidered for import table.

  • IncludeAll: true
    If set to true, all objects are included into import process.

  • ApplyImport: true
    Release from source workspace to be processed during import. If nothing is specified in the "task" prompt - newest release from source workspace is used. 

  • ReportAfterBuild: false
    If set to true, an import report is created after the creation of the import table.

  • ReportAfterApply: true
    If set to true, an import report is created after the import table was applied. 

  • DeleteAfterApply: true
    If set to true, an import table is deleted after import process.

  • MailResult: true
    If set to true, the log results from the import will be sent as an attachment to an email. 

  • MailResultDetail: true
    If set to true, the log results from the import will be sent as an attachment to an email,  in addition to that log content is added to email body.

  • DeleteExistingImportTable: true
    If set to true, an existing import table is deleted. 

  • CompileAfterImport: true
    If set to true, specified workspaces are compiled after import process.  

  • CreateTaskForImport: true
    If set to true, a task is created for import process. 

  • CompleteImportTask: true
    If set to true, import task is competed after import process. 

  • MaxWorkspaces: "${RtbMaxWorkspaces}"
    Setting is usually inherited from the base property settings. Alternatively can be set to a specific number.

  • ProcessImportTableTasks: true
    If set to true, a list of tasks with compilation errors is created.

Schema updates

Schema update properties

The following properties are relevant for schema update processing: 

  "RtbSchema": [
    {
      "WspaceId": "prompt",
      "RtbUser": "${RtbUser}",
      "RtbPassword": "${RtbPassword}",
      "DbList": "",
      "DeleteExistingSchupd": false,
      "ProcessSchema": false,
      "SkipAllSchemaUpdates": true,
      "DeleteAfterprocess": false,
      "MailResult": "${BuildMailResult}",
      "MaxWorkspaces": "${RtbMaxWorkspaces}"
    }
  ]

 

  • WspaceId: "prompt"
    When set to "prompt" the user will be prompted for the workspace(s) to be processed during schema update. This can also be set to a specific workspace.  
    Another option is to set the RtbImportWspaceId property when the automation task is run (i.e. as a property set with the command executing the script). Properties that are set with the command take precedence and override the contents of the properties file.  

  • RtbUser: "${RtbUser}"
    Setting is usually inherited from the base property settings. 

  • RtbPassword: "${RtbPassword}"
    Setting is usually inherited from the base property settings. 

  • DbList: ""
    Database(s) to be processed during schema update. If left empty all workspace databases are processed.

  • DeleteExistingSchupd: false
    If set to true, an existing schema update procedure is deleted before schema update process. 

  • ProcessSchema: false
    If set to true, schema change table(s) are applied to database(s).

  • SkipAllSchemaUpdates: true
    If set to true, all objects are considered up-to-date, get status 'Compl' and don't show up in subsequent builds. 

  • DeleteAfterprocess: false
    If set to true, schema update table is deleted after schema update process is over. 

  • MailResult: "${BuildMailResult}"
    Setting is usually inherited from the base property settings. Alternatively can be set to 'true' or 'false'. If set to true, the log results from the import will be sent as an attachment to an email. 

  • MaxWorkspaces: "${RtbMaxWorkspaces}"
    Setting is usually inherited from the base property settings. Alternatively can be set to a specific number.

Workspace Deployments

The toolkit can also be used to create deployments from Roundtable workspaces. 

Deployment properties

The following properties are relevant for deployment processing: 

"RtbDeployment": [
    {
      "WspaceId": "prompt",
      "RtbUser": "${RtbUser}",
      "RtbPassword": "${RtbPassword}",
      "DeploymentSiteCode": "Default",
      "DeploymentSequence": 0,
      "DeploymentReleaseNum": 0,
      "DeploymentDir": "${RtbDeploymentBaseDir}/<workspace-id>/<site-code>/<release-num>",
      "IncludeSchema": false,
      "MarkCompleteAfterMake": true,
      "MailResult": true,
      "CreateReport": true
    }
  ]

 

  • WspaceId: "prompt"
    When set to "prompt" the user will be prompted for the workspace(s) to be processed during deployment. This can also be set to a specific workspace.  
    Another option is to set the RtbDeploymentWspaceId property when the automation task is run (i.e. as a property set with the command executing the script). Properties that are set with the command take precedence and override the contents of the properties file.  
     

  • RtbUser: "${RtbUser}"
    Setting is usually inherited from the base property settings. 
     

  • RtbPassword: "${RtbPassword}"
    Setting is usually inherited from the base property settings. 
     

  • DeploymentSiteCode: "Default"
    This indicates that the deployment site marked as the default deployment site for the workspace will be used during deployment processing. 
     

  • DeploymentSequence: 0
    If 0, then the deployment sequence will automatically be incremented - if there is a release to deploy and a new deployment is created during processing. 
     

  • DeploymentReleaseNum: 0
    If 0, then the latest release in the workspace will be used - if there is a release that has not yet been used by this site to deploy. 
     

  • DeploymentDir: "${RtbDeploymentBaseDir}/<workspace-id>/<site-code>/<release-num>"
    This defines the directory structure of the created deployment.
     

  • IncludeSchema: false
    If set to false, schema is not included in created deployments. Set this to true if schema should also be included. 
     

  • MarkCompleteAfterMake: true
    If set to true, then the deployment will automatically be set to complete once the deployment has been successfully created.
    In some setups, it is common practice to leave a deployment open until it has been processed, delivered and approved. 
     

  • MailResult: true
    If set to true, the log results from the deployment will be sent as an attachment to an email. 
     

  • CreateReport: true
    If set to true, a report is created after the deployment. 

Preparing for deployments

Before deployment processing automation can be used, some setup is required in Roundtable. This can only be done from the RTB GUI client.

Create deployment site

In a workspace to make deployments from (e.g. production) you need to create a Roundtable Deployment Site first. 

Default deployment site

If this site is to be used as a "default site" for deployment from this workspace - add the following to the Site Notes:

DefaultSite=True

This property is used by the deployment process if a workspace deployment site of "Default" is specified. 

It is recommended that this is set even if there is only one deployment site in a workspace. 

Deployment directory

The default structure for the location of deployments is set as a property. The default settings are : 

"DeploymentDir": "${RtbDeploymentBaseDir}/<workspace-id>/<site-code>/<release-num>"

This ensures that all deployments are made into the same base directory and that the structure of deployments is the same for all workspaces. If you want do use a different structure, change the property and test to make sure it works as expected. 

Creating a deployment

When the workspace deployment site is set up, the only missing pre-requisite is creating a release in the workspace. This is a standard requirement for making deployments in Roundtable.

More details on how deployments work in Roundtable can be found in the Roundtable 11.5 User Guide
 

Writing custom processes 

  • No labels
Write a comment…