Dynalivery Corporation provides sample source code, ScreenCam movies, and other documentation only as aids for learning specifically about our Saffron Desktop while providing a general overview of Web Reporting.

These materials are subject to change without notice. We provide them on an "as is" basis without warranty.

Please do not treat them as production quality components to use within your own application without your own comprehensive testing.

Acknowledgments

"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)"

Introduction

Printers are familiar to computer users. They are hardware devices that accept pages of text and graphics from computers and impress them permanently on paper with ink.

With the introduction of Saffron, Dynalivery defines a new product category, the virtual printer, implemented in software. Similar to hardware printers, Saffron accepts as input pages defined in Postscript or other page description languages. However, Saffron has the following key distinctions from ordinary hardware printers:

1) Electronic Documents

Instead of rendering ink on paper, Saffron renders pages into standard, electronic file formats such as the Adobe Portable Document Format (PDF), Hypertext Markup Language (HTML) and others. Electronic documents are fundamentally transmittable, replica table, shareable, and mutable by computers. Inside hardware printers, all work reduces to "ink on paper" with no link back to the sources."

2) Server Software

Saffron is not just software, but is server software. It can concurrently render many print jobs, from many users and locations at the same time. Saffron is also extensible as Dynalivery and partners may add both new input and new output modules over time, based on Dynalivery use of the Java2D specification (with extensions) as an intermediate representation of documents.

3) Personalized, Dynamic, and Composite Documents

Dynalivery has designed Saffron to fundamentally process three types of electronic documents, the personalized document, the dynamic document and the composite document. A personalized document is derived from a template but contains customized formatting or customized underlying data for one consumer/reader or a small group of related consumers/readers. A dynamic document is also derived from a template but is based on data, which is changing quickly. For example, a bank statement is both personalized and dynamic because it is customized for one account holder but it is different for each accounting period.

A composite document is derived from one or more pre-existing documents. The pre-existing documents may have originated in one or more software product producers such as Crystal Reports, Microsoft Word, and others. The pre-existing documents may also have one or more ages. For example, a composite document might be derived from one document that has existed for a month in Saffron's repository, concatenated with another pre-existing document that has an age of one second, having just been processed by Saffron's Postscript interpreter.

4) Java Programming Language

Dynalivery has implemented Saffron in the Java programming language so that the workflow of these electronic documents may exist in secure and scalable server computing environments. Dynalivery's choice of Java on the server side allows it a number of additions client or middle-tier interfaces, including Saffron Desktop, an End-User Graphical tool and an upcoming Web Services interface to allow Java, COM, and .net developers to script document rendering and concatenation jobs.

The remainder of this document concerns Saffron Desktop, which currently has the capability of converting postscript, Formatting Objects (XSL-FO) and WordMl to pdf, html, rtf, svg, png, and jpg documents.

Note: For more information on how to obtain postscript versions of the files you are interested in converting please see the SaffronDesktop GUI Printer section.

Installation

Run the install script and follow the instructions given to install Saffron Desktop on your machine. If the installation is on a non-Windows machine be prepared to give the location of a pdf viewer, a browser, a text editor and the location of installed fonts. You will need a license key obtained from Dynalivery.

New in Version 1.3

· Ability to print the Input Files to a Printer

New in Version 1.1

The user can have FO, WordML files as an input source.
RTF Formatter has a new Option, for getting smaller RTF Output Files.

New in Version 1.0

Multiple projects can be opened at once.
Additional Concatenation controls

· Added more logging controls

New output types and added navigational controls for PNG and JPG output formats

Getting Started

This manual will step you through the process of selecting files to be converted and applying any options necessary to those files.

Once Saffron Desktop is started the splash screen will be displayed giving a status of the starting process. Saffron Desktop will automatically start a Saffron service and connect to it without the user needing to provide any information. You can read more about the Saffron service in the Saffron section.

If the user is working with an evaluation copy the splash screen will indicate the remaining days in the evaluation period.

Once the application has been loaded the main Saffron Desktop workspace will be displayed.

Saffron Desktop is made up of several important sections. Circled in red is the Input File section where files selected to be converted will be listed. Circled in green is the Output File section which is where the corresponding list of output files is located. Circled in blue is the log section, which gives a report of the status of Saffron Desktop and of Saffron as well as any issues raised during the conversion process. Circled in yellow is the Toolbar section, which allows the user easy access to Saffron Desktop's functionality.

Toolbar

Add: Allows user to select the files to be added to the current Saffron Desktop session.

