Archive for April, 2011

Support for unicode characters on Zebra Labels

In ES2, Livecycle introduced support for arbitrary unicode characters in Zebra Labels. Prior to this only latin-I charset was supported. Though there was support for Asian encoding like GBK(Simplified Chinese), Shift-JIS (Japanese), BIG-5 (Traditional Chinese) and KSC-5601 (Korean) but generic unicode support was missing.

Another pain was LC didn’t allow any font that is not present on the printer, to be specified in the label. This combined with above became a real problem with the middle east customers. The problem with Zebra is one cannot embed fonts inside the document like Postscript as downloading fonts on the printer is awfully slow. So the only option we left with is to rasterize the text and represent it as an image in the generated label. This way, the form author can get what he sees on the screen in pdf or in designer. Even with this approach, we felt that there is considerable file size bloating even after compressing the images of the document. Since XTG was rasterizing all the text present in the font other than the printer, which was not necessary sometime. For example, if the text is specified in english in Arial font, the end user might want to substitute it with the font present on the printer. In fact this is what we used to do before this change.

An option in XDC file is used to map to a font which is to be rasterized. The general font mapping sequence that is allowed in XTG needs both from and to font and along with it one can specify which unicodeRange to target. But here, the form author might not know before hand what data is going to be merged with the form. For example, there can be multiple textfields in the form with different fonts specified. The data to be merged in the form may contain non-english characters for some of the textfield. If the end user wants to map the form font into printer font, she has to specify that many mapping in the config file. So to ease the effort on the end user side, we exposed this option in xdc file where one needs to specify only to font and unicodeRange. This is a shortcut to the existing font mapping sequence.



            <!-- ========================================== -->
            <!-- Raster Substitution Font                     -->
            <!-- ========================================== -->

            <rasterSubstitutionFont typeface="CG Triumvirate_Normal_Normal" unicodeRange="U+20-U+FF"/>

The above entry is shortcut to the following config option:

   <map from="FONT_TO_BE_RASTERED" to="CG Triumvirate_Normal_Normal" unicodeRange="U+20-U+FF"/>

Here the printer driver for Zebra printer in XTG determines which font is going to be rasterized and based on that map that font to the specified rasterSubstitutionFont present in the xdc file.

There can be multiple rasterSubstitutionFont in the XDC file for different unicodeRange just like the font substitution entry.

Create Bookmarks in XFA Forms

There is a growing demand from our customers to extend the bookmark capability of pdf documents to XFA also. In LiveCycle Server ES3, we are introducing the support for authoring bookmarks in XFA Forms. It is also available in LiveCycle Server ES2.5 via a patch.  This post will show how one can author bookmark in an XFA form and also how the final pdf does look like.


You can define bookmarks at any of the XFA containers like subform, field or area.

The XFA processor starts processing bookmarks based on the following markup definition, under any of the valid container
elements. You can also specify multiple bookmarks for the same container. However, since only one extras tag is allow under any container markup, one can always wrap multiple extras tags inside another extras tag. LiveCycle supports up to two level of nesting for extras tags.

<subform> <!-- Any container element like subform, field or area-->
	<extras name="bookmark">
		<text name="name">ANY_NAME</text>
		<text name="color">0,0,0|R,G,B</text>
		<text name="style">normal | italic | bold | bold-italic</text>
		<text name="action">gotoPage | setFocus | runScript</text>
		<text name="script">ANY_FORM_LEVEL_SCRIPT</text> <!-- Javascript only. No formcalc support -->

Here is the description for various mark up parameters (Table below).
parameter description
name The name of the bookmark that will appear in the bookmark pane. If it is not specified, the bookmark will not be generated.
color The color in which the bookmark name is rendered. The color parameter should be indicated in the RGB scheme. For example, to insert a bookmark in red color, this parameter should be specified as 255,0,0. The default value for the color parameter is 0,0,0 (black).
style The style in which the bookmark name is rendered. The default value of the style parameter is none. Other values can be bold, italic, or bold-italic.
action The action that is performed when the bookmark is clicked, Values that can be used for the action parameter are: 

  • gotoPage: This is the default value. Focus is shifted to the page where the parent subform starts.
  • setFocus: Can be used when the parent container is a field. Sets the parent field in focus.
  • runScript: Triggers JavaScripts to be run. (This value is ignored in PDF/A documents)
script Relevant, when the value of the action parameter is set to runScript. Supports only JavaScript, that contains script objects present in the document scope.


