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

Setting Task criteria

Querying error conditions and version information

Starting and monitoring tasks

Reading and editing XML configurations and results

Checking out and updating XML configurations

Examining Logs

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.