Open Project: Allows user to select a previously saved project to be added to a new Saffron Desktop session.

Save Project: Save the current session or previously opened project as a project file.

Remove: Remove a previously added file from the current Saffron Desktop session.

View Source: Allows the user to view the actual source that makes up the file.

View File: Allows the user to view the file in the associated application for that file type.

Refresh: Refresh the current Saffron Desktop session

Concatenate: Concatenates all the files that are currently selected in the Input File section.

Un-concatenate: Un-concatenates all groups that contain at least one of the currently selected files.

Convert: Begins the conversion process.

Connect: Connects Saffron Desktop to another Saffron service.

Disconnect: Disconnects Saffron Desktop from the currently connected Saffron service.

About: Displays the Saffron Desktop About box.

Help: Brings up this manual in a web browser.

Adding Files

By either selecting the Add Menu Item in the File Menu, or by selecting the Add button on the toolbar an open dialog box will appear allowing the user to select the postscript or FO or Wordml files they are interested in converting. After selecting the files and pressing the Ok button a list will appear in the Input Files section of the application with the name and path of the files you selected. This should not be viewed as a file explorer, which actually lists files on the hard drive, but is to be viewed only as a list of files selected. The same file is listed in the Output Files section with the extension changed according to what output type is selected (more later).

Setting Options

Input File Options

The Input Files section has several options available to the user, which affect how these selected files are viewed in Saffron Desktop and how Saffron Desktop uses these files during the conversion process. Input file options can be set either by pressing the right mouse button on a file to obtain the popup menu shown below or through the Menu Bar.

Concatenate

Files in the list have the ability to be concatenated with other files. Files selected to be concatenated will be merged into one output file upon conversion. The order of which the files are concatenated depends upon their position in the input file list. If the user adds multiple files at a time these files will be ordered alphabetically. To order files differently the user can add the files in the order they prefer and Saffron Desktop will list them and hence concatenate them in this order. Two or more files can be concatenated together, and there can be zero to many different concatenations in one project/session. (Refer to Concatenation Popup One) The limitations for concatenation are that one file cannot be in multiple concatenation groups.

When files are concatenated only one file is listed in the Output Files section that will be where the input files are concatenated into (more later). To concatenate files, the user can select the files to be concatenated and choose the concatenate menu item on the popup menu (Refer to Concatenation Popup One), or select the Concatenate button from the toolbar or select the Concatenate menu item in the Tools Menu.

To add a file to an existing concatenation group simply select that file and at least one file in the group then right click on the file. The Concatenation Popup Two list below illustrates your concatenation choices. In this case you would select “Add to Concatenation Group”. The user can do this with the Concatenate button from the toolbar or select the Concatenate menu item in the Tools Menu.

Concatenation Popup One Concatenation Popup Two

Un-Concatenate

To un-concatenate a single file from a group you can select the file and select the Un-Concatenate File from the menu item in either of the Concatenate Popup menus.

Input Files in a concatenation group can be un-concatenated by selecting one or more files in the group and selecting the Un-Concatenate Group menu item in either of the Concatenate Popup menus, the Un-concatenate Group button on the toolbar or the Un-Concatenate Group menu item in the Tools Menu.

Remove

One or more files can be removed from the input list by selecting the files to be removed and selecting Remove from the popup menu or the Remove button on the toolbar.

View Source

The source of the postscript or FO or Wordml file can be viewed by selecting the file of interest and then selecting the View Source menu item from the popup menu, selecting the View Source button on the toolbar, or selecting the View Source menu item in the View Menu. This will launch a text editor with the file. It is recommended that if you are not experienced with postscript or FO or WordMl the file should not be altered here. Postscript, FO, and Wordml are specific languages that have specific syntax that needs to be followed.

Show Input Path

The Show Input path menu item on the popup menu is to either show or hide the path from which the file was selected. By hiding the path it does not change where Saffron Desktop will look to find the file during conversion. This option can also be set with the Show Input Path menu item in the View Menu.

Print

The Input Files postscript, FO or WordML can be rendered on a Printer using the Print Menu option. When the Print button is pressed it pops a dialog box listing the Available Printers to the Saffron. If the output of the printer is to be captured in a File or if the Printer uses a File port, check the “Print to File” box and provide the Output File Name.

Only Input Files can be rendered to a Printer.

Output File Options

The Output Files section also has several options to be set which affect not only how they are viewed in Saffron Desktop, but more important how Saffron Desktop converts them to the output file type specified. Output file options can be set either by pressing the right mouse button on a file to obtain the popup menu shown below or through the Menu Bar.