To author bookmarks in XFA forms:

1) You can use the attached Designer macro. The macro has been written for Designer versions ES2 or later. For more information, see the blog on Design macros.

2) Download the bookmark macro from collateral.

When you invoke the macro, a dialog box  (as shown above) is displayed. In the dialog box, specify all the bookmark  parameter values.


Document generation

Once a bookmark has been authored, generate the PDF document. The bookmarks generated are available in dynamic and static documents. Bookmarks are compatible with Reader 9.0 and 10.0. You can use bookmarks in any XFA version document.

The bookmark will be generated in the same hierarchy as it is defined in the XFA Form design.

<subform name="root">
    <extras name="bookmark">
		<text name="name">parent1</text>
   <subform name="level1">
		<extras name="bookmark">
			<text name="name">child1</text>

		<subform name="level2">
			<extras name="bookmark">
				<text name="name">grand1</text>


   <subform name="level1">
		<subform name="level2">
			<extras name="bookmark">
				<text name="name">grand2</text>



For example, for the above form design, the bookmarks will be generated in the following hierarchy:




  1. To ensure compatibility with existing Reader versions, some capabilities are limited.
  2. For security reasons, a user can change the value of any bookmark element/parameter except action and script.
  3. For dynamic forms, you cannot make changes using the script – LiveCycle Server will always generate bookmarks based on what user has specified in the template. For example, assume that a form contains a select-one-subform type subformset, and the author has defined bookmarks for all the subforms of the subformset. In such a scenario, for dynamic PDF documents, LiveCycle Server will generate bookmarks for all subforms, and for static PDF documents, LiveCycle Server will generate one bookmark, depending on which subform gets selected based on user input.
  4. Bookmarks defined for XFA containers which form master page content are ignored
  5. Bookmarks specified on containers other than subform, area, field, and draw objects are not supported, and may result in unpredictable behavior.
  6. Bookmarks with value runScript for the action parameter/element are disabled, if the rendered PDF is archived.
  7. If an interactive form with bookmark is flattened using LiveCycle Output Service, it will not retain the bookmarks that somebody has inserted after the generation of PDF using Acrobat or Assembler.












Simplifying the Input tray set-up

We have observed and also received feedbacks from the users (whoever dared to do it) that setting up input trays has been quite a complex task. After designing the form, one needs to add the medium names used in the form to the xdc file
This blog post aims at simplifying this task and also clarify the steps that one needs to follow in order to set-up the input trays.

Input tray selection.

Basically, the input tray set-up problem can be defined as selection of paper from different input trays of the printer while printing the document. Without loss of generality, let’s take up the case of selection of two different trays (T1 and T2) for a template which has two different master pages (M1 and M2) and the user wants to select paper from tray T1 for master page M1 and similarly for master page M2, the user wants to select paper from tray T2.
We can categorize this requirement into two main sub-categories based on the paper sizes used in the master page. Before going ahead, I should mention that master page is basically a logical page which serves as a template for a set of pages in the xdp. The designer user can specify the page properties like page size at the master page level.

M1 and M2 represent two different page sizes.

In this case,

  1. Make sure that the medium name used in M1 and M2 is present in the printer xdc file.
  2. Configure printer trays T1 and T2 for paper sizes of M1 and M2 respectively.

M1 and M2 represent same paper size.

This is a bit tricky case and one has to make a heck of changes in printer XDC file. The sequence of steps can be as following:

  1. Add the mediums present in M1 and M2 to printer xdc file. To do this one may need the following information.

medium name (copy from template), short edge size, long edge size and in case of PCL one also need to give pcl sequence for this medium.

Please note that one has copy the medium names from template as the designer shows different UI name for any medium. For example it shows “Letter Plain” for “letterPlain” medium.

  1. Specify the tray sequences for T1 and T2 to map it to corresponding mediums M1 and M2. Please note that one has to specify tray sequence for a tray every single time whenever one maps a medium to this tray. This is because the UI table representing xdc schema is not properly normalized.

Basic Idea

One would have realized that input tray set-up is not an easy task esp. for second category use cases. There are lot of duplicate information one asks from user that can be easily determined from previous values given in the xdc file. And also there is no sync between the UI strings shown by designer and XDC Editor.

Separate Medium and Input Tray tables

