eRez Imaging Server 4

Configuring Plug-Ins

 

This document describes how the Plug-Ins bundled with eRez Imaging Server 4.0 and later can be customized and configured.

 

Table of contents

Configuring Plug-Ins 1

Table of contents 1

Configuring the Generic Plug-In. 1

Location of the files 1

Adding a new format 2

Activating the new formats 2

Configuring the PS plug-in. 3

Obtaining Ghostscript 3

Location of the files 5

Configuring Ghostscript 6

Configuring the PDF Page splitter 7

Configuring PS plug-in on MacOS X. 8

Installing and configuring the JPEG Auto Converter Plug-in. 9

Overview. 9

General Installation Process 9

How to configure plugin.xml 9

Worth to Remember 10

More Reading. 11

Configuring the CAD VieW plug-in. 12

 

Configuring the Generic Plug-In

 

This section describes how the Generic Plug-In bundled with eRez Imaging Server 3.0 and later can be used to add support for new file formats.

 

Location of the files

 

The Plug-In code and support files are located inside the webapps/erez4/WEB-INF/plugins/generic folder in the Tomcat folder.

 

The folder “icons” contains small TIFF images used to represent the various file formats when eRez displays them. You will find icons for a small set of common formats in there already.

 

The file “plugin.xml” contains information for use by the eRez Imaging Server as well as description for each of the file formats. This file can be edited by a standard text editor.

 

Adding a new format

 

To add support for a new file format you will need to insert a new line like this:

 

<format name="StuffIt Archive" extension=".sit" mimetype="application/x-stuffit" preview="icons/stuffit.tif"/>

 

The easiest way to do this is to copy an existing format and then modify the value of the attributes. The following attributes can be specified:

 

Name

Description

name

The name of the format as displayed by the eRez Imaging Server.

extension

The file name extension used to detect this format including a leading “.”. Example: “.doc”.

mimetype

The Mime Type used to identify this format as define by IANA.

You can use the mime type “application/octet-stream” if you don’t known the mime type for the file format.

preview

Relative link to the thumbnail TIFF file to use. Example:  icons/stuffit.tif

ole2format

If this attribute is present and the value is “true” the PlugIn will try to read metadata from the files as an OLE2 document and present it as IPTC data. This makes it possible to extract metadata from formats like Microsoft Office documents and display it as IPTC information.

xmp

 

If this attribute is present and the value is “true” the PlugIn will try to locate XMP metadata in the file. If a thumbnail image is present it will be used to generate a preview and the IPTC compatible metadata will be displayed and indexed for searching.

Activating the new formats

 

In order for your new file formats to become active you must restart the eRez Server.


 

Configuring the PS plug-in

 

This section describes how the PS Plug-In bundled with eRez Imaging Server can be configured to create previews for EPS, PDF and Adobe Illustrator documents and include text from PDF documents in the searchable index.

 

These features require installation of the freely available external application Ghostscript, used for rendering documents for preview.

 

For legal reasons we cannot bundle Ghostscript with eRez, so you will need to download and install it separately.

 

Please note that from version 4.1, the eRez server supports native PDF, EPS and Illustrator conversion on Mac OS X 10.4 or later using the Quartz engine. Therefore there is no need to install and configure Ghostscript under Mac OS X.

 

Obtaining Ghostscript

 

Ghostscript is the name of a set of software that provides:

 

 

 

 

 

 

In simple terms, this means that Ghostscript can read a PostScript or PDF file and display the results on the screen or convert them into a form you can print on a non-PostScript printer. Especially together with several popular previewers, with Ghostscript you can view or print an entire document or even isolated pages, even if your computer doesn't have Display PostScript and your printer doesn't handle PostScript itself.

 

Ghostscript is available in several versions and for many platforms. These links may help you find the right version for your platform:

 

  1. http://www.ghostscript.com/ here you the freely available release of Ghostscript as platform independent source code as well as precompiled binaries for Windows.

 

  1. http://sourceforge.net/projects/espgs a GNU Ghostscript distribution with Linux RPMs.

 

  1. http://ii2.sourceforge.net/ ”i-Installer Home Page” - a network-aware installer application for Mac OS X 10.2 or higher which can be used to install Ghostscript 8 very easily. Please note that since version 4.1, eRez can use the built in Quartz engine of Mac OS X rather than GhostScript. So, you probably don’t need or want this anymore.

 

