Folder Monitoring Service

Folder Monitoring Service is a program on the client side that detects the documents copied to the specified folder automatically and outputs the conversion result to the specified folder using Web Interface V6.0.

Folder Monitoring Overview

In order to use the service, there should be a Server Program of Web Interface V6.0 running and available to process requests.

When the folder monitoring service starts, the files in the monitoring folder are processed. After the service is running new files created in the folder are also processed. The service will perform the following operations for each processed file:

  1. Generate a command line for the Web Interface V6.0 Client Program from the contents of the file (the target file for conversion, and the file that instructs the conversion).
  2. Transmit a request to the Server Program of Web Interface V6.0.
  3. Store the result returned from the Server Program of Web Interface V6.0 in the output folder.

Network options like the server address can be saved to a default command file used by the Folder Monitor service or they can be provided in the command file within the ZIP file copied into the folder being monitored.

Starting the Program

The JAR file for the Web Interface V6.0 folder monitor is xds-folder-monitor.jar.

The folders to be monitored and the location of the output folders are specified on the command line as follows:

java -jar xds-folder-monitor.jar [options] <first directory to watch> <first directory output> <second directory to watch> <second directory output> ...
  
Example:
java -jar xds-folder-monitor.jar C:\folder1 C:\folder1\output
  
CAUTION: By default, the folder monitor log will be written in the installation directory ([install directory]/logs/folder-monitor.log). The user starting the folder monitor should have write permission for this directory. The location of the log file can be changed in a log4j configuration file specified with the -log4j-properties command line option.

The output folder must be a subdirectory of the watched folder.

The XDS_FOLDER_MONITOR_CONFIG environment variable can be set with the absolute location of a file that contains default command line options. See Option File for the description of the file format.

Folder Monitor Command Line Options

Parameter Default Functions
-log4j-properties File If this option is not specified it defaults to console and file output ([install directory]/logs/folder-monitor.log) in debug mode.

See samples/log4j.properties for an example with logging appended to a file as well as console output.

If no appenders are defined in the configuration file the default settings listed above are used.

-threads Value 4 Maximum number of files that can be processed at the same time. 0 specifies an unlimited number of threads
-disable-formatter-log Without this option a log file with AH Formatter console output is also saved in the output directory.
-default-command-file File Location of a default command file that is processed before the one contained in the ZIP archives. It is not necessary to set this file name command.txt.
-default-command-file C:\test\default_command.txt
-java-prop Property Value Set a Java system property. This is used, for example, to specify the "mail.user" property when you send e-mail with a ZIP command file. (That property is the default value of the SMTP_FROM key.) See the Sending e-mail section for more information.
-help Print command line options to the console.

Processing

In order to use Folder Monitoring Service, the target files being converted should be ZIP archived and put in the target folder as one file. Folder Monitoring Service finds and processes the files automatically, and puts the conversion result in the output folder.

The following files can be included in the archive for conversion.

The files required for a conversion are all ZIP compressed into one ZIP file. Media files referenced by the input documents must maintain the same directory structure in the ZIP archive. For example, an archive could have the following content:

.-+- command.txt
  +- document.xml
  +- style.xsl
  +- images/
      +- pic01.png
      +- pic02.png

In addition to ZIP archives simple documents like a single FO file can also be dropped into the monitored folder. These will be converted using the folder monitor's default options.

Command File

The command file is used to specify the conversion options and builds a suitable list of Client Program options. It is always named command.txt and should be placed only in the root directory within the ZIP archive.

If a default command file has been specified with the -default-command-file option it is evaluated before the one specified in the ZIP archive.

In the command file, each line is written in the form of key = value. The format for the keys and values are as follows:

ARGS=[space separated list of Client Program options]
ARGS_REMOVE=[comma separated list of Client Program options]
DOCUMENT=filename
STYLESHEET=filename
XSLT_PARAM=[key=value[,key=value...]]
OUTPUT_TYPE=[AH Formatter output type:  pdf|svg|...]
OUTPUT_OPTION=[key=value[,key=value...]]
OUTPUT=filename
FORMATTER_TYPE=auto|html|xhtml|xmlcss|xslfo
EMAIL=[mailaddress[,mailaddress...]]
EXITLEVEL=1|2|3|4
SMTP_HOST=[mail server adress]
SMTP_PORT=[mail server port]
SMTP_PASSWORD=[mail server password]
SMTP_STARTTLS=[boolean value: 'true' or 'false']
SMTP_SSL=[boolean value: 'true' or 'false']
SMTP_FROM=[mailaddress]
SMTP_USER=[user login name]

The recommened method of specifying options is with the ARGS key. DOCUMENT, STYLESHEET, XSLT_PARAM, OUTPUT_TYPE, OUTPUT_OPTION, OUTPUT, FORMATTER_TYPE, and EXITLEVEL are kept for compatibility with previous versions of Web Interface V6.0.

Sample command file:

  ARGS = -xds-host 10.1.10.14 -d input.fo -o output.pdf -tpdf -x 4
  EMAIL = test@antenna.co.jp

When a key, except for ARGS and ARGS_REMOVE, is set to a blank value (ex: 'EMAIL=') it will erase the option. Blank values for ARGS and ARGS_REMOVE have no effect. If, for example, a default command file is specified with -default-command-file and it sets 'EMAIL=test@antenna.co.jp' a setting of 'EMAIL=' in the ZIP archive command file, that will prevent sending emails.

The following table describes the supported keys and values.

Key Description Action when the key is omitted
ARGS Specifies space separated AH Formatter command line options. This key can be specified multiple times. It will append to the Client Program command line being generated.
	ARGS = -xds-host 10.1.10.24
	ARGS = -d input.fo
	ARGS = -o output.pdf
	...
      
No effect.
ARGS_REMOVE Specifies comma separated AH Formatter command line options. This key can be specified multiple times. It will remove the option from the Client Program command line being generated. Command line options that are followed by additional values need to specify the number of additional values. For example, if '-d input.fo' is currently part of the current command line being generated, it would be removed with '-d 1'. The '-d' option is removed as well as 1 additional parameter.
	ARGS_REMOVE = -xds-host 1
	ARGS_REMOVE = -tpdf, -lpdf, -o 1
	...
      
No effect.
DOCUMENT Specifies the input file. The file name can be specified by a relative path from the command file. The first .fo found in the root directory is used as long as it wasn't also specified as the Data XML Files. If no .fo is found, the first .xml found in the root directory is used as long as it wasn't also specified as the Data XML Files. If no .xml is found, the first file found in the root directory is used as long as it doesn't have an .xsl extension, isn't specified as the Data XML Files, and is not named command.txt.
STYLESHEET Specifies the stylesheet file. The file name can be specified by a relative path from the command file. (Please do not specify a CSS file here.) If there is a file with an .xsl extension among the files in the archive, it will be considered as the stylesheet.
OUTPUT Specifies the output file. The file name of the archived target file for conversion will be be used to create the output file name. The extension will be the same as the output format specified by OUTPUT_TYPE or the '-p' ARGS option. For example, if the archive of the target files is Document.zip and ARGS = -p @PDF is specified, the output file name will be Document.pdf.
OUTPUT_TYPE Specifies the output type. PDF is output.
OUTPUT_OPTION Specifies the output options. Multiple options can be specified by comma-separated value. Available options are listed in the Rendering Options section. No effect.
XSLT_PARAM Specifies the parameter xsl:param at the time of XSLT transformation. Multiple parameters can be specified by comma-separated value. No effect.
FORMATTER_TYPE Specifies the formatting type. 'auto' (automatically detect type) is considered to be specified as the formatting type.
EXITLEVEL Specifies a condition to stop formatting when an error occurs. Available values are from 1 to 4:
  1. Information
  2. Warning
  3. Recoverable Error
  4. Fatal Error
