Advanced Topics - MessageWay CLI

MOVEit Central's built-in MessageWay Translator script uses a command-line program, xformviamway, to communicate with a MessageWay server. In ordinary use, MOVEit Central administrators can rely upon the built-in script to handle all interaction with the command-line program. Thus, ordinarily, MOVEit Central administrators do not need to know how xformviamway works, or even that it exists at all. However, advanced MOVEit Central administrators may wish to invoke the command-line program themselves, to handle unusual or complex scenarios. This section describes xformviamway for those advanced administrators.

xformviamway.exe, which by default is installed in \Program Files\MOVEit, is a program that sends a single file to MessageWay and, after MessageWay has completed processing the file, receives the resulting output files, writes two status files, and terminates.

Program arguments

The program is invoked as follows:

xformviamway.exe -i infile -o outfile -c completionfile

`infile`	is the name of an input file giving such information as how to connect to the MessageWay server, where the input file is, and where the output files should be created. See below for a description of the format of this file.
`outfile`	is the name of an output file to be created by xformviamway, giving the status of the completed translation, and listing the names of the data and report files returned from MessageWay. See below for a description of the format of this file.
`completionfile`	is the name of a completion file to be created by xformviamway when it finishes. The contents of this file are unimportant; the creation of this file indicates that xformviamway has completed writing `outfile`.

Input file

The input file is a text file in ".INI file" format, with one input value per line. Here's a sample file:

[Params]
Host=172.16.23.204
SSL=False
Port=6280
SSLFingerprint=
User=micentral
Password=G7z3fN9wP
Recipient=translate:moveit
Sender=X850TEST
MIMEType=
ExceptionsInsteadOfData=True
FilenameToProcess=C:\TEMP\MIC\c88-0002\atc10001.tmp
OriginalFilename=X850test-MultOut.txt
OutputDir=C:\TEMP\MIC\c88-0002
MaxSeconds=300
PollIntervalSeconds=5
TraceFilename=
ForceAtLeastSeconds=20

The input values are described below. All values are required except where marked optional.

Name	Description
Host	The hostname or IP address of the MessageWay server.
SSL	True if SSL should be used, else False. Note: if you use SSL, you must specify the MessageWay server's certificate's fingerprint in SSLFingerprint. If the server is on the same computer as MOVEit Central, you can safely specify False here and avoid having to know the certificate's fingerprint.
Port	The TCP port to which the program should connect. Typically 6280 if not SSL, or 6243 if SSL.
SSLFingerprint	(Optional) Hexadecimal fingerprint (MD5 or SHA1) of the server's certificate. Required if SSL is True. (There is no way to specify that any certificate should be accepted.) The string consists of groups of 2 hex characters separated by spaces.
User	The MessageWay username. This user must have sufficient permission to access the recipient location.
Password	The password of the MessageWay user.
Recipient	Destination (in MessageWay terminology) of the translated files. Typically this will be something like "translate:moveit", which means that there must be a translation location named "translate" and a mailbox named "moveit" configured in MessageWay. The specified user must have sufficient access to these locations.
Sender	An arbitrary sender's name. The MessageWay translation engine may base its translation partly on the sender's name.
MIMEType	(Optional) An arbitrary MIME type string.
ExceptionsInsteadOfData	Tells the script how to behave when any exception occurs (meaning poorly formatted data). True means no data files should be returned if an exception occurs; instead, the exception report files are returned. Defaults to False, which means only data files are returned. If False and exceptions do occur, you will have to look up the exception reports directly through MessageWay.
FilenameToProcess	The full path to the input data file to process. However, MessageWay is not informed of this filename; instead, MessageWay is told that the filename is OriginalFilename (below).
OriginalFilename	The filename to present to MessageWay. Depending upon MessageWay's configuration, the type of processing done may be partially determined by this filename. This filename should not include a path.
OutputDir	The full path of the directory into which xformviamway should write its data and report files. For instance, C:\data\xlate.
MaxSeconds	(Optional) The maximum number of seconds to wait for MessageWay to process the file. A value of 0 means no limit. May include macros. Defaults to 7200 (two hours).
PollIntervalSeconds	(Optional) The number of seconds to wait between queries to MessageWay to determine whether processing has completed. May include macros. Defaults to 5 seconds.
TraceFilename	(Optional) The full path to a file which will receive a detailed trace log of xformviamway's communications with the MessageWay server. For example, C:\tmp\MWTrace.txt. Use this parameter only to debug problems interacting with the MessageWay server.
ForceAtLeastSeconds	(Optional) A rarely-used parameter which specifies the minimum amount of time that xformviamway should take before responding. Specified as an integer number of seconds. If specified, xformviamway will wait until at least ForceAtLeastSeconds seconds have passed before returning, even if the processing was complete before that amount of time. This parameter was implemented to allow testing of progress bars.