You can install Ghostscript anywhere on your system.

 


 

Location of the files

 

The Plug-In code and support files are located inside the webapps/erez4/WEB-INF/plugins/ps folder in the Tomcat folder.

 

 

The file “plugin.xml” contains information for use by the eRez Imaging Server as well as the settings for using Ghostscript and the PDF Splitter. This is what the default plugin.xml looks like:

 

<?xml version="1.0" encoding="UTF-8"?>

<plugin class="com.yawah.erez.plugins.ps.PSPlugIn">

 

      <ghostscript

            enabled="false"

            executable="C:\Program Files\gs\gs8.57\bin\gswin32c.exe"

            timeout="300"

            debug="false"

            >

            <parameter value="-r150"/>   

            <parameter value="-dQUIET"/>

            <parameter value="-dSAFER"/>

            <parameter value="-dBATCH"/>

            <parameter value="-dNOPAUSE"/>

            <parameter value="-dNOPROMPT"/>

            <parameter value="-sDEVICE=tiff24nc"/>

            <parameter value="-dUseCIEColor"/>

            <parameter value="-dTextAlphaBits=4"/>

            <parameter value="-dGraphicsAlphaBits=4"/>

            <parameter value="-dEPSCrop"/>

      </ghostscript>

 

      <!-- quartz is for use on MacOS X only -->

      <quartz

            enabled="true"

            executable="PDFPSConverter"

            resolution="150"

            timeout="300"

      />

     

      <splitter

            enabled="true"

            folder-postfix=" pages"

            page-prefix="page "

            page-postfix=".tif"

            extract-text="auto"

            extract-links="true"

            page-format="master-tiff"

      />

     

</plugin>

 


Configuring Ghostscript

 

The Ghostscript element contains the 3 attributes “enabled”, “executable” and “timeout” followed by a series of Ghostscript parameters. To enable Ghostscript you must change the value for enabled to “true” and set “executable” to point to your Ghostscript application as shown below:

 

      <ghostscript

            enabled="true"

            executable="C:\Program Files\gs\gs8.57\bin\gswin32c.exe"

            timeout="300"

            >

            <parameter value="-r150"/>

            <parameter value="-dQUIET"/>

            <parameter value="-dSAFER"/>

            <parameter value="-dBATCH"/>

            <parameter value="-dNOPAUSE"/>

            <parameter value="-dNOPROMPT"/>

            <parameter value="-sDEVICE=tiff24nc"/>

            <parameter value="-dUseCIEColor"/>

            <parameter value="-dTextAlphaBits=4"/>

            <parameter value="-dGraphicsAlphaBits=4"/>

            <parameter value="-dEPSCrop"/>

      </ghostscript>

 

When the PS Plug-in call the Ghostscript application it will wait for a maximum of “timeout” seconds for Ghostscript to complete the rendering. If GhostScript has not completed within that period it will be terminated by the Plug-in.

 

If for some reason Ghostscript encounters an error or is terminated by the Plug-in a log file is saved in a hidden folder “.erez/{filename}/GhostScriptLog.txt” where {filename} reperesent the name of the eps, pdf or illustrator file. 

 

As long as the file “GhostScriptLog.txt” is present, no further attempt is made to render a preview. You can inspect the fille to see the output from Ghostscript including possible error messages. This is handy when experimenting with parameters etc.

 

The Ghosstcript parameters are passed to Ghostscript in the order they appear in the XML file followed by the parameters  "-sOutputFile={tmpfile} {srcfile}" where {tempfile} respresents the path and filename of a temporary TIFF file and {srcfile} the path and filename of the original eps, pdf or illustrator file.

 

The example configuration that comes with the Plug-in is optimized for AFPL Ghostscript version 8.14. Depending on the Ghostscript version that you are using you may need to remove some of the parameters. Particularly the parameters “TextAlphaBits”, "GraphicsAlphaBits" and “EPSCrop” may not be supported by earlier versions of Ghostscript and may cause Ghostscript to fail. Likewise you may want to add extra parameters to take advantage of features implemented after the writing of this document.

 

Configuring the PDF Page splitter

 

The PDF Splitter is use to automatically create a folder with a TIFF file for each page in a PDF document. This greatly simplifies the process of preparing files to be published using FSI Pages.

 

Since version 4.1 of eRez Imaging Server this feature is enabled per default.

 

