MOVEit Automation API Overview

Overview

MOVEit Automation API allows you to connect to MOVEit Automation, start tasks, and obtain information on the status of currently running and completed tasks. It provides a subset of the capabilities of the human-oriented GUI MOVEit Automation Admin program, but also provides the ability to perform operations that cannot be accomplished through the GUI program alone, such as picking different sources (even ad-hoc hosts) at runtime and limiting the submission of tasks if the number of tasks already running is more than desired.

MOVEit Automation API flow

In ordinary use, MOVEit Automation starts tasks itself automatically, based on schedules that you configure, and/or based on notifications of the arrival of files. However, in some cases, you may want to control tasks or create/run temporary tasks from another application. For instance, you may have an existing scheduling application that is used for a number of different purposes and you want to integrate MOVEit Automation's secure transport and processing capabilities into it. MOVEit Automation API allows you to use such an application to control MOVEit Automation tasks.

When accessed with administrative credentials, reports about past task runs, file/folder activity and audit logs may be generated through MOVEit Automation API. Information about currently running tasks is also available to those applications providing administrative credentials.

This document describes the Microsoft Windows version of MOVEit Automation API. This consists of a command-line client and a programmatic interface. Both provide similar capabilities (though the programmatic interface provides more); choose which one to use according to your needs. The programmatic interface supports both 32-bit and 64-bit applications.

There is also a very similar Java version of the API. All versions require that the MOVEit Automation server being connected to be licensed for the MOVEit Automation API option.


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:j7df3g -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).


MOVEit Automation API Installation

Installation Overview

MOVEit Automation API can be installed on any system that needs to connect to MOVEit Automation in order to monitor or control tasks. The setup program for MOVEit Automation API installs both a command-line client and a programmatic interface.

MOVEit Automation API users should expect to upgrade MOVEit Automation API each time MOVEit Automation is upgraded in order to take advantage of new features in MOVEit Automation.

Installation Steps

The setup program for MOVEit Automation API is a straight-forward process. Following the welcome and the click-through license, there are two prompts. First is the prompt for the installation path.

MOVEit Automation API Installation

Next, if you are going to use the command-line client, you will need to reply "Yes" to the next prompt. This will add the install path to the system PATH environment variable.

MOVEit Automation API Installation

Following the installation, you should logoff and logon if you want to immediately use the command-line client.

Silent Installation

An unattended or "silent mode" option to the install program, along with an input parameter file, allows you to install, upgrade, repair or uninstall MOVEit Automation API without user interaction.

Two files are required to be pre-loaded on the system in order to perform an unattended installation. The files are:

  • CenAPI_Win_xxxx.exe - The self-extracting MOVEit Automation API Installation program.
  • Setup.iss - The "Silent Mode" Install control file.

Setup.iss

The Setup.iss file is used by the InstallShield installation program to simulate the responses by a user to the install dialogs in silent mode. You can use this for the Setup.iss file:

[InstallShield Silent]
Version=v7.00
File=Response File
[File Transfer]
OverwrittenReadOnly=NoToAll
[{50631962-66E7-46B0-96AE-21DF036A7D6D}-DlgOrder]
Dlg0={50631962-66E7-46B0-96AE-21DF036A7D6D}-SdLicense2Rtf-0
Count=6
Dlg1={50631962-66E7-46B0-96AE-21DF036A7D6D}-SdAskDestPath2-0
Dlg2={50631962-66E7-46B0-96AE-21DF036A7D6D}-SdStartCopy2-0
Dlg3={50631962-66E7-46B0-96AE-21DF036A7D6D}-SdFinish-0
Dlg4={50631962-66E7-46B0-96AE-21DF036A7D6D}-SdWelcomeMaint-0
Dlg5={50631962-66E7-46B0-96AE-21DF036A7D6D}-MessageBox-0
[{50631962-66E7-46B0-96AE-21DF036A7D6D}-SdLicense2Rtf-0]
Result=1
[{50631962-66E7-46B0-96AE-21DF036A7D6D}-SdAskDestPath2-0]
szDir=C:\Program Files\MOVEit\MOVEitCentralAPI
Result=1
[{50631962-66E7-46B0-96AE-21DF036A7D6D}-SdStartCopy2-0]
Result=1
[{50631962-66E7-46B0-96AE-21DF036A7D6D}-SdWelcomeMaint-0]
Result=302
[{50631962-66E7-46B0-96AE-21DF036A7D6D}-MessageBox-0]
Result=6
[Application]
Name=MOVEit Automation API
Version=5.5.0.0
Company=Ipswitch, Inc.
Lang=0009
[{50631962-66E7-46B0-96AE-21DF036A7D6D}-SdFinish-0]
Result=1
bOpt1=0
bOpt2=0

If you would like to choose a destination path other than the default, you can modify the path in the ISS file. In a silent install, the prompt for modifying the system PATH environment variable, is always assumed to be answered: "Yes".

To launch the unattended install, run the installation package EXE from a command prompt or the Start | Run dialog. Substitute the path for the setup.iss file with the location in which you stored that file.

CenAPI_Win_xxxx.exe /s /f1"c:\setup.iss" /f2"c:\setup.log"

Or:

start /wait CenAPI_Win_xxxx.exe /s /f1"c:\setup.iss" /f2"c:\setup.log"

The "Start /wait" form of the installation will wait until the MOVEit Automation API installation is complete before returning to a command prompt. The installation package will run and create the Setup.log file which contains the result code returned by the installation process:

[InstallShield Silent]
Version=v7.00
File=Log File
[ResponseResult]
ResultCode=0
[Application]
Name=MOVEit Automation API
Version=5.5.0.0
Company=Ipswitch, Inc.
Lang=0009

For a successful installation, the ResultCode will be 0.

MOVEit Automation API Unattended Upgrade or Repair

The MOVEit Automation API unattended install will automatically perform an Upgrade or a Repair if it finds an existing MOVEit Automation API already in place. An Upgrade will be performed if the existing MOVEit Automation API is an older version. A Repair will be performed if the existing MOVEit Automation API is the same version.

MOVEit Automation API Unattended Uninstall

In order to perform an unattended uninstall, run the command this way:

CenAPI_Win_xxxx /removeonly /s /f1"c:\setup.iss" /f2"c:\setup.log"

Like the unattended install, the unattended uninstall will leave a LOG file on disk when it completes.


MOVEit Automation API Reference

This section describes the programmatic interface to MOVEit Automation. See also the command-line interface.

The examples in this document use VBScript syntax; however, any COM- or ActiveX-capable language may be used. This includes VB6, VB.NET, C#.NET, C++, Perl, Python, and almost any other language used on Windows platforms. Both 32-bit and 64-bit applications are supported. When using VBScript on a 64-bit OS, the API operates in 64-bit mode if the 64-bit version of CScript.exe, (or WScript.exe) in the \Windows\System32\ directory is used, or 32-bit mode if the 32-bit version is used from the \Windows\SYSWow64\ directory.

A MOVEit Automation API object is created using code like:

Dim oAPI
Set oAPI = CreateObject("MICentralAPICOM.MICentralAPI")

The main MICentralAPICOM.MICentralAPI object provides the following methods:

Connecting to MOVEit Automation

  • oAPI.SetHost(Hostname)
  • oAPI.SetUser(Username)
  • oAPI.SetPassword(Password)
  • bOK = oAPI.Connect()
  • oAPI.Disconnect()

Setting Task criteria

  • OldMaxTasks = oAPI.SetMaxTasks(MaxTasks)
  • MaxTasks = oAPI.GetMaxTasks()

Querying error conditions and version information

  • ErrorCode = oAPI.GetErrorCode()
  • ErrorDescription = oAPI.GetErrorDescription()
  • Version = oAPI.GetAPIVersion()
  • Version = oAPI.GetCentralVersion()

Starting and monitoring tasks

  • TaskHnd = oAPI.StartTask(Task, bUsingName, TaskParams)
  • TaskHnd = oAPI.StartNewTask(TaskXML [, TaskParams [, Extra ] ])
  • WResult = oAPI.WaitForTasks(TaskHnds, WaitSecs)
  • strXML = oAPI.GetTaskRunInfoXML(WaitResult)
  • strXML = oAPI.GetTaskRunXfersXML(WaitResult)
  • strXMLReply = oAPI.ShowRunningTasks()

Reading and editing XML configurations and results

  • strXML = oAPI.GetItemXML(ItemType, Item, bUsingName)
  • Ciphertext = oAPI.EncryptPW(Plaintext)
  • strXML = oAPI.SetAttribute(XML, NodeName, NodeOrd, AttribName, AttribValue)
  • strValue = oAPI.GetAttribute(XML, NodeName, NodeOrd, AttribName)
  • strValue = oAPI.GetValue(XML, NodeName, NodeOrd)

Checking out and updating XML configurations

  • strXML = oAPI.CheckoutItem(ItemType, ItemID [, bForce ])
  • bOK = oAPI.ReleaseItem(ItemType, ItemID)
  • bOK = oAPI.CreateItem(ItemType, ItemID, ItemXML [, Groups ])
  • bOK = oAPI.ModifyItem(ItemType, ItemID, ItemXML [, bCreate [, Groups ] ])
  • bOK = oAPI.DeleteItem(ItemType, ItemID)
  • strID = oAPI.SuggestItemID(ItemType)

Examining Logs

  • strXMLReply = oAPI.RunCustomSQL(SQL, MaxCount, SkipCount, Delimited, Delimiter)

Connecting to MOVEit Automation

oAPI.SetHost(Hostname)

Sets the name of the MOVEit Automation host to which the API will connect.

Hostname is a hostname. If it is not "localhost" or "127.0.0.1", you must also call SetUser and SetPassword.
oAPI.SetUser(Username)

Sets the username on the MOVEit Automation host which the API will use to log in. This is not required if you are connecting to localhost.

Username is a username recognized on the MOVEit Automation host.
oAPI.SetPassword(Password)

Sets the password for the username on the MOVEit Automation host .

Password is the password for the above user.
bOK = oAPI.Connect()

Connects to MOVEit Automation and logs in. If the host is not localhost, the method will first attempt to connect with SSL, and if that fails, will try without SSL.

Returns True if we connected and logged in successfully. Otherwise, returns False and sets the error code and description.

