DMT - Using the DMT Command Line

Using the DMT Command Line

---

The CAST Delivery Manager Tool (DMT) is provided with a Command Line utility that can be used in various scenarios. Before you can use the Command Line utility, there are various prerequisites.

• Prerequisites
• Scenarios
• How does it work?
• Required common batch file parameters
• Required Batch file parameters for one single Delivery Manager scenario
• Required Batch file parameters for multiple Delivery Manager scenario
• Notes about the -logFilePath parameter in a Linux environement
• Notes for using the CAST Delivery Manager Tool CLI via a web proxy

Prerequisites

• All Delivery Managers must be working in CAST AIC Portal mode. If you are working with the CAST Delivery Manager Tool launched directly from the CAST Management Studio, you should use the CAST Management Studio command line instead.
• All Delivery Managers must have already Delivered and Closed one Version (including packages) using the CAST Delivery Manager Tool GUI interface and have that Application and Version in their local copy of the DMT - this is because the aim of the command line options is to automate the delivery of a Version "n+1" and all its Packages - i.e. you can automate this process via the command line when your source code has changed and you do not need to add additional packages, however, the Version "n" must exist already.

Scenarios

The DMT command line utility is designed for the following scenarios, ONLY:

• One single CAST Delivery Manager - can automate the delivery of a Version "n+1" and all its Packages, e.g.: it is possible to add a new Version "n+1" (copied from an existing Version "n"), package the same packages created in Version "n" and deliver the Version "n+1" (with "close" option).
• Multiple CAST Delivery Managers:
  • Delivery Manager 1 - can add a new Version "n+1" (copied from an existing Version "n"), package his/her packages and deliver the Version "n+1" (with no "close" option)
  • Delivery Manager 2 - can refresh to import the latest Version "n+1" delivered by Delivery Manager 1, package his/her packages and deliver the Version "n+1" (with "close" option if he/she is the last Delivery Manager)

How does it work?

In CAST AIC Portal mode, the CAST Delivery Manager Tool is launched from the CAST AIC Portal using the Java Network Launch Protocol. The same is true for the command line utility and as such, you must use batch files containing the required instructions to run your operations.

For each of the above scenarios, a batch file requires certain common configuration parameters, and then parameters that are specific to each action. These are explained below.

Please note that when launching the CAST Delivery Manager Tool via the CLI for the first time, you may be prompted that the application represents a security risk - which can hinder command line operations. Please do the following to prevent this dialog box displaying again in subsequent command line operations:

- tick the "Do not show this again..." option - Click Run.

Required common batch file parameters

Each batch file you create requires the following common parameters to launch the CAST Delivery Manager Tool in command line mode - you should modify them all (except the JNLP_FILE parameter) and match them to your local environment:

REM ===============================================REM = DMT - ConfigurationREM = Please do not change the JNLP_FILE parameterREM ===============================================set AICPORTAL_HOST=<name of machine hosting CAST AIC Portal - see below>set AICPORTAL_PORT=<port used by the application server hosting the CAST AIC Portal, e.g.: 8080>set AICPORTAL_WEBAPP=<Name of the CAST AIC Portal web application, e.g.: CAST-AICPortal>set APPLICATION_ID=<Application ID - this can be found in the DMT in the Application screen and will consists of a string of random characters and letters - see below>set AUTH=<The DMT requires authentication with CAST AIC Portal credentials prior to launch - see below for format>set JNLP_FILE=http://%AICPORTAL_HOST%:%AICPORTAL_PORT%/%AICPORTAL_WEBAPP%/%APPLICATION_ID%/dmt-launcher.jnlp?url=http%%3A%%2F%%2F%AICPORTAL_HOST%%%3A%AICPORTAL_PORT%%%2F%AICPORTAL_WEBAPP%

AICPORTAL_HOST

Please note that the value used in the AICPORTAL_HOST variable is case sensitive. Please ensure that you use the SAME case for the CAST AIC Portal host name as used when accessing the CAST AIC Portal in your web browser to download the GUI version of the CAST Delivery Manager Tool. This can be determined by looking at the start menu item for the GUI version of the CAST Delivery Manager Tool installed on your workstation.

For example - the host name is displayed as highlighted below:



Failure to do so will cause a second instance of the CAST Delivery Manager Tool to be downloaded when you run the batch file, and this will point to a different local workspace.