If the error level is same or higher than the EXITLEVEL specified here, formatting will be stopped.
Outputting will be done with the default value of 4.
EXT_REPLACE Replace the extension with the default one named when output file name is not specified with "ARG = -o" or "OUTPUT = " option. For example, if the archive of the target files is Document.zip and ARGS = -p @PDF is specified, the output file name will be Document.pdf by default. But if you specify EXT_REPLACE = PDF in same time, the output file name will be Document.PDF. No effect.
EXT_APPEND Append extension after original file's name when output-name is not specified with "ARG = -o" or "OUTPUT = " option. For example, if the archive of the target files is Document.zip and ARGS = -p @PDF is specified, the output file name will be Document.pdf by default. But if you specify EXT_APPEND = pdf in same time, the output file name will be Document.zip.pdf. No effect.
EMAIL Specifies the e-mail address to send the conversion result to. Multiple e-mail addresses can be specified by comma-separated value. See Sending e-mail section for more information. No effect.
SMTP_HOST SMTP server address. No effect. The default value is localhost.
SMTP_PORT SMTP server port. No effect. The default value is 25.
SMTP_USER User login name on the SMTP server. Does not try to authenticate user on the SMTP server.
SMTP_PASSWORD SMTP server password. Does not try to authenticate user on the SMTP server.
SMTP_STARTTLS Boolean value ('true' or 'false') indicating whether the SMTP server uses StartTLS. Note that an appropriate trust store must configured so that the client will trust the server's certificate. The default value is false.
SMTP_SSL Boolean value ('true' or 'false') indicating whether the SMTP server uses SSL. The default value is false.
SMTP_FROM Specifies the return email of the user. Some servers might not allow this or need it to match SMTP_USER. In those cases this should be set to the same value as SMTP_USER. Uses the value for SMTP_USER. If SMTP_USER isn't set, the value obtained from the property "mail.user" as default. If this property is also absent, the Java system property "user.name" is used.
  • Lines that begin with # are treated as comments and ignored.
  • All keys are case sensitive.
  • The white space before and after delimiters (= and ,) will be disregarded. With the ARGS key white space is used to separate the different options specified.
  • When you want to include a white space, a comma, etc. in the value, please surround it by "...".
  • Use \" to include a literal quote.

The following shows an example of a command file that applies the stylesheet called test.xsl to test.xml and transforms them into PDF. The result is outputted as output.pdf and a notification is sent to test@antenna.co.jp via e-mail.

  ARGS=-xds-host 10.1.10.24
  ARGS=-d test.xml -s test.xsl -p @PDF -o output.pdf
  EMAIL=test@antenna.co.jp

Result of Conversion

When the Folder Monitoring Service processes a file placed in the monitoring folder, it makes a folder called backup under the monitoring folder and saves the processed file to that folder. After the web service request to convert the document the result is stored in the output folder specified in the Folder Monitoring Service command line.

When the EMAIL option is specified, you will receive an e-mail notifying whether the conversion was completed normally or not. See Sending e-mail section for more information.

When the EMAIL option is not specified, you have to check yourself whether the result has been put in the output folder. If -disable-formatter-log has not been used there will be a log file in the output folder that has the AH Formatter console output. The completion status can also be checked in the Folder Monitor Service's log file.

The backup folder has sub folders that show the conversion date and time.

  backup/20130930203046/2/archive.zip

Furthermore, the folder named with the date and time has a sub folder with a sequence number. This number is created in order to distinguish files received and converted at the same time. If the backup files are not needed they may be deleted at any time.

An AH Formatter log file is saved to the output folder with the same name as the output file plus an -log.txt extension. For example, output.pdf would have a corresponding log file named output-log.txt.

Sending e-mail

To specify the EMAIL option, you need to set appropriate SMTP server settings to send e-mail. Please get information about SMTP server settings (ex. from administrator). To see the default value of those keys, see "Action when the key is omitted" on the key table. Some SMTP server may need certification to connect from client machine. So check the settings if you can't connect.

