MOVEit Automation API Command Line Client

MICentralClt is a command-line program that communicates with MOVEit Automation to start and monitor tasks.  It provides similar capabilities to the programmatic interface.  In other words, MICentralClt allows you to start tasks, wait for their completion, and return basic or detailed status information. 

Command-line syntax

MICentralClt is invoked as follows.  [] designates optional arguments. {} designates that one of the enclosed arguments is required.

MICentralClt  [-host:hostname] [-user:username] [-password:password] 
{-start:"taskname" | -startid:taskid} 
[-p:ParamName=Value] [-waitsecs:waitsecs] [-noxfers:err] 
[-rf:response_file] [-tf:task_file] [-sf:steps_file]
[-df:debug_file] [-D:debug_level]
where:
hostname is the name or IP address of the server running MOVEit Central.  The default is "localhost".
username is the Windows username of a user on the MOVEit Automation server that is a member of the "MOVEit Admin" user group.  This is not required and is ignored if the hostname is "localhost" or "127.0.0.1".
password is the password of the above user; it is not required and is ignored if the hostname is "localhost" or "127.0.0.1".
taskname is the name of a task to start.  If the name contains spaces, you must surround the name in double quotes; for instance, either -start:"Detroit Report" or "-start:Detroit Report".  
taskid is the ID of a task to start.  This is rarely used; although MOVEit Automation uses task IDs internally, most users refer to tasks by name.
ParamName=Value  is an optional task parameter to pass to the task.  You may specify the -p:ParamName=Value argument multiple times, to pass multiple task parameters to the task.  Enclose the argument with quote marks if the name or value includes spaces.  You may also use the syntax -p:ParamName:Value.
waitsecs is the number of seconds to wait, polling MOVEit Automation for the completion of the started task.  If this is not specified, the program will not wait for the task to complete.
noxfers is an alternate error code to return when the task being run results in a "No Action". The default is to return a value of "0" for both "Success" and "No Action" task runs.
response_file   is the name of a file to which the response will be written, indicating success or failure of the requested action.  The default is to write it to standard output.  
task_file is the name of an optional output file that will contain the overall results of the task run.  See Overall task status format.
steps_file is the name of an optional output file that will contain the details on the individual steps of the task run.  See Detailed job step status format.
debug_file is the name of a file to which a debug log will be written.  The default is "MICentralClt.log" in the current directory.
debug_level indicates the verbosity of the debug file.  The default is 0, which shows only internal errors.  A value of 40 logs basic actions, while 60 is fairly verbose.  Other values may be defined in the future.

Response file

MICentralClt writes a response file to indicate whether it was successful in starting the task, and if the task completed, whether the task run successfully.

The response file consists of several ASCII lines.  Each line contains a tag name, a colon, a space, and a value.  The lines have the form:

Tag name    Meaning
ErrorCode An integer error code, with the following meanings:
  • 0 means no error.
  • 5500 means the task started, but did not complete within the timeout value specified on the MICentralClt command line.
  • Other values, indicating various reasons for failure.
Because of the large number of different error codes, it is best simply to check this value for 0, 5500, or other.
ErrorDescription   A description of the error.  If the value is empty, there was no error.
TaskID The ID of the task.  If the task was started by name (with the -start parameter), this value will be filled in with task ID obtained from MOVEit Automation.
TaskName The name of the task.
NominalStart The time at which MOVEit Automation received the request to start the task.  The task may not have actually started until shortly afterward.  If the task did not start, this is empty.  The time is in the form: YYYY-MM-DD HH:MM:SS.
TimeEnded The time the task ended.  This value can be empty for these reasons:
  • The task did not start
  • MICentralClt was not instructed to wait for task completion
  • The timeout interval specified by -waitsecs was reached and the task had not yet completed.

Examples

Note: A complete example involving the use of the command-line app and several task parameters to drive a template task that uploads files to different destination hosts and paths (determined at runtime) is available as a Knowledge Base ("KB") on our support site (https://moveitsupport.ipswitch.com).

Here is an example of a successful task run:

   

MICentralClt -start:"Detroit Report" -waitsecs:90

Response:

ErrorCode: 0
ErrorDescription:
TaskID: 367869478
TaskName: Detroit Report
NominalStart: 2005-09-25 12:57:00
TimeEnded: 2005-09-25 12:57:06

Here is an example of a task run that started successfully, but failed due an error on a source:

   

MICentralClt -host:centsrv1 -user:miadmin -password:password -start:"Get from filesystem" -waitsecs:60

Response:

ErrorCode: 6
ErrorDescription: Could not access filesystem c:\zzzzbad on try 1 of 1: The system cannot find the file specified.
TaskID: 652946401
TaskName: Get from filesystem
NominalStart: 2005-09-25 13:21:16
TimeEnded: 2005-09-25 13:21:16

Here is an example of a failure due to a misspelled task name:

   

MICentralClt -start:"zzzMonthly Reports" -waitsecs:60

Response:

ErrorCode: 4020
ErrorDescription: No such task name: zzzMonthly Reports
TaskID:
TaskName: zzzMonthly Reports
NominalStart:
TimeEnded:

Here is an example of a task that started, but did not complete within the specified wait period:

   

MICentralClt -start:"Chicago Report" -waitsecs:60

Response:

ErrorCode: 5500
ErrorDescription: The task did not complete within the specified wait time
TaskID: 156967384
TaskName: Chicago Report
NominalStart: 2005-09-25 13:07:38
TimeEnded:

Return code

MICentralClt's return code (the value returned to the %errorlevel% variable in a batch file) is the same as the ErrorCode in the response file (unless no files have been transferred and the -noxfers option has been specified).