MOVEit Automation custom scripts use Microsoft VBScript or PowerShell. In addition to the basic functions provided by that environment, MOVEit Automation also makes available several MOVEit-specific functions.

Functions and Subroutines

The functions and subroutines, and associated details are listed in alphabetical order in the following table.

The functions and subroutines are described as follows:

  • The function name is displayed in bold text.
  • The return value of the function, if applicable, precedes the function name. Not all functions have a return value.
  • The function arguments follow the function name.
    • In VBScript, function calls with a return value require the function arguments to be surrounded by parenthesis, while function calls without a return value require the parenthesis to be omitted.
    • Arguments that are optional in VBScript are surrounded by brackets in the following content.
    • In PowerShell, all arguments are required. Also, in PowerShell, parentheses must always be used around the list of arguments.
    • In PowerShell, all function calls must be preceded by the $miaclient object reference. The $miaclient object is automatically available in any MOVEit PowerShell script. It does not need to be instantiated.

Function call example:

VBScript: errcode = MISetDestHost(ConfiguredHostName [,idest])

PowerShell: $errcode = $miaclient.MISetDestHost($ConfiguredHostName,””)

  • Where MISetDestHost is the function name
  • errcode is the return value
  • ConfiguredHostName is the required argument
  • idest is an optional argument.

For examples of how to use custom scripting to add, change, or edit files during processing in MOVEit Automation, see Application Notes. Also, sample VBScipt and PowerShell scripts for Web Admin are available from the Progress Community.

Functions and Subroutines

Description

MIAddFile CacheFilename, AssignedFilename

Adds a file to the list of files to be sent to destinations.

Note: Before you use MIAddFile, you must have already created a temporary file in the cache with your data in it. For more information, see Application Notes for an example of how this is accomplished.

CacheFilename - The name of the temporary file to send. This name comes from the MINewCacheFilename() call below.

AssignedFilename - The name to be given to the file on the destination server. The filename can be specified with forward slash ( / ) or backslash ( \ ) characters, in which case the name is considered a folder path and filename relative to the destination path.

To prevent infinite loops, scripts are not currently run on files added via MIAddFile.

DirName = MICacheDir()

Returns the full path of the directory where MOVEit Automation keeps its temporary files

FileName = MICacheFilename()

Returns the name of the temporary copy of the file in the cache. This file can be overwritten or modified if the custom script needs to change the contents of the file before it is transferred.

FilesString = MICacheFiles()

Returns a string containing the subdirectories and filenames for all active files in the cache. These names are relative to MICacheDir and reflect the actual names on disk in the cache directory, not the original names from the sources. The names are separated by the pipe (|) character. The last file does not have a | at the end.

This list is empty immediately after a call to MIIgnoreFiles. The list does not include, for instance, the names of zip files that have been downloaded from sources marked Uncompress Archives.

bOK = MIDeleteFileSecure(Filename)

Overwrites the specified file with random bytes, and then deletes the file. Returns True if successful.

MIDirAddEntry FilenameToMatch, Date, Size, bIsDir, FilenameForGet, FilenameOriginal

Adds an entry to the FTP or SSH directory listing that is being parsed. This should be called only from custom directory parsing scripts. For more information, see Custom Directory Parsing

sDirListing = MIDirGetListing()

Returns the entire verbatim listing from the FTP or SSH server. Call this function only from custom directory parsing scripts. For more information, see Custom Directory Parsing.

DbgLevel = MIGetDebugLevel()

Returns the debug level currently set in MOVEit Automation. Values:

Level Meaning

0 Internal errors

10 Task/File Errors

20 Task/File Warnings

30 Task Completions

40 File Completions

50 Some Debug

60 More Debug

70 All Debug

OriginalFilename=MIGetOriginalFilename()

Returns the original filename of the file.

Result = MIGetTaskInfo(InfoString)

Returns the specified information about the current task. Values:

Info String

Value returned by MIGetTaskInfo

CacheUsesOriginalNames

True if the task is configured to use original filenames in the cache directory

False if the task is configured to use random filenames.

NSources

The number of sources in the task.

ProcessIsPerFile

True if the current process is run for each file

False if the current process is run one time after all downloads.

ShouldStop

True if an operator has requested that the task be stopped.

If you call MIGetTaskInfo from PowerShell and give it a parameter that causes it to return a boolean result, to get the correct value you must prefix the result with [bool][int]

For example:

$isPerFile = [bool][int]$miaclient.MIGetTaskInfo('ProcessIsPerFile')

ParamValue = MIGetTaskParam(ParamName)

Returns the value of the specified task parameter. If the current task has no such parameter, the empty string is returned.

There are some times that the parameters need to be ‘cast’ to another type after they are brought into a script. For more information, see Application Notes.

MIGetTaskParamDisplay(ParamName)

Retrieves the value of a parameter. If the parameter's value is secured, the placeholder is retrieved. Use to ensure that the script will not expose the value of a secured parameter where it should be suppressed, for example, in the logs if you are calling MILogMsg with the retrieved value.

