TCL Script Writer Reference

Version: 10.0 / Modifications: 0

Using the scripting interface

The Tomorrow Software console ships with a scripting interface to facilitate automated management by other tools. The scripting interface is based on the TCL (Tools Command Language) version 8.4 syntax and commands, but also includes a number of Tomorrow Software specific commands.

As scripting is a programming interface, the scripting engine is not multi-lingual. It is invoked by a simple HTTP/S POST command to the URL:

http://<server>/console/ScriptRunner

The parameters for the POST are as follows:

Parameter

Value

user

The console user ID under which the script will be executed

password

The password for the user

script

The script to execute

All parameters should be UTF-8 encoded.

Learning TCL

It is beyond the scope of this manual to provide complete details of the TCL language. TCL has been in use for many years and plenty of online resources exist for learning the language. An excellent primer can be found here:

https://www.tcl.tk/

Also, several sample scripts can be found in the /Education/script samples folder.

Testing scripts

To assist with testing scripts, a specific page has been made available:

http://<server>/console/scriptRunner.jsp

This page allows you to enter a user ID and password, as well as a script, and submit it to the console. The output from the submission is returned to the browser.

Tomorrow Software specific TCL extensions

Tomorrow Software introduces a number of extensions to the standard TCL language. All of the extensions relate to specific console management tasks.

In addition, output written with the "puts" command is written to the HTTP Response stream rather than STDOUT.

Command: createUser

The createUser command creates a new console user. The command takes a number of parameters to correctly define a user in the console:

Parameter

Value

Logon

The console user ID for the new user

Name

The full name of the user

Password

The initial password for the user

Email

The email address of the user

Type

The user type. Valid values are:

0 = Administrator

1 = Standard User

2 = Super User

3 = Security User

Role

The role name for the user. Can be blank if no role is required.

Time Zone

The new users time zone. Must correspond to the time zone list found in the appendixes of this manual.

Additional Auth

The class name of any additional authentication settings. Can be blank if no additional authentication is required. Please note that only basic authentication selections are available. Overrides (such as the number of digits for one-time emails) are not supported. Currently the following are valid additional auth classes:

software.tomorrow.authenticate.OneTimeEmailPlugin

software.tomorrow.authenticate.LocalHostPlugin

The following script snippet shows an example of how to use this command:

createUser test123 "Test User" test123 test@test.com 1 "" GMT ""

This command can only be executed with administrator or security authority.

Command: deployConfiguration

The deployConfiguration command deploys a specific configuration to a nominated server. Only configurations located in a repository can be deployed using this command. The parameters for the command are Server ID, Repository Name and Configuration Name. The following script snippet shows an example of how to use this command:

deployConfiguration Qwerty "Product Trial" BasicWebTrial

The command will wait for the deployment task to complete before continuing. The deployment does not result in a server restart. The stopServer and startServer commands should be used after this command to ensure that the deployed configuration takes effect. This command is only valid for production servers.

Command: deleteUser

The deleteUser command deletes a user based on a provided user ID. The following script snippet shows an example of how to use this command:

deleteUser super

This command can only be executed with administrator or security authority.

Command: getAudit

The getAudit command retrieves a subset of the internal Tomorrow Software audit log. The following snippet shows an example of how to use this command:

set clause "WHERE ACTIONTIME>1425064936463 ORDER BY ACTIONTIME DESC"
set auditRows [getAudit $clause]
puts "Row count = [$auditRows length]<p>\n"
for { set i 0 } { $i < [$auditRows length] } { incr i } {
puts "[$auditRows get $i]<p> \n"
}

The above commands retrieve all audit log entries after the Java Time Stamp 1425064936463.

This command can only be executed with administrator or security authority.

Command: getConfiguration

