Created 12 Oct 2009
Modified 07 Apr 2012

Introduction

A script can be assigned to a transfer queue item which will be loaded right before the transfer queue item is processed. The transfer queue fires several events which can be handled by event handlers within the script. An event handler has access to the transfer queue operation object and indirectly - through this object - to the complete transfer queue facility.
Scripts assigned to individual transfer queue items make most sense when the same transfer queue item is processed multiple times. For example when it contains a trigger with a recurring schedule.

Technical

Objects exposed in the global scope:

• ScriptHost
  The object that created the script context. It offers some basic methods:
  Echo: Display the first argument in a message box
• TransferQueueOperation
  This object is responsible to run the actual operation and additionally offers helper methods.

The following events are sent from the TransferQueueOperation object:

• OnBegin
  This event is fired before the operation starts.
• OnRun
  This event is fired after OnBegin and before the actual operation begins. This is the place to add the logic of a custom operation.
• OnEnd
  This event is fired after the operation ended.
• OnAddItems(items)
  This event is fired right before the items are added to the transfer queue

For the complete reference please refer to the documentation included in the SmartFTP SDK¹.

Mini Tutorial

In the this tutorial we demonstrate how to use a script to transfer a file or folder to a different destination each time the item is processed. The idea is to implement a custom operation which does the following:

1. Create a new item based on the item we are processing
2. Copy all the important item properties (name, size, operation type, source, destination) to the new item
3. Change the destination path of the new item
4. Add the new item to the transfer queue
5. Set the operation result to success to prevent the execution of the normal operation

Let's start with the skeleton of the script:

VBScript

ScriptHost.Echo "Load"

Sub TransferQueueOperation_OnBegin() 
  ScriptHost.Echo "OnBegin" 
End Sub 

Sub TransferQueueOperation_OnRun() 
  ScriptHost.Echo "OnRun" 
End Sub 

Sub TransferQueueOperation_OnEnd() 
  ScriptHost.Echo "OnEnd" 
End Sub

JavaScript

ScriptHost.Echo("Load");

function TransferQueueOperation::OnBegin()
{
  ScriptHost.Echo("OnBegin");
}

function TransferQueueOperation::OnRun()
{
  ScriptHost.Echo("OnRun");
}

function TransferQueueOperation::OnEnd()
{
  ScriptHost.Echo("OnEnd");
}

We choose to implement the logic for the custom operation in the OnRun() event handler.

VBScript

Sub TransferQueueOperation_OnRun() 
  'ScriptHost.Echo "OnRun" 
  '// Create new transfer queue item based on this item
  Dim newItem 
  Set newItem = TransferQueueOperation.CreateItem()
  '// copy its properties
  Dim item 
  Set item = TransferQueueOperation.TransferQueueItem
  newItem.Type = item.Type
  newItem.Size = item.Size
  newItem.Operation = item.Operation  
  newItem.SizeUnit = item.SizeUnit 
  newItem.Source = item.Source.Clone()
  newItem.Destination  = item.Destination.Clone()
  '// now change the destination path
  '// format the date/time "YYYYMMDD 'T' HHMMSS"
  Dim date
  date = CStr(Year(Now())) & CStr(prefixWithZero(Month(Now()))) & CStr(prefixWithZero(Day(Now())))
  Dim time
  time = CStr(prefixWithZero(Hour(Now()))) & CStr(prefixWithZero(Minute(Now()))) & CStr(prefixWithZero(Second(Now())))
  Dim suffix
  suffix = date & "T" & time

  newItem.Destination.Path = newItem.Destination.Path & suffix
  '// ScriptHost.Echo newItem.Destination.Path
  
  '// add the new item using the AddItem helper
  TransferQueueOperation.AddItem(newItem)
  
  '// return success. This prevents the operation to continue any further
  TransferQueueOperation.Result = sfTransferQueueOperationResultSuccess
End Sub

JavaScript

function TransferQueueOperation::OnRun()
{
  //ScriptHost.Echo("OnRun");
  // Create new transfer queue item based on this item
  var newItem = TransferQueueOperation.CreateItem();
  // copy its properties
  var item = TransferQueueOperation.TransferQueueItem;
  newItem.Type = item.Type;
  newItem.Size = item.Size;
  newItem.Operation = item.Operation;  
  newItem.SizeUnit = item.SizeUnit;  
  newItem.Source = item.Source.Clone();
  newItem.Destination  = item.Destination.Clone();
  // now change the destination path
  // format the date/time "YYYYMMDD HHMMSS"
  var now = new Date();
  var date = now.getFullYear().toString() + prefixWithZero(now.getMonth() + 1).toString() + prefixWithZero(now.getDate()).toString();
  var time = prefixWithZero(now.getHours()).toString() + prefixWithZero(now.getMinutes()).toString() + prefixWithZero(now.getSeconds()).toString();
  var suffix = date + "T" + time;

  newItem.Destination.Path = newItem.Destination.Path + suffix;
  // ScriptHost.Echo newItem.Destination.Path;
  
  // add the new item using the AddItem helper
  TransferQueueOperation.AddItem(newItem);
  
  // return success. This prevents the operation to continue any further
  TransferQueueOperation.Result = sfTransferQueueOperationResultSuccess;
}

For the complete scripts please see the SmartFTP SDK¹.

References

1. SmartFTP SDK