Option Levels

Before the details of the options are given the levels of options must be explained. There are default options that are used when Saffron Desktop is started and can be changed by the user from the Default Preferences menu item in the Settings Menu. Upon start up the session level options are initially created from the default options. While using Saffron Desktop the user can set options that will affect only that session and will not change the default options. Some of the session options may pertain only to how Saffron Desktop is viewed/used, and other options are applied to the list of files in the output file list. The last level of options is the file level. While using Saffron Desktop there are ways to apply options to only the files that are currently selected. These file level options will override any session level options, but those files that do not have file level options set will continue to abide by the options set at the session level.

Rename

The path and filename can be renamed by selecting the Rename menu item in the popup menu. By changing the path it is assumed that the path does exist and the user has access to it. Saffron Desktop is not responsible for creating non-existing paths. If an extension is added to the filename that is not one of the supported output types then that extension will be added as part of the filename, but will not change the output type.

Change Output Type

The output file types currently supported are pdf, html, rtf, png, jpg and svg. All the files in the list can be changed to a different output type by selecting the radio buttons above the output file section containing the type that is desired. This selection will affect all the files that do not already have a file specific output type selected. This selection is considered to be at the session level.

If the user would only like to change the output type of certain files, they can select those files and then modify their output type by selecting that desired type from the Change Output Type menu item in the popup menu or from the Change Output Type in the Tools Menu. You can visually see what output type is going to be used for each file by noticing the icon that is displayed on the left side of the file, or be checking the extension that is automatically added to the filename. By double clicking on the radio button representing the output type desired for all the files, the file level output type option set will be cleared and all the files will again be of the session level output type.

For PNG, JPG and SVG outputs each page is in a different file. To make it easy for the user to view all the pages from Saffron Desktop, the View File menu item changes for these output types. It is populated with files in the output directory that contain the name of the base output file. The user can then select the page of the report that they wish to see and it will be loaded in the appropriate application.

View Source

After the conversion process is complete the user can view the source of the converted file. To do this select the file of interest and then select the View Source Menu item from the popup menu, select the View Source button on the toolbar, or select the View Source Menu Item under the View Menu. This will launch a text editor with the source of the file loaded.

View File

After the conversion process is complete the user can view the actual output file. To do this select the file of interest and then select the View File Menu item from the popup menu, select the View File button on the toolbar, or select the View File Menu Item under the View Menu. This will launch the application that is associated with the output type.

Overwrite Existing Files

Saffron Desktop gives the user the option to automatically overwrite an existing converted file. This option cannot be set at the file level, but can be set at the session level by selecting Overwrite existing files from the popup menu. It can be set at the default level in the Default Preferences section. If the option is set then Saffron Desktop will overwrite the existing file. If the option is set to false then Saffron Desktop will ask, for each file with an existing version on the hard drive, whether the user wants to overwrite it, leave it and move to the next file, or cancel the conversion process.

Show Output Path

The Show Output path menu item on the popup menu is to either show or hide that path into which the converted file will be placed. By hiding the path it does not change where Saffron Desktop will place the converted file. This option can also be set with the Show Output Path menu item in the View Menu.

Use Default Output Directory

The user has the ability to specify a default directory into which all converted files will be placed. Currently this directory can only be specified in the Default Preferences section, but the option to use it or not can be set in that section or by selecting Use Default Output Directory menu item from the popup menu. The files listed in the output file list will now be displayed with the output directory, and upon conversion these files can be found in that directory. If you hide the path using the Show Output Path menu item the default directory will still be used if it has been selected. If the user decides not to use this option and deselects it the original path will be restored and displayed in the output file list.

Refresh

After a conversion has been executed, another conversion and many other actions cannot be executed again until a refresh. The refresh can be found as Refresh menu item in the View Menu or the Refresh button on the toolbar. This is to prevent a user from making options changes to already converted files and expecting these options to take affect without converting again.

Conversion Options

Conversion option is another area that follows the three-tier option level.

In the Default Preferences section conversion options can be set that will be used as session options each time Saffron Desktop is started. If it is desired to make session level changes to all the files in the output file list the user can select the Conversion Options menu item in the Settings Menu and these options will be applied to all the files that do not have file level options set. To set file level conversion options the user can select the files of interest and then select the Conversion Options menu item in the popup menu. When changing file level conversion options the user can select the option of using the default conversion options. By selecting this it clears the file level options for all the files currently selected and those files will again use session level conversion options. If the user is changing session level options and selects the use default options all files will revert back to the default conversion options that were set in the Default Preferences section.