Currently the medium table allows one to add and modify both mediums and the input trays they are mapped to. This table will be separated into two tables for medium and input trays. By giving a separate table to input trays, redundancy in input tray data can be avoided and better visibility is given to the user into what input trays are available.

Add a separate mapping tale

The mapping information is currently embedding in the medium table. Once medium and input tray tables are separated, a mapping table can better manage the mapping of mediums to trays.

Changes in UI

  • The tab page ‘Medium and Trays’ will be split into two pages, ‘Trays’ and ‘Mediums’, in order of appearance.
  • ‘Trays’ page will have the Input, Output trays specifications and input-tray-medium mapping tables. User will mostly be dealing with ‘Trays’ page.
  • ‘Mediums’ page will only have a Medium table with buttons to add/modify/delete mediums. Mediums page will be the last page as user will add/delete mediums rarely.
  • Sample screenshots are shown below.

Input Trays table

The current input trays table is merged with the medium table and looks like as follows:

The new input tray table will not have any mention of medium, and will look like as follows:

Please note that ‘Tray type’ column will be shown only for Postscript.

All columns in the table have unique values individually. An input tray cannot share its tray name, number or type with another input tray.

Addition of a new tray

Addition of new input tray is separated from adding a new medium. The new dialog looks like:

Medium table

The current medium table is the same as the current input trays table, and shown above .
The new medium table will be moved to its own ‘Mediums’ page. A sample screenshot follows:

The ‘PCL Sequence’ column will be shown only for PCL printers.
The Stock name in Medium table will be unique. Rest of the columns may not have unique values.

Addition of new medium

The current ‘add new medium’ dialog mixes adding a new medium with adding a input tray and input-tray-medium mapping. It looks like as follows,

The new ‘Add new medium’ dialog looks like,

Input tray and medium mappings table

This is a new table proposed to be located in ‘Trays’ page.

Modification of a mapping after addition is not intuitive, so user will have to remove and then re-add a mapping to modify its medium or input tray.
The medium name column will have unique values.

Specify a new medium mapping

‘Map medium to tray’ is a new dialog.

The medium and input tray will be available as drop downs. Mediums already mapped to a tray will not be available.

Document Printing Using Adobe LiveCycle Output

Adobe LiveCycle Output generates printer ready document in various formats like ps, pcl etc from a form design (xdp) or pdf. The form design here refers to the combination of a template and the data associated with it. These printer ready documents can be directly streamed to the printer for printing. I will start start with the types of printers first and then examine the Output API to access them.

Printers can be broadly classified into two categories based on the way to access them.

Directly accessible printer

If a printer is installed on the same machine from where it is being accessed (means on the same machine where LiveCycle is installed), it is called directly accessible printer and the machine is called printer host (or print server) machine. These type of printers can be a local printer connected to the machine directly or a remote network printer installed on that machine.

Indirectly Accessible Printer

Now-a-days, there are technologies like LPR/LPD, CUPS etc. available to obviate the need of the printer being installed on the same machine, to use that.
In this model, the printer installed on a machine (print server) is accessed from another machine. This is called indirect access. In this type of access we need to know the print server IP or hostname and the printer’s name.

One Solution to all problem

LC Output has following single API to access all kinds of printers. The user needs to pass the access mechanism, described later in this blog in the API.

void sendToPrinter(Document document, Enum accessMechanism, String printServerUri, String printerName)

where document being the document to be printed, printerName being the printer on which the document to be printed, printServerUri being the print server on which the printerName is installed and accessMechanism being the method to use to direct the document on the printerName.

The LPD service might be listening to the ports different than the standard ports. In that case the caller needs to pass the ip address and port number in x.x.x.x:portNo format.

Enumeration Description
This is used for direct access of the printer. In this case, the user needs to specify only the printerName, The printServerUri argument will be ignored in this case.
LPD If specified, LC will use indirect method to access the printerName via the printServerUri using LPR/LPD technology.
CUPS If specified, LC will use indirect method to access the printServerUri using IPP 1.1 technology.
If specified, LC will use the direct ip mechanism to access the printServerUri. The printerName argument, in this case, will be ignored by the API.


The following table describes the expected results in case of each accessMechanism that the user can expect:

