Most often, you will execute projects from within TimeXtender or on a defined schedule. It is, however, also possible to execute a project from the command line. This can be useful if you wish to trigger the execution of projects in a script or on custom events.
Before you begin
When executing a package from the command line, TimeXtender will execute the last deployed version of the project. A deployed version is a version of the project that TimeXtender 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 the 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 save as deployed or deploy a table in your project to create a deployed version.
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 the table ExecutionLogs for details about execution times.
Example
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%Additional considerations
Spaces
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 the directory to the folder that contains the TimeXtender executable before making the call. The full command might look like this:
CD C:\Program Files\TimeXtender\<TimeXtender Version>
Start /Wait timextender.exe <Project Name> <Execution Package Name>
Echo %ERRORLEVEL%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\TimeXtender\<TimeXtender Version>\timextender.exe" <ProjectName> <Execution Package Name>
Echo %ERRORLEVEL%Permissions
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.
User Configuration
When a user opens TimeXtender, 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\TimeXtender\TimeXtender Classic\<Version>\config.xmlNote that if an environment has a service user running a TimeXtender Server service, that user will have the proper permissions and configuration to run command line executions by default.