APPLICATION_ID

You can determine the APPLICATION_ID value in the CAST Delivery Manager Tool:



AUTH The DMT requires authentication with the CAST AIC Portal credentials prior to launch - and this applies in command line mode (as well as in GUI mode). Use the following format to define the credentials that you wish to use to authenticate when the command line is run - the example below shows the default "cast" username with the default "cast" password (modify this as required):

set AUTH=-username cast -password cast

This will send the username and password in clear-text - if you need to encrypt the password to improve security (highly recommended), you should instead generate an encryption key (please see Encrypting the password for the DMT command line for more information) for your password and use it as follows:

set AUTH=-username cast -authkey <your encrypted key>

For example:

set AUTH=-username cast -authkey u0tjM5qkCZO8IpzrD0CYUw==

If the authentication fails (incorrect username/password, or user not authorised), then the action specified in the command line will fail. If any errors occur, they will be logged in the latest CAST-jnlpInstaller.CastLog2 file created in C:\Users\<user_name>\AppData\Local\Temp, as shown by the following dialog:



Clicking OK will cause another dialog to be displayed:



By clicking the Details button you can see the java exception stack trace:

Required Batch file parameters for one single Delivery Manager scenario

In this scenario, we have one Delivery Manager who is responsible for all source code. In this case, the Delivery Manager can run one command line batch that will automate the creation of a new version (copied from an existing version) - V2, package the same packages and deliver the Version (V2) with "close" option.

AutomateVersion

