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

This Java 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. Our example assumes we have connected to MOVEit Automation per the overview.

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:

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.

Reference Existing Hosts

Example Run

Assuming you are in the samples directory.

>java -cp .;..\MICentralAPI.jar TempTaskExistingHost

Read configuration for task 'Template Task - Upload to FTP': 439 bytes
Read configuration for host 'Template FTP Host': 376 bytes
Starting task Temporary Task Test Using Existing Host
Task Temporary Task Test Using Existing Host has started
TaskName             = Temporary Task Test Using Existing Host
TaskID               = 12345678
TaskNominalStartTime = 2007-10-26 12:04:14
TaskTimeEnded        = 2007-10-26 12:04:18
TaskErrorCode        = 0
TaskErrorDescription =

--- Information about the task run as a whole: ---
TotalBytesSent = 272

--- Information about the individual file transfers: ---
Sent /Home/adminandy/java sample/20071026120414-testfile4 (128)
Sent /Home/adminandy/java sample/20071026120417-testfile5 (144)
Current Task Limit is 3
Temporary task (1 of 5) has started
Temporary task (2 of 5) has started
Temporary task (3 of 5) has started
Temporary task (4 of 5) failed to start Running this task would exceed the maxim
um simultaneous tasks specified in the command.
Temporary task (5 of 5) failed to start Running this task would exceed the maxim
um simultaneous tasks specified in the command.
Current handles = 98245241^2007-10-26 12:04:22|98245242^2007-10-26 12:04:23|9824
5243^2007-10-26 12:04:23|

--- Information about the task run as a whole: ---
TotalBytesSent = 272
Current handles = 98245241^2007-10-26 12:04:22|98245242^2007-10-26 12:04:23|

--- Information about the task run as a whole: ---
TotalBytesSent = 272
Current handles = 98245241^2007-10-26 12:04:22|

--- Information about the task run as a whole: ---
TotalBytesSent = 272
Current handles = |

Code Excerpts

The example code loads descriptions of tasks and hosts. These are described using XML - a reference document for that XML is available. The first step is to load the template Task and Host:

String origTaskName = "Template Task - Upload to FTP";
String newHostName = "Template FTP Host";

// Get a copy of the template task configuration.
String origTaskXML = oAPI.queryItem("Task", origTaskName, true);
if (origTaskXML.equals("")) {
	showMsg("Failed to read configuration for task '" + origTaskName +
		"': " + oAPI.getErrorDescription());
	return;
}
showMsg("Read configuration for task '" + origTaskName + "': " +
	origTaskXML.length() + " bytes");

// Get a copy of a named FTP site
String newHostXML = oAPI.queryItem("Host", newHostName, true);
Document newHostDoc = null;
if (newHostXML.equals("")) {
	showMsg("Failed to read configuration for host '" + newHostName +
		"': " + oAPI.getErrorDescription());
	return;
}
showMsg("Read configuration for host '" + newHostName + "': " +
	newHostXML.length() + " bytes");

The host id will be necessary for the task. To get the host id, parse the Host template and get the ID attribute.

newHostDoc = parse_xml(newHostXML);

String newHostID = newHostDoc.getDocumentElement().getAttribute("ID");
String newTaskName = "Temporary Task Test Using Existing Host";

Next a temporary task is built from the template task. Varying from the template, the source path is changed as is the destination host id and path.

// Override the appropriate attributes in our copy of the template task XML in order to create
// the definition for our temporary task.
String newTaskXML = origTaskXML;

// Task ID: 8-digit task ID values are safe to use for temporary tasks.
newTaskXML = oAPI.updateAttribute(newTaskXML, "Task", 1, "ID", "12345678");
// Task Name
newTaskXML = oAPI.updateAttribute(newTaskXML, "Task", 1, "Name",
	newTaskName);
// Source Path: change to new local source path
newTaskXML = oAPI.updateAttribute(newTaskXML, "Source", 1, "Path",
	"C:\\TEMP\\ftpdump");
// Destination FileName: change to new destination filename on existing destination host
newTaskXML = oAPI.updateAttribute(newTaskXML, "Destination", 1,
	"FileName", "[yyyy][mm][dd][hh][tt][ss]-[OrigName]");
// Destination Host ID: use ID of existing host
newTaskXML = oAPI.updateAttribute(newTaskXML, "Destination", 1,
	"HostID", newHostID);
// Destination Path: change to path on new FTP host
newTaskXML = oAPI.updateAttribute(newTaskXML, "Destination", 1,
	"Path", "/Home/adminandy/java sample/");

The temporary task is configured and next it is run. The example waits until the task has completed and then provides a summary of the run.