Common error codes include:

  • 5 - The connection timed-out. (either MOVEit Automation isn't running or the wrong hostname/IP has been configured)
  • 1326 - Logon failure: unknown user name or bad password.

oAPI.Disconnect()

Disconnects from the MOVEit Automation server.

Setting Task criteria

OldMaxTasks = oAPI.SetMaxTasks(MaxTasks)

Sets the maximum number of running tasks to allow from this connected instance of MOVEit Automation API. If at least this many tasks are already running, Central will refuse to run a task submitted using StartTask() or StartNewTask(), and will return error code 5120.

Note that this value has no relation to the "Maximum Running Tasks" limit set on regular, scheduled tasks through MOVEit Automation Admin. Furthermore, multiple and concurrent instances of MOVEit Automation API can set this value differently. For example, one session may be working with a task submission limit of 2 tasks while a "high priority" MOVEit Automation API thread may be working without any task submission limit at all.

MaxTasks | is an integer number to set for all future StartTask() or StartNewTask() functions.
Returns | the previous value stored for MaxTasks. If SetMaxTasks() has not been called before, the default value would be zero.
MaxTasks = oAPI.GetMaxTasks()

Gets the current maximum number of running tasks to allow.

Returns the current value stored for MaxTasks. If SetMaxTasks() has not been called before, the default value would be zero.

Querying error conditions and version information

ErrorCode = oAPI.GetErrorCode()
Returns the numeric error code associated with the most recent call. This is 0 if the last call succeeded.
ErrorDescription = oAPI.GetErrorDescription()
Returns a description of the error associated with the last call, or "" if the last call succeeded.
Version = oAPI.GetAPIVersion()
Returns The version number string for MOVEit Automation API.
Version = oAPI.GetCentralVersion()
Returns The version number string for MOVEit Automation.

Starting and monitoring tasks

TaskHnd = oAPI.StartTask(Task, bUsingName, TaskParams)

Starts a task.

Task | is a task ID or task name.
bUsingName | is 1 if Task is a task name, or 0 if Task is a task ID.
TaskParams Optional task parameters. If no task parameters are required, pass "". The format of TaskParams is ParamName1=ParamVal1|ParamName2=ParamVal2|...
The trailing | at the end of the last task parameter is optional.
Returns | a string that is an opaque task handle. An empty string means that the task failed to start; see the error code and description. This task handle can be provided to WaitForTasks to wait for this task run to complete.

TaskHnd = oAPI.StartNewTask(TaskXML [, TaskParams [, Extra ] ])

Creates and starts a temporary task.

TaskXML | is an XML node tree that specifies the full XML source of a new temporary task. This temporary task can either reference existing hosts and script or provide its own temporary hosts and scripts. See "XML Document Formats - Task Configuration - Overview" for more information about the expected XML.
TaskParams Optional task parameters. The format of TaskParams is ParamName1=ParamVal1|ParamName2=ParamVal2|...
The trailing | at the end of the last task parameter is optional.
Extra | Optional extra parameters for future use.
Returns | a string that is an opaque task handle. An empty string means that the task failed to start; see the error code and description. This task handle can be provided to WaitForTasks to wait for this task run to complete.

Common error codes include:

  • 4000 - Cannot run task "[TaskName]": it is already running (appears if you try to submit multiple tasks with the same ID without waiting for each one to complete)
  • 4080 - You must provide a task name (appears if you try to submit a task without a task name)
  • 4090 - The temporary task ID XXX conflicts with existing task "YYY" (temporary task name or ID cannot match those used by any "permanent" tasks)
  • 5120 - Running this task would exceed the maximum simultaneous tasks specified in the command. (Relates to .SetMaxTasks setting.)

Hints

If you plan on using the "new files only" flag with "ad hoc" hosts (i.e., you will submit "Host" nodes in your TaskXML) you MUST use the same values of HostID and FileMask in future submissions involving the same server because MOVEit Automation stores "newness timestamps" by host, path and filemask. (If you have multiple servers with similar paths, be sure you are using one HostID per server when working with the "only new files" option, not a common HostID for all servers.)

This feature is much easier to use if you can start with a local copy of a "template task", modify a few elements and submit the altered task using StartNewTask. See the extended examples of this in use in the "Examples - Create/Run a Temporary Task Based on an Existing Template Task" documentation.

WaitResult = oAPI.WaitForTasks(TaskHnds, WaitSecs)

Waits for a task to finish.

TaskHnds | is a task handle from the StartTask method, or multiple task handles concatenated with "|" characters. If you supply multiple task handles, the method will return when any of the tasks completes.
WaitSecs | is the number of seconds to wait. If this amount of time passes without any of the specified tasks completing, then the method returns "". If WaitSecs is 0, the method will query the tasks and if none has finished, it will return immediately.
Returns | a value of type WaitResult, describing the result of the first task that completed, or stating that none of the specified tasks completed within the wait time. If multiple tasks completed, you will need to call the method again to learn about the next one.

Hints

To check on the results of multiple tasks started "asynchronously", start with a TaskHnds value containing all the handles of the started tasks and then remove the handle of each returned task result from the TaskHnds string before giving it to the next call of WaitForTasks(). See the "Examples - Create/Run a Temporary Task Based on an Existing Template Task" documentation for an example.

strXML = oAPI.GetTaskRunInfoXML(WResult)

Queries MOVEit Automation for information about a task run overall.

WResult | is a WaitResult object returned by WaitForTasks in response to a successful wait for a task run.
Returns | an XML string which contains a table with one row containing information about this task run overall. See Overall task status format.

strXML = oAPI.GetTaskRunXfersXML(WResult)

Queries MOVEit Automation for information about the individual steps in a task run.

WResult | is a WaitResult object returned by WaitForTasks in response to a successful wait for a task run.
Returns | an XML string which contains a table with potentially multiple rows, one for each action (e.g., transfer or process run) during this task run. See Detailed job step status format.

strXMLReply = oAPI.ShowRunningTasks()

Returns an XML structure containing information about all running tasks. This command may only be issued by users signed on from localhost and users who are members of the MOVEit Admin and/or MOVEit Log Windows groups. See the "Examples - Show Running Tasks" documentation for examples.

Returns the XML string response from Central. See Detailed running task status format.

Reading and editing XML configurations and results

strXML = oAPI.GetItemXML(ItemType, Item, bUsingName)

Queries MOVEit Automation for a configuration entry, returns it in XML.

ItemType | is a string identifying the type of entry requested, (for example "Task", "Host" or "Script"). See "XML Document Formats - Task Configuration - Overview" for more information about types of nodes that can be requested.
Item | is the name or ID of the item requested.
bUsingName | is true if Item is a name, or false if Item is an ID.
Returns | an XML string which contains the configuration data for the requested item.

Common error codes include:

  • 4020 - This section name does not exist. (usually, a task/host/etc. with this name could not be found)

Ciphertext = oAPI.EncryptPW(Plaintext)

Encrypts a string using the encryption algorithm Central uses for passwords.

Plaintext | is the password in plain text.
Returns | the encrypted password that can be used in task sources or destinations.

AttribValue = oAPI.GetAttribute(XML, NodeName, NodeOrd, AttribName)

Given any XML string, returns the value of the named attribute from a given node. If the attribute does not exist, a blank value will be returned and an error code will be set.

XML | is a string containing valid XML.
NodeName | is the name of the XML node to query, (for example "Task" or "Source").
NodeOrd | is the index (1-based) of the node if there are multiple (for example multiple destinations in a task).
AttribName | is the name of the attribute to query.
Returns | the value of the attribute, or a blank string if errors were encountered (such as invalid source XML or missing attribute).

Common error codes include:

  • 2850 - Can't find '[AttribName]' node.

strXML = oAPI.SetAttribute(XML, NodeName, NodeOrd, AttribName, AttribValue)

Modifies an XML string to assign an attribute to a given node. If the attribute already exists, it will be modifed.

XML | is the original XML string to modify.
NodeName | is the name of the XML node to modify, (for example "Task" or "Source").
NodeOrd | is the index (1-based) of the node if there are multiple (for example multiple destinations in a task).
AttribName | is the name of the attribute to add or modify within the node.
AttribValue | is the value to assign to the new or modified attribute.
Returns | the XML string with the new/modified attribute, or a blank string if errors were encountered (such as invalid source XML).

AttribValue = oAPI.GetValue(XML, NodeName, NodeOrd)

Given any XML string, returns the value of the named node. If the node is a text node, the text value is returned. If the node is a parent node, the child node is returned. If the node does not exist, a blank value will be returned and an error code will be set.

XML | is a string containing valid XML.
NodeName | is the name of the XML node to query.
NodeOrd | is the index (1-based) of the node if there are multiple (for example multiple destinations in a task).
Returns | the value of the given named node, or a blank value if the node doesn't exist.

Common error codes include:

  • 2850 - Can't find '[NodeName]' node.

Checking out and updating XML configurations

These functions allow you to checkout, create, and modify MOVEit Automation config items. There are two main types of config sections: those that define a single element and require a unique ID, and those that define a collection of elements and do NOT require an ID. For the latter, in order to "Add" a new item to the collection, you must Checkout the entire section and append the XML defining the new element into the XML defining the entire collection, and for the "ItemID" parameter you should simply specify a blank string, as these sections don't actually have IDs associated with them.

See "XML Document Formats - Task Configuration - Overview" for more information about the expected XML.

NOTE: SECTION TYPES ARE CASE SENSITIVE.

Sections that define single objects with unique IDs:

DateList | Defines a DateList. Scheduled tasks can use Date Lists to run on specific dates, rather than days of the week.
 | <DateList Name="Example Datelist #1" ID="5551584"><Date>2009-10-23</Date>...</DateList>
Host | Defines a single MOVEit Automation Host. Host XML is unique in that there is no <Host> node. Instead, nodes are named after the type of host it defines. The "ItemXML" that you submit must conform to the Host Types defined below. For "ItemType" values, however, you should simply use "Host".
Share | Defines a Windows UNC Share.
 | <Share ID="383562872" DriveLetter="" UNC="\\Example\share" DefUsername="user" DefPassword="!s!t5/TSc==" UseNotif="0" DefRetryCount="0" DefRetryTimeoutSecs="30" DefRescanSecs="0" Name="\\Example\share"/>
siLock | Defines a MOVEit DMZ host.
 | <siLock ID="338203594" ID2="998021066|522412139" DotNET="1" Name="SampleDMZHost" Host="192.168.1.300" Port="443" DefUsername="user" DefPassword="!s!t5/TSc==" UseNotif="0" ScriptPath="siLockNet" Secure="1" IgnoreCertProbs="1" DefRetryCount="1" DefRetryTimeoutSecs="6" DefSort="Filename,A" DefMxFi="0" DefMxBy="0"/>
FTP | Defines an FTP/S host.
 | <FTP ID="504300147" ID2="304833758" NATUseServerIPForData="1" Name="SampleFTPHost" Host="192.168.1.301" Port="2121" DefUsername="user" DefPassword="!s!t5/TSc==" DefAccount="!s!t5/TSc==" DefAB="binary" DefPassive="1" DefBlindDL="0" Secure="none" DefRetryCount="1" DefRetryTimeoutSecs="11" DefRescanSecs="0" RenameAfterUpload="0" TempUploadName="CTMP[Rnd:4]"/>
SSHFTP | Defines an SFTP host.
 | <SSHFTP ID="637864178" Name="SampleSSHHost" Host="192.168.1.302" Port="22" DefUsername="user" DefPassword="!s!t5/TSc==" IgnoreCertProbs="1" DefClientKeyID="0" DefBlindDL="0" DefRetryCount="0" DefRetryTimeoutSecs="30" DefRescanSecs="0" RenameAfterUpload="0" TempUploadName="CTMP[Rnd:4]"/>
SMTP | Defines an SMTP host.
 | <SMTP ID="138975984" Name="SampleSMTPHost" Host="mail.mycompany.com" Port="25" DefAddressFrom="admin@mycompany.com" DefRetryCount="0" DefRetryTimeoutSecs="30" ID2="715815878"/>
POP3 | Defines an POP3 host.
 | <POP3 ID="416847688" ID2="327458513" Name="SamplePOP3Host" Host="mail.mycompany.com" Port="110" DefUsername="user" DefPassword="!s!t5/TSc==" DefRetryCount="0" DefRetryTimeoutSecs="30"/>
AS1 | Defines an AS1 host.
 | <AS1 ID="897059125" Name="SampleAS1Host" MDNPollCount="10" MDNPollTimeoutSecs="30" DefRetryCount="3" DefRetryTimeoutSecs="30" DeleteIfOlderThanDays="7" PauseRerunSecs="10" OrgName="SampleOrg" UseSigningCertForDecrypt="1" DefPartnerName="SamplePartner" DefEncryptionAlgorithm="None" DefCompressionFormat="None" DefEDIDataType="application/edi-x12" POPServer="mail.mycompany.com" POPPort="110" SSLStartMode="None" IgnoreCertProbs="0" Username="user" Password="!s!t5/TSc==" DeleteIfNewerThanDays="7"/>
AS2 | Defines an AS2 host.
 | <AS2 ID="563255531" Name="SampleAS2Host" MDNPollCount="10" MDNPollTimeoutSecs="30" DefRetryCount="3" DefRetryTimeoutSecs="30" OrgName="SampleOrg" UseSigningCertForDecrypt="1" DefPartnerName="SamplePartner" DefEncryptionAlgorithm="None" DefCompressionFormat="None" DefEDIDataType="application/edi-x12" DefPartnerURL="" IgnoreCertProbs="0"/>
AS3 | Defines an AS3 host.
 | <AS3 ID="755954438" Name="SampleAS3Host" MDNPollCount="10" MDNPollTimeoutSecs="30" DefRetryCount="3" DefRetryTimeoutSecs="30" PauseRerunSecs="10" OrgName="SampleOrg" UseSigningCertForDecrypt="1" DefPartnerName="SamplePartner" DefEncryptionAlgorithm="None" DefCompressionFormat="None" DefEDIDataType="application/edi-x12" Host="192.168.1.304" Port="21" Secure="None" IgnoreCertProbs="0" Username="user" Password="!s!t5/TSc==" Passive="1"/>
Script | Defines a MOVEit Automation custom script.
 | <Script ID="456046402" Name="CustomScript1"><Description>Sample Script</Description><Source>!s!IaiRSUub8+ANsBaobttXZ3XNJHSJRsrIIy4UJafdhc4aUvH4cII+d7+6LLZc</Source></Script>
SSHClientKey | Defines an SSH client key.
 | <SSHClientKey ID="69433227" Name="NewSSHKey"><Fingerprint>ef:13:20:94:6c:8b:d2:4f:be:5e:72:0d:e5:22:e7:56</Fingerprint><PrivateKey>!s!EiXVSS8zTqznSjn...9HtEmV1lJ</PrivateKey><PublicKeySSH>---- BEGIN SSH2 PUBLIC KEY ----AAAAB3NzaC1yc...fr/WJttJE=---- END SSH2 PUBLIC KEY ----</PublicKeySSH><PublicKeyOpenSSH>ssh-rsa AAAAB3NzaC1...CUutPfr/WJttJE=</PublicKeyOpenSSH></SSHClientKey>
Task | Defines a single MOVEit Automation Task.
 | <Task ID="535919529" Name="Sample MOVEit Automation Task" Active="0" NextEID="27" TT="COS" AR="0"><Schedules/><Source HostID="0" Type="FileSystem" Path="C:\tmp\Test" FileMask="*.bin" DeleteOrig="0" NewFilesOnly="0" SearchSubdirs="0" Unzip="0" RetryIfNoFiles="0" UseDefRetryCount="1" UseDefRetryTimeoutSecs="1" UseDefRescanSecs="1" UDMxFi="1" UDMxBy="1" ID="22"/><Destination HostID="838545018" Type="siLock" FolderID="494152289" FolderType="4" FolderName="Home/TestUser/" Subject="" FileName="[OrigName]" UseOrigName="1" ForceDir="1" OverwriteOrig="1" UseRelativeSubdirs="1" Zip="0" UseDefRetryCount="1" UseDefRetryTimeoutSecs="1" UseDefUser="1" UseDefClientCert="1" ID="26"/>...</Task>

Sections that define collections of objects and do NOT require IDs:

GlobalParameters | Defines the Global Parameters within MOVEit Automation.
 | <GlobalParameters><Global1>Value1</Global1><Global2>Value2</Global2>...</GlobalParameters>
Globals | Defines various MOVEit Automation system settings.
 | <Globals><LogToDisk>1</LogToDisk><DebugLevel>70</DebugLevel><EventLogLevel>0</EventLogLevel><LogFile>MOVEitC.log</LogFile><MaxLogFileSize>10485760</MaxLogFileSize><EventLogName>Application</EventLogName><EventLogAuditLevel>0</EventLogAuditLevel><PollIntervalSecs>120</PollIntervalSecs><AS2PollIntervalSecs></AS2PollIntervalSecs><SuppressHashing>0</SuppressHashing><MaxSimulTasks>0</MaxSimulTasks><AllowMultRuns>0</AllowMultRuns></Globals>
Groups | Defines MOVEit Automation Task Groups.
 | <Groups><Group Name="Group1"><Notes>Sample Notes</Notes><Member t="host">338203594</Member></Group><Group Name="Group2"><Notes></Notes><Member t="task">284392482</Member></Group>...</Groups>
Permissions | Defines Permissions to various MOVEit Automation elements as allocated to Windows User Groups.
 | <Permissions><NTGroup Name="MOVEit Users-Group1"><TaskGroup Name="Group1" View="1" AddDel="1" Run="0" Edit="1" HView="1" HEdit="0" SView="1" SEdit="0" SSLView="1" SSLEdit="1" SSHView="1" SSHEdit="0" PView="1" PEdit="0"/></NTGroup>...</Permissions>

The following functions can be used to manipulate the MOVEit Automation config elements listed above:

strXML = oAPI.CheckoutItem(ItemType, ItemID [, bForce ])

Checks out a section from the MOVEit Automation XML configuration file given a section type and ID number. If successful, the item's XML is returned, otherwise a blank string is returned.

ItemType | is a string for the type of config section to checkout.
ItemID | is a string for the ID of the specific item to checkout, if any.
bForce | Optional parameter: set to TRUE to force a checkout if the item is already checked out (NOTE - this will terminate the existing lock on the section and establish a new lock for the current API session). The default value is FALSE.
Returns | The section XML that was checked out. If there was an error, returns a blank string.

Common error codes include:

  • 2850 - The section type (or section ID) 'xxxx' is invalid.
  • 4010 - This section has been checked out to xxxx since xxxx-xx-xx.

bOK = oAPI.ReleaseItem(ItemType, ItemID)

Releases the lock on a config section that was obtained using the CheckoutItem() function.

ItemType | is a string for the type of config section to release.
ItemID | is a string for the ID of the specific item to release, if any.
Returns | TRUE if successful, FALSE otherwise.

Common error codes include:

  • 2850 - The section type (or section ID) 'xxxx' is invalid.
  • 4015 - This section is not checked out.

bOK = oAPI.CreateItem(ItemType, ItemID, ItemXML [, Groups ])

Creates a new item in the Central configuration. The item does NOT have to be checked out prior to calling CreateItem(). The Groups parameter can be used to add the new item to Task Groups, if desired.

ItemType | is a string for the type of config section to which the item will be added.
ItemID | is a string for the ID of the item to be created. This ID must match the ID embedded in the ItemXML parameter.
ItemXML | is an XML string that defines the new item to add. This must be consistent with the ItemType and ItemID parameters.
Groups | Optional paramater: contains the names of the Task Groups which the new item should be added to, if any, separated by "|" characters; e.g. "Detroit|Chicago|...", where the Trailing "|" is negligible. Use a blank string ("") if no group membership actions need to be performed (default).
Returns | TRUE if successful, FALSE otherwise.

Common error codes include:

  • 53 - Cannot mount path \\xxxx\xxxx drive 'xxxx' user xxxx: The network path was not found. (NOTE - This error occurs AFTER the config is updated with ItemXML)
  • 2850 - The section type (or section ID) 'xxxx' is invalid.
  • 2850 - Cannot create items for section type 'xxxx', use ModifyItem() to edit the entire section.
  • 4011 - This section ID already exists.

bOK = oAPI.ModifyItem(ItemType, ItemID, ItemXML [, bCreate [, Groups ] ])

Modifies an existing item in the Central configuration, or creates a new item if the item ID doesn't already exist and bCreate is TRUE (default is FALSE). If modifying an existing item, that item must be checked out using CheckoutItem() prior to calling ModifyItem(). The Groups parameter can be used to add new items to Task Groups, however existing items that are being modified cannot be added to Task Groups in this manner (you must update the "Groups" section of the config to add existing items to Task Groups).

ItemType | is a string for the type of config section to which the item belongs (or will be added to).
ItemID | is a string for the ID of the item to be modified (or created). This ID must match the ID embedded in the ItemXML parameter.
ItemXML | is an XML string that defines what the item to be modified to (or created). This must be consistent with the ItemType and ItemID parameters.
bCreate | Optional parameter: set to TRUE if the item should be created in the case that it doesn't already exist in the Central config. The default value is FALSE.
Groups | Optional parameter: contains the names of the Task Groups which any new item should be added to, if any, separated by "|" characters; e.g. "Detroit|Chicago|...", where the Trailing "|" is negligible. Use a blank string ("") if no group membership actions need to be performed (default). If modifying an existing item, this parameter has no effect.
Returns | TRUE if successful, FALSE otherwise.

Common error codes include:

  • 53 - Cannot mount path \\xxxx\xxxx drive 'xxxx' user xxxx: The network path was not found. (NOTE - This error occurs AFTER the config is updated with ItemXML)
  • 2850 - The section type (or section ID) 'xxxx' is invalid.
  • 4011 - This section is not checked out.

bOK = oAPI.DeleteItem(ItemType, ItemID)

Deletes an existing item from the Central configuration. The item does NOT need to be checked out prior to calling DeleteItem().

ItemType | is a string for the type of config section to which the item belongs.
ItemID | is a string for the ID of the item to be deleted.
Returns | TRUE if successful, FALSE otherwise.

Common error codes include:

  • 2850 - The section type (or section ID) 'xxxx' is invalid.
  • 2850 - The section type 'xxxx' cannot be deleted.

strID = oAPI.SuggestItemID(ItemType)

Suggests a unique ID for the given ItemType. Returns the ID as a string, else a blank string ("") if there was an error.

ItemType | is a string for the type of config section for which we want to generate a new ID.
Returns | The new ID as a string. If there was an error, returns a blank string.

Common error codes include:

  • 2850 - The section type (or section ID) 'xxxx' is invalid.
  • 2850 - The section type 'xxxx' doesn't require an ID.

Examining logs

strXMLReply = oAPI.RunCustomSQL(SQL, MaxCount, SkipCount, bDelimited, Delimiter)

Allows MOVEit Automation API to issue read-only ("SELECT") SQL queries against the tamper-evident MOVEit Automation task run, file activity and audit logs (i.e., the "taskruns", "stats" and "audit" database tables). This command may only be issued by users signed on from localhost and users who are members of the MOVEit Admin and/or MOVEit Log Windows groups. See your MOVEit Automation manual ("Advanced Topics - Database - Schema" section) for information about the schema. Also see the "Examples - Run Custom Reports" documentation for examples.

SQL | is a MOVEit Automation database SQL string.
MaxCount | is an integer value of the number of records to return if there are a lot.
SkipCount | is an integer value of the number of records skip at the beginning (usually 0).
bDelimited | is true if you want to return a delimited list instead full XML.
Delimiter | is a string containing the delimiter to use of bDelimited is true.
Returns | the XML string response from Central (or else a delimited string if requested). See Run Custom SQL Format.


WaitResult Reference

An object of type WaitResult is returned by the main WaitForTasks method to describe the task that completed, if any. The properties of a WaitResult object are read-only, and are described below.

Typically only the HasCompletion property is used. The GetTaskRunInfoXML method of the main object is usually used in preference to the other WaitResult properties, since it provides more information.

bHasCompletion = WaitResult.HasCompletion
Returns True if this object describes a task that has completed, else False if WaitForTasks timed out or otherwise failed to find a task completion.

The remaining properties of WaitResult are valid only if HasCompletion is True.

TaskID = WaitResult.TaskID
Returns the ID of the task that has just completed.
TaskName = WaitResult.TaskName
Returns the name of the task that has just completed.
TaskErrorCode = WaitResult.TaskErrorCode
Returns the task error code of the completed task. 0 means no error.
TaskErrorDescription = WaitResult.TaskErrorDescription
Returns the task error description of the completed task. This will be "" if there was no error.
TaskNominalStartTime = WaitResult.TaskNominalStartTime
Returns the nominal date and time the task started, in the format YYYY-MM-DD HH:MM:SS. If the task was started by the scheduler, the actual start time will probably be shortly after this time, due to the fact that the scheduler evaluates tasks only once per minute.
TaskTimeEnded = WaitResult.TaskTimeEnded
Returns the date and time the task ended, in the format YYYY-MM-DD HH:MM:SS.


MOVEit Automation API Overview

Examples - Run An Existing Task (Programmatic)

This VBScript sample shows how to use the programmatic API to run an existing task and interpret the results.

' MICentralAPICOMDemo.vbs - VBScript demonstration of how to use the
' COM version of the MOVEit Automation API.
' This script starts a task, waits for it to complete, and then reports
' information on the task run and the files it transferred.
'
' If you don't need the file transfer report, consider using the
' fully-supported MOVEit Automation command line client rather than
' writing your own script.
'
' Ipswitch, 19 April 2006   moveitsupport@ipswitch.com
'
' Typical output from this script:
'
' Starting task Monthly Reports
' Task Monthly Reports has started
' TaskName             = Monthly Reports
' TaskID               = 133254349
' TaskNominalStartTime = 2006-04-20 16:04:23
' TaskTimeEnded        = 2006-04-20 16:04:24
' TaskErrorCode        = 0
' TaskErrorDescription =
'
' --- Information about the task run as a whole: ---
' TotalBytesSent = 36350
'
' --- Information about the individual file transfers: ---
' Sent c:\tmp\two\test1.ggg (33408 bytes)
' Sent c:\tmp\two\test1.hhh (2942 bytes)

Option Explicit

Sub ShowMsg(MyText)
   WScript.Stdout.WriteLine MyText
End Sub

'--- Sub ShowTaskRunInfo ---------------------------------------
' Shows information about a completed task run--information
' about the task run as a whole.
Sub ShowTaskRunInfo(oAPI, WaitResult)
   Dim strXMLTask, xmlDoc, oNode
   ' Fetch the information from MOVEit Automation, in XML format.
   strXMLTask = oAPI.GetTaskRunInfoXML(WaitResult)

   Set xmlDoc = CreateObject("msxml2.DOMDocument")
   xmlDoc.loadXML(strXMLTask)
   Set oNode = xmlDoc.selectSingleNode("/Records/Record/TotalBytesSent")
   ShowMsg ""
   ShowMsg "--- Information about the task run as a whole: ---"
   ShowMsg "TotalBytesSent = " & oNode.firstChild.nodeValue
End Sub

'--- Sub ShowTaskTransfers -------------------------------------
' Shows information about files transferred by a task run.
Sub ShowTaskTransfers(oAPI, WaitResult)
   Dim strXMLXfers, xmlDoc, fileNode, Action, DestFilename, NBytes
   ' Fetch the information from MOVEit Automation, in XML format.
   strXMLXfers = oAPI.GetTaskRunXfersXML(WaitResult)

   Set xmlDoc = CreateObject("msxml2.DOMDocument")
   xmlDoc.loadXML(strXMLXfers)
   ShowMsg ""
   ShowMsg "--- Information about the individual file transfers: ---"

   ' Loop through each file transfer record.
   ' Remember that there may be multiple records per transfer;
   ' in particular, a "get" and a "send" records for each.
   For Each fileNode In xmlDoc.selectNodes("/Records/Record")
      Action = fileNode.selectSingleNode("./Action").firstChild.nodeValue
      ' List only send records.
      If Action="send" Then
         DestFilename = fileNode.selectSingleNode("./DestFilename").firstChild.nodeValue
         NBytes = fileNode.selectSingleNode("./NBytes").firstChild.nodeValue
         ShowMsg "Sent " & DestFilename & " (" & NBytes & " bytes)"
      End If
   Next
End Sub

Sub Main()
   Dim oAPI, TaskHnd, WaitResult, TaskName, WaitSecs
   Set oAPI = CreateObject("MICentralAPICOM.MICentralAPI")
   oAPI.SetHost("localhost")
   If Not oAPI.Connect() Then
      ShowMsg "Can't connect: " & oAPI.GetErrorDescription
      Exit Sub
   End If
   TaskName = "Monthly Reports"
   ShowMsg "Starting task " & TaskName
   ' Start the task.
   TaskHnd = oAPI.StartTask(TaskName, True, "")
   If "" = TaskHnd Then
      ShowMsg "Task " & TaskName & " failed to start"
      ShowMsg oAPI.GetErrorDescription
      Exit Sub
   Else
      ShowMsg "Task " & TaskName & " has started"
   End If
   WaitSecs = 120
   ' Wait for the task to complete.
   Set WaitResult = oAPI.WaitForTasks(TaskHnd, WaitSecs)
   ' The task might not have completed within the timeout we selected.
   If Not WaitResult.HasCompletion Then
      ShowMsg "The task has not yet completed"
   Else
      ShowMsg "TaskName             = " & WaitResult.TaskName
      ShowMsg "TaskID               = " & WaitResult.TaskID
      ShowMsg "TaskNominalStartTime = " & WaitResult.TaskNominalStartTime
      ShowMsg "TaskTimeEnded        = " & WaitResult.TaskTimeEnded
      ShowMsg "TaskErrorCode        = " & WaitResult.TaskErrorCode
      ShowMsg "TaskErrorDescription = " & WaitResult.TaskErrorDescription

      ShowTaskRunInfo oAPI, WaitResult
      ShowTaskTransfers oAPI, WaitResult
   End If
End Sub

Main


Examples - Create/Run a Temporary Task Based on an Existing Template Task

This VBScript example shows how to use the programmatic API to download "templates" for task and host configuration elements, modify them and resubmit/run them as a temporary task.

However, you would first likely want to spend a few moments setting up one or two "template tasks" and at least one "template host" to use. This requires the use of MOVEit Automation Admin and is described below.

Step 1: Set up a MOVEit Automation "template host"

First, create a new "template host" of the appropriate type on MOVEit DMZ. If you are unsure which type to use (because you may be switching between different types of hosts at runtime), create a host of type "FTP".

For detailed instructions, see the "Creating a Template Host" section below."

Step 2: Set up one or two MOVEit Automation "template tasks"

Next you should create one or two "template tasks" that reference your template host. You may find it easier to use two template tasks (one for uploading and one for downloading) if one of your endpoints is a Windows file system (including UNCs) because Windows sources and destinations are treated a little differently than non-Windows sources.

For detailed instructions, see the "Creating Template Tasks" section below."

Step 3: Set up a MOVEit Automation API user with appropriate permissions

To gain access to MOVEit Automation, MOVEit Automation API will need to authenticate with the proper credentials.

If you plan to submit temporary tasks involving existing hosts, your MOVEit Automation API user only needs "View/Select" permission to those existing hosts but "View/Select/Run/Add/Edit/Delete" permission on the template tasks. If you plan to submit temporary tasks involving ad hoc hosts, your MOVEit Automation API user needs "View/Select/Add/Edit/Delete" permission on your template host and "View/Select/Run/Add/Edit/Delete" permission on the template tasks.

Alternatively, you can just grant your MOVEit Automation API full access to MOVEit Automation and avoid a task/host permission structure.

For detailed instructions, see the "Creating Appropriate Permissions for MOVEit Automation API" section below."

Step 4: Write your MOVEit Automation API application

Finally, you are ready to write your own MOVEit Automation API application. This can be done in any language that supports Windows COM components (or Java if you are using the Java classes).

Generally, MOVEit Automation API applications that download template configurations, make changes to them and resubmit/run them as "temporary tasks" will perform the same set of general operations:

  • Use the ".GetItemXML" method to get local copies of a template host and template task configuration.
  • Use the ".SetAttribute" method to override the hostname, path, filenames, etc. in the template host (ad hoc transfers only) and template task. This will yield an XML string containing a "temporary task" definition.
  • Optionally, use the ".SetMaxTasks" method to make sure you are not flooding MOVEit Automation with requests in an asynchronous task submission environment.
  • Use the ".StartNewTask" method to submit/run your temporary task. (Optionally, watch for an error code of "5120" to indicate "too many tasks in mix" and resubmit appropriately.)
  • Use the ".WaitForTasks" and related methods to monitor the task and report or act on its results.

The two examples provided below perform similar operations, but one references existing host definitions while the other accesses remote servers for which no host definition exists.

VBScript Code (Reference Existing Hosts)

Option Explicit

'  Echo a message to the console
Sub ShowMsg(MyText)
  Dim TheSplit
  TheSplit = Split(Now()," ")
  WScript.Echo TheSplit(1) & " - " & MyText
End Sub

'  Echo a message to the console along with last API error (if any)
Sub ShowMsg2(MyText,oAPI)
  Dim TheSplit
  TheSplit = Split(Now()," ")
  if oAPI.GetErrorCode = 0 then
    WScript.Echo TheSplit(1) & " - " & MyText
  else
    WScript.Echo TheSplit(1) & " - " & MyText & " Error#" & oAPI.GetErrorCode & ": " & oAPI.GetErrorDescription
  end if
End Sub

' Display the contents of a WaitResult object
Sub DumpWaitResult(oAPI,oWaitResult)
  Dim TaskRunInfoXML
  ShowMsg   "Task Run Results:"
  ShowMsg   "  Name:  " & oWaitResult.TaskName
  ShowMsg   "  ID:    " & oWaitResult.TaskID
  ShowMsg   "  Time:  " & oWaitResult.TaskNominalStartTime & " to "  & oWaitResult.TaskTimeEnded
  if oWaitResult.TaskErrorCode = 0 then
    ShowMsg "  Error: (none)"
  else
    ShowMsg "  Error: " & oWaitResult.TaskErrorCode & ": " & oWaitResult.TaskErrorDescription
  end if
  TaskRunInfoXML = oAPI.GetTaskRunInfoXML(oWaitResult)
   ShowMsg "  Xfer:  " & oAPI.GetValue(TaskRunInfoXML, "FilesSent", 1) & _
      " files, " & _
      oAPI.GetValue(TaskRunInfoXML, "TotalBytesSent", 1) & _
      " bytes"
  'ShowMsg "-= GetTaskRunInfoXML =-"
  'ShowMsg TaskRunInfoXML
  'ShowMsg "-= GetTaskRunXfersXML =-"
  'ShowMsg oAPI.GetTaskRunXfersXML(oWaitResult)
End Sub

'  This main routine does all the work for the script.
Sub Main

   Dim bOK, TryTasks, MaxTasks
   Dim TaskHnd, TaskHndPipe, StartedTasks
   Dim WaitResult, TaskName, WaitSecs
   Dim TaskXML, iii, HostXML, HostID, TaskLimit, TaskID
   Dim oAPI

   Set oAPI = CreateObject("MICentralAPICOM.MICentralAPI")
   ShowMsg("Starting demonstration using existing hosts.")
   MaxTasks = 3
   TryTasks = 5

   'On Error Resume Next

   ' Sign on and connect
   oAPI.SetHost("192.168.3.178")
   oAPI.SetUser("API1")
   oAPI.SetPassword("A1s2d3f4")
   bOK = oAPI.Connect()
   if NOT bOK then
     ShowMsg2 "Could not sign on to MOVEit Automation!",oAPI
     Exit Sub
   end if
   ShowMsg("Running API version " & oAPI.GetAPIVersion() & _
     " on Central version " & oAPI.GetCentralVersion() )

  ' Use the ".GetItemXML" method to get a local copy of a template task configuration.
  TaskXML = oAPI.GetItemXML("Task", "Template Task - Download from FTP", True)
  if TaskXML="" then
    ShowMsg2 "Failed to read template task configuration! ", oAPI
    Exit Sub
  else
    ShowMsg "Read template task configuration; " & Len(TaskXML) & " bytes."
  end if

  ' Look up the HostID of a named FTP site
  HostXML = oAPI.GetItemXML("Host", "Hewlett Packard Public FTP Site", True)
  if HostXML="" then
    ShowMsg2 "Failed to read target host configuration! ", oAPI
    Exit Sub
  else
    ShowMsg "Read target host configuration; " & Len(HostXML) & " bytes."
  end if
  HostID = oAPI.GetAttribute(HostXML, "FTP", 1, "ID")

  ' Use the ".SetAttribute" method to override the hostID, path, filenames, etc. in the
  ' template task. This will yield an XML string containing a "temporary task" definition.
  TaskID = "9824524"  ' 8-digit values (10,000,000-99,999,999) are safe (we'll add the 8th later)
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "HostID", HostID)
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "Type", "FTP")
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "Path", "/pub/visualize")
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "FileMask", "TopTools*.*")
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "DeleteOrig", "0")  'Turn off attempt to delete
  TaskXML = oAPI.SetAttribute(TaskXML, "Destination", 1, "Path", "D:\temp\hpdump")
  TaskXML = oAPI.SetAttribute(TaskXML, "Destination", 1, "FileName", "[yyyy][mm][dd]-[OrigName]")
  TaskXML = oAPI.SetAttribute(TaskXML, "Task", 1, "Name", _
    "Download from HP FTP site using existing host")
  TaskXML = oAPI.SetAttribute(TaskXML, "Task", 1, "ID", TaskID & "0")

  ' Submit one task and wait for results
  ShowMsg "Temporary task configuration contains " & Len(TaskXML) & " bytes."
  TaskHnd = oAPI.StartNewTask(TaskXML)
  If "" = TaskHnd Then
     ShowMsg2 "Temporary task failed to start", oAPI
     Exit Sub
  Else
     ShowMsg "Task " & TaskHnd & " has started"
  End If
  WaitSecs = 120
  Set WaitResult = oAPI.WaitForTasks(TaskHnd, WaitSecs)
  DumpWaitResult oAPI, WaitResult

  ' Now set a limit of 3 tasks in the mix and try to submit 5 in quick succession
  TaskLimit = oAPI.SetMaxTasks(MaxTasks)
  StartedTasks = 0
  ShowMsg "Current Task Limit is " & oAPI.GetMaxTasks()
  TaskHndPipe = ""
  For iii = 1 to TryTasks
    TaskXML = oAPI.SetAttribute(TaskXML, "Task", 1, "Name", _
      "Download from HP FTP site using existing host (" & iii & " of " & TryTasks & ")")
    TaskXML = oAPI.SetAttribute(TaskXML, "Task", 1, "ID", TaskID & iii)
    TaskHnd = oAPI.StartNewTask(TaskXML)
    If "" = TaskHnd Then
      ShowMsg2 "Temporary task (" & iii & " of " & TryTasks & ") failed to start", oAPI
    Else
      ShowMsg "Temporary task (" & iii & " of " & TryTasks & ") has started"
      StartedTasks = StartedTasks + 1
      TaskHndPipe = TaskHndPipe & TaskHnd & "|"
    End If
  Next 'iii

  ' Check on the tasks we put into the mix
  Dim LastWaitResult
  LastWaitResult = "NotBlank"   ' Otherwise it matches too soon!
  ShowMsg "TaskHndPipe = " & TaskHndPipe
  For iii = 1 to StartedTasks
    Set WaitResult = oAPI.WaitForTasks(TaskHndPipe, WaitSecs)
    if LastWaitResult = WaitResult.TaskID then
      ' Ignore it and wait for the next one
      iii = iii - 1
      WScript.Sleep(250)
    else
      DumpWaitResult oAPI, WaitResult
      LastWaitResult = WaitResult.TaskID
      ' Take result found out of list we're looking for
      TaskHndPipe = Replace(Replace(TaskHndPipe, WaitResult.TaskID & "^" & _
        WaitResult.TaskNominalStartTime, ""), "||","|")
      'ShowMsg "TaskHndPipe = " & TaskHndPipe
    end if
  Next 'iii

  ShowMsg("Ending demonstration using existing hosts.")

  set oAPI = Nothing

