March 2009
bc
The technical content in this guide has not
changed since version 5.6 of the product.
All “New” and “Updated” references were
added for the 5.6 release.
Adobe® Central Output Server
Version 5.7
XML Import Agent Reference
XML Import Agent Reference
Edition 2.1, March 2009
© 2009 Adobe Systems Incorporated
All rights reserved.
As of April 12, 2002, Accelio Corporation (formerly JetForm Corporation) was purchased by Adobe Systems Incorporated. As of that
date, any reference to JetForm or Accelio shall be deemed to refer to Adobe Systems Incorporated.
Technical information contained herein is subject to change without notice.
The use and copying of this product are subject to a license agreement. Any other use is prohibited. No part of this publication may
be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form by any means without
the prior written consent of Adobe Systems Incorporated. Information in this publication is subject to change without notice and does
not represent a commitment on the part of the vendor. Any reference to company names, persons, or data in this documentation is
for demonstration purposes only and is not intended to refer to any actual organization, person, or data.
Adobe Systems Incorporated does not warrant that XML Import Agent will function properly in every hardware/software environment.
Trademarks
Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or
other countries.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other
countries.
Sun and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd.
All other product names are trademarks or registered trademarks of their respective trademark holders.
Contents
1
Overview............................................................................................................ 5
About XML Import Agent ...................................................................................................5
Who Should Read This Guide? .........................................................................................5
Processing XML Data........................................................................................................6
Other Resources ...............................................................................................................6
About This Guide...............................................................................................................6
2
Installation and Configuration ......................................................................... 7
Installing and Configuring XML Import Agent ....................................................................7
Creating or Modifying Configuration Files .........................................................................8
Configuration File Elements ........................................................................................8
Environment Variables .................................................................................................... 11
3
Processing Options ........................................................................................ 12
Specifying Options........................................................................................................... 12
Generating a Response File ..................................................................................... 14
Producing Log Information ........................................................................................ 14
Log File Output ................................................................................................... 15
Log File Name and Location............................................................................... 15
Log File Mode..................................................................................................... 18
Multiple Logs ...................................................................................................... 18
Unrecognized Options............................................................................................... 20
Specifying the Input File............................................................................................ 23
Specifying the Output File ......................................................................................... 24
Assigning the Job Name ........................................................................................... 24
Assigning Other Job Options .................................................................................... 26
Printer Name ...................................................................................................... 26
Copies ................................................................................................................ 26
Legacy Parameters ............................................................................................ 27
Specifying the Document Range............................................................................... 27
Nominating the Start Element............................................................................. 27
Excluding Namespaces ...................................................................................... 29
Nominating Records ........................................................................................... 31
Incremental Loading.................................................................................................. 35
Using an XSLT Stylesheet ........................................................................................ 38
Verifying XSL Transformations........................................................................... 39
Adobe Central Output Server
XML Import Agent Reference
3
Contents
4
Processing Options (Continued)
Specifying Options (Continued)
Generating End Group Commands........................................................................... 39
Assigning the Group Prefix ....................................................................................... 41
Start Group Prefix............................................................................................... 41
End Group Prefix ................................................................................................ 41
Suppressing Data Groups......................................................................................... 42
Specifying a Template Name .................................................................................... 43
Processing XML Attributes as Data Values ..............................................................44
Changing the Field Order..........................................................................................46
Setting Line and Paragraph Ends ............................................................................. 48
Specifying the Symbol Set (Code Page)................................................................... 49
Suppressing the Banner............................................................................................ 50
Index ................................................................................................................ 51
1
Overview
Today's Internet industry brings new and exciting implementations that add value to existing
solutions. Many organizations are already using Extensible Markup Language (XML) to
exchange data across the Internet. This data format is extensible and is one that organizations
can tailor to their business processes.
XML Forms Architecture (XFA) extends the value of XML by providing specific functionality for
customers who produce and use electronic forms. XFA is the Internet's first open
standards-based forms architecture that implements all aspects of process automation - the
capture, movement, processing, and presentment of information.
ABOUT XML IMPORT AGENT
XML Import Agent is an XFA-Data handling application that can translate any well-formed XML
data file into field-nominated format, for use with Adobe® Central Output Server (Central). This
translation enables you to create customer-focused documents such as invoices, statements,
and purchase orders that Central can present in a variety of formats using different delivery
channels.
Using XML Import Agent you can:
●
Control where processing begins on the XML data.
●
Control how much data is extracted.
●
Perform simple data transformations by authoring Extensible Stylesheet Language
Transformations (XSLT).
●
Convert XHTML 1.0 elements encountered in the XML data into Inline Text Control
commands for Print Agent, providing a means for expressing font changes and paragraph
formatting.
WHO SHOULD READ THIS GUIDE?
This guide supplements the Integrating XML with Central guide. We suggest that you read that
guide first. The scenarios in that guide will assist you in setting up your environment and
integrating your XML data with Central.
As you develop your applications, you will likely want to override the default settings for
processing XML data. For example, you may want to process only a portion of the XML data or
call an XSLT stylesheet to reorder XML data. This guide describes the syntax for the XML
Import Agent processing options that you can specify to do just that. There are also many
examples that illustrate the use of these options.
Adobe Central Output Server
XML Import Agent Reference
Overview
6
PROCESSING XML DATA
When XML Import Agent processes XML data, it performs two steps:
1. Loads the XML data into the XFA-Data Document Object Model (XFA-Data DOM). If an
XSLT stylesheet exists, applies XSL transformations as it loads the data into the XFA-Data
DOM.
2. Translates XFA-Data DOM objects into corresponding Dynamic Merge commands, resulting
in a field-nominated data file.
You may want to revisit the “Overview” chapter in the Integrating XML with Central guide for a
detailed description of each step.
OTHER RESOURCES
There are many resources available that are relevant to XML Import Agent:
●
The XFA-Data Handling Specification and the XFA-Data Text Handling Specification define
the rules that XML Import Agent uses to uses to load XML data into the XFA-Data DOM. You
can obtain these documents by contacting Customer Support.
●
The Integrating XML with Central guide provides an overview of XML support within Central.
It uses scenarios to describe how to integrate XML data with Central using either XML
Import Agent or Print Agent.
●
The Developing Templates guide for Adobe Output Designer contains instructions on how to
develop templates for use with Central.
●
The Working with Central guide describes how Central processes transaction files.
●
The Print Agent Reference guide provides a reference of the Dynamic Merge commands
used in this guide.
●
The Adobe Web site contains samples that illustrate the various features that XML Import
Agent provides. To access this site, go to www.adobe.com.
ABOUT THIS GUIDE
As well as the new features listed in the What’s New document, there are additional changes
throughout the guide. These symbols draw your attention to “new” and “updated” topics.
NE
UP
New - indicates a new topic in this guide.
W
TE
DA
D
Updated - indicates an updated topic in this guide.
In addition to the symbol, updated text within the topic is marked
with change bars, like the one to the left of this text.
2
Installation and Configuration
We suggest that you review the scenarios described in the Integrating XML with Central guide.
Each scenario uses a different configuration and contains a checklist to help you set up your
environment including Central and XML Import Agent. Then follow the instructions below to
install and configure XML Import Agent.
We mentioned in the “Overview” chapter that you can specify options to control how XML
Import Agent processes XML data. One way to specify options is in the XML Import Agent
default configuration file and in a user-defined configuration file. As you develop your
applications, you may want to update the default configuration file or create separate
configuration files tailored to each application, as described in this chapter.
INSTALLING AND CONFIGURING XML IMPORT AGENT
UP
TE
DA
D
Use the appropriate configuration checklist in the Integrating XML with Central guide as a
reference, to set up your environment. Each checklist points to the XML Import Agent
installation and configuration instructions below.
➤ To install and configure XML Import Agent
1. XML Import Agent is normally installed at the same time as Central. If XML Import Agent was
not selected for installation at the time of the Central installation, run the Central Setup
program again to select this item.
2. Central uses entries in the Job Management Database to determine how to process
transaction files. This database consists of several tables. The Setup program adds a default
entry for XML Import Agent, XMLIMPORT, in the Task Table. You may want to modify this
default entry and add or modify entries in the other Job Management Database tables.
You will find an example of the XML Import Agent default Task Table entry and examples of
other Job Management Database entries in the Integrating XML with Central guide.
3. On UNIX®, the LANG environment variable will be set automatically at installation to an
appropriate value for your operating system. (See “Environment Variables” on page 11.)
Depending on what code page your XML data needs, if the value set is not appropriate, you
will need to set the LANG variable to an appropriate value.
When XML data contains characters from more than one 8-bit character set, such as the
ISO 8859/Latin1… Latin15 family, you must run XML Import Agent in a UTF-8 locale. You
can use any UTF-8 locale, including en_US.UTF-8. For example, set the value of the LANG
variable (and the LC_ALL variable on Solaris 6, 7, and 8) to “en_US.UTF-8”.
Adobe Central Output Server
XML Import Agent Reference
Installation and Configuration
8
4. Set the processing options for XML Import Agent. For example, you will likely want to output
log information to the Central Log. You might also want to generate a response file that
Central will use to determine whether to place successful or unsuccessful transaction files in
the backup or error directory at runtime. There are processing options that allow you to do
these things.
You can specify processing options in an XML Import Agent configuration file, in the Task
Table of the Job Management Database, and within a processing instruction in the XML data
file. The complete listing of available options is included on page 9.
CREATING OR MODIFYING CONFIGURATION FILES
UP
TE
DA
D
When you run XML Import Agent, it looks for its default configuration file, xmlimport.xci. This
file is located, by default, in the Adobe\Central\Server directory (on Microsoft® Windows®) or
the adobe/central/etc directory (on UNIX). On Windows, you can access this configuration file
from the Configuration menu in Central Control.
The configuration file is in XML format and contains elements whose names correspond to
options described in the “Processing Options” chapter on page 12. Some of the elements are
initially empty. When left empty, XML Import Agent applies the default values for the options
when it processes an XML data file.
You can either modify the default configuration file or create any number of auxiliary
configuration files. The configuration files that you create must be structured in the same way
as the default configuration file and use the same element names. The element names and
associated values are case-sensitive. For these reasons, when you create your own
configuration files, it is best to use the default configuration file as a starting point. You may
want to create a copy of the default configuration file before proceeding with the updates.
The standard extension for XML configuration files is .xci. When you use a configuration file
with a file name other than xmlimport.xci, you must specify an option as described in the
“Configuration File” section on page 12.
Configuration File Elements
The configuration file is divided into several sections. The element <common id="COMMON">
contains elements that are common to all XFA-processing applications, such as XML Import
Agent. The element <xmlImport> contains elements that are specific to XML Import Agent.
XML Import Agent also supports a subset of the elements in the
<pa desc="presentationAgent"> and <tp desc="transactionProcessor">
sections. Some elements are reserved for use with other products, while other elements are
reserved for future use.
Adobe Central Output Server
XML Import Agent Reference
Installation and Configuration
The table below provides a cross-reference of each element that applies to XML Import Agent
and its corresponding opton. The table also includes a link to additional information on usage
and syntax:
XML Element
Option
See …
data.uri
page 23
data.xsl.uri
page 38
data.xsl.debug.uri
page 39
<flatten/>
data.flatten
page 42
<record/>
data.record
page 31
<excludeNS/>
data.excludeNS
page 29
<startNode/>
data.startNode
page 27
<attributes/>
data.attributes
page 44
<incrementalLoad/>
data.incrementalLoad
page 35
<to/>
log.to
page 15
<uri/>
log.uri
page 15
<mode/>
log.mode
page 18
<msgId/>
messaging.message.msgID
page 20
<severity/>
messaging.message.severity
page 20
<common id="COMMON">
<data>
<uri/>
<xsl>
<uri/>
<debug>
<uri/>
</debug>
</xsl>
</data>
<log>
</log>
<messaging>
<message>
</message>
</messaging>
</common>
9
Adobe Central Output Server
XML Import Agent Reference
XML Element
Installation and Configuration
Option
See …
<useFormCommand/>
useFormCommand
page 43
<order/>
order
page 46
<codepage/>
codepage
page 49
<suppressBanner/>
suppressBanner
page 50
<legacyParms/>
legacyParms
page 26
<useEndGroup/>
useEndGroup
page 39
<startGroupPrefix/>
startGroupPrefix
page 41
<endGroupPrefix/>
endGroupPrefix
page 41
<paragraphEnd/>
paragraphEnd
page 48
<lineEnd/>
lineEnd
page 48
rsp.uri
page 14
output.uri
page 24
pa.output.uri
page 26
pa.copies
page 26
tp.xpr.uri
page 24
<xmlImport>
<common use="#COMMON"/>
<rsp>
<uri/>
</rsp>
<output>
<uri/>
</output>
</xmlImport>
<pa desc="presentationAgent">
<output>
<uri/>
</output>
<copies/>
</pa>
<tp desc="transactionProcessor">
<xpr>
<uri/>
</xpr>
</tp>
Note: There are other ways to specify options, as described in the “Processing Options”
chapter on page 12.
10
Adobe Central Output Server
XML Import Agent Reference
Installation and Configuration
11
ENVIRONMENT VARIABLES
NE
W
On UNIX platforms, these environment variables are set automatically during installation:
Platform
Environment variable
When ...
Is set to ...
HP-UX
LANG
not defined or set to
“C” or “POSIX”
en_US.iso88591
AIX, Solaris,
Linux
LANG
not defined or set to
“C” or “POSIX”
en_US
All Unix/Linux
LANG
set to some other value
no change
Solaris 5.6+
LC_ALL
LANG is not defined or
set to “C” or “POSIX”
en_US
Solaris 5.6+
LC_ALL
LANG is set to some
other value
no change
All Unix/Linux
NLSPATH
not defined
adobe_exepath
All Unix/Linux
NLSPATH
some value is defined
adobe_exepath/%N:$NLSPATH
HP-UX
SHLIB_PATH
not defined
adobe_libpath
HP-UX
SHLIB_PATH
some value is defined
adobe_libpath:$SHLIB_PATH
AIX
LIBPATH
not defined
adobe_libpath
AIX
LIBPATH
some value is defined
adobe_libpath:$LIBPATH
Solaris, Linux
LD_LIBRARY_PATH
not defined
adobe_libpath
Solaris, Linux
LD_LIBRARY_PATH
some value is defined
adobe_libpath:$LD_LIBRARY_PATH
3
Processing Options
When XML Import Agent processes XML data, it uses a number of options to determine how to
process that data. The default behavior is described in the Integrating XML with Central guide.
This chapter describes the options that you can specify to override the default settings. These
options correspond to the extended rules defined in the XFA-Data Handling Specification.
Certain options described in this chapter do not impact the loading of XML data into the
XFA-Data DOM. For this reason, they do not have corresponding rules and are not described in
the XFA-Data Handling Specification. These options, however, impact the translation of XML
data.
You can also override the default settings by applying XFA-Data namespaced attributes to XML
data elements, as described in the Integrating XML with Central guide.
SPECIFYING OPTIONS
You can specify options in several ways:
●
In the default XML Import Agent configuration file
●
In a user-defined XML Import Agent configuration file
●
In the Task Table of the Job Management Database
●
In a processing instruction at the beginning of the source XML data file
The options are case-sensitive, which complies with the XML specification, and are processed
in the order specified above. For example, an option specified in the Task Table will replace the
same option specified in a user-defined configuration file and the default configuration file. This
does not apply to the log-related options. That is, XML Import Agent merges or overwrites the
log-related options depending on how and where you specify the option. You will find several
examples in the “Multiple Logs” section on page 18.
When it processes XML data, XML Import Agent merges the different options specified in the
default and user-defined configuration files, in the Task Table, and in a processing instruction.
Configuration File
Each option is case-sensitive and corresponds to an XML element in the XML Import Agent
configuration file. You can use the default configuration file or a user-defined configuration file,
or a combination of configuration files. XML Import Agent processes the default configuration
file, xmlimport.xci, then any specified user-defined configuration file.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
13
We recommend that you specify critical and constant options (such as generating a log file and
a response file) in the default or user-defined configuration file. Otherwise, if a fatal error occurs
as a result of an unrecognized option, it may be difficult to diagnose the cause of the problem in
the absence of a log file or response file.
The syntax for calling a user-defined configuration file is:
-config my_config_file.xci [options]
where:
-config tells XML Import Agent to look for a user-defined configuration file. This option is not
required when using only the default configuration file, because XML Import Agent always looks
for its default configuration file at runtime.
my_config_file.xci is the Uniform Resource Identifier (URI) or fully qualified path of the
user-defined configuration file. The example above demonstrates the use of a URI that is
relative to the location of the XML Import Agent executable. Since no path has been specified,
the configuration file my_config_file.xci must reside in the same directory as the XML Import
Agent executable or in the current working directory.
options are the options described in this chapter. You can also supply variations for certain
options (excludeNS, log.to, log.uri, and log.mode) by adding elements in the configuration
file. Examples are provided in this chapter.
Task Table
You can specify options in the Task Table of the Job Management Database. The options are
case-sensitive. The XFA-SOM expression for each option is described in this chapter.
For certain options (excludeNS, log.to, log.uri, and log.mode), it is also possible to supply
variations for the option by using an array-style syntax:
option1=value1 option1[2]=value2 option1[3]=value3
where:
option1 is the same option.
[2] and [3] are arrays. In this example, the syntax for option1=value1 is equivalent to
option1[1]=value1. Arrays start at 1.
You will find an example of this array-style syntax in the “Multiple Logs” section on page 18.
Processing Instruction
You can insert certain options within a processing instruction placed at the beginning of the
XML data file. The options are case-sensitive.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
14
The syntax of the processing instruction is:
<?xfa option1="value" option2="value" ...optionN="value"?>
where:
option1 through optionN are the options.
The names, acceptable values, and syntax for using options within a processing instruction are
described in this chapter.
Generating a Response File
When XML Import Agent processes an XML data file, it returns an exit status of “0” indicating a
successful completion, or “1” for an unsuccessful completion. XML Import Agent can record this
information in a response file named jetform.rsp. Central uses this response file at runtime to
determine whether to place the input data in its backup directory or error directory.
To generate a response file, use this option, which is case-sensitive:
●
Configuration file syntax:
<rsp><uri>jetform.rsp</uri></rsp>
●
Command line or Task Table syntax:
rsp.uri=jetform.rsp
where:
jetform.rsp is the name of the response file that Central looks for at runtime. The specified
location is the URI or fully qualified path that corresponds to the Central collector directory, by
default, c:\Program Files\Adobe\Central\Server\data (on Windows) or
/usr/local/adobe/central/server/data (on UNIX). The example above demonstrates the use of
a URI that corresponds to the current directory. That is, when running XML Import Agent, the
current directory is the collector directory.
Producing Log Information
You can create a log file to record each activity of XML Import Agent. This enables you to
diagnose and resolve problems that may occur when XML Import Agent processes XML data.
There are several options that you can set when generating a log file:
●
Log file output
●
Log file name and location
●
Log file mode
You can also direct the output of log information to different locations, as described in this
section.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
15
Log File Output
You can direct the output of log information to the console, to an area in memory, or to a log file.
To output log information, use this option, which is case-sensitive:
●
Configuration file syntax:
<log><to>stdout|uri|central|memory|null</to></log>
●
Task Table syntax:
log.to=stdout|uri|central|memory|null
where:
stdout writes log information to the console.
uri writes log information to the XML Import Agent Log. You specify the name and location of
XML Import Agent Log using the option log.uri described in the next section. You also specify
whether you want to overwrite or append the log information, using the option log.mode
described in the “Log File Mode” section on page 18.
central appends log information to the Central Log. This is the default value that the Central
Setup sets in the XML Import Agent default configuration file. You specify the name and
location of the Central Log using the option log.uri described in the next section.
memory writes log information to an area in memory. This value is reserved for use with future
products that will incorporate XML Import Agent technology. It causes logging to silently
accumulate in memory where it can be retrieved by a calling application.
null or when not specified, does not write log information. When specified, clears all log
settings. For example, when you specify log.to=null log.to=stdout in the Task Table,
XML Import Agent clears any settings for the log.to option included in the default configuration
file and any user-defined configuration file. It then writes log information to the console.
Log File Name and Location
When you specify uri or central for the log.to option described in the previous section,
you must also indicate the name and location of the log file.
To specify the name and location of the log file, use this option, which is case-sensitive:
●
Configuration file syntax:
<log><uri>log_file</uri></log>
●
Task Table syntax:
log.uri=log_file
where:
log_file is the URI or fully qualified path of the XML Import Agent Log or Central Log.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
16
XML Import Agent Log
To generate the XML Import Agent Log, specify the URI or fully qualified path of the log. Ensure
that you also specify uri for the log.to option described in the “Log File Output” section on
page 15.
When running XML Import Agent via Central, the current directory is the collector directory.
Therefore, when you specify the name of the XML Import Agent Log, ensure that you also
include a path.
The XML Import Agent Log consists of two XML files: an XML stub file that contains an entity
reference to an XML fragment file. This mechanism ensures that the log file information is
well-formed, in the event of an interruption in the writing of log information. To view the contents
of both files, open the XML stub file in your XML viewer.
When XML Import Agent generates log information, it assigns the specified file name to the
XML stub file. It appends an .ent extension to the file name of the XML fragment file, then saves
both XML files in the specified location.
XML Import Agent Log Example
This sample XML stub file, named xmlimport-log.xml, contains an entity reference to a second
XML fragment file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE log [
<!ENTITY logcontent SYSTEM "xmlimport-log.ent">
]>
<log>&logcontent;</log>
The entity declaration that XML Import Agent generates within the XML stub file references the
second XML fragment file. The file name of the XML fragment file is based on the file name
prefix of the XML stub file and uses the extension .ent.
The XML fragment file, xmlimport-log.ent, contains the detailed log information:
<message>
<msgId>29234</msgId>
<dateTime>2005-10-11T07:08:05.796-04:00</dateTime>
<severity>INFORMATION</severity>
<text>XMLImport Version 5.6.0.000 -- Copyright 1985 - 2005 Adobe
Systems Incorporated. All rights reserved.</text>
</message>
<message>
<msgId>29236</msgId>
<dateTime>2005-10-11T07:08:05.874-04:00</dateTime>
<severity>INFORMATION</severity>
<text>End of processing: Success</text>
</message>
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
17
In the XML fragment file, there are several <message> elements. The first <message> element
always contains information relevant to the version of the software.
Each <message> element contains these elements:
●
The element <msgId> contains the identification number of the message.
●
The element <dateTime> contains the date and time of the message. The format is in
accordance with the International Organization for Standardization (ISO) 8601 standard for
the representation of dates and times.
In the example above, the second element <message> contains the date and time value
2005-10-11T07:08:05.796-04:00, where:
2005-10-11 represents the century, month, and day.
T is a separator between the date and time.
07:08:05.796 represents the time, including the seconds and fractional seconds.
-04.00 represents the time zone designator expressed in number of hours ahead or behind
Coordinated Universal Time (UTC). In this example, the “-” (minus sign) indicates that the
local time zone is 4 hours behind UTC. A “+” (plus sign) would have indicated that the local
time zone was 5 hours ahead of UTC.
●
The element <severity> contains the value “INFORMATION”, “WARNING”, or
“FATAL_ERROR”.
●
The element <text> provides a description associated with the <severity> value
“INFORMATION”, indicating that the translation was successful or unsuccessful. When the
<severity> element contains the value “WARNING” or “FATAL_ERROR”, the element <text>
contains the warning or error message.
Central Log
When you specify central for the log.to option described in the “Log File Output” section on
page 15, you must also specify the path of the Central Log.
●
Configuration file example:
<log><uri>../server/jfserver.log</uri></log>
●
Task Table example:
log.uri=../server/jfserver.log
where:
jfserver.log is the name of the Central Log, which by default, resides in the Server
directory below the Central installation directory. The example above illustrates the use of a
relative URI. The Central Setup sets the appropriate path to the Central Log in the XML Import
Agent default configuration file.
You will find additional information on viewing and maintaining the Central Log in the Working
with Central guide.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
18
Log File Mode
When you specify memory or uri for the log.to option described in the “Log File Output”
section on page 15, you can either replace the contents of an existing XML Import Agent Log
file, or append the log information to that log file.
To append or overwrite the log information, use this option, which is case-sensitive:
●
Configuration file syntax:
<log><mode>append|overwrite</mode></log>
●
Task Table syntax:
log.mode=append|overwrite
where:
append or when not specified, adds the log information at the end of an existing XML Import
Agent Log file. This is the default setting.
overwrite replaces the contents of an existing XML Import Agent Log file.
Multiple Logs
You can direct the output of log information to the console, the XML Import Agent Log, and the
Central Log simultaneously. You can do this in several ways:
●
Add a separate <log> element for each type of log output in the XML Import Agent
configuration file.
●
Use an array-style syntax in the Task Table.
Configuration File Example
...
<log>
<to>stdout</to>
</log>
<log>
<to>uri</to>
<uri>../server/xmlimport-log.xml</uri>
<mode>append</mode>
</log>
<log>
<to>central</to>
<uri>../server/jfserver.log</uri>
</log>
...
where:
stdout outputs the log information to the console.
uri outputs the log information to the XML Import Agent Log.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
19
xmlimport-log.xml is the name of the XML Import Agent Log that is generated in the
specified directory.
append appends the log information to the XML Import Agent Log.
central appends the log information to the Central Log. For the Central Log, there is never a
<mode> element to indicate whether to append or overwrite the log information. That is
because the log.mode option only applies to the XML Import Agent Log. In other words, it is the
value “central” that indicates to append to the Central Log. There is no option to overwrite the
Central Log.
jfserver.log is the name of the Central Log, which by default, resides in the Server
directory below the Central installation directory. The example above uses a relative URI.
Task Table Example
You can use an array-style syntax in the Task Table. This example produces the same results
as in the previous example:
log.to=stdout log[2].to=uri log[2].uri=../server/xmlimport-log.xml
log[2].mode=append log[3].to=central
log[3].uri=../server/jfserver.log
In this example, the option log.to=stdout is equivalent to log[1].to=stdout.
Configuration File and Task Table Example
You can specify multiple log options in the Task Table, in the default configuration file, and in a
user-defined configuration file. XML Import Agent merges the log options defined in the default
and user-defined configuration files. However, when you specify log options in the Task Table,
XML Import Agent overwrites any like-named log options included in the default configuration
file.
For example, if the default configuration file contained this log entry:
...
<log>
<to>uri</to>
<uri>../server/xmlimport-log.xml</uri>
<mode>append</mode>
</log>
...
... and a user-defined configuration file contained this log entry:
...
<log>
<to>central</to>
<uri>../server/jfserver.log</uri>
</log>
...
... the XML Import Agent would merge the log entries specified in both configuration files and
write log information in the XML Import Agent Log and the Central Log.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
20
However, if you specified a third log entry in the Task Table:
log.to=stdout or log[1].to=stdout
... XML Import Agent would overwrite the log option defined in the default configuration file with
the option specified in the Task Table. This would result in two log settings for the log.to option:
log.to=stdout log[2].to=central log[2].uri=../server/jfserver.log
... which would write log information to the console and in the Central Log.
But if you specified the third log entry as:
log[3].to=stdout
... then XML Import Agent would not overwrite the log option in the default configuration file.
This would result in three log settings for the log.to option:
log.to=uri log.uri=../server/xmlimport-log.xml log.mode=append
log[2].to=central log[2].uri=../server/jfserver.log log[3].to=stdout
... which would write log information in the XML Import Agent Log, the Central Log, and to the
console.
But what if you wanted to output log information only to the console in this scenario? You could
then specify this option in the Task Table:
log.to=null log.to=stdout
XML Import Agent would first reset the log settings to null (which means do not output any log
information), then output log information to the console.
Unrecognized Options
In a typical Central environment, it is likely that you will want to process XML data files using
XML Import Agent and other Agents as part of a single job. As it processes an XML data file,
Central passes a union of all the options required for all Agents participating in the single job.
Each Agent ignores unknown options, because they are intended for another Agent.
You can control whether XML Import Agent continues or stops processing an XML data file
when it encounters an option that it does not recognize, that is, when the option is meant for
another Agent. You do this by specifying message-related options. These options also
determine the type of information to record in the XML Import Agent Log, if any, for an
unrecognized option.
XML Import Agent has two styles of options:
●
One style is referred to as an XFA-SOM expression. It uses the syntax name=value, where
name is the name of the option and value is the value to assign the option. For example,
the option log.to=stdout is an XFA-SOM expression that sets the option log.to to the value
“stdout”, which results in the writing of log information to the console.
●
Another style is referred to as an XFA Agent option. It uses the syntax -option value,
where -option is the name of the option and value is an optional argument. For
example, the option -config myConfigFile.xci instructs XML Import Agent to load the
configuration file myConfigFile.xci.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
21
To set the message-related options, use this syntax, which is case-sensitive:
●
Configuration file syntax:
<messaging>
<message>
<msgId>message-id</msgId>
<severity>message-severity</severity>
</message>
</messaging>
●
Task Table syntax:
messaging.message.msgID=message-id
messaging.message.severity=message-severity
where:
message-id contains the value 29195 (for an unrecognized XFA-SOM expression) or
29245 (for an unrecognized XFA Agent option).
message-severity contains one of these values:
●
INFORMATION or WARNING, which writes a message to the XML Import Agent Log. XML
Import Agent continues processing the XML data file. The <severity> element in the log
contains the value INFORMATION or WARNING. The associated <text> element contains
the information or warning message that identifies the unrecognized XFA-SOM expression
or XFA Agent option. The default setting in the XML Import Agent configuration file is
WARNING.
●
FATAL_ERROR, which writes a message to the XML Import Agent Log. XML Import Agent
performs any other requested termination processing such as generating a response file
(jetform.rsp), then stops processing the XML data file. The <severity> element in the log
contains the value FATAL_ERROR. The associated <text> element contains the error
message that identifies the unrecognized XFA-SOM expression or XFA Agent option. In the
absence of the <message> elements in the XML Import Agent configuration file,
FATAL_ERROR is the default setting.
●
IGNORE, which does not write a message to the XML Import Agent Log. XML Import Agent
ignores the unrecognized XFA-SOM expression or XFA Agent option and continues
processing the XML data file.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
22
Configuration File Example
This example illustrates the use of the message-related options in a configuration file:
...
<common id="COMMON">
<messaging>
<message>
<msgId>29195</msgId>
<severity>WARNING</severity>
</message>
<message>
<msgId>29245</msgId>
<severity>WARNING</severity>
</message>
</messaging>
...more configuration information here...
</common>
...
- or ...
<xmlImport>
<common use="#COMMON">
<messaging>
<message>
<msgId>29195</msgId>
<severity>WARNING</severity>
</message>
<message>
<msgId>29245</msgId>
<severity>WARNING</severity>
</message>
</messaging>
</common>
...more configuration information here...
</xmlImport>
...
When XML Import Agent writes a message to the log as a result of an unrecognized XFA-SOM
expression, the format of the message is:
<message>
<msgId>29195</msgId>
<dateTime>2005-10-11T07:08:05.874-04:00</dateTime>
<severity>WARNING</severity>
<text>Invalid attempt to add node (node)</text>
</message>
where:
node is replaced with the name portion of the unrecognized XFA-SOM expression of the style
“name=value”.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
23
When XML Import Agent writes a message to the log as a result of an unrecognized XFA Agent
option, the format of the message is:
<message>
<msgId>29245</msgId>
<dateTime>2005-10-11T07:08:05.874-04:00</dateTime>
<severity>WARNING</severity>
<text>Unrecognized command-line argument (argument)</text>
</message>
where:
argument is replaced with the option portion of the unrecognized XFA Agent option of the
style “-option value”.
Task Table Example
This example shows how you can overwrite the two message severity settings specified in the
default XML Import Agent configuration file:
messaging.message.severity=FATAL_ERROR
messaging.message[2].severity=FATAL_ERROR
where:
messaging.message.severity overwrites the first <severity> element and
messaging.message[2].severity overwrites the second <severity> element.
Specifying the Input File
The input file corresponds to the name of the XML data file that requires translation. To specify
the name of the input file, use this option, which is case-sensitive:
●
Configuration file syntax:
<data><uri>../server/data/my_xml.dat</uri></data>
●
Task Table syntax:
data.uri=../server/data/my_xml.dat
where:
my_xml.dat is the URI or fully qualified path of the XML data file. The examples above
demonstrate the use of relative URIs that correspond to the location of the Central collector
directory. In this example, Central is configured to scan for XML files with the extension .da?.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
24
Specifying the Output File
The output file corresponds to the name of the resulting field-nominated data file. To specify the
name of the output file, use this option, which is case-sensitive:
●
Configuration file syntax:
<output><uri>../server/data/output_file.tmp</uri></output>
●
Task Table syntax:
output.uri=../server/data/output_file.tmp
where:
output_file.tmp is the URI or fully qualified path of the field-nominated data file that XML
Import Agent creates when it completes the translation. The specified URI or path corresponds
to the location of the Central collector directory. The examples above demonstrate the use of a
relative URI.
Assigning the Job Name
The first line of any transaction file processed by Central typically contains a ^job command.
This command identifies the job name, as it appears in the Job Table of the Job Management
Database, and can also include other options necessary to process the transaction file.
XML Data
In your XML data files, you specify the ^job command in a processing instruction using the
syntax described on page 25. When Central picks-up the XML data file, it detects and retains
the ^job command in memory as it processes each job step. The first job step typically invokes
XML Import Agent to process the XML data and translate that data into field-nominated format.
Field-Nominated Data
When XML Import Agent processes the XML data, it does not automatically produce a ^job
command in the resulting field-nominated data. However, there may be instances when you
would want to generate a ^job command in the field-nominated data. For example, after
Central completes a job that uses XML Import Agent to process the XML data input file, you
might want Central to run a different job that uses the resulting field-nominated data as the input
file.
There are different ways in which you can cause the XML Import Agent to produce a ^job
command in the field-nominated data:
●
Using a <JF_JOB_CARD> element in the XML data file, as described below
●
Using the tp.xpr.uri option in an XML Import Agent configuration file or in the Task Table, as
described below
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
25
Syntax
The syntax for specifying the ^job command is:
●
Processing instruction syntax:
<?xml version="1.0"?><?jetform ^job jobname [-zprtname] [-axxtaskid]
[jobtokens]
?>
Note: When you specify a ^job command in a processing instruction, use the structure
illustrated in the example above. The ^job command must appear on the first line of the
XML data file. You must also position the closing tag “?>” on a separate line.
●
<JF_JOB_CARD> element syntax:
<JF_JOB_CARD>jobname [-zprtname] [-axxtaskid]
[jobtokens]</JF_JOB_CARD>
Note: When you specify the job name using the element <JF_JOB_CARD>, ensure that you
insert the element as a data value within a record (any record) in the document range.
The job name specified using the element <JF_JOB_CARD> in the XML data file will
replace the job name specified in any XML Import Agent configuration file or in the Task
Table.
●
Configuration file syntax:
<tp desc="transactionProcessor"><xpr><uri>jobname</uri>
</xpr></tp>
●
Task Table syntax:
tp.xpr.uri=jobname
where:
jobname is the name of the job, as it appears in the Job Table of the Job Management
Database.
-zprtname in a processing instruction or <JF_JOB_CARD> element is optional. When
specified, it identifies the logical printer name, as it appears in the Printer Table of the Job
Management Database. This option is described in the Working with Central guide.
-axxtaskid in a processing instruction or <JF_JOB_CARD> element is optional. When
specified, it identifies the name of the task that Central executes exclusively. You will find
additional information on this option in the Working with Central guide.
jobtokens in a processing instruction or <JF_JOB_CARD> element are optional options that
are passed to the task that Central executes. The supported options are described in the
appropriate Central Agent documentation.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
26
Assigning Other Job Options
There are other job options that you can specify that relate to the job name. When you use the
tp.xpr.uri option, XML Import Agent creates a ^job command in the resulting field-nominated
data file and appends the job options to the ^job command. The job options are:
●
Printer name
●
Copies
●
Legacy parameters
Printer Name
This option enables you to specify a printer name, as it appears in the Printer Table of the Job
Management Database. You will find instructions for setting up the Printer Table in the Working
with Central guide.
When you specify both a printer name and the job name using the tp.xpr.uri option, XML
Import Agent appends a -z parameter to the ^job command.
To specify a printer name, use this option, which is case-sensitive:
●
Configuration file syntax:
<pa desc="presentationAgent"><output><uri>prtname</uri>
</output></pa>
●
Task Table syntax:
pa.output.uri=prtname
where:
prtname is the printer name.
Copies
You can specify the number of copies of the template to output to a printer. When you specify
both the job name (using the tp.xpr.uri option) and the number of copies, the XML Import
Agent adds the -c parameter and value to the ^job command. By default, the XML Import
Agent sets the number of copies to “1”. To specify a different number of copies, use this option,
which is case-sensitive:
●
Configuration file syntax:
<pa desc="presentationAgent"><copies>N </copies></pa>
●
Task Table syntax:
pa.copies=N
where:
N is the number of copies to print.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
27
Legacy Parameters
There may be other parameters that you want to include as part of the ^job command. These
are optional arguments that Central passes to the executable program for a task.
You can use the legacyParms option to specify any parameter that the executable program
supports. When you specify a job name (using the tp.xpr.uri option), XML Import Agent
appends the values you specify for the legacyParms option to the ^job command in the
resulting field-nominated data file.
To specify the parameters, use this option, which is case-sensitive:
●
Configuration file syntax:
<legacyParms>"parameter1 ...parameterN"</legacyParms>
●
Task Table syntax:
legacyParms="parameter1 ... parameterN"
where:
each parameter is a string of program options separated by spaces. These program options
correspond to the options described in the appropriate Central Agent documentation. The
values are case-insensitive. The maximum length is 1023 characters.
Specifying the Document Range
The term document range refers to the portion of the XML data that XML Import Agent
processes, such as the whole XML data file or a fragment of that data file. By default, XML
Import Agent processes the content of the XML data file beginning with the root element (also
known as the document element) inclusively.
You can change the position and extent of the document range using different methods:
●
Nominate the start element
●
Exclude namespaces
●
Nominate records
Nominating the Start Element
The start element represents the element where the XFA-Data processing begins, and
consequently, the end of the element determines where processing ends. By default, XML
Import Agent processes the content of the XML data file starting with the root element
inclusively.
Developers often wrap XML data files inside other XML data files, and in turn, these get
wrapped again as organizations exchange the data files. It is necessary to be able to start well
into an XML data file that has been wrapped or packaged inside another XML data file.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
28
XML Import Agent enables you to nominate an element within the XML data file, which
represents the “root” of the data file where the XFA-Data processing will begin. This lets you
constrain the processing to a fragment of the XML data file.
To specify a start element, use this option, which is case-sensitive:
●
Configuration file syntax:
<data><startNode>xfasom(xfasom-expression)</startNode></data>
●
Task Table syntax:
data.startNode="xfasom(xfasom-expression)"
●
Processing instruction syntax:
<?xfa data_startNode="xfasom(xfasom-expression)" ?>
where:
startNode is the root of the XML data file. This sets the start (top-level) element of the XML
data file. XML Import Agent ignores all elements outside of this element. When not specified,
the default start element is the outermost node.
xfasom-expression is a fully-qualified path of element types (tag names), starting with the
root of the XML data file and referring to a single element. On UNIX, when specifying the
expression in the Task Table, or in a processing instruction, surround the expression with
“ ” (quotation marks). On Windows, when specifying the expression in a processing instruction,
surround the expression with “ ” (quotation marks).
This XML data file contains the root element <order>. The example demonstrates how to
specify a different start element using a processing instruction. The processing instruction
specifies that the document range is the content enclosed by the element <book> for the
second element <item>:
<?xfa data_startNode="xfasom(order.item[2].book)"?>
<order>
<number>1</number>
<shipto>
<reference><customer>c001</customer></reference>
</shipto>
<item>
<book>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
<quantity>1</quantity>
<unitprice>25.00</unitprice>
</book>
</item>
<item>
<book>
<ISBN>15536456</ISBN>
<title>XML Power</title>
<quantity>2</quantity>
<unitprice>30.00</unitprice>
</book>
</item>
</order>
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
29
The result of loading the XML data into the XFA-Data DOM is:
[DataGroup (book)]
[DataValue (ISBN) = "15536456"]
[DataValue (title) = "XML Power"]
[DataValue (quantity) = "2"]
[DataValue (unitprice) = "30.00"]
XML Import Agent ignores all elements outside of the element <book> for the second element
<item>, resulting in:
^symbolset UTF8
^group G_book
^field ISBN
15536456
^field title
XML Power
^field quantity
2
^field unitprice
30.00
With a start element expressed as data.startNode="xfasom(order.item)", the result of
loading the previous XML data into the XFA-Data DOM is:
[DataGroup (item)]
[DataGroup (book)]
[DataValue (ISBN) = "15536455"]
[DataValue (title) = "Introduction to XML"]
[DataValue (quantity) = "1"]
[DataValue (unitprice) = "25.00"]
XML Import Agent ignores all elements outside of the first “item” of the element <order>,
resulting in:
^symbolset UTF8
^group G_item
^group G_book
^field ISBN
15536455
^field title
Introduction to XML
^field quantity
1
^field unitprice
25.00
Excluding Namespaces
You can prevent XML Import Agent from processing content by providing one or more XML
namespaces that refer to the content intended for exclusion.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
30
To exclude content that belongs to namespaces from the translation, use this option, which is
case-sensitive:
●
Configuration file syntax:
●
<data>
<excludeNS>uri1</excludeNS>
<excludeNS>uri2</excludeNS>
</data>
Task Table syntax:
data.excludeNS=uri1 data.excludeNS=uri2
●
Processing instruction syntax:
<?xfa data_excludeNS="uri1 uri2 ... uriN"?>
where:
each uri is a URI that refers to a namespace. XML Import Agent ignores all elements that
belong to the specified URIs.
In the configuration file, you can add one entry for each namespace. In the Task Table, you can
specify one or more namespaces separated by whitespace. XML Import Agent merges any
URIs specified in the Task Table with those present in the configuration file. When you use
namespaces in a processing instruction, XML Import Agent ignores any URIs specified in the
configuration file or in the Task Table.
This example uses the option data.excludeNS=“urn:microsoft:biztalk”
“urn:microsoft:body-biztalk” to exclude the content that belongs to those namespaces:
<biztalk xmlns="urn:microsoft:biztalk">
<head>
<info/>
</head>
<body xmlns="urn:microsoft:body-biztalk">
<po xmlns="mypo">
<date xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
xfa:match="many">2000-11-10</date>
<shipTo>
<name>Charles Porter</name>
<address/>
</shipTo>
</po>
<po xmlns="mypo">
<date xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
xfa:match="many">2000-11-10</date>
<shipTo>
<name>Julie Porter</name>
<address/>
</shipTo>
</po>
</body>
</biztalk>
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
31
The result of loading the XML data into the XFA-Data DOM is:
[DataGroup (po)]
[DataValue (date) = "2000-11-10"]
[DataGroup (shipTo)]
[DataValue (name) = "Charles Porter"]
[DataValue (address) = ""]
[DataGroup (po)]
[DataValue (date) = "2000-11-10"]
[DataGroup (shipTo)]
[DataValue (name) = "Julie Porter"]
[DataValue (address) = ""]
XML Import Agent excluded the elements <biztalk>, <head>, and <info> that belong to the
namespace “urn:microsoft:biztalk”, and the element <body> that belongs to the namespace
“urn:microsoft:body-biztalk”. It also excluded the namespace declaration attributes “xmlns” and
the XFA-Data attributes that belong to the namespace
“http://www.xfa.org/schema/xfa-data/1.0/”. It retained the content of the elements <po> that
belongs to the namespace “mypo”.
The translation results are:
^symbolset UTF8
^group G_po
^global date
2000-11-10
^group G_shipTo
^field name
Charles Porter
^field address
^undefine global:date
^group G_po
^global date
2000-11-10
^group G_shipTo
^field name
Julie Porter
^field address
^undefine global:date
Nominating Records
By default, XML Import Agent considers the document range to enclose one record of data
represented by the first (top-level) data group. Some XML data files enclose repeating groups
of data, each with different content. This document refers to these repeating groups of data as
“records”. An XML data file may contain many records.
XML Import Agent provides an option that enables you to nominate the data group elements
within the document range that represent records.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
32
To nominate records, use this option, which is case-sensitive:
●
Configuration file syntax:
<data><record>nodeLevel|elementType</record></data>
●
Task Table syntax:
data.record=nodeLevel|elementType
●
Processing instruction syntax:
<?xfa data_record="nodeLevel"|"elementType"?>
where:
nodeLevel is an integer that indicates the level in the hierarchy down from the start element.
XML Import Agent interprets each data group element at that level in the hierarchy as a
separate record. The start element is located at a node level of “1”. All data groups at the
nodeLevel will translate to ^group commands. XML Import Agent ignores all higher-level
nodes.
elementType is the element type (tag name) of an element. XML Import Agent interprets
each data group element at the same level in the hierarchy of the specified element type as a
separate record. Data groups with names that match the elementType will translate to
^group commands. XML Import Agent ignores all higher-level nodes and same-level data
groups with names that do not match the elementType.
This example demonstrates the use of this option in a processing instruction, to specify that the
data group elements <item> represent records:
<?xfa data_record="item"?>
<order>
<number>1</number>
<shipto>
<reference><customer>c001</customer></reference>
</shipto>
<date><day>14</day><month>11</month><year>1998</year></date>
<item>
<book>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
<quantity>1</quantity>
<unitprice>25.00</unitprice>
</book>
</item>
<item>
<book>
<ISBN>15536456</ISBN>
<title>XML Power</title>
<quantity>2</quantity>
<unitprice>30.00</unitprice>
</book>
</item>
</order>
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
The result of loading this XML data into the XFA-Data DOM is:
[DataGroup (item)]
[DataGroup (book)]
[DataValue (ISBN) = "15536455"]
[DataValue (title) = "Introduction to XML"]
[DataValue (quantity) = "1"]
[DataValue (unitprice) = "25.00"]
[DataGroup (item)]
[DataGroup (book)]
[DataValue (ISBN) = "15536456"]
[DataValue (title) = "XML Power"]
[DataValue (quantity) = "2"]
[DataValue (unitprice) = "30.00"]
The translation results are:
^symbolset UTF8
^group G_item
^group G_book
^field ISBN
15536455
^field title
Introduction to XML
^field quantity
1
^field unitprice
25.00
^group G_item
^group G_book
^field ISBN
15536456
^field title
XML Power
^field quantity
2
^field unitprice
30.00
Notice that the elements outside of the <item> records were not transferred.
33
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
34
When the XML data makes use of different element types for similar groupings of data, the
ability to express data records via a node level is useful. This example demonstrates the use of
the option data.record=2 to specify that the data group elements at the node level “2” represent
records:
<order>
<bookitem>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
<quantity>1</quantity>
<unitprice>25.00</unitprice>
</bookitem>
<musicitem>
<cdid>4344-31020-2</cdid>
<title>Big Calm</title>
<quantity>1</quantity>
<unitprice>19.00</unitprice>
</musicitem>
</order>
The result of loading this XML data into the XFA-Data DOM is:
[DataGroup (bookitem)]
[DataValue (ISBN) = "15536455"]
[DataValue (title) = "Introduction to XML"]
[DataValue (quantity) = "1"]
[DataValue (unitprice) = "25.00"]
[DataGroup (musicitem)]
[DataValue (cdid) = "4344-31020-2"]
[DataValue (title) = "Big Calm"]
[DataValue (quantity) = "1"]
[DataValue (unitprice) = "19.00"]
The translation results are:
^symbolset UTF8
^group G_bookitem
^field ISBN
15536455
^field title
Introduction to XML
^field quantity
1
^field unitprice
25.00
^group G_musicitem
^field cdid
4344-31020-2
^field title
Big Calm
^field quantity
1
^field unitprice
19.00
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
35
Incremental Loading
UP
TE
DA
D
When XML Import Agent processes an XML data file, it loads the data into memory, then into
the XFA-Data DOM. During this process, if it detects an XSLT stylesheet, it calls a built-in XSLT
processor to transform the data. XML Import Agent then loads the result of the transformation (if
it is well-formed) into the XFA-Data DOM.
For large XML data files that contain many records, XML Import Agent provides the capability to
incrementally load the XML data into memory on a record-by-record basis.
In addition, when you set incremental loading and specify an XSLT stylesheet, the XML Import
Agent built-in XSLT processor transforms each record one at a time, as it is loaded into
memory.
Note: When XML Import Agent processes an XSLT stylesheet with incremental loading
activated, the stylesheet is only permitted access to the current record loaded into
memory and therefore cannot see the hierarchy above that record. For this reason, an
XSLT stylesheet that is designed to work when incremental loading is off may require
changes when you activate incremental loading. See page 36 for an example of an
XSLT stylesheet that can be used with or without incremental loading.
To activate incremental loading, use this option, which is case-sensitive:
●
Configuration file syntax:
<data><incrementalLoad>1|0</incrementalLoad></data>
●
Task Table syntax:
data.incrementalLoad=1|0
where:
1 loads each record in the document range into memory, one record at a time. This is the
default value that the Central Setup sets in the XML Import Agent default configuration file. This
option works in concert with the data.record option. That is, you must nominate the data group
elements that represent records within the document range, as described in the “Nominating
Records” section on page 31. Otherwise, XML Import Agent will attempt to load the entire XML
data file into memory, which may result in an error depending on the size of the file.
If an XSLT stylesheet exists, XML Import Agent transforms each record in the document range,
one record at a time, as it is loaded into memory. You must also supply the name and location of
the XSLT stylesheet, as described in the “Using an XSLT Stylesheet” section on page 38.
0 or when not specified, loads the entire XML data file into memory. If an XSLT stylesheet
exists, XML Import Agent transforms and loads the entire XML data file into memory.
This example demonstrates the use of incremental loading with an XSLT stylesheet, using the
options:
data.incrementalLoad=1 data.record=item
data.xsl.uri=http://www.adobe.com/xslt/order.xsl
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
36
where:
data.incrementalLoad=1 activates incremental loading.
data.record=item specifies that the data group elements <item> represent records.
data.xsl.uri=http://www.adobe.com/xslt/order.xsl specifies the URI of the XSLT
stylesheet “order.xsl”.
This is the sample XML data file:
<order>
<number>1</number>
<shipto>
<reference><customer>c001</customer></reference>
</shipto>
<date><day>14</day><month>11</month><year>1998</year></date>
<item>
<book>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
<quantity>1</quantity>
<unitprice>25.00</unitprice>
</book>
</item>
<item>
<book>
<ISBN>15536456</ISBN>
<title>XML Power</title>
<quantity>2</quantity>
<unitprice>30.00</unitprice>
</book>
</item>
<!--additional item elements omitted from this example-->
</order>
This XSLT stylesheet can be used with or without incremental loading:
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<!-This stylesheet copies the <item> elements to the output excluding
the <book> element. The header elements <number>, <shipTo>, and
<date> are not copied.
This stylesheet can be used with or without incremental loading.
-->
<!-- This template is only used when incremental loading is off -->
<xsl:template match="order">
<order>
<xsl:apply-templates select="item"/>
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
37
</order>
</xsl:template>
<!-- When incremental loading is on, this template is the first one called
-->
<xsl:template match="item">
<item>
<xsl:apply-templates/>
</item>
</xsl:template>
<!-- Handle the book children but do not write out the <book> element -->
<xsl:template match="book">
<xsl:apply-templates/>
</xsl:template>
<!-- Create a leaf element with its value -->
<xsl:template match="*">
<xsl:element name="{name()}">
<xsl:value-of select="."/>
</xsl:element>
</xsl:template>
</xsl:stylesheet>
By activating incremental loading, each record named “item” is loaded into memory and then
into the XFA-Data DOM, one record at a time. An XSLT stylesheet exists, therefore, each
record named “item” is transformed as it is loaded into memory. When XML Import Agent
processes the XML data, it starts with the first record. The XFA-Data DOM result is:
[DataGroup (item)]
[DataGroup (book)]
[DataValue (ISBN) = "15536455"]
[DataValue (title) = "Introduction to XML"]
[DataValue (quantity) = "1"]
[DataValue (unitprice) = "25.00"]
XML Import Agent processes the first record named “item” and removes it from memory upon
completion. It then proceeds with transforming and loading the next record named “item” into
memory, then into the XFA-Data DOM.
[DataGroup (item)]
[DataGroup (book)]
[DataValue (ISBN) = "15536456"]
[DataValue (title) = "XML Power"]
[DataValue (quantity) = "2"]
[DataValue (unitprice) = "30.00"]
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
38
This process continues for each record in the XML data file.
The complete transformation results are:
<?xml version="1.0" encoding="UTF-8"?>
<order>
<item>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
<quantity>1</quantity>
<unitprice>25.00</unitprice>
</item>
<item>
<ISBN>15536456</ISBN>
<title>XML Power</title>
<quantity>2</quantity>
<unitprice>30.00</unitprice>
</item>
</order>
XML Import Agent translates the result of the transformation into field-nominated format:
^symbolset UTF8
^group G_item
^field ISBN
15536455
^field title
Introduction to XML
^field quantity
1
^field unitprice
25.00
^group G_item
^field ISBN
15536456
^field title
XML Power
^field quantity
2
^field unitprice
30.00
Using an XSLT Stylesheet
By default, XML Import Agent does not apply an XSLT stylesheet when it translates XML data.
When you specify an XSLT stylesheet, XML Import Agent calls an XSLT processor to transform
the source XML data file, then translates the result of the transformation into field-nominated
format.
The “Using XSLT” section in the Integrating XML with Central guide provides additional
information on this topic.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
39
To specify the XSLT stylesheet, use this option, which is case-sensitive:
●
Configuration file syntax:
<data><xsl><uri>xsl_uri</uri></xsl></data>
●
Task Table syntax:
data.xsl.uri=xsl_uri
●
Processing instruction syntax:
<?xfa xsl="xsl_uri"?>
where:
xsl_uri is the URI or fully qualified path of the XSLT stylesheet.
Verifying XSL Transformations
When you use an XSLT stylesheet, you may want to examine the results of the transformed
XML data that XML Import Agent loads into the XFA-Data DOM, in the event of an error. For
example, you can review the results to validate if the transformed XML data is well-formed.
To specify where to save the XSL transformation results, use this option, which is
case-sensitive:
●
Configuration file syntax:
<data><xsl><debug><uri>xslt_results_uri</uri></debug></xsl>
</data>
●
Task Table syntax:
data.xsl.debug.uri=xslt_results_uri
where:
xslt_results_uri is the URI or fully qualified path where the results of the transformation
are saved.
Generating End Group Commands
By default, XML Import Agent outputs a ^group command at the beginning of each data group.
You can instruct XML Import Agent to output a ^group command at the end of each data group.
This enables the Print Agent to recognize when a data group ends and perform any “wrap-up”
actions.
To output a ^group command at the end of each data group, use this option, which is
case-sensitive:
●
Configuration file syntax:
<useEndGroup>1|0</useEndGroup>
Adobe Central Output Serverr
XML Import Agent Reference
●
Processing Options
40
Task Table syntax:
useEndGroup=1|0
where:
1 generates a ^group command at the end of each data group with the default end group
prefix “G_END_”.
0 or when not specified, generates a ^group command only at the beginning of each data
group, with the default start group prefix “G_”. This is the default setting.
This XML data file contains the elements <book> and <author>, which represent data groups:
<book>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
<author>
<firstname>Charles</firstname>
<lastname>Porter</lastname>
</author>
</book>
By default, XML Import Agent inserts a ^group command at the beginning of each data group,
resulting in:
^symbolset UTF8
^group G_book
^field ISBN
15536455
^field title
Introduction to XML
^group G_author
^field firstname
Charles
^field lastname
Porter
When you specify the option useEndGroup=1, this results in:
^symbolset UTF8
^group G_book
^field ISBN
15536455
^field title
Introduction to XML
^group G_author
^field firstname
Charles
^field lastname
Porter
^group G_END_author
^group G_END_book
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
41
Assigning the Group Prefix
When XML Import Agent outputs a ^group command at the beginning and at the end of a data
group, it uses a default prefix in the format:
^group G_tagname and ^group G_END_tagname
where:
G_ is the default start group prefix, and G_END_ is the default end group prefix.
tagname is the tag name of the corresponding element in the XML data file.
You can assign a different start group and end group prefix, as described below.
Start Group Prefix
To assign a different group prefix for a ^group command that appears at the beginning of each
data group, use this option, which is case-sensitive:
●
Configuration file syntax:
<startGroupPrefix>prefix_name</startGroupPrefix>
●
Task Table syntax:
startGroupPrefix=prefix_name
where:
prefix_name is the name of the prefix for each ^group command that appears at the
beginning of each data group. The default start group prefix is “G_”.
End Group Prefix
To assign a different group prefix for each ^group command that represents the end of each
data group, use this option, which is case-sensitive:
●
Configuration file syntax:
<endGroupPrefix>prefix_name</endGroupPrefix>
●
Task Table syntax:
endGroupPrefix=prefix_name
where:
prefix_name is the name of the prefix for each ^group command that appears at the end of
each data group. The default end group prefix is “G_END_”.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
42
Suppressing Data Groups
When the structure of the XML data matches the structure of an existing form, particularly after
XSLT application, you may want to prevent the generation of unnecessary ^group commands
in the field-nominated data file.
XML Import Agent provides an option that you can use to suppress the creation of data groups
within records. With this option, XML Import Agent processes only the content within a record
that corresponds to data values.
To suppress data groups, use this option, which is case-sensitive:
●
Configuration file syntax:
<data><flatten>1|0</flatten></data>
●
Task Table syntax:
data.flatten=1|0
●
Processing instruction syntax:
<?xfa data_flatten="1"|"0"?>
where:
1 prevents the generation of data groups within records. Only top-level data groups will
translate to ^group commands.
0 or when not specified, outputs data groups as ^group commands. This is the default setting.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
43
This XML data file illustrates how to suppress data groups, using the option data.flatten=1:
<book>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
<author>
<firstname>Charles</firstname>
<lastname>Porter</lastname>
</author>
</book>
The XFA-Data DOM result is:
[DataGroup (book)]
[DataValue (ISBN) = "15536455"]
[DataValue (title) = "Introduction to XML"]
[DataValue (firstname) = "Charles"]
[DataValue (lastname) = "Porter"]
XML Import Agent did not interpret the element <author> within the record “book” as a data
group, resulting in:
^symbolset UTF8
^group G_book
^field ISBN
15536455
^field title
Introduction to XML
^field firstname
Charles
^field lastname
Porter
XML Import Agent translated only the top-level data group “book” to a ^group command. It
ignored the lower-level data group “author”, and translated its data values to ^field commands
contained by the top-level data group “book”.
Specifying a Template Name
To specify the name of the template that Central uses to process the data, you can instruct XML
Import Agent to output a ^form command instead of a ^group command for each record in an
XML data file.
To output a ^form command for each record, use this option, which is case-sensitive:
●
Configuration file syntax:
<useFormCommand>1|0</useFormCommand>
●
Task Table syntax:
useFormCommand=1|0
where:
1 outputs data groups that represent records as ^form commands.
0 or when not specified, outputs data groups as ^group commands. This is the default setting.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
44
This example demonstrates the use of two options to output a ^form command for each record.
The option data.record=2 specifies that the data group elements <bookitem> and
<musicitem>, which appear at level 2 in the hierarchy, represent records. The option
useFormCommand=1 specifies to output ^form commands for the specified records.
<order>
<bookitem>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
<quantity>1</quantity>
<unitprice>25.00</unitprice>
</bookitem>
<musicitem>
<cdid>4344-31020-2</cdid>
<title>Big Calm</title>
<quantity>1</quantity>
<unitprice>19.00</unitprice>
</musicitem>
</order>
This results in the output of a ^form command for each record:
^symbolset UTF8
^form bookitem
^field ISBN
15536455
^field title
Introduction to XML
^field quantity
1
^field unitprice
25.00
^form musicitem
^field cdid
4344-31020-2
^field title
Big Calm
^field quantity
1
^field unitprice
19.00
Processing XML Attributes as Data Values
By default, XML Import Agent ignores XML attributes for data group elements. You can override
the default behavior and process these XML attributes as data values.
To process XML attributes for data group elements as data values, use this option, which is
case-sensitive:
●
Configuration file syntax:
<data><attributes>preserve|ignore</attributes></data>
Adobe Central Output Serverr
XML Import Agent Reference
●
Processing Options
45
Task Table syntax:
data.attributes=preserve|ignore
●
Processing instruction syntax:
<?xfa data_attributes="preserve"|"ignore"?>
where:
preserve processes the XML attributes for data group elements as data values, resulting in
^field commands in the output file. This setting does not apply to XML attributes for data
values. XML Import Agent always ignores XML attributes specified for data values, as
described in the Integrating XML with Central guide.
ignore or when not specified, discards the XML attributes for data group elements. This is the
default setting.
When you specify the data.attributes=preserve option, XML Import Agent interprets each
attribute of data group elements as data values. This example demonstrates the use of this
option in a processing instruction, to preserve XML attributes:
...
<?xfa data_attributes="preserve"?>
<book status="stocked">
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
</book>
...
The element <book> represents a data group that has the attribute “status” with a value of
“stocked”.
The XFA-Data DOM result is:
...
[DataGroup (book)]
[DataValue (status) = "stocked" contains="metadata"]
[DataValue (ISBN) = "15536455"]
[DataValue (title) = "Introduction to XML"]
...
XML Import Agent processes the attribute “status” as a data value with a value of “stocked”,
within the enclosing data group “book”.
The translation results are:
...
^group G_book
^field status
stocked
^field ISBN
15536455
^field title
Introduction to XML
...
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
46
Changing the Field Order
When using the Print Agent and dynamic templates, depending on the template design, it may
be necessary to process all the data values for a data group before processing a child data
group. By default, XML Import Agent outputs the data groups and data values in the same order
as they appear in the XML data. You can instruct XML Import Agent to output the data values of
a data group first, then the child data groups contained within that same data group.
To output the data values before the data groups, use this option, which is case-sensitive:
●
Configuration file syntax:
<order>dataValuesFirst|document</order>
●
Task Table syntax:
order=dataValuesFirst|document
where:
dataValuesFirst specifies that for each parent data group, XML Import Agent outputs the
data values first, then the child data groups.
document or when not specified, outputs the data values and data groups in the same order as
in the XML data file. This is the default setting.
This XML data file contains the element <author>, which represents a child data group of the
data group element <bookitem>:
<order>
<bookitem>
<ISBN>15536455</ISBN>
<author>
<firstname>Charles</firstname>
<lastname>Porter</lastname>
</author>
<title>Introduction to XML</title>
<quantity>1</quantity>
<unitprice>25.00</unitprice>
</bookitem>
<musicitem>
<cdid>4344-31020-2</cdid>
<title>Big Calm</title>
<quantity>1</quantity>
<unitprice>19.00</unitprice>
</musicitem>
</order>
Notice how the data value elements <title>, <quantity>, and <unitprice> belong to the data
group element <bookitem>.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
47
By default, XML Import Agent outputs the data values and data groups in the same order as in
the XML data file, resulting in:
^symbolset UTF8
^group G_order
^group G_bookitem
^field ISBN
15536455
^group G_author
^field firstname
Charles
^field lastname
Porter
^field title
Introduction to XML
^field quantity
1
^field unitprice
25.00
^group G_musicitem
^field cdid
4344-31020-2
^field title
Big Calm
^field quantity
1
^field unitprice
19.00
In the example above, the translation results do not match the template. The fields “title”,
“quantity”, and “unitprice” do not belong to the subform “author”. These fields belong to the
subform “bookitem”.
To associate the fields “title”, “quantity”, and “unitprice” with the subform “bookitem”, use the
option order=dataValuesFirst. The translation results are:
^symbolset UTF8
^group G_order
^group G_bookitem
^field ISBN
15536455
^field title
Introduction to XML
^field quantity
1
^field unitprice
25.00
^group G_author
^field firstname
Charles
^field lastname
Porter
^group G_musicitem
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
48
^field cdid
4344-31020-2
^field title
Big Calm
^field quantity
1
^field unitprice
19.00
The fields “title”, “quantity”, and “unitprice” appear below the subform “bookitem”. The data
structure now matches the structure of the template.
Setting Line and Paragraph Ends
You can control the way XML Import Agent handles line breaks (<br/>) and paragraph breaks
(<p/>). When XML Import Agent encounters a line break or paragraph break in the XML data
file, it outputs the characters specified by the lineEnd or paragraphEnd setting. These
characters produce the appropriate line breaks and paragraph breaks in rich text fields on your
template.
To set line and paragraph end handling, use these options, which are case-sensitive:
●
Configuration file syntax:
<lineEnd>itc|itccr|crcr|cr</lineEnd>
<paragraphEnd>itc|itccr|crcr|cr</paragraphEnd>
●
Task Table syntax:
lineEnd=itc|itccr|crcr|cr
paragraphEnd=itc|itccr|crcr|cr
where:
itc outputs the Inline Text Control command \n. This is the value for line ends that the Central
Setup places in the XML Import Agent default configuration file.
itccr outputs the Inline Text Control command \n and a carriage return/line feed (CR/LF)
character. This is the default setting for paragraph ends and line ends.
crcr outputs two CR/LF characters. Use this setting if you want XML Import Agent to handle
paragraph breaks as it did in Central 5.4.1 and earlier.
cr outputs one CR/LF character. Use this setting if you want XML Import Agent to handle line
breaks as it did in Central 5.4.1 and earlier.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
49
Specifying the Symbol Set (Code Page)
XML Import Agent supports XML data files encoded in:
UTF-8
Latin 2 (ISO-8859-2)
Hebrew (ISO-8859-8)
Roman 8
Baltic (ISO-8859-4)
Turkish (ISO-8859-9)
PC-850
Russian (ISO-8859-5)
Russian (DOS)–Windows only
Latin 1 (ISO-8859-1)
Greek (ISO-8859-7)
When XML Import Agent loads the data into the XFA-Data DOM, it uses the code page
specified in the XML data file. For UNIX platforms, ensure that you have set and exported the
LANG environment variable as described in “Installing and Configuring XML Import Agent” on
page 7.
By default, XML Import Agent inserts a ^symbolset command with the value UTF8 in the
field-nominated data file.
To output the field-nominated data file using a different symbol set, use this option, which is
case-sensitive:
●
Configuration file syntax:
<codepage>codepage_name</codepage>
●
Task Table syntax:
codepage=codepage_name
where:
codepage_name is the name of one of the supported code pages. The default code page is
UTF-8.
The supported code pages are:
Code Page Name
Output ^symbolset
UTF-8
UTF8
ISO-8859-1
WINLATIN1
ISO-8859-2
Latin2
Shift-JIS
SHIFT-JIS (Windows only)
KSC-5601
HANGEUL (Windows only)
Big-Five
BIGFIVE (Windows only)
GB2312
GB2312 (Windows only)
For example, by specifying codepage=ISO-8859-1, XML Import Agent outputs ^symbolset
WINLATIN1 at the top of the field-nominated data file.
Adobe Central Output Serverr
XML Import Agent Reference
Processing Options
Suppressing the Banner
When you run XML Import Agent, it can display a banner indicating the version that you are
running. To suppress the banner, use this option, which is case-sensitive:
●
Configuration file syntax:
<suppressBanner>1|0</suppressBanner>
●
Task Table syntax:
suppressBanner=1|0
where:
1 suppresses the banner. This is the default value that the Central Setup sets in the XML
Import Agent default configuration file.
0 or when not specified, displays a banner when you run XML Import Agent.
50
Index
A
D
attributes, XML 44
data groups, assigning the group prefix 41
document order 46
document range 27
namespaces 29
record elements 31
start element 27
B
banner 50
C
configuration file elements 8
<codepage/> 49
<data><attributes/> 44
<data><excludeNS/> 30
<data><flatten/> 42
<data><incrementalLoad/> 35
<data><record/> 32
<data><startNode/> 28
<data><uri/> 23
<data><xsl><debug><uri/> 39
<data><xsl><uri/> 39
<endGroupPrefix/> 41
<legacyParms/> 27
<lineEnd/> 48
<log><mode/> 18
<log><to/> 15
<log><uri/> 15, 17
<messaging><message><msgID/> 21
<messaging><message><severity/> 21
<order/> 46
<output><uri/> 24
<pa><copies/> 26
<pa><output><uri/> 26
<paragraphEnd/> 48
<rsp><uri/> 14
<startGroupPrefix/> 41
<suppressBanner/> 50
<tp><xpr><uri/> 25
<useEndGroup/> 39
<useFormCommand/> 43
configuring XML Import 7
configuring XML Import Agent 7
copies 26
F
field order 46
I
incremental loading 35
input file 23
J
JF_JOB_CARD element 24, 25
job name 24
job options 26
L
legacy parameters 27
log file 14
mode 18
name and location 15
output 15
severity 20
log, multiple 18
N
namespaces 29
Adobe Central Output Server
XML Import Reference Agent
Index
O
P
options
-c 26
codepage 49
-config 13
data.attributes 45
data.excludeNS 30
data.flatten 42
data.incrementalLoad 35
data.record 32
data.startNode 28
data.uri 23
data.xsl.debug.uri 39
data.xsl.uri 39
endGroupPrefix 41
legacyParms 26, 27
lineEnd 48
log.mode 18
log.to 15
log.uri 15, 17
messaging.message.msgID 21
messaging.message.severity 21
order 46
output.uri 24
pa.copies 26
pa.output.uri 26
paragraphEnd 48
rsp.uri 14
startGroupPrefix 41
suppressBanner 50
tp.xpr.uri 25
useEndGroup 40
useFormCommand 43
-z 26
order of fields 46
output file 24
processing instruction syntax 13
processing instructions
data_attributes 45
data_excludeNS 30
data_flatten 42
data_record 32
data_startNode 28, 39
processing options 12
processing XML data 6
R
record elements 31
response file 14
S
start element 27
status verification 14
T
template name 43
U
unrecognized options 20
user-defined configuration file, invoking 12
V
verifying XSLT results 39
X
XML attributes, preserving 44
XSLT
incremental loading of transformation results 35
using an XSLT stylesheet 38
verifying transformation results 39
52