Most often, you will execute projects from within TX DWA or on a schedule defined in TX DWA. It is, however, also possible to execute a project from the command line. This can be useful if you wish to trigger execution of projects in a script or on custom events.
Before you begin
When executing a package from the command line, Discovery Hub will execute the last deployed version of the project. A deployed version is a version of the project Discovery Hub is certain has been fully saved and committed.
Any change made to a project that is not part of a deployed version will be ignored by a command line execution. Changes that will be ignored include enabling or disabling slowly changing dimensions. As a result, running a package through the command line may result in loss of historical data unless you have created a deployed version of the project that includes that change!
To create a deployed version of a project be sure to either deploy a table in your project to create a deployed version, or save your project as a deployed version manually (for versions 14.6.1 and later).
Arguments and exit codes
The TX executable, timexetender.exe, can be run with two parameters: ProjectName and ExecutionPackage.
It returns the following exit codes:
- -1 = Execution failed; please refer either to the trace log file or Windows event log for details
- 0 = Project or execution package was not found
- > 0 = A positive integer value indicates a successful execution, referring to the batch ID that was assigned. Please refer to table ExecutionLogs for details about execution times.
The following example shows you how you can execute a project and review the exit code on the command line or in a batch file.
Start /Wait timextender.exe <ProjectName> <Execution Package Name> Echo %ERRORLEVEL%
If your project or execution package name has spaces in its name, you must surround the name with double quotation marks. An example would appear like so:
Start /Wait timextender.exe "My Project Name" "My Execution Package Name"
Qualifying the execution file path
The basic example above makes a call on "timextender.exe." In most cases this will not work as written, as the command will not be able to locate the file.
There are two ways around this issue. The first is to change directory to the folder that contains the TimeXtender executable before making the call. The full command might look like this:
CD C:\Program Files\TX DWA Server\<TX DWA Server Version>
Start /Wait timextender.exe <Project Name> <Execution Package Name>
Additionally, you can also fully qualify the call on timextender.exe. If you do this, you must also pass in an additional string as a title parameter. Since the title is not required for the command to run, you may pass in an empty string. This modified command might look like this:
Start /Wait "" "C:\Program Files\TX DWA Server\<TX DWA Server Version>\timextender.exe" <ProjectName> <Execution Package Name> Echo %ERRORLEVEL%
If the command is going to be part of a .bat file or run by a third-party scheduling service, you must keep permissions in mind if you want the command to run successfully. This is because the command inherits the permissions of the account that runs it. While the necessary permissions will differ depending on your setup, the account that runs the command must have:
- Permission to run an executable
- Permissions to read and write in the repository and all other involved databases
- Permission to read from the involved data sources
Without these permissions, the command may not start or may fail after starting.
When a user opens TX DWA, the software generates that user a configuration file that records the last project repository that user had open. Much like permissions, the command inherits these configuration settings from the account that runs it as well. In order to ensure that the execution package is run in the correct environment, the config file for that user must reference the correct repository.
The file can also be edited manually. The default extension for the file is:
C:\Users\<UserName>\AppData\Roaming\TX DWA Server\TX DWA Server\<TX DWA Version>\config.xml
Note that if an environment has a service user running a TX DWA Server service, that user will have the proper permissions and configuration to run command line executions by default.
This article applies to: timeXtender 4.5, tX2012, TX2014, TX DWA, Discovery Hub
Is it possible to publish a list of all command prompt parameters TX can accept? I noticed "TimeXtender.exe /?" doesn't show anything...
Have there been any improvements / additions in SR2 for the Command Line?
SR2 has not brought any changes to using TX from the command line. Executing a project, using the two parameters described above, is still the entire functionality.
If there's any particular functionality you'd like added, please feel free to post your idea in the Suggestions and feature requests forum.
I have an error showing timextender.exe is not located on the machine I am using cmd prompt. Does this remote control to be installed on the machine?
I worked with Satish and his team yesterday and we were able to resolve his problem. The issue was two fold;
Solution: We modified the config file nested under the UC4 service users appdata folder to point to their active repository. This resolved the issue.
Can you update this article to include this important piece of info?
Is it possible to execute at table/object level when invoking from command line. In other words, is there an option of passing table name as parameter to the start command.
We are trying to execute multiple tables in parallel, and want to have a finer grained control than at the package level.
Hi Raj, at this time, command line execution is only supported at the package level, not the table level.
Maybe off-topic but it would be really nice if you can trigger a script using REST API. And if go wild then It would be super cool to get notifications using webhook
Did I miss something here - can you also trigger Data Source transfer tasks from here, so that once the transfer of new data is complete, the execution package runs next? This way, if the transfer task from the data source to the DL takes longer (more data than expected) then the execution package won't run until it completes. There seems to be no method currently to trigger a transfer load within the execution packages - hoping that I'm wrong of course.