OpenOverlay 1.

0
Getting Started Guide

Authors: Dan Gilbert Ian Whiting

Last Updated: October 23, 2007

OpenOverlay Getting Started Guide Approval/Signoff: Name Naveen Aggarwal Project Role Project Manager Signature Date

Revision History: Revision 1.0 10/2007 Name Dan Gilbert Description of Change New document Reason For Change New document Justification for Change New document

Technology Services Group, Inc. - All Rights Reserved

Page 2 of 14

OpenOverlay Getting Started Guide

Table of Contents
What is OpenOverlay? .................................................................................................................. 4 Getting Started with OpenOverlay ............................................................................................... 4 Overview ..................................................................................................................................... 4 What You Will Need .................................................................................................................... 4 Installing OpenOverlay ................................................................................................................. 4 Configuring the OpenOverlay Environment ............................................................................... 5 Configuring OpenOverlay............................................................................................................. 5 Defining an OpenOverlay Configuration File .............................................................................. 5 Creating an OpenOverlay Configuration File .............................................................................. 6 The OpenOverlay Configuration File ........................................................................................... 6 Components of OpenOverlay Configuration File ........................................................................ 7
<overlay-config> .................................................................................................................................... 7 <text-templates>.................................................................................................................................... 7 <text-template> ..................................................................................................................................... 7 <text> .................................................................................................................................................... 7 <overlay>............................................................................................................................................... 8 <restrictions>......................................................................................................................................... 8 <restriction>........................................................................................................................................... 8 <actions>............................................................................................................................................... 8 <action>................................................................................................................................................. 9 <block>.................................................................................................................................................. 9 <text> ...................................................................................................................................................10 <rectangle> ..........................................................................................................................................10 <image> ...............................................................................................................................................11 <barcode> ............................................................................................................................................11 <pdf> ....................................................................................................................................................12

Running OpenOverlay from the Command Line ...................................................................... 12 Command Line Statement Format ............................................................................................ 12 Using Tokens with OpenOverlay ............................................................................................... 12 Tokens as Definable Text ......................................................................................................... 13 Tokens as Restriction Properties .............................................................................................. 13

Technology Services Group, Inc. - All Rights Reserved

Page 3 of 14

OpenOverlay Getting Started Guide

What is OpenOverlay?
OpenOverlay is a lightweight, open-source textual and graphical overlay tool for PDF documents. It provides streamlined configuration settings (no coding required) and allows great flexibility in applying overlays. It can easily be deployed in a web application, invoked from the command line, or embedded in server software such as Documentum or Alfresco. Popular uses include Apply letterhead/logo Display document properties o Status, Version, Intended use, Author/Dept., etc. Permissions watermarking Overlay form responses

Getting Started with OpenOverlay

Overview OpenOverlay follows a powerful four step procedure to create textual and graphical overlays. The process can be summarized as follows: a) Gathers properties a. PDF properties (page orientation, number) b. Document metadata (dept, author, date) c. Data from invoker (user, role, application) b) Determines applicable overlays c) Applies and merges overlays d) Produces a seamless PDF What You Will Need In order to utilize open overlay, you will need the following: a. A distribution of OpenOverlay b. Java Runtime Environment version 1.4 or higher. May be obtained at http://www.java.com

Installing OpenOverlay
OpenOverlay is an open-source software initiative provided free of charge by Technology Services Group. The latest distribution of OpenOverlay, as well as other open-source solutions from TSG, may be downloaded at http://tsgrp.com/services_solutions/open-source.jsp. Once you have obtained OpenOverlay, extract the folder to a directory of your choice. The contents of the directory will include two configuration files, the open-overlay.jar file, and a folder containing supplemental .jar files.

Technology Services Group, Inc. - All Rights Reserved

Page 4 of 14

OpenOverlay Getting Started Guide

Configuring the OpenOverlay Environment

In order to run OpenOverlay, several additions must be made to your machines environment. The following paths must be added to youre the CLASSPATH environmental variable: 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. . (current directory) open-overlay.jar lib/bfopdf.jar lib/commons-lang.jar lib/itext-1.4.8.jar lib/junit.jar lib/log4j.jar lib/spring-beans.jar lib/spring-context.jar lib/spring-core.jar lib/tsgrp.jar lib/xalan.jar