• -application
• [-version] > Note that this parameter is optional (if you omit it, then the last Version (I.e. the most recent) will always be used
• -name
• [-releaseDate] > Note that this is optional (defaults to current date if not set)
• [-logFilePath]

REM ========================================================REM = AutomateVersion - one single Delivery Manager scenarioREM = Please only modify the path to your Java JRE "bin" folder REM = note the quote marks that must be used for this pathREM = if it contains spaces.REM ========================================================set APPLICATION=<Name of the Application that you are working with>set VERSION=<Name of the Version which will be copied>set NAME=<Name of the new Version which will be created>set RELEASE_DATE=<Date of release of the Version, e.g., YYYYMMDDHHSS>set LOG_FILE_PATH=<Absolute path to the folder that will be used to store the log files generated using the command line, e.g. C:\TEMP - this folder must exist already!>set ACTION_AUTOMATE=AutomateVersion -application \"%APPLICATION%\" -version \"%VERSION%\" -name \"%NAME%\" -releaseDate \"%RELEASE_DATE%\" -logFilePath \"%LOG_FILE_PATH%\""C:\Program Files (x86)\Java\jre7\bin\javaws.exe" %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_AUTOMATE%"

What you should expect after running the batch

Required Batch file parameters for multiple Delivery Manager scenario

In this scenario, we have Version V1 containing two packages that has been delivered and closed. We have two Delivery Managers:

• DM1 is the "first" Delivery Manager and is responsible for the database source code (TSQL_CASTPUBS)
• DM2 is the "last" Delivery Manager and is responsible for the client source code (VB_CASTPUBS)

Step 1 - DM1 (first Delivery Manager) will create a new Version

In this example, DM1 will create a new Version (V2) from V1.

AddVersion

• [-application]
• [-version]
• -name
• [-releaseDate] > Note that this is optional (defaults to current date if not set)
• [-logFilePath]

set APPLICATION=<Name of the Application that you are working with>set VERSION=<Name of the Version which will be copied>set NAME=<Name of the new Version which will be created>set RELEASE_DATE=<Date of release of the Version, e.g., YYYYMMDDHHSS>set LOG_FILE_PATH=<Absolute path to the folder that will be used to store the log files generated using the command line, e.g. C:\TEMP - this folder must exist already!>set ACTION_addVersion=addVersion -application \"%APPLICATION%\" -version \"%VERSION%\" -name \"%NAME%\" -releaseDate %RELEASE_DATE% -logFilePath \"%LOG_FILE_PATH%\""C:\Program Files (x86)\Java\jre7\bin\javaws.exe" %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_addVersion%"

After running this step, you should expect the following:

Step 2 - DM1 (first Delivery Manager) Packages his specific source code Package

In this example, DM1 will package his database source package, because the database has changed since V1. We are using the -reset option because the source code has changed.

Generate

• [-application]
• [-version]
• [-package]
• [-reset] > Note that this is optional, it will force the package to be extracted
• [-forceScan] > Note that this is optional, it will force the CAST Delivery Manager Tool to run the scan step. This is recommended when you are re-packaging source code following the installation of a CAST AIP Extension.
• [-logFilePath]

set APPLICATION=<Name of the Application that you are working with>set VERSION=<Name of the Version that you are working with>set PACKAGE=<Name of the source code package to Package>set LOG_FILE_PATH=<Absolute path to the folder that will be used to store the log files generated using the command line, e.g. C:\TEMP - this folder must exist already!>set ACTION_Generate=Generate -application \"%APPLICATION%\" -version \"%VERSION%\" -package \"%PACKAGE%\" -reset -logFilePath \"%LOG_FILE_PATH%\""C:\Program Files (x86)\Java\jre7\bin\javaws.exe" %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_Generate%"

After running this step, you should expect the following:

Step 3 - DM1 will Deliver the version to the CAST AIC Portal

In this example, DM1 will now Deliver the Version (including his package) to the CAST AIC Portal. DM2 (and other Delivery Managers if they exist) will then be able to perform a Refresh and download V2 from the CAST AIC Portal. We are NOT using the -close action because we do not want to close the Version yet.

Deliver

• -application
• [-version] > Note this is optional, use -package instead if you need to Deliver just a Package.
• [-package] > Note this is optional, use -version instead if you need to Deliver just a Version.
• [-close] > Note that this is optional, it will force the Version to be closed (read-only)
• [-logFilePath]

set APPLICATION=<Name of the Application that you are working with>set VERSION=<Name of the Version that you are Delivering>set LOG_FILE_PATH=<Absolute path to the folder that will be used to store the log files generated using the command line, e.g. C:\TEMP - this folder must exist already!>set ACTION_Deliver=Deliver -application \"%APPLICATION%\" -version \"%VERSION%\" -logFilePath \"%LOG_FILE_PATH%\""C:\Program Files (x86)\Java\jre7\bin\javaws.exe" %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_Deliver%"

After running this step, you should expect the following:

Step 4 - DM2 refreshes the Version (V2) that was created by DM1

Refresh

• -application
• [-version] > Note this is optional, use -package instead if you need to Refresh just a Package.
• [-package] > Note this is optional, use -version instead if you need to Refresh just a Version.
• [-logFilePath]

set APPLICATION=<Name of the Application that you are working with>set VERSION=<Name of the Version that you are working with>set LOG_FILE_PATH=<Absolute path to the folder that will be used to store the log files generated using the command line, e.g. C:\TEMP - this folder must exist already!>set ACTION_Refresh=Refresh -application \"%APPLICATION%\" -version \"%VERSION%\" -logFilePath \"%LOG_FILE_PATH%\""C:\Program Files (x86)\Java\jre7\bin\javaws.exe" %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_Refresh%"

After running this step, you should expect the following:

Step 5 - DM2 (last Delivery Manager) Packages his specific source code Package

In this example, DM2 will package his VB source package, because the code has changed since V1. We are using the -reset option because the source code has changed.

Generate

• [-application]
• [-version]
• [-package]
• [-reset] > Note that this is optional, it will force the package to be extracted
• [-logFilePath]

set APPLICATION=<Name of the Application that you are working with>set VERSION=<Name of the Version that you are working with>set PACKAGE=<Name of the source code package to Package>set LOG_FILE_PATH=<Absolute path to the folder that will be used to store the log files generated using the command line, e.g. C:\TEMP - this folder must exist already!>set ACTION_Generate=Generate -application \"%APPLICATION%\" -version \"%VERSION%\" -package \"%PACKAGE%\" -reset -logFilePath \"%LOG_FILE_PATH%\""C:\Program Files (x86)\Java\jre7\bin\javaws.exe" %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_Generate%"

After running this step, you should expect the following:

Step 6 - DM2 will Deliver the version to the CAST AIC Portal

In this example, DM2 will now Deliver the Version (including his package) to the CAST AIC Portal. We are using the -close action because we want to close the Version as DM2 is the "last" Delivery Manager.

Deliver

• -application
• [-version] > Note this is optional, use -package instead if you need to Deliver just a Package.
• [-package] > Note this is optional, use -version instead if you need to Deliver just a Version.
• [-close] > Note that this is optional, it will force the Version to be closed (read-only)
• [-logFilePath]

set APPLICATION=<Name of the Application that you are working with>set VERSION=<Name of the Version that you are Delivering>set LOG_FILE_PATH=<Absolute path to the folder that will be used to store the log files generated using the command line, e.g. C:\TEMP - this folder must exist already!>set ACTION_Deliver=Deliver -application \"%APPLICATION%\" -version \"%VERSION%\" -close -logFilePath \"%LOG_FILE_PATH%\""C:\Program Files (x86)\Java\jre7\bin\javaws.exe" %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_Deliver%"

After running this step, you should expect the following:

Notes about the -logFilePath parameter in a Linux environment

When using the CAST Delivery Manager Tool command line interface in a Linux environment and when multiple Linux users are being used, care must be taken to ensure that the optional -logFilePath option is handled correctly:

When the -logFilePath option is not defined in the command line, a default path for the log will be used as follows:

• When the DMT is operated for the first time by user A, the log file directory structure is automatically created by the tool under /tmp. The new directories are owned by user A with access rights rwx------, i.e. only A can access these directories. The DMT will function correctly.
• If the DMT is then operated by user B, the DMT will try to access the default log file path under /tmp as user B, however, user B has no access rights to the path, therefore the DMT will fail because it cannot write to the log file path.

There are several options that can be used to avoid this issue:

1. Ensure that the -logFilePath option is always defined in the command line - this will ensure that the DMT will always be able to write to the log file regardless of the user that is used.
2. If it is not possible to define a -logFilePath and you want to rely on the Linux default log file location under /tmp there are several options available:
   • Set a custom TMPDIR environment variable for the each user that will be using the DMT, for instance /tmp/UserA instead of just /tmp
   • At the end of each command line execution, remove the /tmp/.CAST directory and its content so that it will be created again when a different user uses the DMT
   • Grant rwx access rights on the whole directory structure starting at /tmp/.CAST to the new user

Notes for using the CAST Delivery Manager Tool CLI via a web proxy

If your organization uses a forward web proxy to control or improve performance of internet or intranet access, the CAST Delivery Manager Tool supports this. Note that HTTP proxies are fully supported, however, SOCKS proxies are untested. To support this, the DMT relies on Java's proxy configuration.

To configure a proxy in your command line, please alter the very last line in the batch file where the javaws.exe is called, for example:

"C:\Program Files (x86)\Java\jre7\bin\javaws.exe" %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_Deliver%"

You need to add the following two parameters, changing <value> respectively to the IP address of the proxy server and the port it functions on:

• -J-Dhttp.proxyHost=<hostIPAddress>
• -J-Dhttp.proxyPort=<hostPortNumber>

The following shows these parameters in action:

"C:\Program Files (x86)\Java\jre7\bin\javaws.exe" -J-Dhttp.proxyHost=10.0.1.50 -J-Dhttp.proxyPort=81 %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %ACTION_Deliver%"

Authentication

If your web proxy requires authentication, you need to use the following two parameters to allow auto login during the command line action:

• -pxUsername
• -pxPassword  or -pxAuthKey

CAST recommends that these parameters are added to your command line by setting a variable (%PXAUTH%) in the batch file - this variable should be set in the same location as the %AUTH% variable (see above):

set PXAUTH=-pxUsername JoeBloggs -pxPassword cast

This will send the username and password in clear-text - if you need to encrypt the password to improve security (highly recommended), you should instead generate an encryption key (please see Encrypting the password for the DMT command line for more information) for your password and use it as follows:

set PXAUTH=-pxUsername JoeBloggs -pxAuthKey <your encrypted key>

For example:

set PXAUTH=-pxUsername JoeBloggs -pxAuthKey u0tjM5qkCZO8IpzrD0CYUw==

You should then use the %PXAUTH% variable within the quote marks for the -open command as follows:

"C:\Program Files (x86)\Java\jre7\bin\javaws.exe" -J-Dhttp.proxyHost=10.0.1.50 -J-Dhttp.proxyPort=81 %JNLP_FILE% -Xnosplash -silent -wait -open "%AUTH% %PXAUTH% %ACTION_Deliver%"

---