Output file

xformviamway's outfile is an XML file describing the results of the translation. The actual data and report files resulting from the MessageWay processing are separate files which are pointed to by outfile. Here's a sample file:

<Output>
  <InputProcessingStatus>Accepted</InputProcessingStatus>
  <RFiles>
    <RFile>
      <MessageID>2010080413120504btdb</MessageID>
      <CacheFilename>C:\TEMP\MIC\c88-0002/2010080413120504btdb.tmp</CacheFilename>
      <FileType>Output</FileType>
      <Filename>M2010080413120504btdb.dat</Filename>
    </RFile>
    <RFile>
      <MessageID>2010080413120504c55l</MessageID>
      <CacheFilename>C:\TEMP\MIC\c88-0002/2010080413120504c55l.tmp</CacheFilename>
      <FileType>Output</FileType>
      <Filename>M2010080413120504c55l.dat</Filename>
    </RFile>
    <RFile>
      <MessageID>2010080413120504deg9</MessageID>
      <CacheFilename>C:\TEMP\MIC\c88-0002/2010080413120504deg9.tmp</CacheFilename>
      <FileType>Output</FileType>
      <Filename>M2010080413120504deg9.dat</Filename>
    </RFile>
    <RFile>
      <MessageID>2010080413120504egd8</MessageID>
      <CacheFilename>C:\TEMP\MIC\c88-0002/2010080413120504egd8.tmp</CacheFilename>
      <FileType>Report</FileType>
      <Filename>2010080413120504ac2j.txt</Filename>
    </RFile>
  </RFiles>
  <ErrorCode>0</ErrorCode>
  <ErrorDescription></ErrorDescription>
  <ShouldRetry>false</ShouldRetry>
  <OriginalMessageID>2010080413120504ac2j</OriginalMessageID>
</Output>

The XML tags are described below.

Name	Description
InputProcessingStatus	The processing status as returned by MessageWay. The possible values are: Accepted Rejected Accepted with errors Partially accepted (empty) An empty value usually indicates an error.
RFile	Each RFile node represents a single file returned from MessageWay. The subnodes are: MessageID - The Message ID of the file inside MessageWay. This is typically useful only if you are going to look up the message from the MessageWay Dashboard. CacheFilename - The filename of a file created by MessageWay. This file will be in the OutputDir specified in the input file. FileType - Either Data or Report. MessageWay Data files contain the translated output. A single input file might result in multiple data output files. MessageWay Report files contain descriptions of the processing of the input file, including detailed error messages if the input file contained incorrect data. Filename - The name of the file (message) as it is known inside MessageWay.
ErrorCode	An error code giving the overall success of the process. 0 means success. Non-zero values mean failure. Generally, translation runs that result in exceptions due, for instance, to invalid input data result in an error code of 0. Non-zero errors are normally returned only if xformviamway cannot connect to or login to the MessageWay error, or if the MessageWay server returns an ill-formatted response.
ErrorDescription	An error description elaborating on the error that causes a non-zero ErrorCode. If ErrorCode is 0, ErrorDescription will be empty.
ShouldRetry	true if the xformviamway run failed, but in a way that implies that a subsequent run may succeed. For instance, if xformviamway cannot not connect to the MessageWay server, it returns a ShouldRetry of true, because the MessageWay server may be down only temporarily. ShouldRetry is false if the xformviamway run succeeded, or if it failed in a way that implies that a retry is unlikely to succeed. ShouldRetry is intended to be used by retry logic of the process invoking xformviamway.
OriginalMessageID	The message ID assigned by MessageWay to the input file. This can be useful for analysingThe message ID assigned by MessageWay to the input file. This can be useful for analysing message flow via MessageWay Dashboard. OriginalMessageID will be empty if MessageWay did not accept the input file - for instance, if the user could not login.

Return code

The program returns 0 if processing succeeded; this includes translation that resulted in exceptions. The program return a non-zero error code upon failure.