The "splitter" section in the configuration file is used to control the behavior of the automatic PDF Splitter.

 

This is what the default splitter section looks like:

 

      <splitter

            enabled="true"

            folder-postfix=" pages"

            page-prefix="page "

            page-postfix=".tif"

            extract-text="auto"

            extract-links="true"

            page-format="master-tiff"

      />

 

 

If the "enabled" attribute is set to "true", the PDF Splitter will create a folder next to the original PDF document with a name composed by the original name (without extension) plus the string defined by the "folder-postfix" attribute.

 

Inside this folder the Splitter will create a file for each page in the PDF document named as the value of the "page-prefix" attribute plus the number of the page plus the value of the "page-postfix" attribute (example "page 42.tif".

 

If the PDF document is not encrypted and the value of the "extract-text" attribute is either "caption", "erez" or "auto" then the splitter will try to extract the text and store it inside the resulting TIFF file either in the IPTC Caption field, the special eRez large text field (which can hold texts larger then 2000 characters) or in the case of "auto" the caption field if the text is less or equal to 2000 characters otherwise the text is store in the special eRez field. The text can be used for searching from within FSI Pages.

 

If the "extract-links" attribute is set to "true", the splitter will try to extract links such as URLs to web pages etc. as well as internal links to pages inside the PDF. These links can be used from within FSI Pages.

 

The final attribute "page-format" specifies the "download template" used to prepare the TIFF files. We suggest that you leave this as "master-tiff" for optimal quality and display performance.

 

PDF files with a single page only are not processed. If the Ghostscript or Quartz application fails to render the document the error message from the application is stored as a note in the folder created by the Splitter

 

 

Configuring PS plug-in on MacOS X

 

On MacOS X a native converter is used that utilize the build Quartz graphics engine to convert PDF, EPS and illustrator files. If the quartz part for the configuration file is enabled, an eRez server running on MacOS X will use the native engine, and ignore the GhostScript configuration. Notice that one can still enable the GhostScript configuration and disable the Quartz configuration, and that way use GhostScript on MacOS X.

 

The converter is path of the eRez server installation. Sometimes when move files a file can loose its UNIX attributes. The MacOS X native converter is located on the MaxOSX folder in the PS plug-in folder. The converter is named PDFPSConverter. If the converter does not have execute permissions, one must use the terminal to change this. When standing in the MacOSX folder use the following command chmod a+x PDFPSConverter.

 

The Quartz configuration is shown below.

 

<quartz enabled="false" executable="PDFPSConverter" resolution="150" timeout="300"/>

 

The enabled attribute turns the Quartz engine on and off.

 

The executable attribute should not be changed.

 

The resolution attribute specifies the output resolution of the converted file. The unit is DPI (dots per inch).

 

The timeout attributes specifies how long the eRez server waits for the converter to finish. The unit is seconds. If the converter is not finished within this time, eRez will terminate the converter.

 

 


 

Installing and configuring the JPEG Auto Converter Plug-in

 

Overview

 

This Plug-in makes it possible to auto-convert JPEG files to the TIFF format when new JPEG files are added “behind the scene” - without the Web Interface.

 

If the .jpeg-files are copied directly to one of the user-defined source folders or their subfolders they will automatically get converted if they are monitored by the periodic scanner. These folders are also known as hot folders.

 

General Installation Process

 

The installation process consists of 4 steps:

 

1. Stop the eRez Server

 

2. Move the folder “jpeg autoconverter” from the “folder webapps/erez4/WEB-INF/plugins (disabled)” to the folder “webapps/erez4/WEB-INF/plugins”.

 

3. Configure the plug-in by editing the text file webapps/erez4/WEB-INF/plugins/jpeg autoconverter/plugin.xml using notepad or any other text editor. Follow the instructions below and save it.

 

4. Start the eRez application

You are now up running with the JPEG to TIFF Auto-Converter Plug-in.

 

How to configure plugin.xml

 

You also find the information below in the plugin.xml as comments. They are encapsulated in <!-- comment here -->

 

<Plugin> is they first tag element having x numbers of <convert> tags. Eg.

 

<plugin>

          <convert ..1.. />

          <convert ..2.. />

          <convert ..3.. />

</plugin>

 

Note that you can have multiple <convert> elements.


 

 

CONVERT ATTRIBUTES

 

ATTRIBUTE

DESCRIPTION

EXAMPLE

 

srcDir

(fully path, required)

Path to the source directory and its subdirectories where the plug-in are monitoring for new JPEG files.

Note that the source folder must be a shared folder with "Monitor files" enabled - also known as a hot folder.

          

 

srcDir="c:/program files/yawah/erez4/tomcat/webapps/erez4/web-inf/sample images/Other documents"

 

destDir

(fully path, optional, if nothing specified srcDir is used)

Path to destination directory where the converted TIFF files are saved when converted.

destDir="c:/program files/yawah/erez4/tomcat/webapps/erez4/web-inf/output/"

 

Template

(optional, if nothing specified "tiff-master" is used)

Name of the predefined template that contains information about conversion details

template=" master-tiff"

 

backupEnabled

(optional, false is default value if nothing specified)

To enable/disable the backup feature you must specify either true/false

If false the source file is deleted, otherwise it is moved to the specified backup directory

backupEnabled="true"

 

backupDir

(optional, srcDir is used as backup directory if nothing specified)

Path to backup directory where the source file are moved to. Eg. C:/mydir/myimage.jpg.bak

backupDir="c: /jpegs/backup

 

backupExtension

(optional, "bak" is used as default extension if nothing specified)

Backup extension that is appended to source file when finished conversion

backupExtension="bak"

 

Worth to Remember

It is important that the defined source directories are monitored by the scanner. You can check this by clicking the shared folder from the Administration Console. If the “Monitor Files” is enabled (default) and the shared folder or one of its subfolders that are defined as srcDir in plugin.xml they will automatically be converted to TIFF.

 

This “Monitor Files” option is the same that automatically track changes to the files and index files for searching, generate previews etc.

 

Always remember to restart eRez application when modified plugin.xml.

 

More Reading

You can read more about "Working with the Searchable Index and Hot Folder" in the documentation.

 


Configuring the CAD VieW plug-in

 

This section contains a description of how to configure the CAD VieW plug-in.

 

The CAD VieW plug-in enables eRez to display zoomable CAD drawings. The plug-in uses a converter to convert the drawings to SVG preview file. The original file is untouched and can be downloaded.

 

To use the CAD VieW plug-in a valid license key with CAD VieW enabled is needed. To see if there is a valid licenses look at server status in the administrator console. In the license tab, the entry CAD VieW should be 1 for a valid CAD VieW license.

 

If for some reason the CAD Converter encounters an error or is terminated by the Plug-in a log file is saved in a hidden folder “.erez/{filename}/CADLog.txt” where {filename} reperesent the name of the CAD file. 

 

As long as the file “CADLog.txt” is present, no further attempt is made to render a preview. You can inspect the fille to see the output from the CAD Converter including possible error messages.

 

The CAD View plug-in is default installed, but unless there is a valid license key the plug-in is not loaded.

 

The CAD VieW plug-in will work out of the box, but you might want to change the behavior of the plug-in. To do this you need to open the plugin.xml file. The file is located in the in cad folder in the plugins folder of the eRez server. If you made a standard installation the path will look something like this:

 

C:\Program Files\yawah\erez4\tomcat\webapps\erez4\WEB-INF\plugins\cad

 

The plugin.xml file has two parts, the first part is parameters to eRez for the behavior of the CAD VieW plug-in, and the second part is parameters for the CAD converter.

 

The plugin.xml file looks like this:

 

<?xml version="1.0" encoding="UTF-8"?>

 

<plugin class="com.yawah.erez.plugins.cad.CADPlugIn">

 

    <cadconverter

            enabled="true"

            executable="SvgExport.exe"

            timeout="300"

            debug="false"

            >

 

        <parameter value="-e"/>

    </cadconverter>

</cadconverter>

 

</plugin>

 

The property enabled controls whether or not the plug-in should be used. Notice that there must still be a valid license for the CAD VieW plug-in for the plug-in to load.

 

The property executable specifies the location of the CAD Converter. It should not be necessary to change this attribute.

 

The property timeout controls how long time eRez will allow the CAD Converter to use for converting one CAD file. The value is in seconds. If the CAD Converter uses more than "timeout" seconds, the converter is terminated.

 

Setting the property debug to true will turn on additional logging that may help if there for some reason are problems with the plug-in. In a normal production environment this should always be false.

 

The parameters control the behavior of the CAD Converter. The only parameter one would add was the -s parameter. This parameter specifies the full path to extra CAD fonts.