To set the CLASSPATH environment variable: 1. In a command shell, navigate to the directory where your distribution of OpenOverlay is installed. 2. Execute the following commands: set set set set set set set set set set set set CLASSPATH=.;%CLASSPATH% CLASSPATH=open-overlay.jar; %CLASSPATH% CLASSPATH=lib/bfopdf.jar; %CLASSPATH% CLASSPATH=lib/commons-lang.jar; %CLASSPATH% CLASSPATH=lib/itext-1.4.8.jar; %CLASSPATH% CLASSPATH=lib/junit.jar; %CLASSPATH% CLASSPATH=lib/log4j.jar; %CLASSPATH% CLASSPATH=lib/spring-beans.jar; %CLASSPATH% CLASSPATH=lib/spring-context.jar; %CLASSPATH% CLASSPATH=lib/spring-core.jar; %CLASSPATH% CLASSPATH=lib/tsgrp.jar; %CLASSPATH% CLASSPATH=lib/xalan.jar%CLASSPATH%

3. These jar files must be included in the classpath for every console you wish to use OpenOverlay in. If these commands become bothersome, a .bat file may be used to programmatically set the classpath.

Configuring OpenOverlay
OpenOverlay provides a highly configurable interface which allows complete control of functionality without the necessity of modifying code. Configuring your distribution of OpenOverlay is a two-step process. Defining an OpenOverlay Configuration File OpenOverlay applies overlays specified by a configuration file. The name of the configuration file may be set in the openoverlay-spring-config.xml file. In this file, there is a bean definition identified by the name overlayConfig. The value of the first

Technology Services Group, Inc. - All Rights Reserved

Page 5 of 14

OpenOverlay Getting Started Guide constructor-arg element defines the name of the configuration file that OpenOverlay will use when executed.
<bean id="overlayConfig" class="com.tsgrp.openoverlay.core.XmlConfigFactory" factory-method="createInstance"> <constructor-arg value="overlay-config-jnj.xml" /> <constructor-arg value="default" /> </bean>

Figure 1.1 openoverlay-spring-config.xml bean which defines which configuration file to use

Creating an OpenOverlay Configuration File After the name of the configuration file has been set in step one, you are ready to create an OpenOverlay configuration file. In your OpenOverlay installation directory, create a file with the name specified in the previous step. OpenOverlay configuration files must be well-formed XML. This file defines templates, overlays, restrictions, actions and elements in order to construct PDF overlays and watermarks. Further details regarding the format and construction of configuration files may be found in the OpenOverlay Configuration File section of this guide.
<overlay-config> <text-templates> <text-template name="default"> <text font-size="12" font-family="arial" font-weight="none" font- style="none" color="black"> default text.</text> </text-template> <text-template name="date"> <text color="gray">Reference Copy - Printed on ${date} (EST)</text> </text-template> </text-templates> <overlay id="LetterLegalPortaitFooter"> <restrictions> <restriction key="page.size" value="letter|legal" /> <restriction key="page.orientation" value="portrait" /> </restrictions> <actions /> <block id="1" x="10" y="24" rotation="0" alignment="left" background-color="white" opacity="1"> <rectangle x-offset="592.8" y-offset="778.8" background-color="white" border-width="0.5" /> </block> <block id="2" x="308.4" y="204" rotation="0" alignment="center"> <text template="date" color="white" font-size="26">Watermark</text> </block> <block id="0" x="124.80" y="241.2" rotation="0" alignment="left"> <image file="images/logo.jpg" /> </block> </overlay> </overlay-config>

Figure 1.2 Example of a simple OpenOverlay Configuration File

The OpenOverlay Configuration File

OpenOverlay uses streamlined settings to define overlays to apply. Understanding the configuration file is the best way to explore the functionality that OpenOverlay presents to users. A valid configuration file is comprised up of valid XML with several constraints.

Technology Services Group, Inc. - All Rights Reserved

Page 6 of 14

OpenOverlay Getting Started Guide Components of OpenOverlay Configuration File

<overlay-config>
Parent Element: Number of occurrences: Attributes: Description: None; this is the root element. 1 None This is the documents root element. All other elements are descendents of this element.

<text-templates>
Parent Element: Number of occurrences: Attributes: Description: <overlay-config> 1 None This element acts as a container for all of the files text templates.

<text-template>
Parent Element: Number of occurrences: Attributes: <text-templates> [1 unlimited] name - required - defines the name of this template Each of these elements describes a template, which can be referenced from the rest of the configuration file. Each one has one child element, named <text>. Each file must contain one <text-template> element named default.

Description:

<text>
Parent Element: Number of occurrences: Attributes: <text-template> 1 per <text-template> element color - optional - defines the default font color of elements referencing this template font-family - optional - defines the default font family of elements referencing this template font-size - optional - defines the default font size of elements referencing this template font-style - optional - defines the default font style of elements referencing this template font-weight - optional Page 7 of 14

Technology Services Group, Inc. - All Rights Reserved

OpenOverlay Getting Started Guide defines the default font weight of elements referencing this template Defines the default text content of elements referencing this template. This is the documents root element. All other elements are descendents of this element.

Text Content:

Description:

<overlay>
Parent Element: Number of occurrences: Attributes: <overlay-config> [0unlimited] id - required - defines a unique name to identify this overlay with Each <overlay> element represents a distinct overlay which may be applied to a document. When multiple overlays are applied to the same page in a document, they are applied in the order which they appear in the configuration file.

Description:

<restrictions>
Parent Element: Number of occurrences: Attributes: Description: <overlay> 1 per <overlay> element None This is a container for overlay-specific restrictions.

<restriction>
Parent Element: Number of occurrences: Attributes: <restrictions> [0unlimited] key - required - defines a restriction key to use for this overlay - see CHART 1.1 for valid values value - required - defines a restriction value to use for the corresponding key - see CHART 1.1 for valid values Each <restriction> element represents a restriction to be used when applying this overlay to a document. This allows users to specify this overlay to only be applied to pages in a document that exhibit certain traits (page size, orientation, etc).

Description:

<actions>
Parent Element: Number of occurrences: <overlay> 1 per <overlay> element Page 8 of 14

Technology Services Group, Inc. - All Rights Reserved

OpenOverlay Getting Started Guide Attributes: Description: Note: None This is a container for overlay-specific actions. Actions are not currently implemented.

<action>
Parent Element: Number of occurrences: Attributes: <actions> [0unlimited] value - required - defines an action value - see CHART 1.1 for valid values Each <action> element represents an action to be used when applying this overlay to a document. This allows users to specify this overlay the PDF to be locked, etc. Actions are not currently implemented.

Description:

Note:

<block>
Parent Element: Number of occurrences: Attributes: <overlay> [0unlimited] x - required - represents the horizontal position of the lefthand side of the element, in points from the left hand side of a page y - required - represents the vertical position of the bottom of the element, in points from the bottom of a page alignment - defines the alignment of the element - valid for <text> elements only - if not defined, defaults to left - if value is left, the x attribute value corresponds to the position of the left-hand side of the element - if value is center, the x attribute value defines the center horizontal position of the element - if value is right, the x attribute value defines the position of right-hand side of the element rotation - optional - represents the amount, in degrees, the element is rotated counter-clockwise about its bottom left corner

Technology Services Group, Inc. - All Rights Reserved

Page 9 of 14

OpenOverlay Getting Started Guide only valid for <text> and <image> element types

Description:

opacity - optional - represents the opacity of the element - must be a value between 0 (transparent) and 1 (fully opaque), inclusive Each <block> element represents a screen feature contained in the overlay. Currently supports element types of text, rectangles and images. Each <block> element may have one child element, either <text>, <rectangle>, or <image>.

<text>
Parent Element: Number of occurrences: Attributes: <block> maximum of 1 per <block> element template - optional - defines the name of a template to use - value must match the name of a <texttemplate> element - if not defined, or not a valid value, the <texttemplate> element default is used color - optional - defines the font color of this element font-family - optional - defines the font family of this element font-size - optional - defines the font size of this element font-style - optional - defines the font style of this element font-weight - optional - defines the font weight of this element Defines the text content of this element. This represents a textual element on an overlay. Use these elements to overlay text onto an existing document, or to create a watermark.

Text Content: Description:

<rectangle>
Parent Element: Number of occurrences: Attributes: <block> maximum of 1 per <block> element x-offset - required - defines the width of the element, in points y-offset - required - defines the height of the element, in points Page 10 of 14

Technology Services Group, Inc. - All Rights Reserved

OpenOverlay Getting Started Guide background-color - optional - defines the color of the rectangle - if not defined, defaults to white border-width - optional - defines the width of the elements border - if not defined, defaults to 0 This represents a rectangle element on an overlay. Use these elements to cover existing text on a document, or as a background to make text elements more readable.

Description:

<image>
Parent Element: Number of occurrences: Attributes: <block> maximum of 1 per <block> element file - required - defines a path to an image file This represents an image element on an overlay. Use these elements to add the specified image file to the overlay.

Description:

<barcode>
Parent Element: Number of occurrences: Attributes: <block> maximum of 1 per <block> element type - optional - defines the type of iText supported barcode that will be produced. - valid values: 39 128 EAN Inter25 Postnet Codabar - default value is 128. format - optional - defines the formatting of the barcode that will be produced. - if formatting and type are not compatible, barcode will not be generated. - default formatting will be used if not specified. This represents a barcode element. iText can generate several different kinds of barcodes. There are restrictions on values, types and formats which are evaluated at runtime. If there are incompatibilities, the barcode is not generated. For more information, Page 11 of 14

Description:

Technology Services Group, Inc. - All Rights Reserved

OpenOverlay Getting Started Guide please see the iText documentation.

<pdf>
Parent Element: Number of occurrences: Attributes: <block> maximum of 1 per <block> element file - required - defines a path to a pdf file This represents a PDF file element, which will be appended on top of the input PDF. All elements from this PDF will be added to pages in the document that utilize an overlay with a pdf node element.

Description:

Running OpenOverlay from the Command Line

Command Line Statement Format OpenOverlay may be invoked from the command shell using this instruction while in your installation directory.
java com.tsgrp.openoverlay.FileSystemOverlayer [input][output][tokens][values]

With the following parameters defined: a. b. c. d. [input] specifies the path and name of a PDF file to overlay. [output] specifies the path and name of the PDF file to be generated. [tokens] a comma delimited list of token names [values] a comma delimited list of token values (order must correspond to the [tokens] parameter)

The input and output parameters gives users flexibility on which file OpenOverlay will overlay, and how it will be saved to your machine. The token list and value list allow the user to specify values for restriction keys and define text token values located in the configuration file.

Using Tokens with OpenOverlay

The following tokens are automatically generated and may be used in text elements and restrictions without definition in the command line: a. currentPage The number of the current page in a document b. totalPages The total number of pages in a document c. page.orientation The orientation of the current page in a document; either landscape or portrait d. page.size The size of the current page in a document; either Letter, Legal, or Executive The values of these tokens may not be overridden from the command line.

Technology Services Group, Inc. - All Rights Reserved

Page 12 of 14

OpenOverlay Getting Started Guide When a configuration file contains multiple tokens, the lists of tokens and values must be delimited by commas, and all items containing spaces must be encapsulated within quotation marks. Tokens as Definable Text Tokens may be used in configuration files as placeholders for text to be defined at runtime. Text elements and text-template elements may include tokens in the following manner: ${token} If this token is defined at runtime, the text is resolved and replaced by the corresponding value. For example, if the following element were present in the utilized overlay configuration file,
<block id="2" x="308.4" y="204" rotation="0" alignment="center"> <text template="default" color="white" font-size="26">${token}</text> </block>

Figure 1.2 Example of a text element utilizing a token and this command was used to run OpenOverlay,
java com.tsgrp.openoverlay.FileSystemOverlayer in.pdf out.pdf token Hello

then, the text element will contain the word Hello. If a text element contains one or more tokens which are not defined by the command line instruction, that element will not be used in the overlay. Tokens as Restriction Properties In addition to resolving text placeholders, token name/value pairs may be used to determine the validity of overlay restrictions. Restrictions are overlay-specific elements defined as key/value pairs in the configuration file.
<restrictions> <restriction key="page.size" value="letter|legal" /> <restriction key="currentPage" value="1.*" /> <restriction key="customToken" value="Approved" /> </restrictions>

Figure 1.3 Example of restrictions using custom and automatically generated tokens. Restriction key attributes correspond to token names. Restriction value attributes are regular-expressions corresponding to token values. An overlay containing the above restrictions node would only be applied to letter or legal sized pages whose page numbers start with a 1 and when customToken is defined as Approved. Multiple restrictions are AND-ed together, thus they must all pass in order for an overlay to be applied to the page. This means that in the above example, the token Technology Services Group, Inc. - All Rights Reserved Page 13 of 14

OpenOverlay Getting Started Guide customToken must be defined as Approved at runtime in order for this overlay to have a chance of passing all restrictions. If it is not defined, or defined as something else, the overlay will not be applied to any pages in a document. The other tokens are automatically generated by OpenOverlay at runtime.

Technology Services Group, Inc. - All Rights Reserved

Page 14 of 14