Running a Task Outside Automate (Command-line Operation)

Introduction

Occasionally users may have a need to run a task created in Automate from outside of Automate. Usually the user wishes to run the task from one of the following:

• A batch file
• An external program
• The command line
• A desktop icon

The files AMTask.exe and AMTaskCm.exe (collectively AMTask) exist for this purpose and can be found in the Automate folder which is installed (by default) at "C:\Program Files\Automate 6\".

How to use AMTask
Proper usage of AMTask.exe or AMTaskcm.is entering the default installation path of AMTask.exe or AMTaskCm.exe enclosed in parenthesis, followed by the path location of the .AML file associated with the task, also enclosed in parenthesis (see the syntax examples below). Once started, AMTask does not end until the task specified on the command-line parameter has finished processing.

Command Line Options 
AMTask accepts several command-line parameters to control its operation:

• Taskname
  The filename of the task to run. If the task file name includes spaces it must be surrounded in quotes or improper operation will result. The first parameter must be "taskname". 
• /v:varname1=value1
  Specifies variable(s)/value(s) to pass to the task. Format is semi-colon delimited name=value pairs. For 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: This parameter is only available in AMTask.exe
• /? 
  Display a message box (or output to standard output) the usage and syntax help.

Since the variable 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.

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. Additionally, AMTaskCm.exe emits proper return codes: 0 for task success, 1 for task failure and 2 if the task stops.

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 its 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 then? 
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
The following are syntax examples that can used when running a task outside of the Task Administrator.

Get help
"C:\Program Files\Automate 6\AMTask.exe" /?

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

Run a task and pass variables 
"C:\Program Files\Automate 6\AMTask.exe" "C:\Documents and Settings\All Users \Documents\My Automate Tasks\check email.aml" /v:MyName=MrJones;Phone=213-738-1700

Applies To: Automate 5, Automate 6 

For more on variables, datasets and expressions, watch this tutorial.