End Sub

Main

Sample Output

4:30:47 - Starting demonstration using existing hosts.
4:30:47 - Running API version 4.9.1.0 on Central version 4.9.2.5
4:30:47 - Read template task configuration; 469 bytes.
4:30:47 - Read target host configuration; 392 bytes.
4:30:47 - Temporary task configuration contains 488 bytes.
4:30:47 - Task 98245240^2007-10-16 16:30:47 has started
4:30:51 - Task Run Results:
4:30:51 -   Name:  Download from HP FTP site using existing host
4:30:51 -   ID:    98245240
4:30:51 -   Time:  2007-10-16 16:30:47 to 2007-10-16 16:30:50
4:30:51 -   Error: (none)
4:30:51 -   Xfer:  2 files, 170952 bytes
4:30:51 - Current Task Limit is 3
4:30:51 - Temporary task (1 of 5) has started
4:30:52 - Temporary task (2 of 5) has started
4:30:52 - Temporary task (3 of 5) has started
4:30:53 - Temporary task (4 of 5) failed to start Error#5120: Running this task
would exceed the maximum simultaneous tasks specified in the command.
4:30:53 - Temporary task (5 of 5) failed to start Error#5120: Running this task
would exceed the maximum simultaneous tasks specified in the command.
4:30:53 - TaskHndPipe = 98245241^2007-10-16 16:30:51|98245242^2007-10-16 16:30:5
2|98245243^2007-10-16 16:30:52|
4:31:01 - Task Run Results:
4:31:01 -   Name:  Download from HP FTP site using existing host (1 of 5)
4:31:01 -   ID:    98245241
4:31:01 -   Time:  2007-10-16 16:30:51 to 2007-10-16 16:30:59
4:31:01 -   Error: (none)
4:31:01 -   Xfer:  2 files, 170952 bytes
4:31:05 - Task Run Results:
4:31:05 -   Name:  Download from HP FTP site using existing host (3 of 5)
4:31:05 -   ID:    98245243
4:31:05 -   Time:  2007-10-16 16:30:52 to 2007-10-16 16:31:05
4:31:05 -   Error: (none)
4:31:05 -   Xfer:  2 files, 170952 bytes
4:31:21 - Task Run Results:
4:31:21 -   Name:  Download from HP FTP site using existing host (2 of 5)
4:31:21 -   ID:    98245242
4:31:21 -   Time:  2007-10-16 16:30:52 to 2007-10-16 16:31:20
4:31:21 -   Error: (none)
4:31:21 -   Xfer:  2 files, 170952 bytes
4:31:21 - Ending demonstration using existing hosts.

