MOVEit Central API Reference

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

A MOVEit Central API object is created using code like:

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

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

MICentralAPI objects provide the following methods:

Connecting to MOVEit Central

• oAPI.setHost(Hostname);
• oAPI.setUser(Username);
• oAPI.setPassword(Password);
• boolean bOK = oAPI.connect();
• oAPI.disconnect();

Setting Task criteria

• int OldMaxTasks = oAPI.setMaxTasks(MaxTasks)
• int MaxTasks = oAPI.getMaxTasks()

Querying error conditions and version information

• int ErrorCode = oAPI.getErrorCode();
• String ErrorDescription = oAPI.getErrorDescription();
• String Version = oAPI.getAPIVersion();
• String Version = oAPI.getCentralVersion();

Starting and monitoring tasks

• String TaskHnd = oAPI.startTask(Task, bUsingName, TaskParams);
• String TaskHnd = oAPI.startNewTask(TaskXML, TaskParams)
• WaitResult WResult = oAPI.waitForTasks(TaskHnds, WaitSecs);
• String strXML = oAPI.queryTaskRunInfo(WaitResult);
• String strXML = oAPI.queryTaskRunXfers(WaitResult);
• String strXMLReply = oAPI.queryRunningTasks();

Reading and editing XML configurations and results

• String strXML = oAPI.queryItem(ItemType, Item, bUsingName);
• String Ciphertext = oAPI.encryptPW(Plaintext);
• String strXML = oAPI.updateAttribute(XML, NodeName, NodeOrd, AttribName, AttribValue);
• String strValue = oAPI.queryAttribute(XML, NodeName, NodeOrd, AttribName);
• String strValue = oAPI.queryValue(XML, NodeName, NodeOrd);

Checking out and updating XML configurations

• String strXML = oAPI.checkoutItem(ItemType, ItemID [, bForce ]);
• boolean bOK = oAPI.releaseItem(ItemType, ItemID);
• boolean bOK = oAPI.createItem(ItemType, ItemID, ItemXML [, Groups ]);
• boolean bOK = oAPI.modifyItem(ItemType, ItemID, ItemXML [, bCreate [, Groups ] ]);
• boolean bOK = oAPI.deleteItem(ItemType, ItemID);
• String strID = oAPI.suggestItemID(ItemType);

Examining Logs

• String strXMLReply = oAPI.runCustomSQL(SQL, MaxCount, SkipCount, Delimited, Delimiter);

Connecting to MOVEit Central

oAPI.setHost(String Hostname);

Sets the name of the MOVEit Central 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(String Username);

Sets the username on the MOVEit Central 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 Central host.

oAPI.setPassword(String Password);

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

Password

is the password for the above user.

boolean bOK = oAPI.connect();

Connects to MOVEit Central 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 Central 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 Central Admin. Furthermore, multiple and concurrent instances of MOVEit Central 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 Central 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 Central API.

String Version = oAPI.getCentralVersion();

Returns

The version number string for MOVEit Central.

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 Central 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 Central 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 signed on from localhost and 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 Central 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 Central 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:

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

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

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

Checks out a section from the MOVEit Central 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.

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:

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

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:

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

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:

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

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:

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

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:

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

Examining logs

String strXMLReply = oAPI.runCustomSQL(SQL, MaxCount, SkipCount, bDelimited, Delimiter);

Allows MOVEit Central API to issue read-only ("SELECT") SQL queries against the tamper-evident MOVEit Central 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 Central manual ("Advanced Topics - Database - Schema" section) for information about the schema.

SQL	is a MOVEit Central 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.