Introduction

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.

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 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>
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\TX DWA Server\<TX DWA Server 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 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