VBScript Code (Reference Ad Hoc Hosts)

Option Explicit

'  Echo a message to the console
Sub ShowMsg(MyText)
  Dim TheSplit
  TheSplit = Split(Now()," ")
  WScript.Echo TheSplit(1) & " - " & MyText
End Sub

'  Echo a message to the console along with last API error (if any)
Sub ShowMsg2(MyText,oAPI)
  Dim TheSplit
  TheSplit = Split(Now()," ")
  if oAPI.GetErrorCode = 0 then
    WScript.Echo TheSplit(1) & " - " & MyText
  else
    WScript.Echo TheSplit(1) & " - " & MyText & " Error#" & oAPI.GetErrorCode & ": " & oAPI.GetErrorDescription
  end if
End Sub

' Display the contents of a WaitResult object
Sub DumpWaitResult(oAPI,oWaitResult)
  Dim TaskRunInfoXML
  ShowMsg   "Task Run Results:"
  ShowMsg   "  Name:  " & oWaitResult.TaskName
  ShowMsg   "  ID:    " & oWaitResult.TaskID
  ShowMsg   "  Time:  " & oWaitResult.TaskNominalStartTime & " to "  & oWaitResult.TaskTimeEnded
  if oWaitResult.TaskErrorCode = 0 then
    ShowMsg "  Error: (none)"
  else
    ShowMsg "  Error: " & oWaitResult.TaskErrorCode & ": " & oWaitResult.TaskErrorDescription
  end if
  TaskRunInfoXML = oAPI.GetTaskRunInfoXML(oWaitResult)
   ShowMsg "  Xfer:  " & oAPI.GetValue(TaskRunInfoXML, "FilesSent", 1) & _
      " files, " & _
      oAPI.GetValue(TaskRunInfoXML, "TotalBytesSent", 1) & _
      " bytes"
  'ShowMsg "-= GetTaskRunInfoXML =-"
  'ShowMsg TaskRunInfoXML
  'ShowMsg "-= GetTaskRunXfersXML =-"
  'ShowMsg oAPI.GetTaskRunXfersXML(oWaitResult)
End Sub

'  This main routine does all the work for the script.
Sub Main

   Dim bOK, TryTasks, MaxTasks
   Dim TaskHnd, TaskHndPipe, StartedTasks
   Dim WaitResult, TaskName, WaitSecs
   Dim TaskXML, iii, HostXML, HostID, TaskLimit, TaskID, ReadyXML
   Dim oAPI

   ShowMsg("Starting demonstration using ad hoc hosts.")
   Set oAPI = CreateObject("MICentralAPICOM.MICentralAPI")
   MaxTasks = 3
   TryTasks = 5

   'On Error Resume Next

   ' Sign on and connect
   oAPI.SetHost("192.168.3.178")
   oAPI.SetUser("API1")
   oAPI.SetPassword("A1s2d3f4")
   bOK = oAPI.Connect()
   if NOT bOK then
     ShowMsg2 "Could not sign on to MOVEit Automation!",oAPI
     Exit Sub
   end if
   ShowMsg("Running API version " & oAPI.GetAPIVersion() & _
     " on Central version " & oAPI.GetCentralVersion() )

  ' Use the ".GetItemXML" method to get a local copy of a template task configuration.
  TaskXML = oAPI.GetItemXML("Task", "Template Task - Download from FTP", True)
  if TaskXML="" then
    ShowMsg2 "Failed to read template task configuration! ", oAPI
    Exit Sub
  else
    ShowMsg "Read template task configuration; " & Len(TaskXML) & " bytes."
  end if

  ' Use the ".GetItemXML" method to get a local copy of a template host configuration.
  HostXML = oAPI.GetItemXML("Host", "Template FTP Host", True)
  if HostXML="" then
    ShowMsg2 "Failed to read target host configuration! ", oAPI
    Exit Sub
  else
    ShowMsg "Read target host configuration; " & Len(HostXML) & " bytes."
  end if

  ' Use the ".SetAttribute" method to override the hostname/IP, path, filenames, etc. in the
  ' template host and task.
  ' This will yield XML strings containing a "temporary task" definition.
  TaskID = "9824524"  ' 8-digit values (10,000,000-99,999,999) are safe (we'll add the 8th later)
  HostID = "41243513"  ' 8-digit values (10,000,000-99,999,999) are safe
  HostXML = oAPI.SetAttribute(HostXML, "FTP", 1, "ID", HostID)
  HostXML = oAPI.SetAttribute(HostXML, "FTP", 1, "Host", "ftp.hp.com")
  HostXML = oAPI.SetAttribute(HostXML, "FTP", 1, "DefRetryCount", "0")  'For instant response
  HostXML = oAPI.SetAttribute(HostXML, "FTP", 1, "DefUsername", "anonymous")
  HostXML = oAPI.SetAttribute(HostXML, "FTP", 1, "DefPassword", _
    oAPI.EncryptPW("sample@ipswitch.com"))      'Plaintext password will not work
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "HostID", HostID)
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "Path", "/pub/visualize")
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "FileMask", "TopTools*.*")
  TaskXML = oAPI.SetAttribute(TaskXML, "Source", 1, "DeleteOrig", "0")  'Turn off attempt to delete
  TaskXML = oAPI.SetAttribute(TaskXML, "Destination", 1, "Path", "D:\temp\hpdump")
  TaskXML = oAPI.SetAttribute(TaskXML, "Destination", 1, "FileName", "[yyyy][mm][dd]-[OrigName]")
  TaskXML = oAPI.SetAttribute(TaskXML, "Task", 1, "Name", _
    "Download from HP FTP site using ad hoc host")
  TaskXML = oAPI.SetAttribute(TaskXML, "Task", 1, "ID", TaskID & "0")
  'Append related host XML to temporary task (needs surrounding "Hosts" tag)
  ReadyXML = TaskXML & "<Hosts>" & HostXML & "</Hosts>"

  ' Submit one task and wait for results
  ShowMsg "Temporary task configuration contains " & Len(ReadyXML) & " bytes."
  TaskHnd = oAPI.StartNewTask(ReadyXML)
  If TaskHnd = "" Then
     ShowMsg2 "Temporary task failed to start", oAPI
     Exit Sub
  Else
     ShowMsg "Task " & TaskHnd & " has started"
  End If
  WaitSecs = 120
  Set WaitResult = oAPI.WaitForTasks(TaskHnd, WaitSecs)
  DumpWaitResult oAPI, WaitResult

  ' Now set a limit of 3 tasks in the mix and try to submit 5 in quick succession
  TaskLimit = oAPI.SetMaxTasks(MaxTasks)
  StartedTasks = 0
  ShowMsg "Current Task Limit is " & oAPI.GetMaxTasks()
  TaskHndPipe = ""
  For iii = 1 to TryTasks
    TaskXML = oAPI.SetAttribute(TaskXML, "Task", 1, "Name", _
      "Download from HP FTP site using ad hoc host (" & iii & " of " & TryTasks & ")")
    TaskXML = oAPI.SetAttribute(TaskXML, "Task", 1, "ID", TaskID & iii)
    ReadyXML = TaskXML & ">Hosts<" & HostXML & ">/Hosts<"
    TaskHnd = oAPI.StartNewTask(ReadyXML)
    If TaskHnd = "" Then
      ShowMsg2 "Temporary task (" & iii & " of " & TryTasks & ") failed to start", oAPI
    Else
      ShowMsg "Temporary task (" & iii & " of " & TryTasks & ") has started"
      StartedTasks = StartedTasks + 1
      TaskHndPipe = TaskHndPipe & TaskHnd & "|"
    End If
  Next 'iii

  ' Check on the tasks we put into the mix
  Dim LastWaitResult
  LastWaitResult = "NotBlank"   ' Otherwise it matches too soon!
  ShowMsg "TaskHndPipe = " & TaskHndPipe
  For iii = 1 to StartedTasks
    Set WaitResult = oAPI.WaitForTasks(TaskHndPipe, WaitSecs)
    if LastWaitResult = WaitResult.TaskID then
      ' Ignore it and wait for the next one
      iii = iii - 1
      WScript.Sleep(250)
    else
      DumpWaitResult oAPI, WaitResult
      LastWaitResult = WaitResult.TaskID
      ' Take result found out of list we're looking for
      TaskHndPipe = Replace(Replace(TaskHndPipe, WaitResult.TaskID & "^" & _
        WaitResult.TaskNominalStartTime, ""), "||","|")
      'ShowMsg "TaskHndPipe = " & TaskHndPipe
    end if
  Next 'iii

  ShowMsg("Ending demonstration using ad hoc hosts.")

  set oAPI = Nothing

