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:
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:
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:
The following script snippet shows an example of how to use this command:
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:
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:
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:
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:
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:
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:
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:
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:
A sample output from running the above script is as follows:
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:
The return value from the command is a server status object. The following methods are available on the object:
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:
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:
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:
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:
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:
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:
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:
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:
A sample output from running the above script is as follows:
This command can only be executed with administrator or security authority.
Last updated