accessMechanism value of sPrintServerUri value of sPrinterName Expected result
Any null Exception : Required Argument sPrinterName cannot be null
Any Invalid Exception : Printer not found
Any Valid Printed Output
LPD null Any Exception : Required Argument sPrintServerUri cannot be null
LPD Invalid null Exception : Required Argument sPrinterName cannot be null
LPD Invalid non-null Exception : sPrintServerUri not found
LPD Valid Invalid Exception : Printer Not Found
LPD Valid Valid Printed Output
CUPS null Any Exception : Required Argument sPrintServerUri cannot be null
CUPS Invalid Any Exception : Printer Not Found
CUPS Valid Any Printed Output
null Any Exception : Required Argument sPrintServerUri cannot be null
Invalid Any Exception : Printer Not Found
Valid Any Printed Output

The sPrintServerUri parameter, in case of CUPS will be something like http://<server>:<port>/<path>/<printerName>. If the user wants to use a port other than the default port in case of LPD and DirectIP, he can pass <server>:<port> in the sPrintServerUri argument. Here <port> is strictly a positive integer and <server> is either a valid IP address or a valid hostname. If one passes anything other than the integer in place of <port>, one will get Malformed URI exception.

Set up output trays for LC Output

Long time back I have posted a blog on how to select paper from various input trays of the printer while printing an XFA form using LC Output. This post is to describe how to specify an output bin/tray on the printer where all the printed papers should go after printing. There can be multiple bins in the printer for various functionality like staple/binding etc. And the user might want to use one of them after printing the document.

There are two steps to enable selection of output trays in LC Output service. You need XDC Editor or you can do manual editing of xdc files to add the various output trays present on your target printer. And then while generating a print document, you need to specify the output tray you want in the xci or configuration file. I’ll describe these steps in detail in the following sections.

Output Trays in XDC Editor

When you open any file in XDC Editor, in the top right corner there is a table which lists the output trays of the target printer.

Output Tray Table

Here the first column “Output Tray Name” will show any meaningful name that the user has specified while adding the output tray. This value can be anything as this is for the user to identify the trays and not used in processing the document. The second column “Tray Bin” is an id which is used by the print driver to identify the tray while generating the print document. This id is used in xci/configuration file to hint the print driver what output tray should it select.

And the third column “Tray Number” is the actual device command that is to be specified in order to select this tray. This command can be found in the printer manual and can be different for PS and PCL.

Please test the tray number commands using a test print before

Adding a new output tray

When you click on the “Add” button of Output tray table, you will get the following dialog box. You can specify the three entries in the text field as described above.

Specify Output tray in XCI file.

There is a <outputBin> element in XCI file under <ps> and <pcl> section. You can specify the “id” of the tray i.e. the entry of the second column to select that particular tray. Here is the example XCI snippet.


jCIFS printing


LiveCycle Output service has a capability to print on a network printer using CIFS protocol. This protocol requires user credential to access that printer. The API doesn’t take those credentials (username and password) as an parameter due to security reasons. Instead this API uses the existing LiveCyle infrastructure named TrustStore to store user credentials.

It would be a tedious task to store user credentials for each printer that the LiveCycle application is going to use as there can be thousands of printers. And to make matter worse, the set of printers might be changing dynamically. This tech note caters such use cases by defining syntax and some limited set of rules to match printers against the user credentials.

Detailed Description

The sendToPrinter API described in my earlier post have been enhanced to support CIFS protocol also.

void sendToPrinter(Document document, Enum accessMechanism, String printServerUri, String printerName)

You need to choose jCIFS as accessMechanism to trigger print using this protocol. printerName parameter is not used by this API. You need to just pass the valid document and printServerUri to use this API. As mentioned in the introduction, you can specify credentials in TrustStore like the following:

TrustStore simplified

Describing the various functionalities of the TrustStore is beyond the scope of this document. One can refer to LiveCycle documents for that. I just aim to describe the functioning of TrustStore from Output Service point of view.
TrustStore stores user name and password against an alias. So one can think of TrustStore as a map where keys are aliases and the values are user credentials.
One entry in TrustStore looks like the following:

alias domain\username password

Need for defining syntax of the TrustStore alias

In order to print a document on a printer, we need user credentials and one can get user credentials from TrustStore map only if we know the alias. So there is a definite need to establish mapping between printer uri and an alias so that one can guess the possible aliases for lookup based on the printer uri.

Rules/Priorities for aliases

The generic printer uri looks like following:


We’ll lookup the various possible aliases in following order:

1. \\\printer
2. \\
3. \\
4. \\
5. \\com
6. \\

As soon as we find match in the TrustStore map, we stop looking further. One cannot store multiple credentials against same alias as alias serves as key in the TrustStore map.