End Sub

Main

Sample Output

4:46:10 - Starting demonstration using ad hoc hosts.
4:46:10 - Running API version 4.9.1.0 on Central version 4.9.2.5
4:46:10 - Read template task configuration; 469 bytes.
4:46:10 - Read target host configuration; 478 bytes.
4:46:10 - Temporary task configuration contains 1014 bytes.
4:46:10 - Task 98245240^2007-10-16 16:46:10 has started
4:46:14 - Task Run Results:
4:46:14 -   Name:  Download from HP FTP site using ad hoc host
4:46:14 -   ID:    98245240
4:46:14 -   Time:  2007-10-16 16:46:10 to 2007-10-16 16:46:13
4:46:14 -   Error: (none)
4:46:14 -   Xfer:  2 files, 170952 bytes
4:46:14 - Current Task Limit is 3
4:46:14 - Temporary task (1 of 5) has started
4:46:15 - Temporary task (2 of 5) has started
4:46:15 - Temporary task (3 of 5) has started
4:46:15 - Temporary task (4 of 5) failed to start Error#5120: Running this task
would exceed the maximum simultaneous tasks specified in the command.
4:46:16 - Temporary task (5 of 5) failed to start Error#5120: Running this task
would exceed the maximum simultaneous tasks specified in the command.
4:46:16 - TaskHndPipe = 98245241^2007-10-16 16:46:14|98245242^2007-10-16 16:46:1
5|98245243^2007-10-16 16:46:15|
4:46:20 - Task Run Results:
4:46:20 -   Name:  Download from HP FTP site using ad hoc host (3 of 5)
4:46:20 -   ID:    98245243
4:46:20 -   Time:  2007-10-16 16:46:15 to 2007-10-16 16:46:19
4:46:20 -   Error: (none)
4:46:20 -   Xfer:  2 files, 170952 bytes
4:46:24 - Task Run Results:
4:46:24 -   Name:  Download from HP FTP site using ad hoc host (1 of 5)
4:46:24 -   ID:    98245241
4:46:24 -   Time:  2007-10-16 16:46:14 to 2007-10-16 16:46:22
4:46:24 -   Error: (none)
4:46:24 -   Xfer:  2 files, 170952 bytes
4:46:24 - Task Run Results:
4:46:24 -   Name:  Download from HP FTP site using ad hoc host (2 of 5)
4:46:24 -   ID:    98245242
4:46:24 -   Time:  2007-10-16 16:46:15 to 2007-10-16 16:46:21
4:46:24 -   Error: (none)
4:46:24 -   Xfer:  2 files, 170952 bytes
4:46:24 - Ending demonstration using ad hoc hosts.

Creating a Template Host

A template host is useful if you plan on connecting to servers not already defined as hosts in MOVEit Automation (i.e., "ad hoc hosts"). If you plan on connecting only to servers that are defined as hosts in MOVEit Automation, you do not need a template host.

To create a template host, start by creating an ordinary host of the type you will be using most often; for example, "FTP".

To minimize programming effort, set options on your temporary host to mostly closely match those needed to connect to those servers.

You can reference/download host definitions in MOVEit Automation API using either HostID (available in the host definition dialog through MOVEit Automation Admin) or name. The advantage of using a HostID reference is that the host can be renamed without losing the reference. The advantage of using a name reference is that the host can be "switched" with another host simply by renaming one of the hosts through MOVEit Automation Admin.

Creating Template Tasks

To create template tasks, set up simple tasks (source and destination only) that reference your template host.

Do NOT include a schedule with these tasks: at best, schedules will be ignored; at worst, schedules will leave a confusing error regarding your template tasks in your logs.

You can override any of your source values later, but you may find it handy to use obviously incomplete values such as "SourceMaskTBA" in your template definitions to make it clear what you need to later.

You may also want to make a "how to handle the source files after download" choice here too. Generally people opt to only download new files, delete originals or rename originals. If you are downloading specific files or are still testing your operation, you may not need one of these selections. If you want to use the "new files only" option, you must take care to use the same TaskID on subsequent temporary task submissions. The delete/rename options are safe to use in any situation.

You can also override any of your destination values later. However, you should UNCHECK the "Use Original Filename" box (even if you leave the "[OrigName]" macro untouched) to make it perfectly clear that you reserve the right to override the destination filename value too.

Creating Appropriate Permissions for MOVEit Automation API

To work with permissions, sign on to MOVEit Automation Admin as a MOVEit Automation administrator and open the "Settings | Permissions" dialog.

If you want to give your MOVEit Automation API application FULL access to MOVEit Automation, simply add a new user to the "MOVEit Admin" Windows group and use that user's credentials in your MOVEit Automation API application.

Otherwise, continue with these instructions...

First, add a new Windows group called something like "MOVEit Users-API1".

Open your new task group and use the "Add" button in the top section to add a new user called something like "API1". Then use the "Create" button in the bottom section to create a new task group called something like "API1 Task Group". This will open a new dialog from which you can add other elements to the task group.

First go to the "Tasks" tab and add in all your template tasks.

Then go to the "Hosts" tab and...

  • If you plan to submit temporary tasks involving existing hosts, add all the hosts that your MOVEit Automation API application will need to create tasks for as well as your template host.
  • If you plan to submit temporary tasks involving ad hoc hosts, only add the template host (if any).

Also add any other elements (such as scripts or certs) that your MOVEit Automation API application will need to access. (You can also change this later if your are unsure.)

When you click the "OK" button at the bottom of this dialog, you will be asked about permissions. Enable both "Run" and "Add/Edit/Delete" permissions on Tasks.

  • If you plan to submit temporary tasks involving existing hosts, make no additional changes. (Leave the Hosts permissions at "View/Select".)
  • If you plan to submit temporary tasks involving ad hoc hosts, enable the "Add/Edit/Delete" permission on Hosts.

When complete, your Windows group should look like something like the following picture.

Click "OK" until you have been returned to the regular MOVEit Automation Admin interface to save your settings.


Examples - Show Running Tasks

This VBScript example shows how to use the "ShowRunningTasks" function to find out what tasks are currently running. Remember that this call can only be made by users signed on through localhost and users in the MOVEit Log and/or MOVEit Admin groups.

VBScript Code

Option Explicit

' Writes out a single task status
Sub DumpTaskStatus(oAPI, StatusXML, iii)
  ShowMsg "===== " & oAPI.GetValue(StatusXML, "TaskName", iii) & _
    " (" & _
    oAPI.GetValue(StatusXML, "TaskID", iii)  & _
    ") ====="
  ShowMsg "=  Started : " & oAPI.GetValue(StatusXML, "TimeStarted", iii) & _
    " (" & _
    oAPI.GetValue(StatusXML, "StartedBy", iii)  & _
    ")"
  Dim ShortStatus
  ShortStatus = oAPI.GetValue(StatusXML, "Status", iii)
  if Len(ShortStatus) > 50 then ShortStatus = Mid(ShortStatus, 1, 50) & "..."
  ShowMsg "=  Status  : " & ShortStatus
  if oAPI.GetValue(StatusXML, "TotFileBytes", iii) > 0 then
    ShowMsg "=  Transfer: " & oAPI.GetValue(StatusXML, "CurFileBytes", iii) & _
      " of " & _
      oAPI.GetValue(StatusXML, "TotFileBytes", iii)  & _
      " bytes"
  end if
End Sub

'  Echo a message to the console
Sub ShowMsg(MyText)
  Dim TheSplit
  TheSplit = Split(Now()," ")
  WScript.Echo TheSplit(1) & " - " & MyText
End Sub

'  Echo a message to the console along with last API error (if any)
Sub ShowMsg2(MyText,oAPI)
  Dim TheSplit
  TheSplit = Split(Now()," ")
  if oAPI.GetErrorCode = 0 then
    WScript.Echo TheSplit(1) & " - " & MyText
  else
    WScript.Echo TheSplit(1) & " - " & MyText & " Error#" & oAPI.GetErrorCode & ": " & oAPI.GetErrorDescription
  end if
End Sub

'---  Sub Main  ------------------------------------------------
Sub Main
   ShowMsg "showrunningtasks.vbs running"

   Dim bOK
   Dim TaskHnd, WaitResult, TaskName, WaitSecs
   Dim oAPI
   Set oAPI = CreateObject("MICentralAPICOM.MICentralAPI")

   'On Error Resume Next
   oAPI.SetHost("localhost")
   'oAPI.SetHost("192.168.1.123")
   'oAPI.SetUser("almostnoaccess")
   'oAPI.SetPassword("A1s2d3f4")

   bOK = oAPI.Connect()
   if NOT bOK then
     ShowMsg2 "Could not sign on to MOVEit Automation!",oAPI
     Exit Sub
   end if
   ShowMsg("Running API version " & oAPI.GetAPIVersion() & _
     " on Central version " & oAPI.GetCentralVersion() )

   Dim reply, HTab, TaskCount, iii
   HTab = chr(9)
   reply = oAPI.ShowRunningTasks()
   reply = Replace(reply, HTab, "  ")  ' Remove tabs for readability
   If "" = reply OR oAPI.GetErrorCode > 0 Then
        ShowMsg2 "Failed to get status: ", oAPI
         Exit Sub
   Else
         TaskCount = UBound(Split(reply,"<Task>"))  ' Count how many tasks are running
         ShowMsg "Scheduler Status: " & oAPI.GetValue(reply, "SchedulerStatus", 1)
         ShowMsg "Tasks Running: " & TaskCount
         if TaskCount > 0 then
           for iii = 1 to TaskCount
             DumpTaskStatus oAPI, reply, iii
           next 'iii
         end if
         ShowMsg "Full XML Reply: " & reply
   End If

   ShowMsg "showrunningtasks.vbs stopped"

End Sub

Main

Sample Output (With Proper Credentials)

5:01:31 - showrunningtasks.vbs running
5:08:16 - Running API version 4.9.1.0 on Central version 4.9.2.5
5:01:31 - Scheduler Status: On
5:01:31 - Tasks Running: 3
5:01:31 - ===== Disk Cache Clear Test 1b (104874969) =====
5:01:31 - =  Started : 2007-10-19 17:01:28 (Via NextTask)
5:01:31 - =  Status  : Running script Sleep
5:01:31 - ===== Disk Cache Clear Test 3a (208385491) =====
5:01:31 - =  Started : 2007-10-19 17:01:26 (Via NextTask)
5:01:31 - =  Status  : Copying d:/temp/diskcachetest3/MOVEitDMZ.chm from ...
5:01:31 - =  Transfer: 720896 of 1689452 bytes
5:01:31 - ===== Disk Cache Clear Test 2a (659952116) =====
5:01:31 - =  Started : 2007-10-19 17:01:26 (Via NextTask)
5:01:31 - =  Status  : Copying d:/temp/diskcachetest2/MIDMZ22.exe from fi...
5:01:31 - =  Transfer: 5695488 of 5695488 bytes
5:01:31 - Full XML Reply:
  <CmdName>SHOWRUNNINGTASKS</CmdName>
  <ReqID>3</ReqID>
  <RepCode>0</RepCode>
  <RepText></RepText>
  <Time>2007-10-19 17:01:31</Time>
  <Output><Tasks><SchedulerStatus>On</SchedulerStatus>
      <Task><TaskID>104874969</TaskID>
        <TaskName>Disk Cache Clear Test 1b</TaskName>
        <NominalStart>2007-10-19 17:01:28</NominalStart>
        <TimeStarted>2007-10-19 17:01:28</TimeStarted>
        <StartedBy>Via NextTask</StartedBy>
        <Status>Running script Sleep</Status>
        <CurFileBytes>0</CurFileBytes>
        <TotFileBytes>-1</TotFileBytes>
        <LastErrorType>0</LastErrorType>
        <LastErrorText></LastErrorText>
      </Task>
      <Task><TaskID>208385491</TaskID>
        <TaskName>Disk Cache Clear Test 3a</TaskName>
        <NominalStart>2007-10-19 17:01:26</NominalStart>
        <TimeStarted>2007-10-19 17:01:26</TimeStarted>
        <StartedBy>Via NextTask</StartedBy>
        <Status>Copying d:/temp/diskcachetest3/MOVEitDMZ.chm from filesystem</Status>
        <CurFileBytes>720896</CurFileBytes>
        <TotFileBytes>1689452</TotFileBytes>
        <LastErrorType>0</LastErrorType>
        <LastErrorText></LastErrorText>
      </Task>
      <Task><TaskID>659952116</TaskID>
        <TaskName>Disk Cache Clear Test 2a</TaskName>
        <NominalStart>2007-10-19 17:01:26</NominalStart>
        <TimeStarted>2007-10-19 17:01:26</TimeStarted>
        <StartedBy>Via NextTask</StartedBy>
        <Status>Copying d:/temp/diskcachetest2/MIDMZ22.exe from filesystem</Status>
        <CurFileBytes>5695488</CurFileBytes>
        <TotFileBytes>5695488</TotFileBytes>
        <LastErrorType>0</LastErrorType>
        <LastErrorText></LastErrorText>
      </Task>
    </Tasks></Output>
</Response>

5:01:31 - showrunningtasks.vbs stopped

Sample Output (Without Proper Credentials)

5:08:15 - showrunningtasks.vbs running
5:08:16 - Running API version 4.9.1.0 on Central version 4.9.2.5
5:08:16 - Failed to get status:  Error#2020: You do not have sufficient permissi
ons for this command.


Examples - Run Custom Reports

This VBScript example shows how to use the "RunCustomSQL" function to obtain information from the tamper-evident MOVEit Automation task run, file activity and audit logs (i.e., the "taskruns", "stats" and "audit" database tables). Remember that this call can only be made by users signed on through localhost and users in the MOVEit Log and/or MOVEit Admin groups.

See your MOVEit Automation manual ("Advanced Topics - Database - Schema" section) for information about the log table schemas.

VBScript Code

Option Explicit

'  Echo a message to the console
Sub ShowMsg(MyText)
  Dim TheSplit
  TheSplit = Split(Now()," ")
  WScript.Echo TheSplit(1) & " - " & MyText
End Sub

'  Echo a message to the console along with last API error (if any)
Sub ShowMsg2(MyText,oAPI)
  Dim TheSplit
  TheSplit = Split(Now()," ")
  if oAPI.GetErrorCode = 0 then
    WScript.Echo TheSplit(1) & " - " & MyText
  else
    WScript.Echo TheSplit(1) & " - " & MyText & " Error#" & oAPI.GetErrorCode & ": " & oAPI.GetErrorDescription
  end if
End Sub