The following shows an example of a command file to send a message by the server requires SMTP Authentication with using STARTTLS.

EMAIL = test@antenna.co.jp
SMTP_HOST = smtp.example.com
SMTP_PORT = 25
SMTP_USER = example
SMTP_PASSWORD = password
SMTP_STARTTLS = true

After conversion succeeded, you can get the message like below with logfiles. The logfile is same as the one saved to the output folder.

Folder Monitor Results: 2017-04-01--12:00:00

Document conversion succeeded.

input file: C:\FolderMonitorTest\test.zip
output file: C:\FolderMonitorTest\output\test.pdf

Logging

The Folder Monitoring Service of Web Interface V6.0 can output logging information to files and the console. Because Apache's log4j library is used the output destination and the output level of the log can easily be changed. See the Logging chapter for more information. If a custom log configuration file is not specified the default logging behavior is to print DEBUG level messages to both [Install directory]/logs/folder-monitor.log and the console.

Rendering options

Rendering options are expressed by pairs of keywords and values. The keywords are named similarly to the command line options for AHFCmd from AH Formatter. Please refer to the manual of AH Formatter for more details.

Keyword Type Functions
pdfver string Specifies the PDF version to output.
tpdf boolean Specifies whether to output tagged PDF.
lpdf boolean Specifies whether to output linearized PDF.
encrypt numeric Specifies the key length when encrypting the PDF file to output.
userpwd string Specifies the user password for PDF.
masterpwd string Specifies the master password for PDF.
npt boolean Prohibits printing the PDF file.
ncg boolean Prohibits making changes of the PDF file.
ncc boolean Prohibits copying the content of the PDF file.
nca boolean Prohibits adding comments and form fields to the PDF file.
nff boolean Prohibits filling in of form fields and signing of the PDF file.
nab boolean Prohibits text access for screen reader devices of the PDF file.
nad boolean Prohibits inserting, deleting and rotating the PDF pages.
peb string Specifies whether to embed the embeddable fonts in PDF or not with one of the following values.
  • part: Specified font only (used with -pee)
  • all: All fonts excluding Base14 font
  • base14: All fonts including Base14 font
pee string Embeds the specified font in PDF.
pesub string Embeds all fonts when the percent of characters used is more than specified value, subsets embedded fonts when the percent of characters used is less than the specified value. The value without unit or % value can be specified. (1.0 = 100%). If nothing is specified, it is considered as 100 and embedded fonts are always subset.
pef boolean Specifies not to issue an error even if font embedding fails.
peg boolean Specifies not to issue an error even if the font has no glyphs.
pex boolean Specifies not to issue an error even if there is an error when PDF/X, PDF/A and PDF/UA is generating.
ppa numeric Specifies whether to permit printing of the PDF.
picc numeric Specifies how to compress the color images embedded in PDF.
picg numeric Specifies how to compress the grayscale images embedded in PDF.
picm numeric Specifies how to compress the monochrome images embedded in PDF.
pjq numeric Specifies the quality of the raster graphics when converting to JPEG format.
pcs boolean Specifies not to compress text and line art in PDF.
plr boolean Specifies how to link to the external location specified by by the local file.
prc numeric Specifies how to convert the RGB color space in PDF.
prr numeric Specifies the value of the resolution when converting vector images to raster images.
pcics boolean Converts RGB images automatically into CMYK when outputting PDF/X and PDF/A.
p3da boolean Imports 3D object.
pdfheight numeric Scales the height of PDF to output.
pdfwidth numeric Scales the width of PDF to output.
svgver string Specifies the version of SVG.
svggzip boolean Outputs SVG compressed in gzip.
svgic numeric Selects how to convert the raster images which may not be embedded in SVG directly.
svgjq numeric Specifies the quality of the raster graphics when converting to JPEG.
svgrr numeric Specifies the value of the resolution when converting vector images to raster images.

Technical Notes


Copyright © 2005-2018 Antenna House, Inc. All rights reserved.
Antenna House is a trademark of Antenna House, Inc.