Command-Line Utility (AMExecute)

Overview

Typically, a user can manually execute a workflow or task from the Server Management Console by navigating to the Repository > Workflows or Tasks folder, right-clicking the desired object, and then selecting Run. The Workflow Designer and Task Builder includes a Run button to allow manual execution of workflows or tasks as well. However, there are occasions when a user may have a need to manually execute a workflow or task from outside of the Server Management Console, Workflow Designer or Task Builder. The Automate Command-Line Utility exists for this purpose.  

Like other Automate components, the Command-Line utility communicates with Automate by way of TCP/IP (whether the server component is installed locally or on a remote machine). This utility is ideal in situations where the user may wish to run a workflow/task from the following:  

  • Command line

  • Batch file

  • External program

  • Desktop icon

Using the Command-Line Utility

The Command-Line Utility uses the command name AMExecute. This executable file is a small application that runs independently from the main application and resides in the Automate program directory on the system where the Automate Development Tools (that is, SMC, WFD, TB) were initially installed. The utility's default path and file name is: C:\Program Files\Automate 2024\AMExecute.exe.

AMExecute is a Windows Command-Line application. This means that it does not have a graphical user interface (GUI) and, instead, must be run by way of the Windows Command prompt. Specific command-line parameters are used to create a command that can be sent to Automate in order to execute a given workflow/task. Parameters within the issued command determines the location of Automate, which workflow/task to execute and which Automate agent to perform the execution.

Required parameters

The Command-Line utility accepts several command-line parameters to control its operation. Certain parameters may or may not be required depending on what type of operation is to be performed. However, three parameters are always required when running AMExecute. These parameters, their associated values and example syntax are referenced in the table below.

Parameter Value Example
Server The hostname or IP Address of the machine where Automate is located. If Automate is installed locally, localhost can be entered as the value (Server Port is optional).
  • Server=ComputerName
  • Server=209.223.157.166
User A valid username used to connect to Automate as specified in the Users section of the SMC.
NOTE: The specified user's permissions must be set to allow manual execution of workflows/tasks as specified in the SMC under the user's Security properties. Only individual users can be specified (as opposed to user groups).
  • User=administrator
  • User="Batman"
Pwd Specifies the password associated with the username entered. password=mypassword

Workflow execution parameters  

To manually execute a workflow, the name or unique ID assigned to that workflow must be included in the command. Because a workflow should already contain the tasks as well as the Agents/Agent Groups that the task should run on, there is no need to enter task or agent information. The available workflow parameters are detailed in the table below.

Parameter Value Example
Workflowname The name assigned to the workflow as specified in the Workflows folder under the Repository tab of the SMC.
  • workflowname="backup workflow"
  • workflowname=\Workflows\subfolder\workflowname
WorkflowID A valid username used to connect to Automate as specified in the Users folder under the System tab of the SMC.
NOTE: The specified user's permissions must be set to allow manual execution of workflows/tasks as specified in the SMC under the user's Security properties. Only individual users can be specified (as opposed to user groups).  
 {workflowid=05a34556-0bb5-496c-a79e-9b67115fa0dc}

Task execution parameters

To manually execute a task, information regarding the task as well as the Agent or Agent Group that the task should execute on must be included in the command. The task name or task ID can be used to specify a task. If specifying an Agent, enter either the Agent name or Agent ID. If specifying an Agent group to run the task, enter either the Agent Group name or Agent Group ID. Available parameters are detailed below.

Parameter Value Example
Taskname The name assigned to the task as specified in the Tasks folder under the Repository tab of the SMC.
  • taskname="task name"
  • taskname=\Tasks\subfolder\taskname
TaskID The unique ID assigned to the task. All Automate objects such as a Agents, tasks, workflows or conditions are assigned a unique ID upon creation. Each object's unique ID can be found in its properties under the Details section. {taskid=82a7491e-b121-4f71-a6d8-3dc78337de05}
Agentname The name assigned to the Agent as specified in the Task Agents folder under the System tab of the SMC. agentname=Agent1
AgentID The unique ID assigned to the Agent. All Automate objects such as a Agents, tasks, workflows or conditions are assigned a unique ID upon creation. Each object's unique ID can be found in its properties under the Details section. {agentid=e92415e2-e714-485b-86e7-bc20a9ccec68}
Agentgroupname The name assigned to the Agent Group as specified in the Agent Groups folder under the System tab of the SMC. agentgroupname=AgentGroup1
AgentgroupID The unique ID assigned to the Agent Group. All Automate objects such as a Agents, Agent Groups, tasks, workflows or conditions are assigned a unique ID upon creation. Each object's unique ID can be found in its properties under the Details section. {agentgroupid=b4e2a9fc-4689-4f51-9c01-ce8a5ad0c2f4}

Command-line syntax

To run the Automate Command-Line utility, the default installation path of AMExecute.exe must be entered followed by various parameters (discussed above) and their associated values. An example of a command to run a task named "Upload Files" is  as shown below:

C:\Program Files\Automate 2024\AMExecute.exe Server=209.223.157.166 User=administrator Pwd=password TaskName="Upload Files" AgentName=DeveloperServer

Notes about the command-line syntax

  • There may be situations where identical tasks or workflows (that contain the same name) exists in the Repository. Therefore, a task or workflow referenced by a non-unique name will require the path to that object as specified under the Repository tab of the SMC. This provides a way for Automate to determine the correct task/workflow to execute. The base directory for tasks/workflows are shown below. Any subfolders created by the user would need to be entered as part of the path.

    • Workflow base directory: \Workflows
    • Task base directory: \Tasks

  • If a parameter value contains multiple words separated by spaces, the entire value string must be enclosed with double or single quotation marks (for example, taskname="Upload Files").

The example below shows a command to run a task that contains multiple words separated by spaces and also specifying the full path:

C:\Program Files\Automate 2024\AMExecute.exe Server=209.223.157.166 User=administrator Pwd=password TaskName=\Tasks\subfolder1\"Upload Files" AgentName=DeveloperServer

If the path is not entered for tasks/workflows with non-unique names, the user will be prompted to choose the path as illustrated below.

Other notes about the command-line syntax

  • A parameter's value immediately follows the parameter separated by an equal (=) sign (for example, user=administrator).

  • Parameter/value combinations must be separated by a single space (for example, user=administrator pwd=password server=209.223.157.166).

  • The order in which parameter/value strings are entered on the command line does not matter.

  • Parameters or associated values are not case sensitive.

  • For more help enter the path and file name to AMExecute.exe followed by a "?".