Note: MOVEit Automation does not normally expose secure parameter values in the MOVEit logs or during an export. However, an administrator can expose the value with certain script commands. For example, a script author may write the value of a secure parameter that was retrieved using the MIGetTaskParam function to the log using the MILogMsg function, saving the decrypted version of the parameter to the log. The script author controls this exposure.

MIIgnoreFiles [bDeleteOrigIfCfg [,bKeepAsNew]]

Causes all files already downloaded or added via MIAddFile to be ignored in subsequent processing steps. For example, use this if your custom script creates a zip file containing the downloaded files, and you do not want the downloaded files to be sent.

Parameter

Meaning

bDeleteOrigIfCfg

Whether to delete the original files if the Delete Original File(s) After Successful Transfer option has been set in the source. Default is True.

bKeepAsNew

Whether to continue to regard these files as new in the next task run even if the task succeeds. This is meaningful only if Collect Only New Files is set in the source. Default is False.

MIIgnoreThisFile [bDeleteOrigIfCfg [,bKeepAsNew]]

Causes the current file to be ignored by subsequent processing steps.

MILogMsg Message

Logs a message to system log file. In the log file, the message is preceded by the task name.

MyString = MIMacro(MacroText)

Evaluates the macro MacroText and returns the resulting text. MacroText can contain any combination of macros.

The MacroText attribute must be enclosed in square brackets surrounded by single quotes.

For example, in PowerShell $miaclient.MIMacro(‘[Origname]’) will return the original file name of the file currently being processed in the script.

MIMacroDisplay

Expands a macro string by masking any secured values with a placeholder. Use to ensure that the script will not expose the value of a secured parameter where it should be suppressed, for example, in the logs if you are calling MILogMsg with the retrieved value.

Note: MOVEit Automation does not normally expose secure parameter values in the MOVEit logs or during an export. However, an administrator can expose the value with certain script commands. For example, a script author may write the value of a secure parameter that was retrieved using the MIGetTaskParam function to the log using the MILogMsg function, saving the decrypted version of the parameter to the log. The script author controls this exposure.

FileName = MINewCacheFilename()

Returns a new, unique temporary filename. The filename will be a full path and will be in the cache folder. This name is used by your script if you need to create a new file that you want added to the list of files that should be moved to a destination. Note that this just returns a name. The script is responsible for actually creating a file using this name.

bOK = MIReplaceCacheFile(Filename)

Securely deletes the current temporary cache file, and replaces it with the contents of Filename.

For example, use this to send a different file, such as a file that you just created, instead of the downloaded file. Typically you first call MINewCacheFilename() to get a filename, then create a new file using that name, dd content to this file, and then call MIReplaceCacheFile() to tell MOVEit Automation to use the new file

retval = MIRunCommand(Command)

Runs a Windows system command through the Windows system command interpreter. Command is a command, such as "Notepad MyFile.txt". This can be the name of a command, such as an .exe or .bat file, or the name of a file with an associated extension, such as .vbs, or a built-in CMD.EXE command such as DIR.

MIRunCommand waits until the command is complete. If you want the custom script to continue running while the command runs, use the Windows START command to launch the program.

MIRunCommand returns either:

  • A long integer: -1 if the program could not be found, or
  • The return code from the program. Programs typically return 0 upon success, or >0 upon failure.

MIRunCommand does not work well with pathnames that contain spaces. To avoid these situations, use the Scripting.FileSystemObject to look up safe versions of paths before passing them to MIRunCommand. For example, in VBScript:

Set fso = CreateObject("Scripting. FileSystemObject")

AppPath = "C:\Program FilesNMy App"

AppExe = AppPath & T & "runit.exe"

SafeAppPath = fso.GetFolder(AppPath).ShortPath SafeAppExe = fso.GetFile(AppExe).ShortPath

ErrorCode = MIRunCommand(SafeAppExe & " " & " -o " & SafeAppPath & "\out.txt")

Similarly, in PowerShell using the same Com Object:

$fso = New-Object -ComObject Scripting.FileSystemObject $AppExe = $fso.GetFile("c:\program files\7-zip\7z.exe")

$retval = $miaclient.MIRunCommand($AppExe.short_path)

Note: Windows does have the ability disable short path capability. In this case, you will need to rename the executable without spaces.

errcode = MISetDestHost(ConfiguredHostName [,idest])

Changes the intended destination host of the current file, so that this file is copied to this host. ConfiguredHostName is the name of one of the configured hosts such as XYZ Corp FTP Server, not an Internet host domain name. The new host does not need to be the same type as the destination being changed. For example, the destination can be of type File System, but you can change it to point to an FTP server. Only the current file being processed (if any), and any files added via MIAddFile during this run of the process, are affected.

If you are using this command to switch between hosts of different types (for example, between FTPS and MOVEit Transfer servers) use the MISetDestPath command to ensure that destination paths are properly parsed.

Use a value of (default) to indicate a Windows file system host; in this case your path value should either begin with a drive letter (for example, C:\ ) or a UNC (for example, \\server\share\) .

idest is the ordinal number of the destination to change. Default is 1, which means the first destination in the task. (Most tasks have only one destination.)

Returns an error code:

0 indicates success