'---  Sub Main  ------------------------------------------------
Sub Main
   ShowMsg "runcustomsql.vbs running"

   Dim bOK
   Dim TaskHnd, WaitResult, TaskName, WaitSecs
   Dim oAPI
   Set oAPI = CreateObject("MICentralAPICOM.MICentralAPI")

   On Error Resume Next
   'oAPI.SetHost("localhost")
   oAPI.SetHost("192.168.3.178")
   oAPI.SetUser("almostnoaccess")
   oAPI.SetPassword("A1s2d3f4")

   bOK = oAPI.Connect()
   if NOT bOK then
     ShowMsg2 "Could not sign on to MOVEit Automation!",oAPI
     Exit Sub
   end if
   ShowMsg("Running API version " & oAPI.GetAPIVersion() & _
     " on Central version " & oAPI.GetCentralVersion() )

   dim reply, SQLSelect, SpecialDelim, SpecialDelim2, HTab, FindPoint
   SpecialDelim = "&#199;"   ' XML version
   SpecialDelim2 = chr(199)  ' VB version
   HTab = chr(9)

   ' See how many records are currently in the audit table
   SQLSelect = "SELECT COUNT(*) AS MyCount FROM audit;"
   ShowMsg "SQL: " & SQLSelect
   reply = oAPI.RunCustomSQL(SQLSelect, 1, 0, False, "ThisWillBeIgnored")
   If "" = reply OR oAPI.GetErrorCode > 0 Then
        ShowMsg2 "Failed to count records: ", oAPI
         Exit Sub
   Else
       ShowMsg "Current Audit Records: " & oAPI.GetValue(reply, "MyCount", 1)
   End If

   ' Compose a SQL query to read a few audit entries for a particular user
   SQLSelect = "SELECT ID,LogTime,Action,TargetType,TargetID,TargetName,Error,ErrorText " & _
        " FROM audit " & _
        " WHERE username='elroy_admin' " & _
        " and action LIKE 'task_%' OR action LIKE 'cfgsec_%' " & _
        " ORDER BY ID DESC;"
   ShowMsg "SQL: " & SQLSelect

   ' Run the query, limit it to 3 entries, and then format the results
   ' in "Excel-friendly" tab-delimited lines
   reply = oAPI.RunCustomSQL(SQLSelect, 3, 0, True, SpecialDelim)
   If "" = reply Then
         ShowMsg "Error: " & oAPI.GetErrorCode
         ShowMsg oAPI.GetErrorDescription
         Exit Sub
   Else
        ' Format for ready import into Excel (strip leading tabs and entry tags, tab-delimit)
     reply = Replace(reply, HTab & HTab & HTab & "<Record>", "")
     reply = Replace(reply, "</Record>", "")  'CRLF is already at the end of each line
     reply = Replace(reply, SpecialDelim2, HTab)
     FindPoint = InStr(reply, "<Records>")
     reply = Mid(reply, Findpoint + Len("<Records>"))
     FindPoint = InStr(reply, HTab & HTab & HTab & "<More>")
     reply = Mid(reply, 1, Findpoint)
         ShowMsg "Ready for Excel Reply: " & reply
   End If

   ' Run the query, limit it to 3 entries, and then dump the XML-formatted results
   reply = oAPI.RunCustomSQL(SQLSelect, 3, 0, False, "ThisWillBeIgnored")
   If "" = reply Then
         ShowMsg "Error: " & oAPI.GetErrorCode
         ShowMsg oAPI.GetErrorDescription
         Exit Sub
   Else
       reply = Replace(reply, HTab, "  ")
         ShowMsg "Normal (XML) Reply: " & reply
   End If

   ShowMsg "runcustomsql.vbs complete"

End Sub

Main

Sample Output (With Proper Credentials)

6:29:52 - runcustomsql.vbs running
6:29:52 - Running API version 4.9.1.0 on Central version 4.9.2.5
6:29:52 - SQL: SELECT COUNT(*) AS MyCount FROM audit;
6:29:52 - Current Audit Records: 3824
6:29:52 - SQL: SELECT ID,LogTime,Action,TargetType,TargetID,TargetName,Error,Err
orText  FROM audit  WHERE username='elroy_admin'  and action LIKE 'task_%' OR ac
tion LIKE 'cfgsec_%'  ORDER BY ID DESC;
6:29:52 - Ready for Excel Reply:
43311   2007-10-19 18:08:49.83  task_run        task    174565303       Get and
Parse X File Paths      0
43310   2007-10-19 18:08:39.41  task_run        task    598707145       AS2 Rece
ive from Shemp to Moe   0
43309   2007-10-19 18:08:35.83  cfgsec_update   task    598707145       AS2 Rece
ive from Shemp to Moe   0

6:29:52 - Normal (XML) Reply: <Response>
  <CmdName>RUNCUSTOMSQL</CmdName>
  <ReqID>6</ReqID>
  <RepCode>0</RepCode>
  <RepText></RepText>
  <Time>2007-10-19 18:29:52</Time>
  <Output><TimeOfLastUpdate></TimeOfLastUpdate>
    <Records>
      <Record><ID>43311</ID>
        <LogTime>2007-10-19 18:08:49.83</LogTime>
        <Action>task_run</Action>
        <TargetType>task</TargetType>
        <TargetID>174565303</TargetID>
        <TargetName>Get and Parse X File Paths</TargetName>
        <Error>0</Error>
        <ErrorText></ErrorText>
      </Record>
      <Record><ID>43310</ID>
        <LogTime>2007-10-19 18:08:39.41</LogTime>
        <Action>task_run</Action>
        <TargetType>task</TargetType>
        <TargetID>598707145</TargetID>
        <TargetName>AS2 Receive from Shemp to Moe</TargetName>
        <Error>0</Error>
        <ErrorText></ErrorText>
      </Record>
      <Record><ID>43309</ID>
        <LogTime>2007-10-19 18:08:35.83</LogTime>
        <Action>cfgsec_update</Action>
        <TargetType>task</TargetType>
        <TargetID>598707145</TargetID>
        <TargetName>AS2 Receive from Shemp to Moe</TargetName>
        <Error>0</Error>
        <ErrorText></ErrorText>
      </Record>
      <More>1</More>
    </Records>
  </Output>
</Response>

6:29:52 - runcustomsql.vbs complete

Sample Output (Without Proper Credentials)

6:32:39 - runcustomsql.vbs running
6:32:39 - Running API version 4.9.1.0 on Central version 4.9.2.5
6:32:39 - SQL: SELECT COUNT(*) AS MyCount FROM audit;
6:32:39 - Failed to count records:  Error#2020: You do not have sufficient permissi
ons for this command.


Examples - Update a global parameter using CheckoutItem and ModifyItem

This VBScript example shows how to checkout an item from the MOVEit Automation config, modify it, and submit the changes. This particular example uses CheckoutItem to checkout a global parameter called NumberSeq, which keeps track of a numberic sequence of numbers. If the Checkout is successful, the script will increment the value, editing the XML to reflect this change, and then re-submit the XML using ModifyItem to update the MOVEit Automation config with the changes that were made.

VBScript Code

Option Explicit

Dim oAPI

Function IncrementCount()
    Dim ItemType, ItemID, ItemXML, Count
    Dim oXML, oNode
    Dim bOK, ErrDesc

    bOK = False
    ItemType = "GlobalParameters"
    ItemID = ""
    ' check out the GlobalParameters section
    ItemXML = oAPI.CheckoutItem(ItemType, ItemID)
    If ItemXML = "" And oAPI.GetErrorCode() = 4010 Then
        WScript.Echo "The global parameters section is currently checked out to someone else. Will retry in 15 seconds..." & vbcrlf
        WScript.Sleep 15000
        ItemXML = oAPI.CheckoutItem(ItemType, ItemID)
    End If
    If Not ItemXML = "" Then
        ' load the XML obtained from CheckoutItem into an MSXML object for parsing
        Set oXML = CreateObject("Msxml2.DOMDocument.4.0")
        oXML.loadXML(ItemXML)
        ' look for a global parameter named "NumberSeq"
        Set oNode = oXML.selectSingleNode("//GlobalParameters/NumberSeq")
        If Not oNode Is Nothing Then
            ' get the current count of the number sequence and then increment the value
            Count = oNode.text
            Count = Count + 1
            oNode.text = Count
            ItemXML = oXML.xml
            ' re-submit the modified GlobalParameter section
            bOK = oAPI.ModifyItem(ItemType, ItemID, ItemXML)
            If Not bOK Then
                ErrDesc = "Error modifying global parameters: " & oAPI.GetErrorCode() & ": " & oAPI.GetErrorDescription()
            End If
        Else
            ErrDesc = "Couldn't find global parameter ""NumberSeq""."
        End If
        Set oXML = Nothing
        Set oNode = Nothing
    Else
        ErrDesc = "Error checking out global parameters: " & oAPI.GetErrorCode() & ": " & oAPI.GetErrorDescription()
    End If

    If Not bOK Then
        WScript.Echo "Error in IncrementCount: " & ErrDesc
    End If

    IncrementCount = bOK
End Function

Sub Main()

    Set oAPI = CreateObject("MICentralAPICOM.MICentralAPI")

    oAPI.SetHost("localhost")
    'oAPI.SetUser("")
    'oAPI.SetPassword("")
    If Not oAPI.Connect() Then
        WScript.Echo "Could not sign on to MOVEit Automation: " & oAPI.GetErrorCode() & ": " & oAPI.GetErrorDescription()
        Exit Sub
    End If
    WScript.Echo "Signed on to MOVEit Automation." & vbcrlf

    If IncrementCount() Then
        WScript.Echo "Successfully incremented global parameter ""NumberSeq""."
    End If

End Sub

Main

Set oAPI = Nothing


Examples - Create a Task From Scratch

This example shows how to create a new task using an existing XML template for a task definition.

VBScript Code

First we need to get some template XML for a task. One method is to define a task XML skeleton as follows:

TaskXMLTemplate = "<Task ID="""" Name="""" Active=""0"" NextEID=""3"" AR=""0"">" & _
    "<Schedules/>" & _
    "<Source HostID="""" Type="""" Path="""" FolderName="""" FolderID="""" FolderType="""" FileMask="""" DeleteOrig=""0"" NewFilesOnly=""0"" SearchSubdirs=""0"" Unzip=""0"" RetryIfNoFiles=""0"" " & _
        "UseDefRetryCount=""1"" UseDefRetryTimeoutSecs=""1"" UseDefRescanSecs=""1"" UseDefBlindDL=""1"" UDMxFi=""1"" UDMxBy=""1"" UseDefMD5Get=""1"" UseDefMD5File=""1"" UseDefUser=""1"" UseDefClientKey=""1"" UseDefRsm=""1"" ID=""1""/>" & _
    "<Destination HostID="""" Type="""" Path="""" FileName=""[OrigName]"" UseOrigName=""1"" ForceDir=""1"" OverwriteOrig=""1"" UseRelativeSubdirs=""0"" Zip=""0"" UseDefRetryCount=""1"" UseDefRetryTimeoutSecs=""1"" ID=""2""/>" & _
"</Task>"

Alternatively, you could have a template task defined in MOVEit Automation from which you can build new tasks:

TaskXMLTemplate = oAPI.GetItemXML("Task", "Template Task", True)

In the following code we alter the template task XML to create a brand new task. The SuggestItemID() function is used to generate a new ID for the task. The CreateItem() function is used to create the new task once done modifying the XML.

    ItemType = "Task"
    ' Get a suggested ID for the task.
    ItemID = oAPI.SuggestItemID(ItemType)
    ' Update the TaskXMLTemplate to include the new Task ID and a friendly name.
    ItemXML = oAPI.SetAttribute(TaskXMLTemplate, "Task", 1, "ID", ItemID)
    ItemXML = oAPI.SetAttribute(ItemXML, "Task", 1, "Name", "New Task Created by API")

    ' We will use a MOVEit DMZ server for the Source.
    SourceType = "Host"
    SourceHostType = "siLock"
    SourceName = "My DMZ Host"
    SourceXML = oAPI.GetItemXML(SourceType, SourceName, True)

    If SourceXML = "" Then
        ErrDesc = "Couldn't find host with name '" & SourceName & "'"
        bOK = False
        Exit Sub
    End If

    ' Get the ID for this Source host.
    SourceID = oAPI.GetAttribute(SourceXML, SourceHostType, 1, "ID")

    ' Update the ItemXML with the source information.
    ItemXML = oAPI.SetAttribute(ItemXML, "Source", 1, "HostID", SourceID)
    ItemXML = oAPI.SetAttribute(ItemXML, "Source", 1, "Type", SourceHostType)
    ItemXML = oAPI.SetAttribute(ItemXML, "Source", 1, "FolderName", "/Distribution/Accounting")
    ItemXML = oAPI.SetAttribute(ItemXML, "Source", 1, "FileMask", "*.xls")

    ' We will use an FTP server for the Destination.
    DestType = "Host"
    DestHostType = "FTP"
    DestName = "My FTP Host"
    DestXML = oAPI.GetItemXML(DestType, DestName, True)

    If DestXML = "" Then
        ErrDesc = "Couldn't find host with name '" & DestName & "'"
        bOK = False
        Exit Sub
    End If

    ' Get the ID for this Destination host.
    DestID = oAPI.GetAttribute(DestXML, DestHostType, 1, "ID")

    ' Update the ItemXML with the destination information.
    ItemXML = oAPI.SetAttribute(ItemXML, "Destination", 1, "HostID", DestID)
    ItemXML = oAPI.SetAttribute(ItemXML, "Destination", 1, "Type", DestHostType)
    ItemXML = oAPI.SetAttribute(ItemXML, "Destination", 1, "Path", "/inbound")

    ' Attempt to add the new item to some task groups.
    Groups = "My Tasks|Production Tasks|DMZ Tasks"

    ' Since we're creating an brand new item, there's no need to call CheckoutItem().
    ' Submit the new item using CreateItem().
    bOK = oAPI.CreateItem(ItemType, ItemID, ItemXML, Groups)
    If Not bOK Then
        ErrDesc = "Error creating item: " & oAPI.GetErrorCode() & ": " & oAPI.GetErrorDescription()
    End If


XML Results

XML Document Formats - Results

MOVEit Automation API optionally returns information about overall task status, and the status of individual job steps. These results are in XML format.

A package of XSL templates that show how to easily render XML returned from the "- tf:..." and "-sf:..." commands as simple HTML, styled HTML and CSV reports is available in the Distribution/MOVEit/Central/API/Windows/Extras folder on the MOVEit support site, https://moveitsupport.ipswitch.com. A Windows batch file, XSL-render utility and a (Flash) demonstration video that shows how to use these templates and utilities to quickly generate user-friendly output is included in this package.

Overall task status format

The command-line client's -tf argument and the API's GetTaskRunInfoXML method both return a single row from the taskruns table in the micstats database, as an XML string of the form:

<Records>
<Record>
<TaskID>id of task</TaskID>
<TaskName>name of task</TaskName>
<TimeStarted>YYYY-MM-DD hh:mm:ss</TimeStarted>
<TimeEnded>YYYY-MM-DD hh:mm:ss</TimeEnded>
<FilesSent>number of files sent</FilesSent>
<TotalBytesSent>total number of bytes sent to destinations</TotalBytesSent>
<LastErrorType>0 if task succeeded</LastErrorType>
<LastErrorText>empty if no errors</LastErrorText>
... other fields ...
</Record>
</Records>

For example:

<Records>
   <Record><ID>405659</ID>
      <LogStamp>2006-06-21 13:58:21.67</LogStamp>
      <TaskID>133254349</TaskID>
      <Node>0</Node>
      <NominalStart>2006-06-21 13:58:20</NominalStart>
      <TaskName>Monthly Reports</TaskName>
      <TimeStarted>2006-06-21 13:58:20.49</TimeStarted>
      <TimeEnded>2006-06-21 13:58:21</TimeEnded>
      <StartedBy>(a local user)</StartedBy>
      <Success>Success</Success>
      <FilesSent>2</FilesSent>
      <TotalBytesSent>36350</TotalBytesSent>
      <HasBeenRead>0</HasBeenRead>
      <LastErrorType>0</LastErrorType>
      <LastErrorText></LastErrorText>
   </Record>
   <More>0</More>
