MOVEit Automation API Reference

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

A MOVEit Automation API object is created using code like:

import com.stdnet.moveit.*;
...
MICentralAPI oAPI = new MICentralAPI();

Although MOVEit Automation API along with all of the MOVEit family of products are now owned and supported by Progress, the "com.stdnet" namespace created by the original developers is being retained for backward compatibility.

MICentralAPI objects provide 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(String Hostname);

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

Hostname  is a hostname. 

oAPI.setUser(String Username);

Sets the username on the MOVEit Automation host which the API will use to log in.

Username  is a username recognized on the MOVEit Automation host. 

oAPI.setPassword(String Password);

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

Password  is the password for the above user. 

boolean 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.

oAPI.disconnect();

Disconnects from a MOVEit Automation server.

Setting Task criteria

int OldMaxTasks = oAPI.setMaxTasks(int MaxTasks)

Sets the maximum number of running tasks to allow.  If at least this many tasks are already running, Central will refuse to run a task 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.

int 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

int ErrorCode = oAPI.getErrorCode();

Returns  the numeric error code associated with the most recent call.  This is 0 if the last call succeeded.

String ErrorDescription = oAPI.getErrorDescription();

Returns  a description of the error associated with the last call, or "" if the last call succeeded.

String Version = oAPI.getAPIVersion();

Returns  The version number string for MOVEit Automation API.

String Version = oAPI.getCentralVersion();

Returns  The version number string for MOVEit Automation.

Starting and monitoring tasks

String TaskHnd = oAPI.startTask(String Task, boolean bUsingName, String TaskParams);

Starts a task.

Task is a task ID or task name.
bUsingName is true if Task is a task name, or false 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.

String TaskHnd = oAPI.startNewTask(String TaskXML, String TaskParams)

Creates and starts a temporary task.

TaskXML is an XML node tree that specifies the full XML source of a new temporary task with temporary hosts and scripts.
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.

WaitResult WResult = oAPI.waitForTasks(String TaskHnds, int 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().

String strXML = oAPI.queryTaskRunInfo(WaitResult 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.

String strXML = oAPI.queryTaskRunXfers(WaitResult 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.

String strXMLReply = oAPI.queryRunningTasks();

Returns an XML structure containing information about all running tasks. This command may only be issued by users who are members of the MOVEit Admin and/or MOVEit Log Windows groups.

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

Reading and editing XML configurations and results

String strXML = oAPI.queryItem(String ItemType, String Item, boolean 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").
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.

String Ciphertext = oAPI.encryptPW(String 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.

String strValue = oAPI.queryAttribute(String XML, String NodeName, int NodeOrd, String 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 add or query.
Returns the value of the attribute, or a blank string if errors were encountered (such as invalid source XML or missing attribute).

String strXML = oAPI.updateAttribute(String XML, String NodeName, int NodeOrd, String AttribName, String 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.

String AttribValue = oAPI.queryValue(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).

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:

String 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:

boolean 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:

boolean 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:

boolean 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:

boolean 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:

String 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

String 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 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.

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 Results Format.