Command-Line Operation (AMTask/AMTaskCm)

Overview

Typically, a user can manually execute tasks from the Task Administrator by selecting the desired tasks and simply clicking the Run button. The Task Builder includes a Run button as well, mainly to enable manual execution of a task for testing purposes. However, there are occasions when a user may require a need to manually execute a task from outside of the Task Administrator or Task Builder. For instance he/she may wish to run a task from:

  • A batch file

  • An external program

  • The command line

  • A desktop icon

The files AMTask.exe and AMTaskCm.exe (collectively, AMTask) exist for such occasions. Both AMTask.exe and AMTaskCm.exe can be found in the Automate Desktop 2024 program files folder normally located (by default) in the following directory:

C:\Program Files\Automate Desktop 2024

The full path and file name of AMTask is: C:\Program Files\Automate Desktop 2024\AMTask.exe

The full path and file name of AMTaskCM is:C:\Program Files\Automate Desktop 2024\AMTaskcm.exe

Using AMTask/AMTaskCM

In order to properly use AMTask or AMTaskCm, you must enter the path and file name of AMTask.exe/AMTaskCm.exe surrounded by quotation marks [ " " ] , followed by a space, then the path and file name of the .AML file associated with the managed task, also surrounded by quotation marks. For example, to run a managed task named 'My_Report' outside of Automate Desktop, enter the following syntax:

"C:\Program Files\Automate Desktop 2024\AMTask.exe" "C:\ProgramData\Automate Desktop 2024\Tasks\My_Report.aml"

Command-line parameters

AMTask allows one or more variables to be passed to the task during execution and accepts several command-line parameters to control its operation. Syntax examples are entered below.

  • Taskname - The file name of the task to run. If the task file name includes spaces - it should be surrounded in quotes or improper operation will result. The first parameter must be “taskname”.
  • /v:varname1=value1 - This optional parameter specifies one or more variables along with their values to pass to the task. If specifying more than one variable name=value pairs, use a semi-colom to properly delimit each. Example: /v:varname1=value1;varname2=value2;varname3=value3
  • /password <password> - If the task is password protected, use <password> to decrypt the task before execution.
  • /passwordprompt - Prompt for the password if the task is password protected and the /password parameter has not been specified.
    NOTE: The /passwordprompt parameter is only available in AMTask.exe and not AMTaskCm.exe. This is because AMTaskCm is a console application designed to run from a command prompt.
  • /? - Display a message box (or output to standard output) the usage and syntax help.

Since the list is semi-colon delimited, semi-colons are not allowed in the variable name or value to pass. This can be worked around by replacing a semi-colon with another special character before passing it to AMTask and configuring the task to replace it back to a semi-colon at run time using an embedded expression in the task. For example, if an exclamation point were used as a replacement character for a semi-colon, a Set Variable action at the beginning of your task using the expression Replace$(var1, "!", ";") as the new variable data would convert the exclamation points back to semi-colons.

Behavior

Once started, AMTask does not end until all of the steps of the task (specified on the command-line parameter) has finished processing. Once finished, AMTask returns 0 if the task failed to finish properly and 1 if the task was successful.

The difference between AMTask.exe and AMTaskCm.exe

The two files AMTask.exe and AMTaskCm.exe work exactly the same with the exception of one characteristic. AMTask.exe is a pure Windows application and is designed to run a task and return to a Windows application when the task specified has been completed, whereas AMTaskCm.exe is a “console application” and is designed to be run from a command prompt or batch file.

Why two files?

True windows applications will return immediately when run from the command prompt regardless of when they actually finish running; thus, using the original AMTask.exe one would not be able to determine when the launched task finished or retrieve a return code to determine it’s success or failure. To avoid this behavior, use AMTaskCm.exe, which is designed for use in a console (command line or batch-file) environment.

Why not always use AMTaskCm.exe?

When AMTaskCm.exe (a console application) is invoked from a true Windows application (not from the command prompt) it causes a command prompt (AKA DOS box) to appear if one was not already open. This is not visually appealing and can confuse users. The rule to remember is:

  • Use AMTask.exe when launching from a Windows application, macro/script, or windows itself.

  • Use AMTaskCm.exe when launching from the command prompt, a DOS based application or most importantly, a batch file.

Syntax examples

Get help - "C:\Program Files\Automate Desktop 2024\AMTask.exe" /?

Run a task - "C:\Program Files\Automate Desktop 2024\AMTask.exe" "C:\Documents and Settings\All Users.WINDOWS\Documents\My Automate Desktop Tasks\check email.aml"

Run a task and pass variables - "C:\Program Files\Automate Desktop 2024\AMTask.exe" "C:\Documents and Settings\All Users.WINDOWS\Documents\My Automate Desktop Tasks\check email.aml" /v:VARNAME1=VALUE1,VARNAME2=VALUE2