// Start the task and wait for results
showMsg("Starting task " + newTaskName);
String taskHnd = oAPI.startNewTask(newTaskXML,"");
if (taskHnd.equals("")) {
	showMsg("Task " + newTaskName + " failed to start");
	showMsg(oAPI.getErrorDescription());
	return;
} else {
	showMsg("Task " + newTaskName + " has started");
}

int waitSecs = 120;
// Wait for the task to complete
WaitResult wresult = oAPI.waitForTasks(taskHnd, waitSecs);

// The task might not have completed within the timeout we selected.
if (wresult.isCompleted()) {
	showMsg("TaskName             = " + wresult.getTaskName());
	showMsg("TaskID               = " + wresult.getTaskID());
	showMsg("TaskNominalStartTime = " + wresult.getTaskNominalStartTime());
	showMsg("TaskTimeEnded        = " + wresult.getTaskTimeEnded());
	showMsg("TaskErrorCode        = " + wresult.getTaskErrorCode());
	showMsg("TaskErrorDescription = " + wresult.getTaskErrorDescription());

	showTaskRunInfo(oAPI, wresult);
	showTaskTransfers(oAPI, wresult);
} else {
	showMsg("The task has not yet completed");
}

The next section of the example runs multiple temporary tasks at once. Through the use of "setMaxTasks" the number of tasks that can be started will be limited and demostrated. The max will be set to three and the example will try to start five.

First limit the number of tasks. The start the temporary task five times using a different task name each time.

oAPI.setMaxTasks(3);
showMsg("Current Task Limit is " + oAPI.getMaxTasks());

int startedTasks = 0;
int totalTasks = 5;
String taskHndPipe = "";

for(int iii = 1; iii <= totalTasks; iii++) {
	String taskID = "9824524" + iii;

	newTaskXML = oAPI.updateAttribute(newTaskXML, "Task", 1, "Name",
		"Temporary Task Test Using Existing Host (" + iii + " of " +
		totalTasks + ")");

	newTaskXML = oAPI.updateAttribute(newTaskXML, "Destination", 1,
		"FileName", "[yyyy][mm][dd][hh][tt][ss]-" + taskID +
		"-[OrigName]");

	newTaskXML = oAPI.updateAttribute(newTaskXML, "Task", 1, "ID", taskID);
	taskHnd = oAPI.startNewTask(newTaskXML, "");

	if (taskHnd.equals("")) {
		showMsg("Temporary task (" + iii + " of " + totalTasks +
			") failed to start " + oAPI.getErrorDescription());
	}
	else {
		showMsg("Temporary task (" + iii + " of " + totalTasks +
			") has started");

		taskHndPipe += taskHnd + "|";
		startedTasks = startedTasks + 1;
	}
}

The example ends by waiting for the tasks to complete. Handles for all of the tasks that started are passed to "waitForTasks". If any task in the list of handles finishes, then a WaitResult is returned. Keep checking "waitForTasks" until all the handles are returned (one at a time).

String lastWaitResult = "NotBlank";
showMsg("Current handles = " + taskHndPipe);

while (taskHndPipe.length() > 1) {
	wresult = oAPI.waitForTasks(taskHndPipe, waitSecs);

	if (lastWaitResult.equals(wresult.getTaskID())) {
		try {
			Thread.sleep(250);
		}
		catch(InterruptedException x) {
		}
	}
	else {
		showTaskRunInfo(oAPI, wresult);
		lastWaitResult = wresult.getTaskID();

		taskHndPipe = taskHndPipe.replace(wresult.getTaskID() + "^" +
			wresult.getTaskNominalStartTime(), "").replace("||","|");
	}

	showMsg("Current handles = " + taskHndPipe);
}

Reference Ad Hoc Hosts

Example Run

Assuming you are in the samples directory.

>java -cp .;..\MIC
entralAPI.jar TempTaskAdHocHost
Read configuration for task 'Template Task - Upload to FTP': 439 bytes
Read configuration for host 'Template FTP Host': 376 bytes
Starting task Temporary Task Test Using Ad Hoc Host
Task Temporary Task Test Using Ad Hoc Host has started
TaskName             = Temporary Task Test Using Ad Hoc Host
TaskID               = 12345678
TaskNominalStartTime = 2007-10-26 13:25:41
TaskTimeEnded        = 2007-10-26 13:25:45
TaskErrorCode        = 0
TaskErrorDescription =

--- Information about the task run as a whole: ---
TotalBytesSent = 272

--- Information about the individual file transfers: ---

Code Excerpts

This example alters the host and uses it to run the task. First, read the template Task and Host:

String origTaskName = "Template Task - Upload to FTP";
String origHostName = "Template FTP Host";

// Get a copy of the template task configuration.
String origTaskXML = oAPI.queryItem("Task", origTaskName, true);
if (origTaskXML.equals("")) {
	showMsg("Failed to read configuration for task '" + origTaskName + "': " + oAPI.getErrorDescription());
	return;
}
showMsg("Read configuration for task '" + origTaskName + "': " + origTaskXML.length() + " bytes");

// Get a copy of a named FTP site
String origHostXML = oAPI.queryItem("Host", origHostName, true);
if (origHostXML.equals("")) {
	showMsg("Failed to read configuration for host '" + origHostName + "': " + oAPI.getErrorDescription());
	return;
}
showMsg("Read configuration for host '" + origHostName + "': " + origHostXML.length() + " bytes");

Then alter the settings for the Task and the Host:

// Override the appropriate attributes in our copy of the template task XML in order to create
// the definition for our temporary task.
String newHostXML = origHostXML;
String newTaskXML = origTaskXML;
String newHostID = "23456789";
String newTaskName = "Temporary Task Test Using Ad Hoc Host";

// Host ID: 8-digit host ID values are safe to use for temporary hosts.
newHostXML = oAPI.updateAttribute(newHostXML, "FTP", 1, "ID", newHostID);
// Host definition
/newHostXML = oAPI.updateAttribute(newHostXML, "FTP", 1, "Host", "ftp.hp.com");
// Host username and password. Password must be encrypted.
newHostXML = oAPI.updateAttribute(newHostXML, "FTP", 1, "DefUsername", "anonymous");
newHostXML = oAPI.updateAttribute(newHostXML, "FTP", 1, "DefPassword",
    "sample@ipswitch.com");

// Task ID: 8-digit task ID values are safe to use for temporary tasks.
newTaskXML = oAPI.updateAttribute(newTaskXML, "Task", 1, "ID", "12345678");
// Task Name
newTaskXML = oAPI.updateAttribute(newTaskXML, "Task", 1, "Name", newTaskName);

// Source Path: change to new local source path
newTaskXML = oAPI.updateAttribute(newTaskXML, "Source", 1, "Path",
	"C:\\TEMP\\ftpdump");
// Destination FileName: change to new destination filename on existing destination host
newTaskXML = oAPI.updateAttribute(newTaskXML, "Destination", 1,
	"FileName", "[yyyy][mm][dd][hh][tt][ss]-[OrigName]");
// Destination Host ID: use ID of existing host
newTaskXML = oAPI.updateAttribute(newTaskXML, "Destination", 1,
	"HostID", newHostID);
// Destination Type: change to FTP for the FTP host we are changing to
newTaskXML = oAPI.updateAttribute(newTaskXML, "Destination", 1, "Type",
	"FTP");
// Destination Path: change to path on new FTP host
newTaskXML = oAPI.updateAttribute(newTaskXML, "Destination", 1,
	"Path", "/Home/adminandy/java sample/");

Next, start the task using the "<Hosts>" tag before the task XML when calling "startNewTask".

// Start the task and wait for results
showMsg("Starting task " + newTaskName);
// When starting the temporary task, include the temporary host XML as well.
// Temporary host XML must be surrounded by <Hosts> tags.
String taskHnd = oAPI.startNewTask("<Hosts>" + newHostXML + "</Hosts>" + newTaskXML,"");

if (taskHnd.equals("")) {
	showMsg("Task " + newTaskName + " failed to start");
	showMsg(oAPI.getErrorDescription());
	return;
} else {
	showMsg("Task " + newTaskName + " has started");
}

Finally, the example waits for the task to complete and then prints out details about the run.

int waitSecs = 120;
// Wait for the task to complete
WaitResult wresult = oAPI.waitForTasks(taskHnd, waitSecs);

// The task might not have completed within the timeout we selected.
if (wresult.isCompleted()) {
	showMsg("TaskName             = " + wresult.getTaskName());
	showMsg("TaskID               = " + wresult.getTaskID());
	showMsg("TaskNominalStartTime = " + wresult.getTaskNominalStartTime());
	showMsg("TaskTimeEnded        = " + wresult.getTaskTimeEnded());
	showMsg("TaskErrorCode        = " + wresult.getTaskErrorCode());
	showMsg("TaskErrorDescription = " + wresult.getTaskErrorDescription());

	showTaskRunInfo(oAPI, wresult);
	showTaskTransfers(oAPI, wresult);
} else {
	showMsg("The task has not yet completed");
}

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

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.

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.