</Records>

For a complete list of the fields returned, see the description of the taskruns table in the MOVEit Automation help file, under the topic Advanced Topics - Database - Schema.

Detailed job step status format

The command-line client's -sf argument and the API's GetTaskRunXfersXML method both return potentially many rows from the stats table, as an XML string of the form:

<Records>
<Record>
<TaskID>id of task</TaskID>
<TimeStarted>YYYY-MM-DD hh:mm:ss</TimeStarted>
<TimeEnded>YYYY-MM-DD hh:mm:ss</TimeEnded>
<Action>get, send, process, or delete</FilesSent>
<SourceFilename>filename of source, with path</SourceFilename>
<DestFilename>filename of source, with path</DestFilename>
<NBytes>number of bytes sent</NBytes>
<ErrCode>0 if success</ErrCode>
... other fields ...
</Record>
... more row nodes ...
</Records>

For example:

<Records>
   <Record><ID>360670</ID>
      <LogStamp>2006-06-21 13:58:21.27</LogStamp>
      <TaskID>133254349</TaskID>
      <Node>0</Node>
      <NominalStart>2006-06-21 13:58:20</NominalStart>
      <Action>get</Action>
      <SourceHost>localhost MS FTP</SourceHost>
      <SourceFilename>/uploads/test1.ggg</SourceFilename>
      <SourceFilenameOnly>test1.ggg</SourceFilenameOnly>
      <SourceFileID></SourceFileID>
      <SourceNBytes>33408</SourceNBytes>
      <SourceDuration>0.34</SourceDuration>
      <SourceMDN></SourceMDN>
      <DestHost></DestHost>
      <DestFilename></DestFilename>
      <DestFilenameOnly></DestFilenameOnly>
      <DestFileID></DestFileID>
      <NBytes>0</NBytes>
      <DestDuration>0</DestDuration>
      <DestMDN></DestMDN>
      <ErrCode>0</ErrCode>
      <Message></Message>
   </Record>
   <Record><ID>360671</ID>
      <LogStamp>2006-06-21 13:58:21.32</LogStamp>
      <TaskID>133254349</TaskID>
      <Node>0</Node>
      <NominalStart>2006-06-21 13:58:20</NominalStart>
      <Action>get</Action>
      <SourceHost>localhost MS FTP</SourceHost>
      <SourceFilename>/uploads/test1.hhh</SourceFilename>
      <SourceFilenameOnly>test1.hhh</SourceFilenameOnly>
      <SourceFileID></SourceFileID>
      <SourceNBytes>2942</SourceNBytes>
      <SourceDuration>0</SourceDuration>
      <SourceMDN></SourceMDN>
      <DestHost></DestHost>
      <DestFilename></DestFilename>
      <DestFilenameOnly></DestFilenameOnly>
      <DestFileID></DestFileID>
      <NBytes>0</NBytes>
      <DestDuration>0</DestDuration>
      <DestMDN></DestMDN>
      <ErrCode>0</ErrCode>
      <Message></Message>
   </Record>
   <Record><ID>360672</ID>
      <LogStamp>2006-06-21 13:58:21.64</LogStamp>
      <TaskID>133254349</TaskID>
      <Node>0</Node>
      <NominalStart>2006-06-21 13:58:20</NominalStart>
      <Action>send</Action>
      <SourceHost>localhost MS FTP</SourceHost>
      <SourceFilename>/uploads/test1.ggg</SourceFilename>
      <SourceFilenameOnly>test1.ggg</SourceFilenameOnly>
      <SourceFileID></SourceFileID>
      <SourceNBytes>33408</SourceNBytes>
      <SourceDuration>0.34</SourceDuration>
      <SourceMDN></SourceMDN>
      <DestHost>(Default)</DestHost>
      <DestFilename>c:\tmp\two\test1.ggg</DestFilename>
      <DestFilenameOnly>test1.ggg</DestFilenameOnly>
      <DestFileID></DestFileID>
      <NBytes>33408</NBytes>
      <DestDuration>0.33</DestDuration>
      <DestMDN></DestMDN>
      <ErrCode>0</ErrCode>
      <Message></Message>
   </Record>
   <Record><ID>360673</ID>
      <LogStamp>2006-06-21 13:58:21.67</LogStamp>
      <TaskID>133254349</TaskID>
      <Node>0</Node>
      <NominalStart>2006-06-21 13:58:20</NominalStart>
      <Action>send</Action>
      <SourceHost>localhost MS FTP</SourceHost>
      <SourceFilename>/uploads/test1.hhh</SourceFilename>
      <SourceFilenameOnly>test1.hhh</SourceFilenameOnly>
      <SourceFileID></SourceFileID>
      <SourceNBytes>2942</SourceNBytes>
      <SourceDuration>0</SourceDuration>
      <SourceMDN></SourceMDN>
      <DestHost>(Default)</DestHost>
      <DestFilename>c:\tmp\two\test1.hhh</DestFilename>
      <DestFilenameOnly>test1.hhh</DestFilenameOnly>
      <DestFileID></DestFileID>
      <NBytes>2942</NBytes>
      <DestDuration>0.01</DestDuration>
      <DestMDN></DestMDN>
      <ErrCode>0</ErrCode>
      <Message></Message>
   </Record>
   <More>0</More>
</Records>

There will generally be more than one row for each file, corresponding to the various actions performed on the file. In this example, you can see two get records, followed by two send records.

For a complete list of the fields returned, see the description of the stats table in the MOVEit Automation help file, under the topic Advanced Topics - Database - Schema.

Do not assume that MOVEit Automation will return only the fields described here, in the exact order described there. Future versions of MOVEit Automation will likely include additional fields in the database. Therefore, an assumption that, for instance, the field after NBytes will always be DestDuration may create an incompatibility with future versions of MOVEit Automation.

Running Tasks Status format

The API's ShowRunningTasks method can return potentially many rows as an XML string of the form:

<Tasks>
<Task>
<TaskID>id of task</TaskID>
<NominalStart>YYYY-MM-DD hh:mm:ss</NominalStart>
<TimeStarted>YYYY-MM-DD hh:mm:ss</TimeStarted>
<StartedBy>user name</StartedBy>
<Status>current task status</Status>
<CurFileBytes>number of bytes transferred for current file</CurFileBytes>
<TotFileBytes>total number of bytes transferred</TotFileBytes>
<LastErrorType>0 if success</LastErrorType>
<LastErrorText>text of error</LastErrorText>
</Task>
... more row nodes ...
</Tasks>

For example:

<Tasks>
   <SchedulerStatus>On</SchedulerStatus>
       <Task><TaskID>12345</TaskID>
           <TaskName>MyTempTask</TaskName>
           <NominalStart>2007-10-24 10:06:26</NominalStart>
           <TimeStarted>2007-10-24 10:06:26</TimeStarted>
           <StartedBy>(a local user)</StartedBy>
           <Status></Status>
           <CurFileBytes>0</CurFileBytes>
           <TotFileBytes>-1</TotFileBytes>
           <LastErrorType>0</LastErrorType>
           <LastErrorText></LastErrorText>
       </Task>
</Tasks>

The fields returned here are similar to database fields, but are not returned from the MOVEit Automation database. They are created from status information kept internally in MOVEit Automation. They are, therefore, not described in any MOVEit Automation Database Schema information in the MOVEit Automation help file.

Do not assume that MOVEit Automation will return only the fields described here, in the exact order described there. Future versions of MOVEit Automation will likely include additional fields in the running task status. Therefore, an assumption that, for instance, the field after Status will always be CurFileBytes may create an incompatibility with future versions of MOVEit Automation.

RunCustomSQL Results Format

The API's RunCustomSQL method can return potentially many rows as an XML string of the form:

<Records>
<Record>
... whatever fields are requested ...
</Record>
... more row nodes ...
<More> 0 if this is the end, or 1 if more data to be sent <More>
</Records>

For example, a request of the form:

oAPI.RunCustomSQL("SELECT TaskID, NominalStart, TimeEnded, LastErrorType, LastErrorText FROM TaskRuns LIMIT 5", 9999, 0, false, "")

could return data like this:

<Records>
   <Record><TaskID>741317087</TaskID>
      <NominalStart>2006-07-27 08:00:00</NominalStart>
      <TimeEnded>2006-07-27 08:00:50</TimeEnded>
      <LastErrorType>0</LastErrorType>
      <LastErrorText></LastErrorText>
   </Record>

   <Record><TaskID>729570621</TaskID>
      <NominalStart>2006-07-27 08:00:00</NominalStart>
      <TimeEnded>2006-07-27 08:00:50</TimeEnded>
      <LastErrorType>0</LastErrorType>
      <LastErrorText></LastErrorText>
   </Record>

   <Record><TaskID>729570621</TaskID>
      <NominalStart>2006-07-26 08:00:00</NominalStart>
      <TimeEnded>2006-07-26 08:00:26</TimeEnded>
      <LastErrorType>0</LastErrorType>
      <LastErrorText></LastErrorText>
   </Record>

   <Record><TaskID>222222</TaskID>
      <NominalStart>2006-07-27 02:15:00</NominalStart>
      <TimeEnded>2006-07-27 02:15:26</TimeEnded>
      <LastErrorType>0</LastErrorType>
      <LastErrorText></LastErrorText>
   </Record>

   <Record><TaskID>507522607</TaskID>
      <NominalStart>2006-07-27 08:00:00</NominalStart>
      <TimeEnded>2006-07-27 08:00:53</TimeEnded>
      <LastErrorType>6</LastErrorType>
      <LastErrorText>Script Command Line App returned error -2: WARNING - 'c:\stdnet\s
      ilock\AS2\ASxSender\bin\debug\ASxSender.exe AS1 C:\TEMP\MIC\7e8-0002\atc10001.tm
      p as1test AS1TestFile4 1>c:\temp\AS2Demo\AS1TestFile4Out.txt 2>c:\temp\AS2
      Demo\AS1TestFile4Err.txt' retur</LastErrorText>
   </Record>

   <More>0</More>
</Records>

For a complete list of the possible fields that may be returned from the database, see the MOVEit Automation help file, under the topic Advanced Topics - Database - Schema.


Task Configuration

XML Document Formats - Task Configuration - Overview

The TaskXML parameter to StartNewTask is an XML string with the following format. Optional sections are shown in this style.

<Task (with attributes)>
<Source .../>
<Destination .../>
<Process .../>
<Parameters>
<ParamName1>ParamValue1</ParamName1>
</Parameters>
 </Task>
<Hosts>
...
</Hosts>
<Scripts>
...
</Scripts>

Most items are configured by XML attributes. True/False settings are indicated by "1" or "0". There are many potential settings, but most tasks use only a few. Reasonable defaults are provided for nearly all attributes, so generally you need to provide only a small number of attributes in any invocation.

Here's a typical TaskXML string:

    <Task ID="12345678" Name="Get from SSH">
<Source ID="11" HostID="69230956" Type="SSHFTP"
Path="/home/fred" FileMask="download.zip" UseDefRetryTimeoutSecs="1"
UseDefRescanSecs="1"/>
<Destination ID="13" HostID="0" Type="FileSystem" Path="C:\TEMP\"
FileName="[OrigName]" UseOrigName="1" ForceDir="1" OverwriteOrig="1"
UseRelativeSubdirs="1"/>
</Task>
<Hosts>
<SSHFTP ID="69230956" Name="loggerSSH" Host="logger" Port="22"
IgnoreCertProbs="1" DefUsername="fred" DefPassword="!s!Bl+gQ4EBPYyiHD=="/>
</Hosts>

If a dynamically-created task contains references to hosts or scripts not provided as part of the XML, MOVEit Automation will fill in the host or script from the configuration file. Any references to PGP keys, SSH keys, or global task parameters will also be satisfied from the configuration file.

Read further about the formats of the following XML nodes:

  • Task
  • Source and Destination
  • Process
  • Host
  • Script


Task Configuration

XML Document Formats - Task Configuration - Task

Task nodes have the following attributes:

Attribute | Description
ID | Task ID
Active | 0 means the task is never run by the scheduler or any of the notifiers.
AR | 1 means that the task should automatically be rerun if any source hits a MaxFiles or MaxBytes limit.
CacheNames "random" (the default) means cache files have random names.
"orig" means that original names are retained; this is necessary for some scripts, but can be problematic if the same filename appears on more than one source.
CAS "Compare Across Sources", an advanced sync-only option that tells us how to decide which files should be downloaded.
  • "N" (never) says to always compare the previous directory listing to the current listing. If there was no previous directory listing, download all files.
  • "A" (always) says to always compare the current files on this source to the current files on the other source, looking for significant differences in timestamps. This method is not reliable because the clocks are usually not in sync.
  • Empty (default) is to compare the previous to the current IF a previous directory listing is available, else compare across servers. Typically a previous listing is available, except for the first time that the sync task runs.
