EMC ® Document Sciences ®
xPression ® xAdmin
Version 4.5 SP1
Integration Guide
EMC Corporation
Corporate Headquarters
Hopkinton, MA 01748-9103
1-508-435-1000
www.EMC.com
Legal Notice
Copyright © 2003-2016 EMC Corporation. All Rights Reserved.
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change
without notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS
OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY
DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. Adobe and Adobe PDF
Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks
used herein are the property of their respective owners.
Documentation Feedback
Your opinion matters. We want to hear from you regarding our product documentation. If you have feedback
about how we can make our documentation better or easier to use, please send us your feedback directly at
[email protected]
Table of Contents
Revision History
Chapter 1
Chapter 2
Chapter 3
..................................................................................................................
7
.................................................................................................
9
xPressionHome ................................................................................................
9
Information Boxes ............................................................................................
9
EMC Document Sciences Technical Support .......................................................
9
Introduction
Managing Your Data
.................................................................................... 11
Managing Data After Upgrading from xPression 1.x ...........................................
11
Using Multiple Data Sources .............................................................................
11
xPression Schema Data Types ............................................................................
12
Manually Creating a Data Reading Definition ....................................................
DTD of the Data Reading Definition File ........................................................
Table Element ..........................................................................................
RowxPath Element ...................................................................................
Column Element ......................................................................................
ColumnXPath Element ..............................................................................
ColumnValue Element ..............................................................................
Multiple Values Reading Definition ...........................................................
CustomerDelimiter Element ......................................................................
13
15
15
15
16
16
16
18
18
Trim Leading and Trailing Spaces in Customer Data ...........................................
18
.......................................................................................
XML Limitations ..............................................................................................
Working Effectively With XML ..........................................................................
Character Length Limitations for String Data Fields ........................................
XML Reserved Characters in Your XML Data .................................................
Successfully Navigating XML in xPression .........................................................
Dynamically Adding Unique Keys with a Reading Definition .........................
XML Differences with xPression Batch ...........................................................
How Should I Set Up Complex XML Data Sources? ............................................
Case 1: How Can I Use XML Attributes With My Data Source? .......................
Sample XML Data File ..............................................................................
Sample Schema ........................................................................................
Mapping the Data Source ..........................................................................
The Data Reading Definition .....................................................................
Case 2: How Can I Use A Table Defined in Several Locations? .........................
Sample Schema ........................................................................................
Tying It All Together .................................................................................
Case 3: How Can I Use XML Data With Mismatched Element Names? ............
Sample Schema ........................................................................................
Sample XML Data File ..............................................................................
Sample Data Reading Definition ................................................................
21
Working With XML
21
22
23
23
23
27
28
29
29
30
31
31
32
33
35
35
36
36
37
38
3
Table of Contents
Case 4: How Can I Map Multiple Element Values to Multiple
Columns?.....................................................................................................
XML Data File Sample ..............................................................................
Splitting the Data......................................................................................
Chapter 4
Chapter 5
Chapter 6
4
..................................................................................
The UserExitDataReader Abstract Class .............................................................
UserExitDataReader.getOneRecord() .............................................................
UserExitDataReader.init() .............................................................................
Implementing the Custom JAVA Class ...............................................................
getOneRecord() Method ................................................................................
init() Method ................................................................................................
No Timeout Setting ......................................................................................
Packaging Your Class ....................................................................................
Add Paths to Application Server ....................................................................
Classpaths....................................................................................................
Sample Custom User Exit ..................................................................................
Setting Up User Exits
.....................................................................................................
Migrating Documents from the Command Line..................................................
Document Metadata .....................................................................................
MigrationServer.xml .....................................................................................
Create a Migration Specification ....................................................................
Sample.....................................................................................................
Sample.....................................................................................................
Run a Command Line Migration ...................................................................
Export from the Command Line ....................................................................
Import from the Command Line ....................................................................
Overwriting Documents on the Target Server .................................................
Migrate a Job Definition from the Command Line...............................................
Create a Migration Specification ....................................................................
Sample.....................................................................................................
Sample.....................................................................................................
Migrate a Job Definition from the Command Line...........................................
Export a Job Definition from the Command Line ............................................
Import a Job Definition from the Command Line ............................................
Migrating Output Profiles from the Command Line ............................................
Create a Migration Specification ....................................................................
Sample.....................................................................................................
Sample.....................................................................................................
Migrate an Output Profile from the Command Line ........................................
Export an Output Profile from the Command Line .........................................
Import from the Command Line ....................................................................
Importing and Exporting Work Items ................................................................
Criteria File .................................................................................................
Export a Work Item from the Command Line .................................................
Import a Work Item from the Command Line .................................................
Sample Criteria Files ....................................................................................
Scheduling a Migration .....................................................................................
Sample Migration DTD .................................................................................
Overriding Category Info ..................................................................................
Command Line Migration Error Codes ..............................................................
Migration
Working With Bar Codes
38
38
39
43
43
44
44
45
45
45
45
45
45
46
46
49
49
49
49
50
51
51
52
52
53
53
53
53
54
54
55
55
55
56
56
56
57
57
57
58
58
58
58
59
59
60
60
61
62
............................................................................. 63
Table of Contents
Check Characters..............................................................................................
63
Bar Code Errors ................................................................................................
64
xPression 1-D Bar Code Support ........................................................................
64
3 of 9 Bar Codes ................................................................................................
64
2 of 5 Interleaved Bar Codes ..............................................................................
65
Code 128 Bar Codes ..........................................................................................
65
PostNet Bar Codes ............................................................................................
Zip Five Digit Bar Code ................................................................................
Zip+4 Nine Digit Bar Code ............................................................................
DPBC POSTNET ..........................................................................................
66
66
66
66
OMR Bar Codes................................................................................................
67
PDF417 Bar Codes ............................................................................................
67
DataMatrix Bar Codes .......................................................................................
69
Bar Code Character Tables ................................................................................
ASCII and EBCDIC Data ...............................................................................
70
70
Code 128 ..........................................................................................................
71
3 of 9................................................................................................................
74
5
Table of Contents
List of Tables
6
Revision History
Revision Date
Description
June, 2016
Updated the contents of the Overwriting
Documents on the Target Server, page 53 section.
August, 2015
Updated the descriptions for the -i parameter
in Migrating Documents from the Command
Line, page 49.
June, 2014
Initial publication
7
Revision History
8
Chapter 1
Introduction
This book covers topics on xAdmin integration and is mainly intended for xDesign users.
xPressionHome
The term “xPressionHome” refers to the location where xPression was installed on your server. By
default on Windows servers, the location is C:\xPression, but your installer may have selected
a different location during installation. Please consult with your administrators or IT personnel to
determine the location where they installed xPression. Throughout the xPression documentation, we
will refer to this location as “xPressionHome”.
Information Boxes
The following colored boxes alert you to special information in the documentation.
Caution: The caution box warns you that a fatal error, unsatisfactory output, or loss of data may
occur if you do not follow the directions carefully.
Tip: A tip offers suggestions to simplify a task or describes a useful shortcut. They may also describe
an alternate way to use the techniques described in the text.
Note: A note offers information that emphasizes or supplements important points of the main text.
EMC Document Sciences Technical Support
For more information or to solve a problem, you can contact EMC Document Sciences Technical
Support in one of the following ways:
Online Support: https://support.emc.com
Telephone Support:
9
Introduction
United States: 800-782-4362
Canada: 800-543-4782
Worldwide: +1-508-497-7901
For additional worldwide access numbers, visit:
http://www.emc.com/collateral/contact-us/h4165-csc-phonelist-ho.pdf
10
Chapter 2
Managing Your Data
This chapter contains advanced information and special topics about your data and xAdmin:
• Managing Data After Upgrading from xPression 1.x
• Using Multiple Data Sources
• Using Multiple Data Sources
• Manually Creating a Data Reading Definition
• Trim Leading and Trailing Spaces in Customer Data
Managing Data After Upgrading from xPression
1.x
In xPression 1.x, xPression automatically trimmed leading and trailing spaces in your customer data.
This functionality is now turned off by default. If you want to continue trimming leading and trailing
spaces in your customer data, you must activate this feature in xAdmin. See Trim Leading and
Trailing Spaces in Customer Data, page 18 for more information.
Using Multiple Data Sources
Multiple data sources can be defined to a data source group. For example, you could assign only your
testing data sources to xDesign, and your production data to xPression Batch and xResponse.
xPression “knows” which data sources are available to your applications when you associate a
data source with a category. Assigning a data source to an application like xDesign or xResponse
enables their users to access the data sources.
After you associate a data source with an application, you must select one data source as primary.
xDesign automatically reads the primary table from the primary data source during the assembly
process. xAdmin assigns primary status to the first data source unless you specify otherwise.
You can override the primary data source during execution for each xPression application. For more
information, see the xDashboard User Guide and the xFramework Developer’s Guide.
11
Managing Your Data
xPression Schema Data Types
xPression supports the following data types in its schemas:
• Integer
• String
• Date
• Float
The following table lists the mapping between the SQL data types offered by a relational database
and the xPression schema data types. User-defined types are not supported in the default mapping.
SQL Data Types
BOOLEAN
Type Mapped to Schema
SQL Data Types
Type Mapped to
Schema
String
DATE
Date
Integer
BINARY
Not Supported
CHAR
LONGVARCHAR
VARCHAR
VARCHAR2
CLOB
LONG
NUMERIC
BIT
VARBINARY
TINYINT
RAW
SMALLINT
INTEGER
BIGINT
NUMBER(p)
FLOAT
REAL
Float
LONGVARBINARY Not Supported
BLOB
DOUBLE
NUMBER(p,s)
If you define float data as an integer to xPression, your data must not contain decimal points.
12
Managing Your Data
Manually Creating a Data Reading Definition
The creation of a reading definition should depend on the data source schema and the XML customer
data. In order to manually create a reading definition, you will need to know the details about
a reading definition’s construction.
The data reading definition is composed of a list of Table elements. The Table element in the data
reading definition describes where to find the data in the CustomerXML and how to retrieve the
value in a relational database. Every Table element in the data reading definition corresponds to a
TableDef element in the data source schema. The name attributes must be same.
The Table element contains a list of Column elements. Every Column element (the Table element’s
child element) in the data reading definition corresponds to a Column element in the data reading
definition. The name attributes must be same.
The Table element contains another required element: RowXPath whose text is an XPath. To write
this XPath you must first identify where to retrieve the data to populate the corresponding table.
Next, construct the XPath using the location of the data in the XMLCustomerData. The XPath is an
absolute path which should point to the row level of the XMLCustomer.
For example, the XMLCustomerData is:
<SalesOrder SONumber="12345">
<Item ItemNumber="1">
<Part PartNumber="123">
<Price>9.95</Price>
</Part>
<Quantity>10</Quantity>
</Item>
<Item ItemNumber="2">
<Part PartNumber="456">
<Price>13.27</Price>
</Part>
<Quantity>5</Quantity>
</Item>
</SalesOrder>
The data source schema is:
<DBSchema>
<TableDef name="SO_ITEM">
<ColumnDef name="SONumber" type="integer"/>
<ColumnDef name="ItemNumber" type="integer"/>
<ColumnDef name="PartNumber" type="integer"/>
<ColumnDef name="Price" type="String" size="10"/>
</TableDef>
</DBSchema>
13
Managing Your Data
Remember that any time there is a “size” attribute for a String type element, the size is interpreted as
bytes. This is important when using a double-byte language. For example, if you have a field whose
size is set to 10, and you are using the Chinese language, only the first 5 characters appear in the field
since each Chinese character uses two bytes. Be sure to designate enough bytes in your size elements
to accurately read the largest possible value in the field.
The data reading definition is:
<XMLReadingDef>
<Table name="SO_ITEM">
<RowXPath>/SalesOrder/Item</RowXPath>
<Column name="SONumber">
<ColumnXPath>../</ColumnXPath>
<ColumnValue type="integer">@SONumber</ColumnValue>
</Column>
<Column name="ItemNumber">
<ColumnXPath/>
<ColumnValue type="integer">@ItemNumber</ColumnValue>
</Column>
<Column name="PartNumber">
<ColumnXPath>Part</ColumnXPath>
<ColumnValue type="integer">@PartNumber</ColumnValue>
</Column>
<Column name="Price">
<ColumnXPath>Part/Price</ColumnXPath>
<ColumnValue type="integer">text()</ColumnValue>
</Column>
</Table>
</XMLReadingDef>
The first RowXPath element in this data reading definition is /SalesOrder/Item. Two instances of the
Item element in the XMLCustomer have an XPath. These two instances also correspond to row
data in the database table.
The Column element’s construction also requires an XPath. This path is a relative path. It is relative to
the RowXPath. In the first case, the ‘part’ in the <ColumnXPath>Part</ColumnXPath> is relative to
the /SalesOrder/Item.
Sometimes we need a filter to identify an XPath. This filter is the expression in square brackets.
For example:
<InsurancePolicy>
<AutoInsurancePolicy>
<DataItem>
<Label>Policy_Number</Label>
<Value>apolicynumber</Value>
</DataItem>
<DataItem>
<Label>Corporation_Text</Label>
<Value>Fisev AIS</Value>
</DataItem>
<DataItem>
<Label>Company_Text</Label>
<Value>Fiserv Insurance</Value>
</DataItem>
<DataItem>
<Label>Expiration_Date</Label>
<Value>03/03/02</Value>
</DataItem>
</AutoInsurancePolicy>
</InsurancePolicy>
14
Managing Your Data
The data reading definition RowXPath should be like /InsurancePolicy/AutoInsurancePolicy.
The ColumnXPath should be like DataItem/Value[../Label/text() = "Corporation_Text"]. Here, the
DateItem/Value can’t identify a column uniquely. So a filter, the expression inside the [ ] brackets, is
used to refine the location.
You can modify the definition displayed in the Data Reading Definition text box. Click in the box and
press CTRL+A to select the text. Copy it (you can either right-click the selected text and choose Copy
from the shortcut menu, or press CTRL+C), and paste it into any text editor). Make your changes and
copy the text back to the text box. Click Save to register your changes.
Remember that any time you make changes to data sources that affect a document assembly, you
must make sure your designers generate XML so that the changes are applied to their documents.
DTD of the Data Reading Definition File
Before constructing the data reading definition file, we need to take a look at the reading definition
file’s structure and some concepts relating to the elements in it. Over using wild-cards and leaving
unused fields in your reading definition can cause serious performance issues. For best performance,
remove unused fields from your reading definition and eliminate as many wild-cards as possible.
Table Element
This element defines how to map a set of data in your XML to a relational database table. It contains
two children elements: the RowXPath element and the Column element. The table element has a
name attribute, which is the table’s name in the your data source.
RowxPath Element
This element defines the XPath of the selected nodes in the XML file. Every node located through this
path corresponds to a row in the table.
A subset of W3C XPath syntax will be used to locate the XML data’s element. The following
addressing mechanism is recognizable.
The basic address mechanism is to use absolute path (start with /). For example:
/AAA, /AAA/BBB
The relative path is needed in the location of the column. For example:
./ or ../
where ./ is the current node, and ../ is the parent node.
15
Managing Your Data
An asterisk (*) selects all elements located by preceding path. For example:
/AAA/*/BBB, /*
An expression in square brackets can further specify an element. A number in the brackets gives the
position of the element in the selected set. For example:
/AAA/BBB[1], /doc/Chapter[5]/section[2]
Attributes are specified by the @ prefix. The presence of a specific attribute or the value of the
attribute can be added to selection criteria. For example:
/AAA/BBB[@id], /BBB[@name=’bbb’]
Some system functions can be used:
Text(): the content of the context node
Name(): return the local name of the context node
Last(): used in /AAA/BBB[last()]
For more information about XPath, see http://www.w3.org/TR/xpath
Column Element
This element defines the mapping from the node data in xml to the table’s column. It has a name
attribute, which is the column name in the table. The column element contains two children elements:
the ColumnXPath element and the ColumnValue element.
ColumnXPath Element
This element is the XPath of the nodes, for which the data will be used as the column value. Here the
XPath must be expressed in the relative path. It is relative to the XPath expressed in the RowXPath
element.
ColumnValue Element
This element defines how to take the data from the nodes located through the XPath. The data could
have three options. They are the text value of the node, the attribute value of the node and the
tag name of the node.
Text(): the content of the context node
@MyAttribute: the content of an attribute
Name(): return the local name of the context node
This element contains a “format” attribute, a “type” attribute, and a third attribute “isMultiple”
indicating if the value contains multiple values. The type attribute is used to express the value’s type.
The format is to describe the value’s format according to its type. For example, if the type attribute
16
Managing Your Data
in the column element is Date, the format attribute is used to identify the format of the date in the
XML file, such as YY-MM-DD or MM/DD/YY.
17
Managing Your Data
Multiple Values Reading Definition
In an XML file, some elements might contain multiple values, such as the data that contains pipe
characters. To read and query this data, the DBSchema should have a way to express these values. In
general, the DBSchema can have two options, one of which is to spawn multiple columns. Every
column corresponds to one of the values. If the number of values is unknown, this method may not
be appropriate. In this case, the values should be stored in an extra table.
The reading definition file needs to support these two options. The ColumnValue element has an
optional child element, MultiValuesDef. If the “isMultiple” attribute of the ColumnValue element
is true, this MultiValuesDef must be defined in the reading definition file. This element has a child
element, Delimiter, which is to identify the multiple values’ separation.
For the first option, the reading definition file needs to define how to locate the value in the data (for
example, give a sequence number for the data delimited by the pipe character). This introduces a new
element, Position, as a child element of MultiValuesDef.
For the second option, the reading definition file needs to define which column is a multi-valued
column and which table the multiple values should be stored in. So, a new element, SubTable, is
introduced. It contains three attributes: Attribute name is the table’s name, Attribute keyColumn is
the column (which is the foreign key of the multi-value storing table), and Attribute valueColumn
(which is the column that stores all of the values, one per record). The Position element and the
SubTable element are exclusive to each other.
CustomerDelimiter Element
This element is introduced solely for large file reading. The Customer Delimiter indicates where a
record set begins and ends.
Trim Leading and Trailing Spaces in Customer
Data
xPression enables you to optionally trim the leading and trailing spaces in your customer data.
Some of the values in your customer data may contain spaces preceding or following the value. For
example, your customer data could contain an address with a space at the end:
“2332 s. Sumac ”
You can use the Trim function to remove the space(s) that appear before or after your customer data
values. You can activate the leading or trailing space trim functions by setting the LTrim and RTrim
values in the customerdata.properties file located in your xPression Server directory.
Function
Definition
Trim Leading Space
Removes any spaces that precede the value in your customer data. This
function is represented in the customerdata.properties file as LTrim.
Trim Trailing Space
Removes any spaces that follows the value in your customer data. This
function is represented in the customerdata.properties file as RTrim.
18
Managing Your Data
By default, both values are disabled:
LTrim=false RTrim=false
To activate leading or trailing trim functions, simply set the value(s) to “true”:
LTrim=true RTrim=true
Caution: After changing this setting, you must restart the server for the setting to take effect.
Using the previous example, the resulting customer data would be: “2332 s. Sumac”.
When activated, the Trim Leading Space and Trim Trailing Space options have the following effect on
your xPression components.
xPression Component
Behavior
Variable Rules
Variables defined in variable rules are not affected by the Trim Leading and
Trim Trailing Space options. This feature only trims leading and trailing
spaces from RDB or XML customer data.
Literal Values
This feature does not affect literal values defined by the user in xDesign for
queries and criteria.
Read Criteria
If your customer data is in a RDB, xPression will not trim leading or trailing
spaces.
Variable Replacements
xPression will trim the leading and trailing spaces in your variable
replacements.
19
Managing Your Data
20
Chapter 3
Working With XML
This chapter covers topics dealing with XML data sources. It contains material describing XML
limitation, tips for implementing XML data sources, advice on how to best structure your XML
files for xPression.
XML Limitations
Before creating your XML data sources and schemas, consult the following list of XML limitations,
most of which applies to xDesign only.
Element
Description
Duplicate table and
field names
xPression does not support table and field names that are identical. While some XML
editors may see the practice as valid, xPression can not validate XML where a table and
a field share the same name. For example, if you define a table name as "ADDRESS",
you cannot subsequently use the name "ADDRESS" to define a field.
XML reserved
characters
Be very careful when using any of the XML reserved characters in your table and
field names. Using them can cause unpredictable results. This includes: ampersand
(&), left and right brackets (<>), apostrophe (‘), and double quote (“). Hyphens (-) are
not supported in field or table names, but underscores (_) are and should be used
in their place.
SQL reserved words
xPression does not support the ability to use SQL Reserved Words in your schema for
table and field names. For example, you cannot use INSERT, PRIMARY, or SELECT.
Please consult outside documentation for a full list of SQL reserved words.
Lowercase and
mixed-case names
Lowercase and mixed case names are allowed, but not recommended because of the
resulting complexity of the XML map.
Schema
When creating a schema for your XML data source, you must use unique table names.
Some XML schemas attempt to use identical table names in different paths, but our
automation tools prohibit this use. If your XML schema already uses this method, you
must re-create one of the tables manually with a unique name.
Customer Delimiter
In order to identify to xPression where a customer record begins and where it ends, you
must specify a delimiter in your reading definition. To learn how to set the customer
delimiter, see Setting the Customer Delimiter.
Data Storage Format
xPression stores XML data in an SQL-type structure and reads the data used by the
document application through an SQL query.
21
Working With XML
Element
Description
Linked Tables
Linked tables must contain key information suitable for that purpose. XML hierarchy is
not a sufficient way to link tables because the tables are created as unique, unrelated
entities within the schema.
Auto Mapping Tool
The xPression Auto Mapping tool requires a reference to your XML data source.
AutoMapping is not available for the Label\Value Pair XML. This means the mapping
definition must be created by hand.
Renamed Tables and
Fields
If you have renamed any tables or fields in your xPression schema, you must manually
update your data reading definition so that the table and field names match the names
in the schema.
Working Effectively With XML
xPression makes extensive use of XML throughout the system in customer data sources, reading
definitions, and schemas. Well formed XML ensures that your text will qualify as valid.
Valid XML requires that you follow these basic rules:
• Must have only a single root element
• All elements require a closing tag or ending slash
• Element names are case-sensitive
• Properly nest all elements
• Double-quote all attribute values
• Use reserved character entities or use <![CDATA[ ]]> sections
An “element” (also known as a tag or node) is an identifier or marker in your XML text which is
intended to represent the meaning and placement of a piece of data or a collection of information.
Elements are easy to spot because they are surrounded by the less than (<) and greater than (>)
bracket characters.
In addition, you should incorporate these guidelines for your elements:
• Element names can contain letters, numbers, underscores and some other characters - but never
spaces.
• Element names should begin with a letter - but not begin with any combination of "xml" in any
case.
• Element names can be descriptive, but you should avoid very long names.
• Element names with international characters should not be used unless the proper processing
instructions are included.
22
Working With XML
Character Length Limitations for String Data Fields
Field length limitations for string-type fields are determined primarily by the database. Current
relational databases supported by xPression provide for up to 4000 characters. XML supports much
greater field lengths than relational databases, up to 64k characters, but the specific limit depends
on usage.
It is possible to place up to 64k characters in an XML field for xDesign documents, OP field for
a generic index, and variables for xEditor, but fields with this much data will probably impair
performance so caution is recommended. Extremely long OP fields should be avoided in any case.
The field length set in xAdmin for data source groups is ignored for both RDB and XML data sources.
The actual limit is 64k but, as stated above, fields approaching the upper limit will most likely impede
performance and should be avoided. Precisely how close to the upper limit can be tolerated depends
upon specific implementations and environments and so cannot be determined in advance.
XML Reserved Characters in Your XML Data
The following reserved character entities are approved for use in your XML data.
Reserved Character Entity
Produces
&amp;
Ampersand (&)
&lt;
Less-than symbol (<)
&gt;
Greater-than symbol (>)
&quot;
Quote (“)
&apos;
Apostrophe (‘)
Successfully Navigating XML in xPression
Note: Content in this section applies to xDesign only.
One of the issues with XML data sources that initially can be difficult to understand is how to
structure your XML file so that xPression can easily navigate through your data and successfully
access the desired records.
When looking at the visual structure of your XML data source, it can seem obvious as to how
xPression should access your records. However, because of the way xPression reads XML, you
cannot rely on xPression to know what you are looking for based on the inherent visual and physical
structure of the XML. You have to clearly tell xPression how to parse through the data as if it was
loaded into a relational structure.
The reason for this is that xPression processes XML data sources by first loading the data source
into a temporary relational structure. From there it accesses the data as indicated by the xDesign
document instructions.
23
Working With XML
This process dissolves the physical relationship among tables that the user can see. In order to
successfully navigate the XML using xPression, you should follow these design suggestions:
• Design your XML data source with unique keys at all levels
• Use this key structure as the method to access records
24
Working With XML
Here’s an example of a simple XML file to illustrate this point:
CustomerDelimiterNode)
(Root)
(RootKey)A1(/RootKey)
(Child1)
(Key)B1(/ Key )
(ParentKey)A1(/ ParentKey )
(Child2)
(Key)C1(/ Key )
(ParentKey)B1(/ ParentKey )
(Child3)
(Key)D1(/ Key )
(ParentKey)C1(/ ParentKey )
(/Child3)
(/Child2)
(Child2)
(Key)C2(/ Key )
(ParentKey)B1(/ ParentKey )
(Child3)
(Key)D2(/ Key )
(ParentKey)C2(/ ParentKey )
(/Child3)
(/Child2)
(/Child1)
(/Root)
(/CustomerDelimiterNode)
(CustomerDelimiterNode)
(Root)
(RootKey)A2(/RootKey)
(Child1)
(Key)B2(/ Key )
(ParentKey)A2(/ ParentKey )
(Child2)
(Key)C3(/ Key )
(ParentKey)B2(/ ParentKey )
(Child3)
(Key)D3(/ Key )
(ParentKey)C3(/ ParentKey )
( (/Child3)
(/Child2)
(Child2)
(Key)C4(/ Key )
(ParentKey)B2(/ ParentKey )
(Child3)
(Key)D4(/ Key )
(ParentKey)C4(/ ParentKey )
(/Child3)
(/Child2)
(/Child1)
(/Root)
(/CustomerDelimiterNode)
Remember that xPression takes the XML loads it into relational tables. If put into a relational
structure, the data above would look like this:
Table Name Root
Key
A1
A2
25
Working With XML
Table Name Child1
Key
ParentKey
B1
A1
B2
A2
Table Name Child2
Key
ParentKey
C1
B1
C2
B1
C3
B2
C4
B2
Table Name Child3
Key
ParentKey
D1
C1
D2
C2
D3
C3
D4
C4
To navigate to the correct child segment, you do not need keys for every parent in its hierarchy to
be located in the child segment itself. What you do need is to read the parent segment of that child
before reading the child itself, then access any children that match the parent key.
26
Working With XML
If you set up your READs this way (checking for end of file appropriately):
READ Child1 where Child1:ParentKey = Root:RootKey READ Child2 where Child2:ParentKey =
Child1:Key READ Child3 where Child3:ParentKey = Child2:Key
you will only get Child3 segments that match the desired Child2, which matched the desired Child1,
which matched the Root which you are currently processing.
This is the same logic you would use if your data was in a relational data source. This enables you
to switch your data sources from XML to relational data sources without having to change the
structure of your READ logic.
Dynamically Adding Unique Keys with a Reading
Definition
Unique keys do not have to physically exist in the sub-tables. They can be dynamically added
through the use of a reading definition. Using the example above:
For the table Child1, we added a field named ParentKey. Instead of physically adding this field to
your tables, you can add it dynamically through a reading definition as follows:
<Table name="Child1">
<RowXPath>/CustomerDelimiterNode/Root/Child1</RowXPath>
<Column name="KEY">
<ColumnXPath>Key</ColumnXPath>
<ColumnValue type="string">text()</ColumnValue>
</Column>
<Column name="PARENT_KEY">
<ColumnXPath>../RootKey</ColumnXPath>
<ColumnValue type="string">text()</ColumnValue>
</Column>
Notice that the bolded line includes the following decimal points: ..
You can use these decimal points to navigate an XML structure in the same manner as a DOS
directory structure. In this example, the two decimal points navigate up from the Child1 table to the
Root table. To navigate through more than one table, use the decimal points with forward slashes
as shown in the following example. This example demonstrates retrieving data from the Root table
from the Child3 table.
<Column name="PARENT_KEY">
<ColumnXPath>../../../RootKey</ColumnXPath>
<ColumnValue type="string">text()</ColumnValue>
</Column>
The first set of decimal points (../) navigates to the Child2 table. The next set navigates to the Child1
table, and the final set navigates to the Root.
You can also navigate down in the XML structure. This is most useful in situations where a nested
table appears only once in the XML structure. Because there are no repeating values, it does not
make sense to create another table in your table structure. A better solution is to pull the data up
into the parent table.
27
Working With XML
To demonstrate this, consider the following XML data:
<Delimiter>
<Root>
<Vehicle>
<Make/>
<Model/>
<Year/>
<TaxInfo>
<State/>
<County/>
</TaxInfo>
</Vehicle>
</Root>
</Delimiter>
In this example, the Taxinfo table only appears once for any given vehicle. You do not need to add
this data to its own TaxInfo table. A better solution is to simple add this information to the existing
Vehicle table.
To accomplish this for the above data, your reading definition would be as follows:
Table name="Vehicle">
<RowXPath>/Delimiter/Root/Vehicle</RowXPath>
<Column name="MAKE">
<ColumnXPath>Make</ColumnXPath>
<ColumnValue type="string">text()</ColumnValue>
</Column>
.
.
.
<Column name="STATE_TAXINFO">
<ColumnXPath>TaxInfo/State</ColumnXPath>
<ColumnValue type="string">text()</ColumnValue>
</Column>
<Column name="COUNTY_TAXINFO">
<ColumnXPath>TaxInfo/County</ColumnXPath>
<ColumnValue type="string">text()</ColumnValue>
</Column>
To navigate down in the XML structure, simply add the table name (TaxInfo) and then the field
name (State or County) in that table. This method effectively pulls the State and County Tax info
into the Vehicle table.
XML Differences with xPression Batch
xPression Batch uses a Customer Delimiter to mark the beginning and the end of one record or one
assembly. This feature ensures that during a batch run, xPression Batch will not retrieve data from
any other customer record.
However, even with this feature it is still possible to retrieve the wrong data within a customer
record. Using the same sample XML above, look at this example:
Let’s say you are positioned at Child2 with a key of C1. If you set up a loop to process all the Child3
segments for Child2 and fail to use a ParentKey value of C1, you would get Child2 segments with
keys of both C1 and C2.
28
Working With XML
You can avoid this by using the correct positioning (re-stated from above):
READ Child1 where Child1:ParentKey = Root:RootKey READ Child2 where Child2:ParentKey =
Child1:Key READ Child3 where Child3:ParentKey = Child2:Key
How Should I Set Up Complex XML Data
Sources?
There are several scenarios where your XML data might not conform to xPression’s standard data
source setup. In this section, we’ll present four different complex cases to illustrate how to get your
data to work with xPression. Because an xPression data source group can contain both RDB and XML
data sources, your XML data sources must follow a structure similar to a relational database.
This section covers the following sample cases:
• Case 1: How Can I Use XML Attributes With My Data Source?, page 29
• Case 2: How Can I Use A Table Defined in Several Locations?, page 33
• Case 3: How Can I Use XML Data With Mismatched Element Names?, page 36
• Case 4: How Can I Map Multiple Element Values to Multiple Columns?, page 38
Case 1: How Can I Use XML Attributes With My Data
Source?
Your XML data may contain elements with attribute/value pairs. If you want to use those attributes
as the basis for conditional rules in your documents, your schema must represent the attributes as
columns in a table. Additionally, you’ll need to map each column to an attribute value in the data
source.
29
Working With XML
Sample XML Data File
Let’s look at a sample XML data file with attributes:
The first thing you’ll notice about the XML is it contains a reference to an external XSD schema.
Unless you’re using an RDB schema, xPression only supports W3C-compliant XSD schemas. We’ll
take a look at the schema in a moment.
The CustomerAddress element has four attributes. The schema should therefore represent
CustomerAddress as a table with four columns: CustomerID, addressCode, streetType, and
residenceCode.
If you want to create conditional rules in your document, you must also establish a link between
the tables in your schema. In this example, we’re using CustomerID as the primary key in the
CustomerAddress table and as the foreign key in the Address table.
30
Working With XML
Sample Schema
Take a look at the ADDRESS table in the schema. Because this is the table that contains the main
customer data, it makes good sense to set it as primary. We also used both STREETNUMBER and
STREETNAME for the primary key. If you don’t set up a primary key, you won’t be able to assemble
documents in xPression.
Notice also that the attributes have been mapped to columns in the CUSTOMERADDRESS table.
If you don’t already have an XSD schema defined for your XML data source, you’ll need to generate
it on your own. For more information, see the World Wide Web Consortium (W3C) Web site:
http://www.w3.org.
Mapping the Data Source
Once you’ve created your data source group using an XSD schema in xAdmin, you then create your
XML data source, and map the columns in the schema to the attribute values in the data source. Let’s
take a closer look, using the example we’ve illustrated throughout this section.
When you create your XML data source, you should click Auto Map to generate your reading
definition. There should be no conflicts between the schema and the data source.
Then you save the data source and click the Mapping tab to map columns in the secondary table to
the attribute values in the XML data source. Each column in the CustomerAddress table maps to its
corresponding attribute value in the data source.
31
Working With XML
The Data Reading Definition
Once the attributes are mapped, your data source should be ready for use in
your applications. The following data reading definition shows how the data is
mapped.
32
Working With XML
Case 2: How Can I Use A Table Defined in Several
Locations?
Your data source might contain multiple instances of the same table name nested in different locations
throughout your XML. This presents a unique problem for xPression. Unless your duplicate table
names are in the same XPath location, you won’t be able to read data from all the tables. Therefore,
you’ll have to modify your data so you can use it in your xPression applications. In this section, we’ll
discuss this process, using sample data to illustrate.
Let’s look at a sample XML file that contains duplicate table names
.
Even though both Contact tables are nested in different locations in the XML, xPression would still
interpret them as the same table. The quickest solution is to rename the tables by appending them
33
Working With XML
with the names of the parent tables, then saving the XML data file with a different file name
.
After you’ve created the adjusted data file, you should generate an XSD schema for it.
34
Working With XML
Sample Schema
Let’s look at an example of the adjusted XSD
schema:
Tying It All Together
Now that you have the original XML, the adjusted XML, and the adjusted XSD schema, you can
create your data source group and data source. Follow the steps described in the xAdmin User Guide
to create your data source group. Be sure to use the adjusted XSD schema.
Creating the XML data source requires a few extra steps to ensure that xPression
reads your XML data correctly.
1.
Create an XML data source using the adjusted XML data file.
2.
Click Auto Map to generate the data reading definition. Save the data source.
3.
Copy the data reading definition and paste it into a text editor. Modify the RowXPath elements
that point to the adjusted table names by removing the appended parent table names. The
following example illustrates how you do this.
35
Working With XML
Notice how the table names still use the adjusted names in your schema. Your data will use its
original structure, but xPression will display the tables with the adjusted names.
4.
Copy the data reading definition you’ve just modified and paste it back into the text window in
xAdmin. You can also save the data reading definition as an XML file and store it on your server
in [drive:][path] \xPression\CustomerData\ReadingDef. Instead of pasting the data reading
definition into the text window, click Get Reading Definition, and select the file you just saved.
5.
Now modify the Customer Data Location to point to the original XML data file. Save the data
source.
You can now use the data source in xPression without compromising the integrity of your original
XML data.
Case 3: How Can I Use XML Data With Mismatched
Element Names?
Your XML data might not conform to the structure laid out in your schema. Because XML has no
rules governing how you structure your data, you can present it in the most human readable format.
This can create problems when trying to assign your XML to a data source group in xAdmin. In
this section, we’ll discuss how you can set up a data reading definition to enable you to map your
XML data to your schema.
Sample Schema
Let’s look at a sample schema to illustrate the
issue:
36
Working With XML
The schema has a single table: EMPLOYEE. EMPLOYEE is the primary table and
EMPLOYEENUMBER is the primary key. This seemingly simple setup gets more complicated when
we look at the XML data we want to use for this schema.
Sample XML Data File
Here’s a sample XML
file:
The first thing you’ll notice is there are no column names and values, only DataItem elements with
nested Field and Value elements. It’s definitely easy to read, but the structure won’t work with the
existing schema. To fix it, we’ll need to create a data reading definition to map the Field elements to
actual columns in the schema.
37
Working With XML
Sample Data Reading Definition
Now let’s look at a simple data reading definition that resolves our problem
.
Usually, ColumnXPath statements point to the location in the XML where column names appear.
In our example, they point to values because that’s how the XML is structured. Using this approach
ensures that the XML data source is properly mapped to its schema. The conclusion we can draw
from this example is your XML structure can vary greatly from your schema. As long as your data
reading definition properly maps elements to tables and columns in your data source group, you’ll be
able to use your data in xPression.
Case 4: How Can I Map Multiple Element Values to
Multiple Columns?
Your XML data might contain multiple distinct data fields passed in a single XML element. Since
xPression interprets these fields as a single value, you’ll need to modify your schema and data
reading definition to map the values to separate columns.
XML Data File Sample
Let’s look at the following XML
sample:
38
Working With XML
When you add a data source group whose schema is in an XSD file, and Auto
Map the nodes in the schema to the tables in your data source, you’d see the
following in the CustomerData table. xPression creates this data reading definition
file:
If you want to use the data that’s nested in fields with the separator, you need to manually split the
data into several columns. The next section describes how to do that.
Splitting the Data
To split data successfully, you must know the exact number of values. In our example, this means it
should always have five words in the <Special> tag:
<Special>Today | is | my | first | day</Special>
To split data:
1.
Select the Special field and click Delete to remove it.
2.
Use xAdmin to add five new fields to host the data.
3.
Delete <Column name=”Special”> in the original data reading definition and replace it with the
highlighted material shown here:
39
Working With XML
The original reading definition with new
data.
4.
Each of the new fields you added are now defined in the XML Data Reading Definition. When
adding this type of information to the ReadingDef you must make sure that the attribute
<ColumnValue isMultiple > in the XMLReadingDef is set to True.
5.
We also added a new element, <MultiValuesDef>, to define the delimiter and position of the data.
At the beginning of this exercise we showed the pipe character as the separator for each of the
data groupings, or words, in the original Special field. That separator is identified between the
<MultiValuesDelimiter> tags:
<MultiValuesDelimiter>|<MultiValuesDelimiter>
40
Working With XML
The value between the <Position> tags identifies the location of the data you want to read. For
instance, to read the first grouping of data, or first word, you would identify the location as
Position 0, to read the second the Position is 1: <Position>0<Position>
41
Working With XML
42
Chapter 4
Setting Up User Exits
An XML user exit enables you to supply data to xPression from any source, such as flat files,
VSAM files, and other non-JDBC databases. The XML user exit is a JAVA abstract class named
UserExitDataReader. From this abstract class you must create a custom JAVA class that extracts data
from a given source and provides it to xPression in the supported XML format.
The UserExitDataReader Abstract Class
The JAVA abstract class provided by Document Sciences is UserExitDataReader. The user exit class
you create must be derived from this abstract class and must implement the init() and getOneRecord()
methods.
The UserExitDataReader class is defined as follows:
package com.docscience.userexitlib.customerdatareader;
import java.util.HashMap;
/**
* The UserExitDataReader abstract class will be used by
* customers to create their own classes for reading data
* from data sources not supported by xPression
*/
public abstract class UserExitDataReader {
protected boolean bInit;
/**
* UserExitDataReader constructor
*/
public UserExitDataReader() {
bInit = false;
}
public void init(HashMap parameterList) throws Exception {
bInit = true;
}
/**
* getOneRecord
*
* @return
* getOneRecord method returns a string of XML data
* if the return value is null, it is assumed there is no more data to read
*/
public abstract String getOneRecord() throws Exception;
}
43
Setting Up User Exits
The following two public methods are declared in the abstract class.
UserExitDataReader.getOneRecord()
This method returns an XML stream that contains one complete customer delimited record in a
format that matches the XML schema and data reading definition defined for the data source. For
example, your data reading definition should define a customer delimiter definition:
<CustomerDelimiter node="Transaction" XPath="/CustomerData/Transaction"/>
This completed delimited record will appear in your XML schema as follows:
<CustomerData> <Transaction> </Transaction> </CustomerData>
All the data that appears between the CustomerData tag and its end tag (</CustomerData>) is
considered one delimited record. This method must return an XML stream that consists of one
customer delimited record. To get all the customer records for both batch and xPression client
applications, the xPression Server code will call getOneRecord() within a loop until the method
returns null.
Syntax: void init(HashMap parameterList) throws Exception
Description: init() should perform any initialization tasks required before getOneRecord() is called.
Parameters (1): parameterList
a java.util.HashMap that contains java.lang.String objects. There is one entry in the hash table for
each parameter defined to the parameter list in xAdmin. The values are keyed by the "name" value
defined in xAdmin.
Return Values: none
UserExitDataReader.init()
This method is called once prior to the getOneRecord() loop and should take care of all initialization
tasks. This method initializes the class before data is read into the character array. This method has a
parameter list that contains all of the parameters you defined in the data source page in xAdmin.
These parameters can include any information that you want to pass to the class. The parameter list
enables you to generalize the code for your user exit by allowing you to pass specific data to the
code as an initialization parameter.
Syntax:java.lang.String getOneRecord() throws Exception
Description: getOneRecord() should return one complete customer record formatted according to
the reading definition defined to the data source.
Parameters: (none)
Return Values:
null = no more data to read valid java.lang.String with length > 0 = valid data read
44
Setting Up User Exits
Implementing the Custom JAVA Class
Please pay special attention to the following list of requirements and constraints:
• getOneRecord() Method
• init() Method
• No Timeout Setting
• Packaging Your Class
• Add Paths to Application Server
• Classpaths
getOneRecord() Method
Please remember that this method must return an XML stream consisting of a single complete
customer delimited record that matches the XML format specified in the data reading definition
and the XML schema.
init() Method
This method is called only once and is called before the getOneRecord method. All initialization
tasks should be implemented by this method.
No Timeout Setting
The UserExitDataReader abstract class is not supplied with a timeout setting. This means that if your
code produces an infinite loop, the process will not timeout and your server will become inoperable.
Packaging Your Class
To enable the xPression server to load the data reading class, you should place the user exit classes
that you create in their own .jar file. The xPression_UserExit.jar file must be set as a dependency
library for your user exit .jar.
Add Paths to Application Server
The path to your user exit .jar file must be placed in two locations:
First, the path must appear in your application server classpath.
45
Setting Up User Exits
Second, the path must be defined in the class path for any batch command script that you are using.
Classpaths
The classpath for your new user exit should be unique. Do not use the classpath for the user exit
abstract class.
Sample Custom User Exit
The following sample user exit is highly simplified and meant to provide a starting point for
developers. This class reads each customer’s XML data from a different file and loads it into a string
buffer for use by xPression.
package com.docscience.xpression.userexit.test;
import com.docscience.userexitlib.customerdatareader.*;
import
import
import
import
java.io.BufferedReader;
java.io.FileInputStream;
java.io.InputStreamReader;
java.util.HashMap;
public class UserExitTest extends UserExitDataReader {
private int iReadCount;
private String strFirstFile;
private String strSecondFile;
private int BUFSIZE = 5000;
public UserExitTest() {
super();
iReadCount = 1;
}
public void init(HashMap parameterList) throws Exception {
// verify paramter list passed correctly
strFirstFile = (String)parameterList.get("firstFile");
strSecondFile = (String)parameterList.get("secondFile");
}
public String getOneRecord() throws Exception {
String strRet = null;
String strFile = null;
int readCount = -1;
BufferedReader fileReader = null;
boolean eof = false;
StringBuffer sbuf = new StringBuffer();
char[] buf = new char[BUFSIZE];
if (iReadCount == 1) strFile = strFirstFile;
if (iReadCount == 2) strFile = strSecondFile;
if (iReadCount < 3) {
try {
46
Setting Up User Exits
fileReader = new BufferedReader(new InputStreamReader(new FileInputStream
(strFile), "UTF-8"));
} catch (Exception e) {
//throw new XMLCRRInvalidFilePathException(4456, e);
}
while (eof == false) {
if ((readCount = fileReader.read(buf, 0, BUFSIZE)) > 0) {
if (readCount < BUFSIZE)
sbuf.append(buf, 0, readCount);
else
sbuf.append(buf);
} else {
eof = true;
}
}
if (sbuf.length() != 0) strRet = sbuf.toString();
}
iReadCount = iReadCount + 1;
return strRet;
}
}
47
Setting Up User Exits
48
Chapter 5
Migration
This chapter discusses scheduling migrations and running migrations from the command line:
• Migrating Documents from the Command Line
• Migrate a Job Definition from the Command Line
• Migrating Output Profiles from the Command Line
• Importing and Exporting Work Items , page 58
• Scheduling a Migration
• Command Line Migration Error Codes
Migrating Documents from the Command Line
xPression enables you to import and export documents from the command line interface. For these
steps you must set up your MigrationServer.xml, page 49 file and Create a Migration Specification,
page 50 before you can Run a Command Line Migration, page 52.
A migration specification is an XML formatted list of documents to export. After creating your
migration specification, proceed to Run a Command Line Migration, page 52 to execute migrate
from the command line.
Document Metadata
If your document contains Catalog or xPressForms document metatdata, the import, export, and
migrate functions will automatically include the metadata with the document. The metadata will
belong to the selected package, and will not take into consideration different versions of the package.
MigrationServer.xml
Before you can migrate your documents, you must set up your MigrationServer.xml file. This file
provides xPression with connection information for the servers you are migrating to. The servers you
configure in this file will appear in the Target Server list.
49
Migration
Your MigrationServer.xml file resides in the xPression installation directory on the server that
contains the source output profiles. The syntax of MigrationServer.xml is as follows:
<ServerList>
<Server name="xpression server 1" url="http://12.64.121.45:9081" context=”/
xAdmin” uid="" password="" socketport="5678" />
<Server name="xpression server 2" url="http://12.64.121.25:9081" context=”/
xAdmin” uid="" password="" socketport="5678" />
</ServerList>
Add the following parameters to your MigrationServer.xml.
Parameter
Definition
Server name
Type a descriptive server name for your target server. This is the server name that will
appear in the server list on the migration and export tabs.
url
Type the entire URL for your target server followed by a colon (:) and the port number.
For example:
"http://12.64.121.45:9081"
context
If the target server is an earlier version of xPression (version 2.1.2 or earlier) the value
should be xPression Admin. For example:
context=”/xPression Admin”
If the target server is version 2.5 or higher, the value should be xAdmin. For example:
context=”/xAdmin”
uid
If a user ID is required to access your server, supply the user ID here.
password
If a user ID is required to access your server, supply the user ID password here.
socketport
Type the socketport number for your target server.
Save your MigrationServer.xml file and restart the server. You should now be able to see the
descriptive name of your target server in the Target Server drop-down box.
Create a Migration Specification
The parameters of the migration specification are defined as follows:
• PdpFile name — The location and file name of the zipped PdpFile. During migration, xPression
will create the PDP file using the supplied name and stream the PDP to the target server. xPression
saves a copy of the PDP file to the location defined here. During export, xPression saves the PDP
file to this location. During import, xPression retrieves the PDP file from this location.
• Server name — For use with migration only. The name of the target server and the URL of its
location. If your package contains category information, you can set the isCheck attribute of
this parameter to true to check whether it is safe to overwrite the existing data source schema.
xPression will generate a warning if the existing schema contains fields used by output variables.
• Object type — A variable that defines the object type and name properties of the document. Object
types copy the names for the attribute set, data source group and category from the originating
50
Migration
document to the content repository on the target server. If you are migrating more than one
document, the properties for each document will be included here.
• Document name — The name of the document to migrate. Each document included in the
migration will have a separate Document name entry. toCat = the name of the category on the
target server that will receive the migrated document. whichObj = defines which objects you
want to migrate. You must set whichObj to one of the following values: Approved to migrate only
approved objects, or All to migrate all approved and non-approved objects. incfont = Choose Yes
or No to migrate your fonts from the development to production environments.
Sample
The following sample shows a migration specification that migrates a document from one server to
another with included category information.
<?xml version="1.0" encoding="UTF-8" ?>
<MigrationSpec>
<PdpFile name="C:\Temp\MigrationPDP.zip" />
<Server name=”prodserve” url=”http://prodserve:9080” context="/xAdmin"
uid="xpression" password="xpression" socketport="5678" isCheck="true" />
<Object type=”attrset” name=”US REGULATORY” />
<Object type=”datasourcegroup” name=”Migrate Test Document” />
<Object type=”category” name=”Migrate Test Document” />
<Document name="Migrate Test Document" toCat="CAT1" whichObj="all" incfont=”no”
/>
</MigrationSpec>
In this example, xPression will create the PDP file (MigrationPDP.zip) and send it to the target
server idenitifed by the server name parameter. All category information will be migrated, but
fonts will not be included.
Sample
The following sample shows a migration specification that exports a document to a network location.
<?xml version="1.0" encoding="UTF-8" ?>
<MigrationSpec>
<PdpFile name="C:\Temp\MigrationPDP.zip" />
<Document name="Migrate Test Document" id=”7” cat_id=”2” whichObj="all" toCat=
"CAT1"
incfont=”no” />
</MigrationSpec>
In this example, xPression creates the PDP file (MigrationPDP.zip) and saves it to the defined location.
You can create a migration specification using two methods:
• Easy Method - Log in xAdmin, click Utilities > Migrate and select xPression document as the
migration type. Fill in the options on the page, but click Save instead of Start. When you click
Save, xPression saves the migration specification to the location you specified. If you want to
migrate documents, add the user name and password information for the target server in the
51
Migration
saved migration specification. If you want to export documents, removed the Server name
parameter in the saved migration specification.
• Manual Method - Create a new XML file with an XML editor or text editor. Create your
specification using the parameters described above and save the file to a network location
accessible by the xPression Server.
Run a Command Line Migration
Open a command window and navigate to the xPressionHome directory.
Type the Migrate command with the export parameter. The migrate command syntax is:
Migrate export migration_spec
where migration_spec is the path and filename of the migration spec you created in Create a Migration
Specification, page 50.
For example:
C:\xPression>migrate export C:\xPression\MigrationSpec.xml
Export from the Command Line
To export your documents, open a command window and navigate to the xPressionHome directory.
Type the Migrate command with the export parameter.
Migrate export migration_spec
where migration_spec is the path and filename of the migration spec you created in Create a Migration
Specification, page 50. Do not include the Server name parameter in your migration specification
when you export documents.
For example:
C:\xPression>migrate export C:\xPression\MigrationSpec.xml
You can use the -o parameter with the export command. The -o parameter enables you to override
existing documents. See Overwriting Documents on the Target Server, page 53 for more information.
52
Migration
Import from the Command Line
To import a document, open a command window and navigate to the xPressionHome directory.
Type the Migrate command with the import parameter.
Migrate import PDP_path
where PDP_path is the name and path to the PDP file you want to import.
For example:
C:\xPression>migrate import C:\migrationPDP.zip
If there is an error during the document import process that causes the migration to stop, all the data
already migrated to the content repository should be clean.
You can use the -i and -o parameters with the import command. The -i parameter enables you to
ignore errors about field usage conflicts. See Overriding Category Info, page 61 for more information.
The -o parameter enables you to override existing documents. See Overwriting Documents on the
Target Server, page 53 for more information.
Overwriting Documents on the Target Server
You can overwrite the files on the target server using the -o parameter as in this example:
Migrate import -o "c:\\uniarch\\migtest.zip"
This parameter works with both import and export. If the parameter is not used, the server will
generate an exception when a file with the same name is found.
Note: We do not recommend to use the -o parameter for the
migrate.bat/.sh import
command as xPression does not overwrite the xPresso documents and document versions neither
using the xAdmin nor the command line migration to prevent invalidation of the document version
history.
Migrate a Job Definition from the Command
Line
Before you can migrate a job definition using the command line, you must Create a Migration
Specification, page 53. You do not need a migration specification to import PDPs from the command
line.
Create a Migration Specification
The parameters of the migration specification are defined in the following table.
53
Migration
Parameters
Definitions
PdpFile name
The location and file name of the zipped PdpFile.
During migration, xPression will create the PDP file using the supplied name
and stream the PDP to the target server. xPression saves a copy of the PDP file
to the location defined here.
During export, xPression saves the PDP file to this location.
During import, xPression retrieves the PDP file from this location.
Server name
For use with migration only. The name of the target server and the URL of its
location. You can set the isCheck attribute of this parameter to true to check
whether there is any job definition or output profile conflicting with the job
definitions or output profiles in the target xPression repository. xPression will
generate warning messages if there are conflicting items.
JobDef name
The name of the output profile to migrate.
IncludeOutputProfile
Enables you to migrate all output profiles associated with the selected job
definition(s).
Sample
The following sample shows a migration specification that migrates job definitions from one server
to another.
<?xml version="1.0" encoding="UTF-8"?>
<MigrationSpec>
<PdpFile name="C:\MigrationPDP.zip" />
<Server name=”xPressionServer” url=”http://localhost:8080” context="/xAdmin"
uid="xpression" password="xpression" socketport=”5678” />
<JobDef name="Policy Recipients" />
<IncludeOutputProfile> 1 </IncludeOutputProfile>
</MigrationSpec>
In this example, xPression will create the PDP file (MigrationPDP.zip) and send it to the target
server idenitifed by the server name parameter.
Sample
The following sample shows a migration specification that exports a job definition to a network
location.
<?xml version="1.0" encoding="UTF-8" ?>
<MigrationSpec>
<PdpFile name="C:\Temp\MigrationPDP.zip" />
<JobDef name="Policy Recipients"/>
</MigrationSpec>
In this example, xPression creates the PDP file (MigrationPDP.zip) and saves it to the defined location.
54
Migration
You can create a migration specification using two methods:
• Easy Method - Log in xAdmin, click Utilities > Migrate and select job definition as the migration
type. Fill in the options on the page, but click Save instead of Start. When you click Save,
xPression saves the migration specification to the location you specified. If you want to migrate
job definitions, add the user name and password information for the Server name parameter
in the saved migration specification. If you want to export job definitions, removed the Server
name parameter in the saved migration specification.
• Manual Method - Create a new XML file with an XML editor or text editor. Create your
specification using the parameters described above and save the file to a network location
accessible by the xPression Server.
Migrate a Job Definition from the Command Line
To migrate job definitions, open a command window and navigate to the xPressionHome directory.
Type the MigrateJobDef command with the export parameter.
MigrateJobDef.bat export migration_spec
where migration_spec is the path and filename of the migration spec you created in Create a Migration
Specification, page 50. Make sure the target server information is included in the migration
specification.
For example:
C:\xPression>MigrateJobDef.bat export C:\xPression\MigrationSpec.xml
Export a Job Definition from the Command Line
To export your job definitions, open a command window and navigate to the xPressionHome
directory.
Type the MigrateJobDef command with the export parameter.
MigrateJobDef.bat export migration_spec
where migration_spec is the path and filename of the migration spec you created in Create a Migration
Specification, page 50.
For example:
C:\xPression>MigrateJobDef.bat export C:\xPression\MigrationSpec.xml
Import a Job Definition from the Command Line
To import job definitions, open a command window and navigate to the xPressionHome directory.
Type the MigrateJobDef command with the import parameter.
MigrateJobDef.bat import PDP_path
where PDP_path is the name and path to the PDP file you want to import.
55
Migration
For example:
C:\xPression>MigrateJobDef.bat import C:\migrationPDP.zip
You can use the -i parameter with the import command. The -i parameter enables you to ignore
errors about field usage conflicts. See Overriding Category Info, page 61 for more information.
Migrating Output Profiles from the Command
Line
Before you can migrate an output profile using the command line, you must Create a Migration
Specification, page 50. You can manually create a migration specification as shown below. You do not
need a migration specification to import PDPs from the command line.
Create a Migration Specification
The parameters of the migration specification are defined in the following list.
• PdpFile name — The location and file name of the zipped PdpFile. During migration, xPression
will create the PDP file using the supplied name and stream the PDP to the target server. xPression
saves a copy of the PDP file to the location defined here. During export, xPression saves the PDP
file to this location. During import, xPression retrieves the PDP file from this location.
• Server name — For use with migration only. The name of the target server and the URL of its
location. You can set the isCheck attribute of this parameter to true to check whether there is any
output profile conflicting with the output profiles in the target xPression repository. xPression
will generate warning messages if there are conflicting items.
• Output Profile name — The name of the output profile to migrate.
Sample
The following sample shows a migration specification that migrates output profiles from one server
to another.
<?xml version="1.0" encoding="UTF-8"?>
<MigrationSpec>
<PdpFile name="C:\MigrationPDP.zip" />
<Server name=”xPressionServer” url=”http://localhost:8080” context="/xAdmin"
uid="xpression" password="xpression" socketport=”5678” />
<OutputProfile name="Encrypted PDF" />
<OutputProfile name="Metacode To File" />
<OutputProfile name="PDF" />
<OutputProfile name="PDF Project" />
<OutputProfile name="PDF Return to Application" />
</MigrationSpec>
In this example, xPression will create the PDP file (MigrationPDP.zip) and send it to the target
server idenitifed by the server name parameter.
56
Migration
Sample
The following sample shows a migration specification that exports an output profile to a network
location.
<?xml version="1.0" encoding="UTF-8" ?>
<MigrationSpec>
<PdpFile name="C:\Temp\MigrationPDP.zip" />
<Output profile name="PDF Return to Application"/>
</MigrationSpec>
In this example, xPression creates the PDP file (MigrationPDP.zip) and saves it to the defined location.
You can create a migration specification using two methods:
Easy Method - Log in xAdmin, click Utilities > Migrate and select output profile as the migration
type. Fill in the options on the page, but click Save instead of Start. When you click Save, xPression
saves the migration specification to the location you specified. If you want to migrate output profiles,
add the user name and password information for the Server name parameter in the saved
migration specification. If you want to export job definitions, removed the Server name parameter
in the saved migration specification.
• Manual Method - Create a new XML file with an XML editor or text editor. Create your
specification using the parameters described above and save the file to a network location
accessible by the xPression Server.
Migrate an Output Profile from the Command Line
To migrate output profiles, open a command window and navigate to the xPressionHome directory.
Type the MigrateOutputProfile command with the export parameter. The migrate command
syntax is:
MigrateOutputProfile.bat export migration_spec
where migration_spec is the path and filename of the migration spec you created in Create a Migration
Specification, page 50. Make sure the target server information is included in the migration
specification.
For example:
C:\xPression>MigrateOutputProfile.bat export C:\xPression\MigrationSpec.xml
Export an Output Profile from the Command Line
To export output profiles, open a command window and navigate to the xPressionHome directory.
Type the MigrateOutputProfile command with the export parameter. The export command
syntax is:
MigrateOutputProfile.bat export migration_spec
where migration_spec is the path and filename of the migration spec you created in Create a Migration
Specification, page 50.
For example:
57
Migration
C:\xPression>MigrateOutputProfile.bat export C:\xPression\MigrationSpec.xml
Import from the Command Line
To import output profiles, open a command window and navigate to the xPressionHome directory.
Type the MigrateOutputProfile command with the import parameter.
MigrateOutputProfile.bat import PDP_path
where PDP_path is the name and path to the PDP file you want to import.
For example:
C:\xPression>MigrateOutputProfile.bat import C:\migrationPDP.zip
You can use the -i parameter with the import command. The -i parameter enables you to ignore
errors about field usage conflicts. See Overriding Category Info, page 61 for more information.
Importing and Exporting Work Items
To export a work item from the command line, see Export a Work Item from the Command Line,
page 58. To import a work item from the command line, see Import a Work Item from the Command
Line, page 59. There is no migrate command for work items.
Criteria File
To export or migrate work items from the command line, you first need to select the work items. You
can create an XML file to specify the work item IDs that you want to export. Supply the path and
filename of the XML file in the Criteria File parameter when exporting or importing work items. For
sample criteria files, see Sample Criteria Files , page 59.
Export a Work Item from the Command Line
To export a work item:
1.
Open a command window and navigate to the xPressionHome directory.
2.
Type the MigrateWIP command with the export parameter:
MigrateWIP.bat export
3.
After the export command, add the criteria file parameter followed by the path and file name of
the criteria file. For more information about the Criteria File, see Criteria File , page 58.
-c <path>
4.
After the criteria file parameter, add the PDP file path parameter followed by the path to the
location where you want to save the PDP file.
-p <path>
58
Migration
5.
After the PDP file path, add the Migration Spec parameters followed by the path to the location
where you want to save the migration specification. This parameter provides for the creation of
the migration specification and the migration_docinfo.xml file.
After the PDP file path, you can optionally add Migration Spec parameters. You can add the
following parameters:
•
-s <path>
— provides for the creation of the migration specification at the specified location.
•
-i<path>
— provides for the creation of the migration_docinfo.xml file.
6.
Press Enter to start the export. The export generates the following three files:
• migration.pdpx
• migration_spec.xml
• migration_docinfo.xml
Import a Work Item from the Command Line
To import a work item:
1.
Open a command window and navigate to the xPressionHome directory.
2.
Type the MigrateWIP command with the import parameter:
MigrateWIP.bat import
3.
After the import command, add the PDP file path parameter followed by the path to the location
where you want to save the PDP file.
-p <path>
4.
You can optionally use the -s parameter to supply a migration specification.
-s <path>
5.
Press Enter to start the Import.
Sample Criteria Files
The following example shows a sample criteria file for selecting work items by ID.
<WorkItems>
<ID>12</ID>
<ID>7</ID>
<ID>204</ID>
<ID>90</ID>
</WorkItems>
The following example shows a sample criteria file that searches for work items based on criteria.
<?xml version="1.0" encoding="UTF-8"?>
<SEARCHCRITERIA isCompleted="false">
59
Migration
<SECTION>
<PHASE>
<DOC_NAME>
<VALUE>insurance</VALUE>
</DOC_NAME>
</PHASE>
<AND />
<PHASE>
<CURRENT_STATE>
<VALUE>approved</VALUE>
</CURRENT_STATE>
</PHASE>
</SECTION>
<AND />
<SECTION>
<PHASE>
<DATERANGE>
<ABSOLUTE>
<OLDER>12-12-11</OLDER>
</ABSOLUTE>
</DATERANGE>
</PHASE>
</SECTION>
<ORDERBY>
<VALUE>CATEGORY_NAME</VALUE>
</ORDERBY>
</SEARCHCRITERIA>
Scheduling a Migration
To schedule an unattended migration:
1.
Create a migration specification.
2.
Create a batch file (Windows) or script (UNIX) that contains the Migrate command. The
command should use the export parameter and reference the migration specification created
in step one. For example:
Migrate export C:\xPression\MigrationSpec.xml
3.
Schedule the batch file or script to run using the scheduling facilities of your operating system.
Sample Migration DTD
If you are creating manual migration specifications, you can use the Migrate DTD with an XML
development tool like XML Spy to make sure you have created a valid specification.
<?xml version="1.0" encoding="UTF-8"?>
<!--xPression Migration document types-->
<!ELEMENT MigrationSpec (TargetSystem?, PdpFile, LogFile, Document+)>
<!ELEMENT TargetSystem EMPTY>
<!ATTLIST TargetSystem
host CDATA #REQUIRED>
<!ELEMENT PdpFile EMPTY>
<!ATTLIST PdpFile
name CDATA #REQUIRED>
<!ELEMENT LogFile EMPTY>
60
Migration
<!ATTLIST LogFile
name CDATA #REQUIRED>
<!ELEMENT Document EMPTY>
<!ATTLIST Document name CDATA #REQUIRED
whichObj (approved | all) "all"
toCat CDATA #REQUIRED
sourceProductID CDATA #IMPLIED>
<!-- sourceProductID is set and used internally by Migration Utility only -->
The elements and parameters of the Migrate DTD are defined as follows.
Element
Definition
Server
Contains information on the target server.
name = A user_readable name.
url = The target server URL.
uid = The User ID for EJB security.
password = The password for EJB security.
serveletURL = An alternate URL in case the URL is RMI.
PdpFile
Identifies the filename and path to the PDP file.
name= The path and filename of the PDP file.
Document
Contains information about a document being migrated.
name = The exact document name as it appears in xDesign.
whichObj = Defines which objects you want to migrate. You must set whichObj to one
of the following values:
Approved to migrate only approved objects.
All to migrate all approved and non-approved objects.
toCat = The target category name for import. This element parameter defaults to the
source category name which is automatically read from the source content repository.
Overriding Category Info
If you are importing a PDP with category information that overrides the data source schema by
removing fields that are in use by output variables, xPression will display the following information:
• An Error indicating that the contents of the PDP conflict with the contents in the target
environment.
• A list of fields in the current data source that will be removed by the import override, but are
currently in use by output variables.
• A list of fields in the current data source that will be changed by the import override, but are
currently in use by output variables.
61
Migration
You can add the -i parameter to the migrate command to instruct xPression to ignore the errors and
override the existing data source. For example:
Migrate import -i -o "C:\\migtest.zip"
Command Line Migration Error Codes
xPression returns three error codes for command line migration:
• 0 = Success
• 1 = Warning
• 2 = Errors
If you receive warnings or errors, please see the migration logs.
62
Chapter 6
Working With Bar Codes
xPression enables you to reuse your bar codes across different products by placing bar code
definitions outside of the document creation process. You add completed bar code definitions to your
documents by associating the bar code with an output stream. You can use conditional logic on the
bar code to place it on the correct page in the correct document.
You need to create separate bar code definitions for each placement of a bar code. For example, if you
want to place the same bar code for a health care policy form number in two different locations on
your document, you need to use two separate bar code definitions. However, you can reuse these bar
code definitions as many times as you want, as long as the definition is the same.
xPression supports these bar code formats:
• 3 of 9
• 2 of 5 Interleaved
• Code 128
• PostNet
• OMR
• PDF 417
• DataMatrix (xPublish only)
The procedure for implementing bar codes depends on your publisher. See the xAdmin User Guide for
instructions on creating bar codes.
Check Characters
Check characters are additional characters appended to bar codes to guarantee good reads. Check
characters are necessary on some bar codes that are prone to human error. For example, Interleaved 2
of 5 is a very dense, numeric-only bar code, but it is prone to substitution errors. You should always
use check characters with this code. Other codes, such as Code 128 and Code 3 of 9, are self-checking
and seldom require a check character.
63
Working With Bar Codes
Bar Code Errors
If you define data in your bar code that contains illegal characters, xPression replaces the illegal
characters with a zeros and issues a warning in the log file. However, if your bar code includes
human readable text, xPression still prints the human readable text with the illegal data you entered.
For example, if you create a Code 128 bar code using character set A, and you define “abcdef” as the
input data, xPression converts “abcdef” to zeros and encodes it in the bar code, but prints “abcdef”
for the human readable text. You can use this feature to debug bar codes that produce errors.
Caution: Additionally, the dollar sign ($) character is not supported for use in xPression bar
code data.
xPression 1-D Bar Code Support
xPression supports several versions of one-dimensional (1-D) bar codes. xPression assumes all
supported 1-D bar codes are font-based. It is your responsibility to provide the appropriate font
for the bar code and ensure that the font is included in the font database and the widths file used
for your job.
Caution: xPression does not support the AFP BCOCA font format.
3 of 9 Bar Codes
Code 3 of 9 was developed by Intermec in the 1970’s. It’s widely used for warehouse management
and general product labelling. In some countries, (for example, Germany) the code is used to identify
pharmaceuticals. The code is an alphanumeric bar code also commonly called LOGMARS or Code 39.
In Code 3 of 9 bar codes, each encoded data character is made up of five bars and four spaces for a
total of nine elements. Code 3 of 9 is called a binary code because each bar or space is either "wide" or
"narrow". It gets its name from the fact that 3 out of the 9 elements are always wide.
The symbol includes the start character, the encoded data, and the stop character. xPression
automatically encodes a 3 of 9 bar code with the correct start and stop characters.
The character set for Code 3 of 9 bar codes encodes 26 uppercase letters, 10 digits, and 7 special
characters. It can be extended to code all 128 ASCII characters by using a two character coding
scheme similar to using a shift key on a typewriter.
See Bar Code Character Tables, page 70 for Code 3 of 9 character tables.
64
Working With Bar Codes
2 of 5 Interleaved Bar Codes
Interleaved 2 of 5 is a a high-density numeric bar code type that can only encode numbers. It is also
referred to as USS ITF 2/5, ITF and I-2/5. The bar code symbol can be as long as necessary to store
your encoded data, however it can only encode an even number of digits. The code can hold up to
18 digits per inch when printed using a 7.5 mil X dimension. A check digit is optional but highly
recommended.
xPression supports only the 2 of 5 Interleaved bar code. It does not support the regular 2 of 5 bar
code. In each bar code character there are five bars (two of which are wide), and five spaces (two
of which are wide). It is "Interleaved" because one digit is encoded in the bars and the next digit is
encoded in the spaces. Each character encodes two digits of data.
xPression automatically encodes 2 of 5 Interleaved bar codes with the correct start and stop
characters. If you define bar code data with characters other than digits, xPression replaces the
characters with zeroes and issues a warning in the log file. xPression also adds a zero to the left of
data that does not contain an even number of digits. You can include a Modulus-10 check in your
2 of 5 Interleaved bar code.
Code 128 Bar Codes
Code 128 is widely used for warehouse management, in the transport industry (UPS and Fed Ex), and
in retail as Code 128 EAN / UCC. It is also referred to as SSCC-18 and SCC-14. Code 128 is a very
high-density alpha-numeric symbology with 106 different printed bar code patterns.
Code 128 is a higher density bar code that requires a checksum to be calculated. It can be difficult
to use if you are not a technical user. The bar code symbol can be as long as necessary to store the
encoded data. Although it is designed to encode all 128 ASCII characters, it uses less space than
other 1-D bar codes.
Code 128 is a very high density alphanumeric bar code. Each data character encoded in a Code 128
symbol is 11 times the width of the narrowest bar (x-dimension). The stop character, however, is 13
times the width of the narrowest bar.
Each character consists of 3 bars and 3 spaces, each of which may be between 1 and 4 x-dimensions
wide.
xPression automatically encodes Code 128 bar codes with the correct start and stop characters,
as well as the required Modulus-103 check character. See Bar Code Character Tables, page 70 for
Code 128 character tables.
65
Working With Bar Codes
PostNet Bar Codes
The POSTNET (POSTal Numeric Encoding Technique) bar code font was developed by the US
Post Office to encode zip code information. Some US Post Offices offer a discount for sending bulk
mail when you use the POSTNET bar code font.
The code contains two frame bars (one at the beginning and one at the end), combinations of five long
and short bars for each of the ZIP code digits, and five more long and short bars for the check digit.
Each digit from zero to nine is a unique pattern of long and short bars.
POSTNET is a demanding bar code symbology because it has size and placement requirements. It
cannot be reduced or enlarged. Bar width, height, and spacing are fixed.
If you define data in your bar code that is longer than what is allowed by the type of POSTNET bar
code you choose, xPression truncates the data to the appropriate size and issues a warning in the log
file. If you define bar code data that is shorter than allowed, xPression appends zeroes to the right
end of the bar code to make it the appropriate size and issues a warning in the log file.
You can define your POSTNET bar code to be a ZIP (five digit), ZIP+4 (nine digit), or DPBC (eleven
digit delivery point) bar code.
Zip Five Digit Bar Code
Like all POSTNET bar codes, the code contains two frame bar, one at the beginning and one at the
end, combinations of five long and short bars for each of the ZIP code digits, and five more long and
short bars for the check digit.
Zip+4 Nine Digit Bar Code
Zip+4 bar codes contains all the elements of a Zip five digit bar code plus the USPS +4 code.
DPBC POSTNET
The eleven-digit bar code is developed from the nine-digit ZIP +4 code and the last two digits of
the street address, PO Box, or route number.
xPression automatically encodes POSTNET bar codes with the correct start and stop characters, as
well as the required check digit. Because POSTNET bar codes encode only digit characters, if you
define bar code data with characters other than digits, xPression replaces the characters with the
zeroes and issues a warning message in the log file.
66
Working With Bar Codes
OMR Bar Codes
OMR (Optical Mark Reading) bar codes are rule-based. xPression uses horizontal rules to create the
marks for the bar code. You can define the start position of the marks, the length and width of the
marks, and the distance between the marks. You can also define the maximum number of marks
that xPression should produce and the placement of the marks on the page. If the data you define
does not produce the specified number of marks, xPression adds zeroes to the data and issues a
warning in the log file.
You can associate any given mark with a Boolean value or field. The values or fields can come from
input data or from tags processed by xPression. OMR bar codes expect data to be encoded as a binary
string, where each bit represents an OMR mark. For example:
01000110
Where the 1s represents the OMR mark (1s indicate marks that should be created). In this example,
xPression creates marks 2, 6, and 7. If you define invalid characters, xPression replaces the illegal
characters with a zeros and issues a warning in the log file.
You can define the number of marks, the mark length, the weight of the marks, and the mark spacing.
PDF417 Bar Codes
PDF417 bar codes are used on documents to encode text and data. Advantages of PDF417 include
the ability to encode large amounts of information, redundancy to mitigate "damaged" bar codes,
error correction, the ability to encrypt information, and the ability to include digital signatures for
authentication. PDF417 is becoming a standard for encoding sensitive data such as insurance policy
numbers. For example, the state of New York has legislation in place that requires the use of PDF417
bar codes on identifying documents such as insurance cards.
It s recommended that you limit bar codes of this type to 800 characters. Theoretically, a PDF417 bar
code can represent 2710 digits, 1850 upper-case letters, or1108 bytes of binary data, However, the
practical limit is lower depending on the number of columns, error correction level, and other factors
such as amount of switching between upper and lower case characters. The scanner that you use may
also be limited, so refer to your scanner documentation when planning your bar code parameters.
xPression supports the PDF417 two-dimensional (2-D) bar code, which is image based. You can
define the number of rows or columns in the bar code, as well as whether the bar code must use the
exact number of rows or columns you defined, or be limited to no more than the defined number
of rows and columns. If you do not define a fixed number of rows or columns, you can define the
aspect ratio of the bar code.
The PDF417 bar code consists of an x-dimension, which is the width of the narrowest bar or space
in the bar code, and a y-dimension, which is the height of a row. Define the x- and y-dimensions
of your PDF417 bar code in points.
67
Working With Bar Codes
xPression calculates the Reed-Solomon error correction for the PDF417 bar code based on the error
correction level you define. You can define whether or not xPression should create the bar code in
the truncated PDF417 format.
68
Working With Bar Codes
xPression does not support automatic encryption of data and creation of digital signatures. However,
xPression accepts data and digital signatures that you encrypt or create outside of xPression for use
as input to a PDF417 bar code. You must define any data that you want encrypted in the bar code in
encrypted form.
xPression enables you to quickly and easily identify information to be coded in a PDF417 bar code
through an easy to use GUI. In the xPression Administrator console, define the variables you want to
encode and map them to fields in your data source. Then simply define a PDF417 bar code and pick
the data elements you wish to encode.
If you look closely at a PDF417 symbol, you will notice that it appears to be made of many "1D-like"
bar codes. In reality, it is made up of multiple rows and columns. A PDF417 bar code can have
anywhere from 3 to 90 rows. This enables a PDF417 symbol to be reshaped by adjusting the number
of rows.
The number of data columns can vary from 3 to 30. These columns contain encoded data, as well as
error correction information. An example of a 5 row, 3 column PDF417 symbol appears below.
DataMatrix Bar Codes
Datamatrix was invented by RVSI Acuity CiMatrix. Today it is covered by an ISO standard,
ISO/IEC16022—International Symbology Specification, Datamatrix, and is in the public domain.
• ISO/IEC 15418:1999 – Symbol Data Format Semantics
• ISO/IEC 15434:1999 – Symbol Data Format Syntax
• ISO/IEC 15415 – 2-D Print Quality Standard
Data Matrix is a two-dimensional matrix barcode consisting of black and white square modules
arranged in either a square or rectangular pattern. The information to be encoded can be text or
raw data. Usual data size is from a few bytes up to 2 kilobytes. The length of the encoded data
depends on the symbol dimension is used. Error correction codes are added to increase symbol
strength: even if they are partially damaged, they can still be read. A Datamatrix symbol can store
up to 2,335 alphanumeric characters.
Datamatrix symbols are square and made of little modules, that is little squares that represent bits. A
white module can represent 0 and a black module 1, or vice versa. Every data matrix is composed of
at least two finder patterns or handles and two syncs. Handles are two perpendicular lines, colored
the same way as 1 modules, while syncs are like handles with the difference that they are made of
alternating black and white modules. Handles are used to achieve a good alignment with the symbol,
while syncs are used to sample modules correctly. If the matrix dimension grows, more syncs and
handles are added up to 8 both horizontally and vertically. Symbol sizes vary from 8×8 to 144×144.
Datamatrix is supported by xPublish only.
69
Working With Bar Codes
Bar Code Character Tables
The following sections provide character tables for the Code 128 and 3 of 9 bar codes:
• ASCII and EBCDIC Data, page 70
• Code 128, page 71
• 3 of 9, page 74
ASCII and EBCDIC Data
You must encode bar code data in the format native to your platform. Data must be in ASCII on an
ASCII platform, and EBCDIC on an EBCDIC platform. The 3 of 9 and Code 128 Set A bar codes
reference non-printable characters in an ASCII position. To encode these characters on an EBCDIC
platform, use the decimal values in the following table.
Description
ASCII Value
EBCDIC Value
NUL
0
0
SOH
1
1
STX
2
2
ETX
3
3
EDT
4
55
ENQ
5
45
ACK
6
46
BEL
7
47
BS
8
22
HT
9
5
LF
10
37
VT
11
11
FF
12
12
CR
13
13
SO
14
14
SI
15
15
DLE
16
16
DC1
17
17
DC2
18
18
DC3
19
19
DC4
20
60
NAK
21
61
70
Working With Bar Codes
Description
ASCII Value
EBCDIC Value
SYN
22
50
ETB
23
38
CAN
24
24
EM
25
25
SUB
26
63
ESC
27
39
FS
28
28
GS
29
29
RS
30
30
US
31
31
DEL
127
7
Code 128
The following table contains values and their corresponding bar code characters for each of the Code
128 sets, as well as the bar and space pattern for each character.
Value
Code
SetA
Code
SetB
Code
SetC
Bar/Space Pattern
BSBSBS
0
SP
SP
00
212222
1
!
!
01
222122
2
"
"
02
222221
3
#
#
03
121223
4
$
$
04
121322
5
%
%
05
131222
6
&
&
06
122213
7
’
’
07
122312
8
(
(
08
132212
9
)
)
09
221213
10
*
*
10
221312
11
+
+
11
231212
12
,
,
12
112232
13
-
-
13
122132
14
.
.
14
122231
15
/
/
15
113222
71
Working With Bar Codes
Value
Code
SetA
Code
SetB
Code
SetC
Bar/Space Pattern
BSBSBS
16
0
0
16
123122
17
1
1
17
123221
18
2
2
18
223211
19
3
3
19
221132
20
4
4
20
221231
21
5
5
21
213212
22
6
6
22
223112
23
7
7
23
312131
24
8
8
24
311222
25
9
9
25
321122
26
:
:
26
321221
27
;
;
27
312212
28
<
<
28
322112
29
=
=
29
322211
30
>
>
30
212123
31
?
?
31
212321
32
@
@
32
232121
33
A
A
33
111323
34
B
B
34
131123
35
C
C
35
131321
36
D
D
36
112313
37
E
E
37
132113
38
F
F
38
132311
39
G
G
39
211313
40
H
H
40
231113
41
I
I
41
231311
42
J
J
42
112133
43
K
K
43
112331
44
L
L
44
132131
45
M
M
45
113123
46
N
N
46
113321
47
O
O
47
133121
48
P
P
48
313121
49
Q
Q
49
211331
72
Working With Bar Codes
Value
Code
SetA
Code
SetB
Code
SetC
Bar/Space Pattern
BSBSBS
50
R
R
50
231131
51
S
S
51
213113
52
T
T
52
213311
53
U
U
53
213131
54
V
V
54
311123
55
W
W
55
311321
56
X
X
56
331121
57
Y
Y
57
312113
58
Z
Z
58
312311
59
[
[
59
332111
60
\
\
60
314111
61
]
]
61
221411
62
^
^
62
431111
63
_
_
63
111224
64
NUL
‘
64
111422
65
SOH
a
65
121124
66
STX
b
66
121421
67
ETX
c
67
141122
68
EOT
d
68
141221
69
ENQ
e
69
112214
70
ACK
f
70
112412
71
BEL
g
71
122114
72
BS
h
72
122411
73
HT
i
73
142112
74
LF
j
74
142211
75
VT
k
75
241211
76
FF
I
76
221114
77
CR
m
77
413111
78
SO
n
78
241112
79
SI
o
79
134111
80
DLE
p
80
111242
81
DC1
q
81
121142
82
DC2
r
82
121241
83
DC3
s
83
114212
73
Working With Bar Codes
Value
Code
SetA
Code
SetB
Code
SetC
Bar/Space Pattern
BSBSBS
84
DC4
t
84
124112
85
NAK
u
85
124211
86
SYN
v
86
411212
87
ETB
w
87
421112
88
CAN
x
88
421211
89
EM
y
89
212141
90
SUB
z
90
214121
91
ESC
{
91
412121
92
FS
|
92
111143
93
GS
}
93
111341
94
RS
~
94
131141
95
US
DEL
95
114113
96
FNC 3
FNC 3
96
114311
97
FNC 2
FNC 2
97
411113
98
SHIFT
SHIFT
98
411311
99
CODE C
CODE C
99
113141
100
CODE B
FNC 4
CODE B
114131
101
FNC 4
CODE A
CODE A
311141
102
FNC 1
FNC 1
FNC 1
411131
103
Start A
Start A
Start A
211412
104
Start B
Start B
Start B
211214
105
Start C
Start C
Start C
211232
106
Stop
Stop
Stop
2331112
3 of 9
The regular 3 of 9 bar code symbology supports only 43 characters. If you want to encode other ASCII
characters, you must use the extended, or full ASCII character set. The full ASCII set obtains the
additional characters by combining two regular 3 of 9 characters, which the bar code reader interprets
as a single ASCII character. The following table contains the regular character combinations you can
use to produce extended characters.
For this ASCII
Character
Use these bar code Characters
NUL
%U
SOH
$A
74
Working With Bar Codes
For this ASCII
Character
Use these bar code Characters
STX
$B
ETX
$C
EOT
$D
ENQ
$E
ACK
$F
BEL
$G
BS
$H
HT
$I
LF
$J
VT
$K
FF
$L
CR
$M
SO
$N
SI
$O
DLE
$P
DC1
$Q
DC2
$R
DC3
$S
DC4
$T
NAK
$U
SYN
$V
ETB
$W
CAN
$X
EM
$Y
SUB
$Z
ESC
%A
FS
%B
GS
%C
RS
%D
US
%E
SPACE
SPACE
!
/A
"
/B
#
/C
75
Working With Bar Codes
For this ASCII
Character
Use these bar code Characters
$
/D possibly $
%
/E possibly %
&
/F
’
/G
(
/H
)
/I
*
/J
+
/K possibly +
,
/L
-
/M better to use -
.
/N better to use .
/
/O possibly /
0
/P better to use 0
1
/Q better to use 1
2
/R better to use 2
3
/S better to use 3
4
/T better to use 4
5
/U better to use 5
6
/V better to use 6
7
/W better to use 7
8
/X better to use 8
9
/Y better to use 9
:
/Z
;
%F
<
%G
=
%H
>
%I
?
%J
@
%V
A
A
B
B
C
C
D
D
E
E
76
Working With Bar Codes
For this ASCII
Character
Use these bar code Characters
F
F
G
G
H
H
I
I
J
J
K
K
L
L
M
M
N
N
O
O
P
P
Q
Q
R
R
S
S
T
T
U
U
V
V
W
W
X
X
Y
Y
Z
Z
[
%K
\
%L
]
%M
^
%N
_
%O
‘
%W
a
+A
b
+B
c
+C
d
+D
e
+E
f
+F
g
+G
77
Working With Bar Codes
For this ASCII
Character
Use these bar code Characters
h
+H
i
+I
j
+J
k
+K
l
+L
m
+M
n
+N
o
+O
p
+P
q
+Q
r
+R
s
+S
t
+T
u
+U
v
+V
w
+W
x
+X
y
+Y
z
+Z
{
%P
|
%Q
}
%R
~
%S
DEL
%T
Also... %X %Y and %Z decode as DEL
78