The getConfiguration command reads a specific configuration from a specific repository and provides access to all elements of the configuration (including the ability to update it if the user has the appropriate authority.

The following script snippet shows an example of how to use this command:

set cnf [getConfiguration "Product Trial" BasicWebTrial]
puts "Configuration rule set [$cnf getRuleSet]"
$cnf setTestDataDepth 20000
$cnf update

The above command obtains the BasicWebTrial configuration from the Product Trial repository, outputs the default rule set file name and then sets the maximum number of test records to 20,000 before updating the configuration (writing it to the file system).

The following table provides a list of all of the readable properties on the configuration object:

Method

Return value

getAttributeLabels

An array of strings with the input field labels of the configuration

getAttributeNames

An array of strings with the input field names of the configuration

getAttributeValues

An array of strings with the input field values of the configuration

getContentRuleSet

The file name of the content rule set

getDatabaseAliases

An array of strings with the database aliases of the configuration

getDatabaseDrivers

An array of strings with the database drivers of the configuration

getDatabaseNames

An array of strings with the database names of the configuration

getDatabaseSchemas

An array of strings with the database schemas of the configuration

getDatabaseSystems

An array of strings with the database system names of the configuration

getDescription

The description of the configuration

getDirectory

The directory where the configuration is located

getDoneRuleSet

The file name of the completion rule set

getFileName

The file name of the configuration

getInitRuleSet

The file name of the startup rule set

getInputClass

The class name of the input adaptor used by the configuration

getInputParms

A string with the input parameters passed to the configuration upon startup

getLoopPrevent

The maximum number of chain point interactions before a rule set is considered looping

getName

The configuration name

getPerformanceLevel

The level of performance data collection

0 = Transaction counts

1 = Transaction count and inline time

2 = Transaction count, inline time and URI statistics

3 = All counters

getRuleSet

The base rule set file name

getServerType

The server type

0 = Production

1 = Test

getTestDataDepth

The maximum number of test data collected

getTimerDelays

An array of strings with the timer delay in seconds for each timer rule set of the configuration

getTimerNames

An array of strings with the timer rule set file names for each timer rule set of the configuration

getTimerTypes

An array of strings with the timer rule set types for each timer rule set of the configuration

0 = Real time

1 = Pause

isAutoStart

Set to 1 if this configuration is auto starting, 0 otherwise

isCollectTestData

Set to 1 if this configuration collects test data by default, 0 otherwise

isEchoOut

Set to 1 if this configuration provides an echo of console messages to System.out, 0 otherwise

isFailOpen

Set to 1 if this configuration fails open, 0 otherwise

Each of the above values can also be set using the equivalent setter method (replacing "get"/"is" with "set").

Please note that for any arrays, ALL arrays in a set (attributes, databases, timer rule sets) MUST be set to the same length before invoking update.

The TCL interface only supports updating existing configurations. New configurations cannot be created using TCL and existing configurations cannot be deleted.

Command: getUser

The getUser command reads a specific user and provides access to some elements of that user.

The following script snippet shows an example of how to use this command:

set usr [getUser test123]
puts "User name [$usr getName]"
$usr setRole analyst
$usr update

The above command reads the user test123, outputs the name of that user and then sets the role before updating the user.

The following table provides a list of all the readable properties on the user object:

Method

Return value

getAuth

The class name of any additional authentication. Can be blank.

getCreated

The time the user was first created in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT.

getEmail

The email address of the user

getLastLogon

The time of the user's last logon in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT.

getLogon

The user ID of the user

getName

The name of the user

getRole

The role set for the user (if any)

getTimeZone

The users time zone. Will contain a value from the time zone list found in the appendixes of this manual.

getType

The user type. Valid values are:

0 = Administrator

1 = Standard User

2 = Super User

3 = Security User

Most of the above values can also be set using the equivalent setter method (replacing "get"/"is" with "set"). The values that cannot be set are: Logon, Created and LastLogon.

This command can only be executed with administrator or security authority.

Command: serverList

The serverList command obtains a list of all configured servers in the console that the user is authorized to view. The response is in the form of an array of server IDs. The following script snippet shows an example of how to use this command:

set srvList [serverList]
puts "Server count = [$srvList length]<p>"
for { set i 0 } { $i < [$srvList length] } { incr i } {
puts "Server [$srvList get $i]<p>"
}

A sample output from running the above script is as follows:

Server count = 5
Server Console
Server LocalProxy
Server MPServer1
Server Qwerty
Server TestServer1

Command: serverStatus

The serverStatus command is used to interrogate the current status of a server, based on the server's ID. The following script snippet shows an example of how to use this command:

set srvId Qwerty
set srv [serverStatus $srvId]
puts "Server status = [$srv getStatus]<p>"
puts "Server is running = [$srv isRunning]<p>"

The return value from the command is a server status object. The following methods are available on the object:

Method

Return value

getBuild

The base rules build number for the server

isCollectTestData

A flag to indicate if the server is collecting test data.

0 = No

1 = Yes

getConfiguration

The name of the configuration currently deployed on the server

getConfUser

The name of the user that created the current configuration used on the server

getConfVersion

The version of the configuration currently deployed on the server

getDeployErrorCode

Any error code issued (if any) when attempting to deploy the last configuration to the server

getDeployFrom

The repository name from which the configuration was deployed

getDeployTime

The time the current configuration was deployed to the server in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT

getDeployUser

The name of the user that deployed the current configuration to the server

getDescription

The description of the configuration currently deployed on the server

getErrorCode

Any error codes detected on the server. The corresponding error messages are found in the "translation.properties" file for the console application.

getFlightRecorders

A string array with the IDs of any flight recorders in use by the currently deployed configuration

getHost

The host name of the server

getInputAdapter

The class name (identifier) of the input adaptor used for the current configuration

getInputParms

The input parameters provided to the configuration to be used in conjunction with the input adaptor. This is mainly used for file polling servers and in that instance provides the directory that is polled for files. For test servers it provides the input file name to the configuration.

getJavaVersion

The current version of Java used by the server

getLastStarted

The time the X Engine was last started in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT

getLastStopped

The time the X Engine was last stopped in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT

getLastTransaction

The time the X Engine was last invoked in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT

getMajorVersion

The major version number of the X Engine

getMinorVersion

The minor version number of the X Engine

getOperatingSystem

The operating system and version of the server

isPolling

If the server is polling for data (feed servers)

getPort

The port the server is accepting instructions from

getRevisionVersion

The revision version number of the X Engine

getRuleset

The name of the currently deployed rule set

isRunning

Whether the server is currently running (started).

getStatus

The status of the server. 0=Offline, 1=Online

getTestData

The number of available test data lines

isTraceData

If the server has trace data

isTraceMode

If the server is in trace mode

getTransactions

Number of transactions processed since last server start

getVersion

Full version number of the X Engine in text format

Command: setCredentials

The setCredentials command is used to set the value of a given field in the credentials vault. The specific vault and field must exist already.

The following script snippet shows an example of how to use this command:

setCredentials KapowSMS UserID Fred

This command can only be executed with administrator or security authority.

Command: startServer

The startServer command is used to start a nominated server.

The following script snippet shows an example of how to use this command:

startServer Qwerty

The command will wait for up to 30 seconds to ensure that the server is actually started. Provided the server starts, the command will return "1". If the server fails to start, then "0" will be returned.

Command: stopServer

The stopServer command is used to stop a nominated server.

The following script snippet shows an example of how to use this command:

stopServer Qwerty

The command will wait for up to 30 seconds to ensure that the server is actually stopped. Provided the server stops, the command will return "1". If the server fails to stop then "0" will be returned.

Command: userExists

The userExists command checks if a given user ID exists. The command returns "0" if the user ID is not found or "1" if the user ID is found. The following script snippet shows an example of how to use this command:

set checkUser admin
puts "User $checkUser exists [userExists $checkUser]"

This command can only be executed with administrator or security authority.

Command: updateApplication

The updateApplication command updates a console application (such as Qwerty or the console itself. The following script snippet shows an example of how to use this command. In this case the console itself will be updated:

updateApplication console

This command can only be executed with administrator authority.

Command: updateExtension

The updateExtension command updates/installs an extension from the update server (such as the Base Rules or the Http Rules). The following script snippet shows an example of how to use this command:

updateExtension "MaxMind Rules"

This command can only be executed with administrator authority.

Command: updateRepository

The updateRepository command updates/installs a repository from the update server (such as the Product Trial repository). The following script snippet shows an example of how to use this command:

updateRepository "Product Trial"

This command can only be executed with administrator authority.

Command: userList

The userList command obtains a list of all users in the console. The response is in the form of an array of user IDs. The following script snippet shows an example of how to use this command:

set usrList [userList]
puts "User count = [$usrList length]<p>"
for { set i 0 } { $i < [$usrList length] } { incr i } {
puts "[$usrList get $i]<p>"
}

A sample output from running the above script is as follows:

User count = 3
admin
security
super

This command can only be executed with administrator or security authority.

Last updated

General Website Terms & Conditions and Privacy Policy

Terms of UsePrivacy Policy

Contact Us

Get Help

© Copyright TomorrowX 2024 Composable Architecture Platform and Connected Agile are trademarks and servicemarks of TomorrowX.