Name | Task name
NextEID | Next entity ID. This is used by Admin to assign IDs to elements. Not needed by Central.
SameSecs This new task attribute will describe how far apart two timestamps can be to still be considered the same. It is used during an initial sync run, when we must compare files across systems whose clocks may not be synced. This number applies after timezone and DST adjustments have been made. The default will be 43200 seconds (12 hours).
A value of -1 means that timestamps are always considered the same.
A value of -2 means that timestamps are always considered different (i.e., "copy all files, even if they have not been modified).
Note: this should be implemented as a signed long integer.
TT | Task Type. If "Sy", this is a Synchronization task. If "COS", this is an Advanced task. Default is Traditional task.


Source and Destination Configuration

XML Document Formats - Task Configuration - Sources and Destinations

These attributes are common to sources and destinations. Most attributes apply to only a few host types.

Attribute | Description | Hosts
AB | "ascii" or "binary" transfer mode. Used only if UseDefAB is 1. | FTP
Account | Account name. Rarely used. | FTP
AddCom | Additional commands ("quote" commands) sent before each transfer. | FTP
AddComAX | Additional commands ("quote" commands) sent after each transfer. | FTP
ClientCertSHA1 | The SHA1 hash of the client certificate. Applies only if UseDefClientCert is 0. | DMZ, FTP
ClientCertStore | The store name (typically "My") of the client certificate. Applies only if UseDefClientCert is 0. | DMZ, FTP
ClientCertSubject | The subject name of the client certificate. Nowadays, the use of ClientCertSHA1 is preferred. Applies only if UseDefClientCert is 0. | DMZ, FTP
ClientKeyID | The ID of the SSH key, if any. | SSH
ConnTimeoutSecs | Number of seconds to wait until timing out a connection to the host, in seconds. Applies only if UseDefConnTimeoutSecs is 0. | DMZ, FTP, SSH, POP3, SMTP
DataTimeoutSecs | Number of seconds to wait until timing out a data transfer to/from the host, in seconds. Applies only if UseDefDataTimeoutSecs is 0. | DMZ, FTP, POP3, SMTP
FolderID | The ID of the folder. | DMZ
FolderName | The full path of the folder. | DMZ
FolderType | The numeric type of the folder; -1 for a pseudo folder, 4 for Distribution or 7 for Home folders. | DMZ
HostID | The numeric ID of the Host node to which this source or destination applies. | All
ID | Arbitrary ID used by MOVEit Automation Admin to identify this node. | All
MDNPath | The path to where the MDN will be stored. Applies only to AS3 hosts. | AS3
Passive | 1 to use passive mode, else 0 to use active mode. Applies only if UseDefPassive is 0. | FTP
Password | Encrypted password. | Most
Path | The full path to the folder. | FTP, SSH, Filesystem
RetryCount | The number of retries. Applies only if UseDefRetryCount is 0. | All
RetryTimeoutSecs | The number of seconds between retries. Applies only if UseDefRetryTimeoutSecs is 0. | All
ReuseSSL | 1 to re-use an existing SSL session, else 0. Applies only if UseDefReuseSSL is 0. | FTP
Rsm | 1 to resume previous transfers, else 0. Applies only if UseDefRsm is 0. | FTP, SSH
Type | The type of the source or destination: siLock (means MOVEit DMZ), FTP, SSHFTP, FileSystem, SMTP, POP3, AS1, AS2, or AS3. | All
UseDefAB | 1 to use the host's default ASCII vs. binary setting, else 0. | FTP
UseDefClientCert | 1 to use the host's default client certificate, else 0. | DMZ, FTP
UseDefClientKey | 1 to use the host's default SSH key, else 0. | SSH
UseDefConnTimeoutSecs | 1 to use host's default connection timeout, else 0. | DMZ, FTP, SSH, POP3, SMTP
UseDefDataTimeoutSecs | 1 to use host's default data transfer timeout, else 0. | DMZ, FTP, POP3, SMTP
UseDefPassive | 1 to use the host's default active vs. passive setting, else 0. | FTP
UseDefRetryCount | 1 to use the host's default retry count, else 0. | All
UseDefRetryTimeoutSecs | 1 to use the host's default retry timeout, else 0. | All
UseDefReuseSSL | 1 to use host's default re-use SSL sessions setting, else 0. | FTP
UseDefRsm | 1 to use host's default resume failed transfers setting, else 0. | FTP, SSH
UseDefUser | 1 to use the host's default username, else 0. | Most
UseDefWinCopyFileAPI | 1 to use the host's default setting for whether to use the Windows CopyFile API, else 0. | Share
UseDefXS | 1 to use the host's default setting for whether to use the XSHA1 command, else 0. | FTP
UseWinCopyFileAPI | 1 to use the Windows CopyFile API, else 0. Applies only if UseDefPassive is 0. | Share
Username | The username to login as. Applies only if UseDefUser is 0. | Most
XS | 1 to use XSHA1 command with host, else 0. Applies only if UseDefXS is 0. | FTP

Sources have the following XML attributes in addition to those common to sources and destinations:

Attribute | Description | Hosts
BlindDL | 1 if this is a blind download. Applies only if UseDefBlindDL is 0. Applies only to FTP and SSH hosts. | FTP, SSH
DeleteOrig 1 means delete orig after successful processing.
2 means rename the original after successful processing. 		All
DelRename | 1 means delete "to" filename before rename. Applies only DeleteOrig is 2. | All
DownloadGroup | A value of Collection means download DMZ bundle. | DMZ
ExFile | Exclude these files (mask) | All
ExFo | Exclude these folders (mask) | All
FileMask | Filemask for file selection. May include ";" as an OR operator, and also ampersand--see doc | All
Format | "CSV" or "XML"; only if bundle. | DMZ
MxBy | The maximum number of bytes that we may download. 0 means infinite. Applies only if UDMxBy is 0. | All
MxFi | The maximum number of files that we may download. 0 means infinite. Applies only if UDMxFi is 0. | All
MD5File | The filename of the MD5 file, if MD5 files are being used. Applies only if UseDefMD5File is 0. | FTP, SSH
MD5Get | "IfPresent", "Required", or "Never". Determines whether to download and process an MD5 file. Applies only if UseDefMD5Get is 0. | FTP, SSH
MDNFilenameToSend | Filename to send MDN file as for AS3, after receive. | AS3
NewFilesOnly | 1 means look for new files only. | DMZ, FTP, SSH, Filesystem
PartnerName | ASx partner name, when configured in the source. | AS1, AS2, AS3
RenameTo | Filename to which this should be renamed; applies only if DeleteOrig=2. | DMZ, FTP, SSH, Filesystem
RescanSecs | The number of seconds to wait before rescanning the directory, to see whether files have changed. Applies only if UseDefRescanSecs is 0. | FTP, SSH, Filesystem
RetryIfNoFiles | 1 means rescan the source if no files were found. | DMZ, FTP, SSH, Filesystem
SearchSubdirs | 1 means recursive directory listing. | DMZ, FTP, SSH, Filesystem
Sort | How to sort filenames. This is a string of form 1,2 where 1 is Date, Size or Filename and 2 is A or D (for Ascending or Descending). Applies only if UseDefSort is 0. | DMZ
SubjectMatch | AS1 email subject mask. | AS1
SyDel Describes whether to synchronize deletions in a sync task.
  • 0 means that no files will be deleted.
  • 1 means that files which go missing from the source so marked should be deleted from the other source. It is expected that Admin will select this by default on both sources when setting up a Sync task.
  • 2 means that in addition to #1, for unidirectional A to B sync, any extra files that materialize on B will be deleted if there is no matching file on A.
DMZ, FTP, SSH, Filesystem
SyF | 1 means sync from this source; only applies to Sync tasks. | DMZ, FTP, SSH, Filesystem
SyT | 1 means sync to this source; only applies to Sync tasks. One-way sync tasks have 1 source with SyF=1 and one with SyT=1. | DMZ, FTP, SSH, Filesystem
UDMxBy | Use default maximum bytes from host. Defaults to 1. | DMZ, FTP, SSH, Filesystem
UDMxFi | Use default maximum files from host. Defaults to 1. | DMZ, FTP, SSH, Filesystem
Unzip | 1 means unzip the file and process the resulting members, but only if the filename ends in ".zip". | All
UseDefBlindDL | 1 to use the host's default blind download setting, else 0. | FTP, SSH
UseDefMD5File | 1 to use the host's default MD5 filename, else 0. | FTP, SSH
UseDefMD5Get | 1 to use the host's default setting whether to download an MD5 file, else 0. | FTP, SSH
UseDefPartner | For ASx only, 1 means to use partner name from host | AS1, AS2, AS3
UseDefRescanSecs | 1 to use the host's default time between rescans, else 0. | FTP, SSH, Filesystem
UseDefSort | 1 to use the host's default directory sort, else 0. | DMZ
UseLCaseComp | 1 to use case-insensitive filename comparison for Sync tasks, else 0; only applies to Sync tasks. | All

Destinations have the following attributes in addition to those common to sources and destinations:

Attribute | Description | Hosts
AddressTo | Email address of recipient. | SMTP
FileName | The desired name on the destination. Applies only if UseOrigName is 0. | All
ForceDir | 1 to force the creation of the destination folder if it does not exist. | DMZ, FTP, SSH, Filesystem
MDNFileMaskToPoll | Filemask to poll for the message disposition notification. | AS1, AS2, AS3
Message | The optional body of the email message. | SMTP
OverwriteOrig | 1 to allow the overwrite of an existing file with the same name. | DMZ, FTP, SSH, Filesystem
RequestMDN | 1 to request an MDN to be returned. | AS1, AS2, AS3
RequestAsyncMDN | 1 to request that the MDN be asynchronous. | AS1, AS2, AS3
Subject | The optional subject of the email message. | SMTP
UseOrigName | 1 if the file on the destination should have the same name as it had on the source. | All
UseRelativeSubdirs | 1 if files in subfolders on the source should be sent to the same subfolders on the destination. Applies only if the source had SearchSubdirs="1". | DMZ, FTP, SSH, Filesystem
Zip | 1 if the file should be zipped before sent. If you set this, you will probably want to set UseOrigName="0" and choose a FileName which ends in .zip. | All


Process Configuration

XML Document Formats - Task Configuration - Process

Process nodes include the following attributes:

Attribute | Description
ID | An arbitrary numeric ID by which the process is identified to MOVEit Automation Admin.
ScriptID | The numeric ID of the script which should be run by this process.
Run | "Once" to run per-task, or "PerFile" to run per-file.


Host Configuration

XML Document Formats - Task Configuration - Host

Unlike other sections of the XML, host XML nodes have node names which reflect the type of the host: siLock (for MOVEit DMZ), FTP, SSHFTP, FileSystem, SMTP, POP3, AS1, AS2, or AS3.

It is not necessary to include a FileSystem host in the TaskXML; if none is included, the configured FileSystem host is used.

Host elements have the following attributes:

Attribute | Description | Hosts
AddCom | The default additional commands ("quote" commands) sent before each transfer. | FTP
AddComAX | The default additional commands ("quote" commands) sent after each transfer. | FTP
AddComSignon | The additional commands ("quote" commands) sent right after signon. | FTP
AdjDST | 1 if this host's timestamps will change when Daylight Savings goes into (or out of) effect. | DMZ, FTP, SSH, Filesystem
AS1HostID | The ID of the related AS1 host, if applicable. | AS2
AuthOrder | An optional string like "tls|tls-x|ssl" specifying the order in which we should try AUTH commands if using explicit SSL. This is for maximum flexibility with unusual FTP servers. The tokens in this string have these meanings: "tls" - Try AUTH TLS, followed by PROT P if nec. "tls-x" - Try AUTH TLS-P or TLS-C. "ssl" - Try AUTH SSL, also switching to SSL instead of TLS. "tls-y" - Try the opposite of the current type; e.g., if current type is TLS-P, try AUTH TLS-C. | FTP
CmpL | SSH compression level; 0-9. Defaults to 6. | SSH
CustomDir | 1 if column-based custom directory parsing is being used. | FTP, SSH
CustomDirSkipTop | The number of lines that should be skipped at the top of a directory listing. Applies only if CustomDir is 1. | FTP, SSH
CustomDirSkipBottom | The number of lines that should be skipped at the bottom of a directory listing. | FTP, SSH
CustomDirColFilename | The column number of a filename in a directory listing. | FTP, SSH
CustomDirColDate | The column number of a data in a directory listing. | FTP, SSH
DefAB | "ascii" or "binary". | FTP
DefAccount | The default FTP "account". This is rarely used. | FTP
DefAddressFrom | The From: address for emails to this SMTP host. | SMTP
DefBlindDL | 1 if downloads from this host should be "blind" by default (no directory listing). | FTP, SSH
DefClientCertStore | The default client certificate store, typically "My". | DMZ, FTP
DefClientCertSubject | The subject name of the default client certificate. | DMZ, FTP
DefClientCertSHA1 | The SHA1 of the default client certificate. | FTP, SSH
DefClientKeyID | The ID of the default SSH key. | SSH
DefMxBy | The default maximum number of bytes to download from this host in one task run. 0 means infinite. | DMZ, FTP, SSH, Filesystem
DefMxFi | The default maximum number of file to download from this host in one task run. 0 means infinite. | DMZ, FTP, SSH, Filesystem
DefMD5File | The filename of the MD5 file, if MD5 files are being used. | FTP, SSH
DefMD5Get | "IfPresent", "Required", or "Never". Determines whether to download and process an MD5 file. | FTP, SSH
DefPartnerName | The default partner name. | AS1, AS2, AS3
DefPassive | 1 if transfers should be in passive mode by default. | FTP
DefPassword | The default password for this host. This string is encrypted. | DMZ, FTP, SSH
DefRescanSecs | The default number of seconds between rescans of this host. The default of 0 disables this feature. | FTP, SSH, Filesystem
DefRetryCount | The default number of retries. | All
DefRetryTimeoutSecs | The default number of seconds between retries. | All
DefSort | The default sort order for filenames. This is a string of form 1,2 where 1 is Date, Size or Filename and 2 is A or D (for Ascending or Descending). | DMZ
DefUsername | The default username. | Most
DirScriptID | If specified, the custom directory parsing script to use. |
DMZHostID | The host ID of the associated MOVEit DMZ host. | AS1, AS2, AS3
ForceNonLumpHash | 1 if uploads should be done in NonLumpHash mode, which is necessary for certain poorly-programmed firewalls. | DMZ
Host | The hostname. | All
ID | The ID by which this host is referred by sources and destinations. | All
ID2 | One or more IDs referring to alternate hosts for this particular host. | Most
IgnoreCertProbs | 1 if certain types of certificate problems, such as hostname mismatch, should be ignored. | DMZ, FTP
MDNPollCount | The number of attempts a task should make to retrieve an MDN after a send. | AS1, AS2, AS3
MDNPollTimeoutSecs | The number of seconds between MDN polls. | AS1, AS2, AS3
Name | The name of the host | All
NATUseServerIPForData | 1 if the FTP client should connect to the IP address on the command socket rather than that given in the response to PASV. | FTP
NATClientIP | The IP address that Central should present during active mode FTP. If not specified, use the host's IP. | FTP
PASVWS | The number of seconds that Central should pause before connecting to a passive port. This is a very obscure attribute needed only by certain buggy FTP servers. | FTP
PauseRerunSecs | The number of seconds to wait before automatically rerunning a task after a successful download. | AS1, AS3
Port | The TCP port number of the host. | DMZ, FTP, SSH
ScriptPath | The script path used to create the URL for the server. | DMZ
Secure | For DMZ hosts, 1 if SSL should be used. For FTP hosts, one of the strings "on", "1", "ssl", "tls-p", "on-ccc", "tls-p-ccc", "off", "none", "0", "tls", "tls-c", "tls-c-ccc", "implicit", "implicit-ccc". | DMZ, FTP
SSHFingerprint | The approved SSH fingerprint of the host's SSH key. | SSH
UseNotif | 1 if notifications should be used. | DMZ, Filesystem
UTCOffset | The number of seconds of time zone difference between this host and Coordinated Universal Time. Rarely used. | DMZ, FTP, SSH, Filesystem
RenameAfterUpload | 1 if Central should upload as a temporary name, then rename to the final name. | FTP, Filesystem
TempUploadName | The temporary filename to use if RenameAfterUpload is in effect. | FTP, Filesystem


Script Configuration

XML Document Formats - Task Configuration - Script

Each script consists of an XML tree that looks like:

<Script ID="id" Name="name">
<Description>Human-readable description</Description>
<Source>Encrypted source</Source>
</Script>

There is no MOVEit Automation API function to encrypt a script, so to use a script, you must fetch an existing one from MOVEit Automation via GetItemXML.

Script elements have the following attributes:

Attribute | Description
ID | The numeric ID by which this script is referred in Processes.
Name | The human-friendly name of the script


About Ipswitch - Contact...

The Ipswitch Support Center is an information and diagnostic center available for Ipswitch customers to:

  • Obtain advice on proper product installation, configuration, and operation
  • Report any product problems and receive timely resolutions
  • Request software updates
  • Inquire on software release contents and status

The support center provides support for all Ipswitch licensed products according to the terms of your Ipswitch Support Agreement. These support services are provided to Ipswitch's direct customers and resellers, while indirect customers are serviced by their own respective reseller. Support for customizations to Ipswitch software is the responsibility of the customer or their reseller’s Integration Services group. For more information on support for customized software please contact your reseller’s Integration Services manager.

To access the Support Center, you can use the following links:

  • Visit our Web site for the latest contact information.
  • Visit the customer portal.