PDF Conversion Options:

Create Linearized:

This will instruct Saffron Desktop to create a linearized version of the PDF file. Linearized PDF enables a user to view a pdf file from a web server before the entire file has been downloaded.

Embed Whole Font:

This will instruct Saffron Desktop to embed the entire font in the PDF file. PDF files with embedded fonts allows for the pdf file to be correctly viewed independent of which platform is being used. Using this option does increase the size of the pdf file.

HTML Conversion Options:

Use Frames:

This option determines whether the output html files use frames for navigation or adds navigation to the bottom of each page.

Image Type:

The user can select JPEG or PNG files to be used.

RTF Conversion Options:

RTF File Size Reducer:

This option determines whether to reduce the size of RTF output file or not.

PNG Conversion Options:

There are currently no options for PNG.

JPG Conversion Options:

There are currently no options for JPG.

SVG Conversion Options:

CSS Style: This will instruct Saffron Desktop to use CSS style sheets when generating SVG code.

· Embed Fonts in SVG: This will instruct Saffron Desktop to embed the glyphs of the fonts used for each character that is used in the SVG page.

· Embed SVG in HTML: This will instruct Saffron Desktop to embed the generated SVG code inside an HTML page that contains navigation controls.

Converting

Once the user has selected all the files to be converted, added any concatenation and changed any output options the files are ready to be converted. Currently all files will be converted in the converting process. Future releases will give the user the ability to convert just selected files. To convert the files select the Convert menu item in the Tools Menu, or select the Convert button from the toolbar. During conversion the user can watch the progress of each file being converted display a yellow light. After that file has been converted the output file displays a green light specifying it has been created and the input file displays a gray light specifying it has been converted.

Log

The log is used to report status of Saffron Desktop, the conversion process and errors generated from the Saffron Server. The user can select what level of logging they wish to see. The lowest setting will only report status from Saffron Desktop. The highest will report all status messages that are sent from Saffron. The middle levels determine whether the user wants Warning or Error messages from Saffron. Setting the level to off will not report anything from either Saffron Desktop or Saffron, but this is NOT recommended. The log can also be saved to a text file. When working with our Tech Support Department it is strongly recommended that you send this text file along with a detailed description of the error.

Projects

Saffron Desktop has the ability to use projects, but a user need not have a project to use Saffron Desktop. When Saffron Desktop starts it creates a new session. The user can stay in this session selecting files and setting options and never need to worry about projects. But if the user wishes to save the work they have done in this session they can elect to save this session as a project. By selecting the Save Project menu item in the File Menu or by selecting the Save Project button in the toolbar a save dialog box appears that will allow the user to specify the name and location to save the project as. Saved in the project is the list of input and output files along with session level and file level options. Saffron Desktop projects are saved with a .hmn file extension.

Once a project has been saved the user can add more files to the project and save again, or save this project as a new project by selecting the Save Project As menu item in the File Menu. The user can have multiple projects open at one time. Once a project has been opened it will then appear in the recent files list and can be reopened from there. The recent files list will always show the last five projects that have been opened.

A project can be loaded at any time by selecting the Open Project menu item in the File Menu or by selecting the Open Project button in the toolbar. An open dialog box appears giving the user the ability to find and select the project they wish to open. Upon opening the session, the file options are set according to what was saved with the project, but the default options are not affected.

The user can close a project by selecting the Close Project menu item in the File Menu.

The user can also create a new project by selecting the New Project menu item in the File Menu.

The user can set an option in the Default Preferences section that will instruct Saffron Desktop to load the last project viewed upon start up.

Saffron

Saffron is the converting engine service that is provided with Saffron Desktop. For Saffron Desktop a version of saffron is embedded within the application and runs within the same process. For the Workgroup and Enterprise Editions, Saffron Desktop can connect to a Saffron service running on a separate machine or running independently on the current machine. The user has the option inside Saffron Desktop to connect to Saffron servers on the fly. If the machine that one Saffron server is running on has a problem the user can quickly change the connection to another machine with a Saffron server running.

SaffronDesktop GUI Printer

Dynalivery has provided a printer that allows the user to create postscript files. To create a postscript file start the printing process in your application of choice as usual. When given the option to select a printer there will be a SaffronDesktop GUI Printer in the list. Select this as the printer of choice and the user will be prompted for the name of a file to which you would like your application to print to. Upon completion there will exist a postscript file representing what you just printed. This can then be used inside SaffronDesktop GUI to convert to different file types.