2540 indicates that the named host does not exist

2850 indicates that idest is out of range

errcode = MISetDestPath(NewPath [,idest])

Changes the intended destination path of the current file, so that this file is copied to the new path on the originally specified destination/host. NewPath is the new path or directory name. idest has the same meaning that it does for MISetDestHost. Only the current file being processed (if any), and any files added via MIAddFile during this run of the process, are affected.

Returns an error code:

0 indicates success

2850 indicates that idest is out of range

MISetErrorCode NumericErrorCode

Sets the error code and error description for this process.

If the custom script determines that the file should not be transferred, it calls MISetErrorCode with a non-zero numeric error code and MISetErrorDescription with a textual description of the error. This information is recorded by MOVEit Automation, and the file is not sent.

If the special value 5000 is set by MISetErrorCode, MOVEit Automation ignores the file. That is, it does not send the file, does not delete the original file, and does not flag an error that would cause the task to fail. Returning error code 5000 can be used to ignore unwanted files without alarming operators by having the task marked as unsuccessful. See also MIIgnoreThisFile

If the special value 5010 is set by MISetErrorCode, MOVEit Automation does not count this process as having been run. Ordinarily, MOVEit Automation marks a task has having completed successfully (as opposed to No actions taken) if any process runs, even if no files were downloaded or uploaded. However, if all processes in a task call MISetErrorCode 5010, and no files are transferred, then that task run is considered to have completed with No actions taken. This affects which Next Actions are executed at the end of the task

MISetErrorDescription ErrorDescription

Sets the error code and error description for this process.

If the custom script determines that the file should not be transferred, it calls MISetErrorCode with a non-zero numeric error code and MISetErrorDescription with a textual description of the error. This information is recorded by MOVEit Automation, and the file is not sent.

If the special value 5000 is set by MISetErrorCode, MOVEit Automation ignores the file. That is, it does not send the file, does not delete the original file, and does not flag an error that would cause the task to fail. Returning error code 5000 can be used to ignore unwanted files without alarming operators by having the task marked as unsuccessful. See also MIIgnoreThisFile

If the special value 5010 is set by MISetErrorCode, MOVEit Automation does not count this process as having been run. Ordinarily, MOVEit Automation marks a task has having completed successfully (as opposed to No actions taken) if any process runs, even if no files were downloaded or uploaded. However, if all processes in a task call MISetErrorCode 5010, and no files are transferred, then that task run is considered to have completed with No actions taken. This affects which Next Actions are executed at the end of the task

MISetFilename NewFilename

Changes the name under which the current file should be stored at the destination. Do not include a path in NewFilename.

MISetStatus StatusText

Set the status text to be displayed by MOVEit Automation Admin while the script is running. This can be used by long-running scripts to inform the operator the status of the process. If MISetStatus is not called, the message Running script scriptname is displayed.

MISetTaskParam ParamName,ParamValue

Sets the value of the specified task parameter ParamName. If the current task has no such parameter, a parameter of that name is created. Parameter names are not case-sensitive.Changed parameters will not retain their values between different runs of a task. They will retain their values during a single task run. And, they can be passed on to another task using the Run Task next action in a Traditional Task, or the Run Task step in an Advanced Task.

MISleep Milliseconds

Suspends the custom script for the specified number of milliseconds. Very little processor time is consumed during the pause.

ErrCode = MIStartTask(TaskNameOrID [,TaskParams])

Starts the specified task. TaskNameOrID is either a task name or a task ID. (MOVEit Automation checks first for a task name match.)

TaskParams allows you to specify values for task parameters. If a parameter name matches the name of a parameter configured in the task definition, the new value overwrites the configured value.

The format of TaskParams is ParamName1=ParamVal1|ParamName2=ParamVal2|... The trailing | at the end of the last task parameter is optional.

Example 1: Run a task called ShowMyID that shows the value of the ID stored in variable strID.

Result = MIStartTask("ShowMyID", "ID is: "&strID)

Example 2: A task called SendSummaryFile is started with two task parameters computed from within the script: ID and CheckNum.

blnResult = MIStartTask("SendSummaryFile", "ID=" & strID & "|CheckNum=" & intCheckNum)

Returns 0 if the task was started. Note: the task will probably still be running when this function returns; a 0 return code does not mean that the task will successfully run to completion

TaskGroups = MITaskGroups()

Returns the names of the task groups to which the task belongs. This is a string containing the names of all applicable groups, separated by |. For example, the result might be "Daily|For Argus Bank|By Fred", or just "". You can process this in VBScript by creating an array from it using the Split function.

TaskName = MITaskname()

Returns the name of the task that is running the custom script.

MISetSecureTaskParam(ParamName, ParamValue, ParamDisplayValue)

Defines a dynamic secure parameter for the duration of the task run.

Note: MOVEit Automation does not normally expose secure parameter values in the MOVEit logs or during an export. However, an administrator can expose the value with certain script commands. For example, a script author may write the value of a secure parameter that was retrieved using the MIGetTaskParam function to the log using the MILogMsg function, saving the decrypted version of the parameter to the log. The script author controls this exposure.