Installation Guide

Arbortext Publishing Engine

8.3.0.0
Copyright © 2024 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved.

Copyright for PTC software products is with PTC Inc. and its subsidiary companies (collectively “PTC”), and
their respective licensors. This software is provided under written license or other agreement, contains
valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States
and other countries. It may not be copied or distributed in any form or medium, disclosed to third parties, or
used in any manner not provided for in the applicable agreement except with written prior approval from
PTC. More information regarding third party copyrights and trademarks and a list of PTC’s registered
copyrights, trademarks, and patents can be viewed here: https://www.ptc.com/support/go/copyright-and-
trademarks

User and training guides and related documentation from PTC are also subject to the copyright laws of the
United States and other countries and are provided under a license agreement that restricts copying,
disclosure, and use of such documentation. PTC hereby grants to the licensed software user the right to make
copies of product documentation and guides in printed form, but only for internal/personal use and in
accordance with the license agreement under which the applicable software is licensed. Any copy made shall
include the PTC copyright notice and any other proprietary notice provided by PTC. Note that training
materials may not be copied without the express written consent of PTC. This documentation may not be
disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made
publicly available by any means without the prior written consent of PTC and no authorization is granted to
make copies for such purposes.

UNITED STATES GOVERNMENT RIGHTS

PTC software products and software documentation are “commercial items” as that term is defined at 48 C.F.
R. 2.101. Pursuant to Federal Acquisition Regulation (FAR) 12.212 (a)-(b) (Computer Software) (MAY 2014)
for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 227.7202-1(a)
(Policy) and 227.7202-3 (a) (Rights in commercial computer software or commercial computer software
documentation) (FEB 2014) for the Department of Defense, PTC software products and software
documentation are provided to the U.S. Government under the PTC commercial license agreement. Use,
duplication or disclosure by the U.S. Government is subject solely to the terms and conditions set forth in the
applicable PTC software license agreement.

PTC Inc., 121 Seaport Blvd, Boston, MA 02210 USA

 Contents

Overview ....................................................................................................................7
Arbortext Publishing Engine Installation ...................................................................... 11
Product Information for Arbortext Publishing Engine ..............................................12
Print Engine Choices on the Server......................................................................12
Arbortext Publishing Engine Distribution ...............................................................13
Arbortext Publishing Engine Documentation .........................................................14
Arbortext Publishing Engine Tools and Resources.................................................15
Security .............................................................................................................16
System and Software Requirements for Arbortext Publishing Engine......................22
Web Server Resources .......................................................................................27
Monitoring and Reporting Using a Web Browser ...................................................27
Installation Overview .................................................................................................31
Configuring a Servlet Container ...........................................................................33
Setup Considerations for Arbortext Publishing Engine ...........................................33
Upgrading from a Previous Release of Arbortext Publishing Engine........................36
Installing Arbortext Publishing Engine ..................................................................37
Configuring a User Account .................................................................................39
Arbortext Publishing Engine Licensing ........................................................................43
Licensing Prerequisites .......................................................................................45
Obtaining Licenses .............................................................................................45
Requesting Licenses...........................................................................................46
Receiving Your License Pack...............................................................................47
PTC_D_LICENSE_FILE Environment Variable .....................................................47
Troubleshooting Arbortext Publishing Engine Licensing .........................................48
Server Configuration .................................................................................................51
Installing and Integrating Tomcat..........................................................................52
Testing Arbortext Publishing Engine Servlet Container Integration .........................55
Configuring OWASP CSRFGuard utility................................................................55
Troubleshooting ........................................................................................................57
Troubleshooting Errors........................................................................................58
Getting Trace Information ....................................................................................58
Publishing Very Large Documents on Windows.....................................................59
Glossary ............................................................................................................59
Glossary...................................................................................................................61
Index........................................................................................................................67

3
 Document Revision History

7.1 M040

Section Update
Various Added requirement to configure
Apache Tomcat in line with current
security best practices.

7.1 M020

Section Update
System and Software Requirements for Added Windows Update requirements
Arbortext Publishing Engine on page
22

5
 Overview

This guide contains installation information for the Arbortext Publishing Engine
and Arbortext PE server. Be sure to review Arbortext Publishing Engine Release
Notes and Configuration Guide for Arbortext Publishing Engine before
proceeding with your Arbortext Publishing Engine installation.
Check the Arbortext Editor, Arbortext Styler, and Arbortext Architect Release
Notes for supported versions. The information in those release notes may apply to
your use of Arbortext PE sub-processes, document types, stylesheets, and custom
applications. Pay particular attention to API and other information that's not
specifically related to the user interface.

Prerequisite Knowledge
This documentation is intended for the Arbortext Publishing Engine administrator.
This document assumes advanced skill using networks, servlet containers, web
servers, and HTTP protocols. To install, set up, and configure Arbortext
Publishing Engine, you should have substantial experience as a web server
administrator. To understand the information in this manual, you should be
familiar with the implementation at your site and with standard system
administration tasks.
In a typical implementation, a client program or web browser sends an HTTP
request to a web server. The web server interprets the URL and passes the request
to the servlet container. The servlet container knows how to call Arbortext PE
Request Manager from its own configuration file, and it constructs and passes a
request object and a response object to the Arbortext PE Request Manager. From
the request object, the Arbortext PE Request Manager determines the client who

7
sent the request, what work to perform, and what data to return in the response
object to the servlet container. In turn, the servlet container returns the response to
the web server, which then returns it to the client making the request.
Refer to the Arbortext Publishing Engine glossary for a list of terms and
definitions.

Technical Support
The PTC eSupport portal provides resources and tools to support your Arbortext
implementation:
www.ptc.com/support/
If you encounter problems using this product, contact PTC Technical Support. For
complete details, see “Opening a Case” on the Processes tab of the PTC
Customer Support Guide:
www.ptc.com/support/csguide/Processes
You must have a Service Contract Number (SCN) before you can receive
technical support. If you do not know your SCN, see “Preparing to contact TS” on
the Processes tab of the PTC Customer Support Guide for information about how
to locate it.

Help for PTC Products

You can access PTC product help using the following resources:
• Online Help
Click Help from the user interface for online help available for the product.
• Reference Documents website — Information assistance in PDF format:

www.ptc.com/support/refdoc
You must have a Service Contract Number (SCN) before you can access the
Reference Documents site. If you do not know your SCN, see “Preparing to
contact TS” on the Processes tab of the PTC Customer Support Guide for
information about how to locate it:
www.ptc.com/support/csguide
• Help Center
Use the following link to access all PTC Help Centers:
support.ptc.com/apps/help_center/help/

8 Installation Guide
Global Services
PTC Global Services delivers the highest quality, most efficient and most
comprehensive deployments of the PTC Product Development System including
Creo, Windchill, Arbortext, and PTC Mathcad. PTC’s Implementation and
Expansion solutions integrate the process consulting, technology implementation,
education and value management activities customers need to be successful.
Customers are led through Solution Design, Solution Development and Solution
Deployment phases with the continuous driving objective of maximizing value
from their investment.
Contact your PTC sales representative for more information on Global Services.

Comments
PTC welcomes your suggestions and comments on its documentation:
• To send feedback about a topic you are viewing in the PTC Arbortext Help
Center, click the send feedback icon in the top right corner of the topic.
The title of the help topic you were viewing when you clicked the icon is
automatically included with your feedback.
• You can also send an email to [email protected].
To help us more quickly address your concern, include the name of the PTC
product and its release number with your comments. If your comments are
about a specific help topic or book, include the title.

Documentation Conventions
This guide uses the following notational conventions:
• Bold text represents exact text that appears in the program's user interface.
This includes items such as button text, menu selections, and dialog box
elements. For example,
Click OK to begin the operation.
• A right arrow represents successive menu selections. For example,
Choose File ▶ Print to print the document.
• Monospaced text represents code, command names, file paths, or other
text that you would type exactly as described. For example,
At the command line, type version to display version information.
• Italicized monospaced text represents variable text that you would
type. For example,

Overview 9
 installation-dir\custom\scripts\
• Italicized text represents a reference to other published material. For example,
If you are new to the product, refer to the Getting Started Guide for basic
interface information.

10 Installation Guide
 1
Arbortext Publishing Engine
Installation
Product Information for Arbortext Publishing Engine.....................................................12
Print Engine Choices on the Server ............................................................................12
Arbortext Publishing Engine Distribution......................................................................13
Arbortext Publishing Engine Documentation ................................................................14
Arbortext Publishing Engine Tools and Resources .......................................................15
Security ....................................................................................................................16
System and Software Requirements for Arbortext Publishing Engine ............................22
Web Server Resources ..............................................................................................27
Monitoring and Reporting Using a Web Browser ..........................................................27

The Arbortext Publishing Engine is implemented as a Java Servlet that complies

with the Java Servlet Specification, v2.4 from Oracle. The servlet is called the
Arbortext PE Request Manager. This implementation makes Arbortext Publishing
Engine portable across operating systems, servlet containers, and web servers.

11
Product Information for Arbortext
Publishing Engine
Arbortext Publishing Engine runs in the servlet container delivered with Tomcat.
Arbortext Publishing Engine provides:
• retrieval of files from the web server disk, a Web DAV resource, or a
supported repository.
• retrieval of SGML and XML input file types.
• conversion to HTML, PDF, PostScript, HTML Help, SGML, XML, and
zipped web output formats.
• export to Microsoft Word RTF format using Arbortext Import/Export.
• return of the requested output to HTTP clients making the request.
• ability to profile the document.
• ability to extract only the table of contents from a profiled document (ATI
XML DocBook documents only).
• support for custom applications to be installed on the Arbortext PE server.
Consult the Programmer's Guide to Arbortext Publishing Engine,
Programmer's Reference, and Customizer's Guide for more information on
writing and loading custom applications.
• support for fulfilling publishing requests from Arbortext Editor clients for all
supported output formats licensed by your site. Consult the Configuration
Guide for Arbortext Publishing Engine for more information.
• support for connecting to supported repositories. Consult Configuration Guide
for Arbortext Publishing Engine for more information.

Print Engine Choices on the Server

You have the option to set the effective print engine for your Arbortext Publishing
Engine environment. Which print engine is used depends on the content of the
document, its stylesheet settings, the output type, the final output format, and how
the stylesheet may have been extended with source edits. Refer to the following
documentation to learn about using print engines:
• Publishing Engine Overview in the Arbortext Editor Help section provides
information about each type of print engine.
• Choosing a Print Engine Setting for Publishing Using the Arbortext PE server
in the Arbortext Editor Help section provides information about print engine
selection on the server.
The following default print engine settings apply to Arbortext Styler stylesheets:

12 Installation Guide
• Existing stylesheets, when updated to this release: PTC APP, FOSI or XSL-
FO as set
If a stylesheet has a value of Default, it will be set to use the PTC APP print
engine when it is updated to this release.
• New stylesheets: PTC APP
• Distributed stylesheets: PTC APP
You can set the print engine in the Arbortext Styler stylesheet. You can also
control the print engine selection on the Arbortext PE server using the set
printengineoverride ACL option. Refer to the Arbortext Command
Language Reference for information.

Using PTC Advanced Print Publisher

The print engine functionality of PTC Advanced Print Publisher (PTC APP) is
automatically installed in your Arbortext Publishing Engine environment.
Arbortext Editor clients can publish and preview documents based on a print or
PDF Arbortext Styler stylesheet that specifies the PTC APP print engine, which is
an alternative to the existing FOSI or XSL-FO print engine options. PTC APP
extends the functionality of an Arbortext Styler stylesheet. Refer to Print Features
Available with PTC APP in Arbortext Styler help for a list of additional features
provided by PTC APP.
You can develop stylesheets for PTC APP using Arbortext Styler. You can set
your stylesheet to use the PTC APP print engine for publishing or Arbortext
Editor preview actions.
Refer to System and Software Requirements for Arbortext Publishing Engine on
page 22 for complete support information.

Arbortext Publishing Engine Distribution

If you are installing from an Arbortext Publishing Engine distribution archive you
downloaded from the PTC support site, it contains:
• The windows directory contains the setup program for installing Arbortext
Publishing Engine.
• Apache Tomcat servlet container for Arbortext Publishing Engine can be
obtained from the Apache Tomcat website. The version details of Apache
Tomcat that are tested with this release can be found in the Product Release
Calendar on PTC.com.

Arbortext Publishing Engine Installation 13

• The flexlm directory contains the cpu_id.exe to obtain the Host ID of
the Arbortext PE server needed to obtain a license.
• The docs directory contains a set of PDFs you will need for preparation,
installation and set-up to use Arbortext Publishing Engine. After you complete
the installation, these documents are also available in HTML form from
Arbortext Help Center.
○ Arbortext Publishing Engine Release Notes
Review this documentation for general information about what is new or
changed in this release.
○ Installation Guide for Arbortext Publishing Engine
This manual describes installation and licensing. Arbortext Publishing
Engine uses PTC’s FlexNet licensing.
○ Configuration Guide for Arbortext Publishing Engine
This manual describes the configuration files and their parameters and
values that affect the Arbortext PE server and its Arbortext PE sub-
processes. It also describes the reporting, monitoring, testing, and
troubleshooting operations you can perform from the Arbortext Publishing
Engine index page.
○ Arbortext Editor, Arbortext Styler, and Arbortext Architect Release Notes
Review this documentation for general information about non-user
interface features and fixes that apply to the Arbortext PE sub-process.

Arbortext Publishing Engine

Documentation
Arbortext Help Center contains all Arbortext Publishing Engine, Arbortext Editor,
and Arbortext Styler documentation as online help.
For all platforms, Arbortext Publishing Engine documentation is available from
Arbortext Publishing Engine Interactive by choosing Help ▶ Help Center to access
Arbortext Publishing Engine online help. You can profile the Help Center content
to display just the Publishing Engine product documentation. See the Help Center
online help to learn more about Help Center.
The following documentation applies specifically to Arbortext Publishing Engine:
• Arbortext Publishing Engine Release Notes
contains general information about what is new or changed this release.
• Installation Guide for Arbortext Publishing Engine
describes installation and licensing.

14 Installation Guide
• Configuration Guide for Arbortext Publishing Engine
describes configuration tasks, files and parameters and values that affect the
Arbortext PE server and its Arbortext PE sub-processes. It also describes the
reporting, monitoring, testing, and troubleshooting operations.
• Programmer's Guide to Arbortext Publishing Engine
describes how to write custom applications for Arbortext Publishing Engine in
Arbortext Command Language (ACL), Java, JavaScript, and VBScript. A
programmer would use this documentation in combination with other
Arbortext developer documentation to implement custom applications.
• Test Utility User's Guide
contains information about how to use the Arbortext Publishing Engine Test
Utility to test your custom applications that will run on your Arbortext PE
server.
The following documentation contain information about using and customizing
Arbortext features as well as developing custom applications.
• Arbortext Command Language Reference
introduction and reference to Arbortext Command Language commands,
functions, hooks, callbacks, and set options. Also includes a guide to the
Arbortext Repository API.
• Document Types Guide
describes the document types delivered with Arbortext Editor and Arbortext
Publishing Engine, information on working with Arbortext Architect, and
details on creating and working with custom document types.
• Content Management Guide
contains administrative and configuration information for the PTC Server
connection and the Arbortext Adapter to Documentum/WDK.

Arbortext Publishing Engine Tools and

Resources
The following describes specific Arbortext Publishing Engine tools and resources
for configuring, developing, and testing your production environment.

Arbortext Publishing Engine Installation 15

Tools and Resources

Component Description
Arbortext Publishing Engine index HTML page that provides monitoring
page and reporting operations and links for
running test applications
Arbortext Publishing Engine status HTML page that displays a status
report report on server activity
Arbortext Publishing Engine Archival tool that can be configured to
transaction archive keep transaction requests, responses,
log messages, and the files used to
process them.
Arbortext Publishing Engine Utility that controls some setup
Configuration program activities
Arbortext Publishing Engine Test Tool for testing Java, JavaScript,
Utility VBScript, and ACL custom scripts
Arbortext Publishing Engine Interactive User interface for the Arbortext PE sub-
process used primarily for server
configuration, application development,
and testing

Security
Arbortext Publishing Engine relies on the servlet container or web application
server for security. You can enhance security by placing Arbortext Publishing
Engine and its servlet container or web application server on an intranet and
isolating them from the internet using a firewall. Within Arbortext Publishing
Engine:
• You must specify a list of Arbortext Publishing Engine application names that
are allowed to be called from an HTTP request.
• HTTPS is on by default. To set up the Arbortext Publishing Engine, if
certificate is not available you must generate a certificate for the server and
point Tomcat to the keystore containing it. The certificate must be imported
into the Trusted store of the Java used by Arbortext Editor and/or Windchill if
publishing is performed from either of these clients. For more information on
disabling HTTPS and generating the certificate, see “Disabling HTTPS”, in
the Configuration Guide for Arbortext Publishing Engine in the Arbortext
Help Center. For more information about setting up Apache Tomcat using
HTTPS, refer to the section ‘SSL/TLS Configuration’ from the documentation
provided for Tomcat by the Apache Software Foundation.

16 Installation Guide
• You can set up a specific Windows user account under which Arbortext PE
sub-processes will run. Then you can set security permissions and restrictions
on that account. For more information, refer to Configuring a User Account on
page 39.
• For communication with Windchill, you must use trusted host authentication,
and the Windchill auth.properties file must not contain a password. If
you cannot use the trusted host authentication, set the e3 configuration
property
com.arbortext.e3.allowAuthenticationWithoutTrusted
Host in the e3config.xml file. For more information on configuring the
auth.properties, see ‘Configuring Arbortext Publishing Engine for the
Windchill Visualization Service’ in the Arbortext Help Center.
• The security framework is enabled by default. You can enable or disable the
security framework by setting the
com.arbortext.e3.enableSecurityFramework property to true or
false, respectively. The property e3config.xml file is in the folder
Arbortext PE\e3\e3\WEB-INF. When the security framework is
configured, you must have a user with the Arbortext Publishing Engine
administrator role to access parts of the Publishing Engine user interface.
You can configure the Arbortext Publishing Engine security framework to
allow or restrict requests sent to the Arbortext PE Request Manager based
each request’s security classification. Security constraints are defined in the
Arbortext Publishing Engine configuration file e3config.xml, working in
conjunction with users and groups defined in Apache Tomcat.
For more information, see Customizing the Security Framework. You must
also ensure that Tomcat is configured in line with current security best
practices.
• You must ensure that Apache Tomcat home page is disabled by default. To do
this, open <Tomcat install directory>\conf\web.xml in a text
editor and comment out welcome-file-list section.
• The logs have been modified to include less information out-of-the-box.
Administrators can include more information by modifying the log level
parameters in the e3config.xml settings. The com.arbortext logger in
the log4j2.xml settings can also be changed. For more information, see
The Global Application Logging Parameters in the Arbortext Help Center.

Enabling Secure HTTP Header in Apache Tomcat

Secure HTTP Headers provide protection against Cross-Site Scripting (XSS)
attacks, cross-site request forgery, and other unauthorized actions.

Arbortext Publishing Engine Installation 17

To enable secure HTTP Header in Apache Tomcat, PTC recommends following
steps. These steps will set the following:
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• X-XSS-Protection: 1; mode=block

Note
It is recommended to take a backup of any configuration file before making
changes in it.

1. Open <Tomcat install directory>\conf\web.xml in a text editor.

2. Uncomment the following filter (by default, it is commented):
<filter>
<filter-name>httpHeaderSecurity</filter-name>
<filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
async-supported>true</async-supported>
</filter>
3. Add the following immediately after the above filter:
<filter-mapping>
<filter-name>httpHeaderSecurity</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
4. Save web.xml.
5. Restart Publishing Engine.

Enabling HTTP Strict-Transport-Security response

header in Apache Tomcat
HTTP Strict-Transport-Security response header helps in preventing users
connecting to application over unencrypted connections. To enable secure HTTP
Header in Apache Tomcat, follow these steps:
1. Open <Tomcat install directory>\conf\web.xml in a text editor.
2. Insert the following initialization parameters into the
httpHeaderSecurity filter after the async-supported parameter.
Ensure that the httpHeaderSecurity filter is uncommented as given in
section Enabling Secure HTTP Header in Apache Tomcat.
<init-param>
<param-name>hstsEnabled</param-name>
<param-value>true</param-value>
</init-param>

18 Installation Guide
 <init-param>
<param-name>hstsMaxAgeSeconds</param-name>
<param-value>31536000</param-value>
</init-param>
<init-param>
<param-name>hstsIncludeSubDomains</param-name>
<param-value>true</param-value>
</init-param>
3. Save web.xml.
4. Restart Publishing Engine.

Disabling HTTP Strict-Transport-Security response

header in Publishing Engine
HTTP Strict-Transport-Security (HSTS) response header helps in preventing users
connecting to application over unencrypted connections. To disable secure HSTS
Header in Arbortext Publishing Engine, follow these steps:
1. Open PE_HOME\e3\e3\WEB-INF\web.xml in a text editor.
2. Comment out or remove the following initialization parameters into the
httpHeaderSecurity filter after the antiClickJackingOption
parameter.
<init-param>
<param-name>hstsEnabled</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>hstsMaxAgeSeconds</param-name>
<param-value>31556927</param-value>
</init-param>
<init-param>
<param-name>hstsIncludeSubDomains</param-name>
<param-value>true</param-value>
</init-param>
3. Save web.xml file.
4. Restart Publishing Engine.

Disabling Password Autocomplete in the Browser

Most browsers have a facility to remember user credentials that are entered into
HTML forms. These credentials are stored on the local computer and retrieved by
the browser on future visits to the same application. These credentials can be
exploited by attackers.
Follow these steps to disable the facility to autocomplete passwords in browsers:

Arbortext Publishing Engine Installation 19

Chrome
1. Click the Menu icon (three dots at the top-right corner of the browser
window) to display the drop-down menu.
2. Click on Settings.
3. Click on Autofill from the menu on the left-hand side of the page.
4. Click on Password Manager from the Autofill section.
5. Switch off the following toggles:
• Offer to save passwords, and
• Auto Sign-in
6. Close the Password Manager page. The system automatically saves your
settings.
Edge
1. Click on the Settings and more icon (three dots at the top-right corner of the
browser window) to display the drop-down menu.
2. Click on Settings.
3. It displays the edge://settings/profiles page. If not, click Profiles.
4. Click on Passwords from the section of Your profile.
5. On the profile / Passwords page, switch off the following toggles:
• Offer to save passwords, and
• Automatically save passwords
6. Close the profile / Passwords page. The system automatically saves your
settings.
Firefox
1. Click on the Menu icon (three horizontal lines stacked at the top-right corner
of the browser window) to display the drop-down menu.
2. Click on Settings to display the about:preferences page.
3. Click on Privacy & Security from the menu on the left-hand side of the page.
4. Under the Logins and Passwords section, uncheck the following check
boxes:
• ask to save logins and passwords for web sites, and
• Autofill logins and passwords
5. Close the about:preferences page. The system automatically saves your
settings.

20 Installation Guide
Customizing Cacheable HTTPS Response for
Browsers
Some browsers may store a local cached copy of content received from web
servers. If sensitive information in application responses is stored in the local
cache, then this may be retrieved by other users who have access to the same
computer at a future time. To avoid this, PTC recommends to set Cacheable
HTTPS response to instruct browsers not to store local copies of any sensitive
data.
1. Open <Tomcat install directory>\conf\web.xml in a text editor.
2. Add the following filter-mapping and filter:
<filter-mapping>
<filter-name>ExpiresFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>

<filter>
<filter-name>ExpiresFilter</filter-name>
<filter-class>org.apache.catalina.filters.ExpiresFilter</filter-class>
<init-param>
<param-name>ExpiresByType image</param-name>
<param-value>access plus 0 seconds</param-value>
</init-param>
<init-param>
<param-name>ExpiresByType text/css</param-name>
<param-value>access plus 0 seconds</param-value>
</init-param>
<init-param>
<param-name>ExpiresByType application/javascript</param-name>
<param-value>access plus 0 seconds</param-value>
</init-param>

<init-param>
<param-name>ExpiresDefault</param-name>
<param-value>access plus 0 seconds</param-value>
</init-param>
</filter>
3. Save web.xml.
4. Restart Publishing Engine.

Setting SameSite Cookie Header in Apache Tomcat

The SameSite cookie flag is used to limit cookie transitions when a request
originates from a third-party origin. Modern browsers set the default SameSite
value to "Lax" when it is not declared by the server. To set SameSite Cookie
Header in Apache Tomcat, follow these steps:

Arbortext Publishing Engine Installation 21

1. Open <Tomcat install directory>\conf\context.xml in a text
editor.
2. Add the following within the Context tags.
<CookieProcessor sameSiteCookies="strict" />
3. Save context.xml.

Note
It is recommended to take a backup of any configuration file before making
changes in it.

Recommended Guidelines for Passwords

PTC recommends following best practices for setting passwords:
Passwords should be at least 8 characters in length and should contain at least:
• 1 lowercase letter,
• 1 uppercase letter,
• 1 number, and
• 1 special character: @ % + \ / ' ! # $ ^ ? : . , ( ) { } [ ] ~ ` -
Passwords should not contain:
• Common passwords such as “changeme” or “password”, or
• Any account attribute such as first and last name, username, city, zip code, and
so on

System and Software Requirements for

Arbortext Publishing Engine
System Requirements
The Arbortext Publishing Engine 64-bit installation requires approximately 1.74
GB of disk space.
Minimum requirements for the operating system and web server application where
you will install Arbortext Publishing Engine apply, as it runs within a servlet
container or web application server on these systems. However, your site's
implementation will likely require more than the minimum requirements.
Considerations based on the site's production environment have an impact on
optimizing your system, including additional disk space, memory, number of

22 Installation Guide
server CPU processors, amount of RAM, throughput and output, number of
requests, number and size of documents, number and size of graphics, and other
network traffic.
This Arbortext Publishing Engine release is compatible with clients running
Arbortext Editor release 8.2.0.0 and later. Some Arbortext Editor exceptions or
limitations may apply regarding backward compatibility.

Platform Support
For a complete list of supported platforms, including post-release updates, refer to
the Product Release Calendar on support.ptc.com. PTC only provides product
support for Arbortext Publishing Engine used on hardware or operating systems
described here.
See these sections:
• Product Platforms
• Arbortext Publishing Engine Web Server and Servlet Container Compatibility
Please take these points into consideration when configuring your environment:
• Tomcat Support
You can implement the Arbortext Publishing Engine with Tomcat alone.
Tomcat has the ability to handle HTTP requests sent directly to it.

Note
You must ensure that Tomcat is configured in line with current security
best practices.

Browser Support
Browser support is listed in the Product Release Calendar for this release. Refer to
support.ptc.com.
See the section Browser Platform Compatibility for PTC Arbortext products.
The web browser support applies to the web clients of Arbortext Publishing
Engine and to launch the Arbortext Publishing Engine administrative web page,
using a URL like the following:
http://server:port/e3/

Internet Protocol Version 6 Support

Arbortext Publishing Engine supports Internet Protocol Version 6 (IPv6).

Arbortext Publishing Engine Installation 23

 Note
If Arbortext Editor fails to connect to Arbortext Publishing Engine, it’s
possible that Arbortext Editor is running on a different type of network than
Arbortext Publishing Engine. Both Arbortext Editor and Arbortext Publishing
Engine support IPv4 and IPv6, but they must both be running on the same type
of network to avoid an error. Check with your system administrator to resolve
networking issues.

Server Considerations
Arbortext Publishing Engine should be installed on its own, separate physical
server. For example, it is not recommended to install Arbortext Publishing Engine
on the same server where Windchill is installed. Installing Arbortext Publishing
Engine on its own server allows you to configure the same number of Arbortext
PE sub-processes as you have physical CPU processors to handle simultaneous
requests. Once configured in this manner, Arbortext Publishing Engine relies on
those CPU processors and will keep them busy fulfilling requests.
If you must install Arbortext Publishing Engine in a shared environment,
configure the number of Arbortext PE sub-processes to a number less than the
total number of CPU processors so that another application can be somewhat
responsive. You may want to implement CPU affinity; if so, see your server
documentation for information on CPU affinity and how to configure it. Also, be
sure to allocate enough memory to allow Arbortext Publishing Engine to process
large documents.
Before deciding on how to install Arbortext Publishing Engine, carefully evaluate
your expected processing needs, including network traffic, throughput
performance, and the size and quantity of documents and graphics.

Virtual Environments
PTC does not explicitly test or certify the use of PTC Arbortext software in virtual
environments such as VMWare, Xen or Microsoft Virtual PC. Customers may use
such environments for their PTC Arbortext deployments, but the guest operating
system must be supported by PTC Arbortext and the PTC Arbortext software must
be correctly licensed. In these cases, PTC will provide technical support for PTC
Arbortext software in a virtualized environment but cannot provide support or
consultation on the configuration of the virtual environment or on issues that are
believed to be caused by the virtual environment. PTC uses the following
guidelines to determine whether an issue involving a virtual environment is
supported:

24 Installation Guide
• For issues directly related to Arbortext products, PTC Technical Support will
provide support. If PTC suspects that the virtualization environment is the
likely reason for the issue, you will be asked to contact the vendor of your
virtualization product for assistance.
• For issues directly related to the virtual machine such as configuration and set
up of the virtual environment, image size, performance, device emulation, or
network emulation, PTC cannot provide technical support. Contact the vendor
of your virtualization product for assistance.

Support for Arbortext Editor Clients

This release of Arbortext Publishing Engine is compatible with Arbortext Editor
release 8.2.0.0 and later, up to the concurrent version of Arbortext Publishing
Engine. However, there may be Arbortext Editor exceptions or limitations
regarding backward compatibility. Be sure to check the Arbortext Publishing
Engine Release Notes for information.
Each Arbortext Editor client must be configured to use Arbortext Publishing
Engine for publishing using one of the following methods:
• From Tools ▶ Preferences, choose Publishing Engine.
1. Use Publishing Engine sends publishing requests to the Arbortext PE
server specified by a URL.
2. URL — specifies the URL to locate the Arbortext PE server using the
form.
http://server:port/e3/servlet/e3
• From Tools ▶ Preferences, choose Advanced Preferences.
1. Set peservices = on in Advanced Preferences
2. Set peserverurl = http://server:port/e3/servlet/e3

Note
If you are using a version of Arbortext Editor earlier than 8.1.2.0, then
Publishing Engine must be configured to not require authentication for
publishing requests sent from Arbortext Editor to Arbortext Publishing
Engine.

For more information on Arbortext Editor, consult Arbortext Editor, Arbortext

Styler, and Arbortext Architect Release Notes and the Arbortext Editor
documentation in Arbortext Help Center.

Arbortext Publishing Engine Installation 25

Support for PTC Server connection
The PTC Server connection supports Internet Protocol Version 6 (IPv6).
Refer to support.ptc.com for a list of supported systems on which the PTC Server
connection can connect to the PTC content management systems.
See these sections:
• Compatibility with Content Management Systems
• Connection to Arbortext Content Manager compatibility
• Connection to Windchill PDMLink compatibility
• Connection to Windchill Project Link compatibility

Producing PDF Output with Arbortext Publishing

Engine
Arbortext Publishing Engine has the built-in capability to produce PDF output by
default, using either the PTC Advanced Print Publisher or the FOSI print engine.
(See Print Engine Choices on the Arbortext PE server for information.) The PDF
output capability in both PTC APP and FOSI produces PDF upon receiving a
publishing request. Refer to the Customizer's Guide for information on using and
customizing PDF features.

Java Runtime Environment Support for Arbortext

Publishing Engine
Arbortext Publishing Engine does not ship with a Java Runtime Environment
(JRE). Arbortext Publishing Engine, requires you to obtain a JDK from Oracle
(www.java.com) or from Amazon and install it, so that Arbortext Publishing
Engine can use the associated JRE.
Arbortext Publishing Engine will work with Oracle Java 21 and Amazon Corretto
21.

Tomcat Updated
Support for Tomcat has been updated to the 10version.

Configuring Publishing Engine Post Installation

You must now configure the Arbortext Publishing Engine post installation. As of
version 8.5-45 and later, the Tomcat server runs the SERVICE group as default
instead of the SYSTEM group. This prevents the Arbortext Publishing Engine
from successfully creating the Arbortext Editor subprocess. To enable creation of

26 Installation Guide
the Arbortext Editor subprocess, the SERVICE group requires permissions similar
to the SYSTEM group. For more information, see “Configuring Publishing
Engine Post Installation”, in the PTC Arbortext Help Center.

Web Server Resources

Information is available about Tomcat and Java servlet containers at the following
locations:
• Information about Java servlets is available from Oracle at:
www.oracle.com/technetwork/java/overview-137084.html
• Information about Tomcat is available from the Apache Software Foundation
web site:
tomcat.apache.org

Monitoring and Reporting Using a Web

Browser
Arbortext Publishing Engine has an administrative web page with links that return
information and perform a variety of administrative actions and sample document
conversions. After you've successfully installed and configured Arbortext
Publishing Engine, this web page is available from a web browser. Use a URL that
follows the example:
http://servername:port/e3/
In the URL, servername is the name of your Arbortext Publishing Engine server
machine, and port is the port number the servlet container or web server uses to
monitor HTTP requests on its behalf.

Arbortext Publishing Engine Installation 27

View Arbortext Publishing Engine Information
• The Status link returns a Status report. It includes:
○ basic installation, system, COM, allowed functions, and global parameters
information.
○ Arbortext PE sub-process pool status includes whether an Arbortext PE
sub-process pool is enabled or disabled, its associated configuration
settings, the process IDs and allocation status of each Arbortext PE sub-
process.
○ The Status report retrieves all configuration settings for caches, queues,
request handlers and request selectors.
○ The Status report retrieves information on the Queue List, if queues are
configured. Information about individual queues is available from the
Queue List page.
○ System Environment Variables are included in the report. If PTC_D_
LICENSE_FILE is set, it will be included in the Environment Variables
report.
• The License link retrieves basic information about the installation, as well as
the license source, the user under which Arbortext Publishing Engine is
running, and the number of processor cores and packages on the Arbortext PE

28 Installation Guide
 server. It also lists the optional software components installed and whether
they are licensed.
A license error report will be returned with the information that PTC_D_
LICENSE_FILE is either missing or set to an incorrect value (and the
incorrect value will be reported).
• The Version link retrieves version information about Arbortext Publishing
Engine and its Arbortext PE sub-processes.
• The Transaction Archive link retrieves information on the transaction archive,
if one has been implemented. More information about individual archived
transactions is available from the Transaction Archive page.
• You can retrieve a report on the Queue List, if queues are configured.
Information about individual queues is available from the Queue List page.
• The Java Properties link returns all information about the JVM.
• The Web Service Definitions link returns the Arbortext Publishing Engine
WSDL definitions. If peaxis2 is not configured for your servlet container or
web application server, this returns an error.
• You can retrieve any of three variations of the Publishing Configuration report.
• You can retrieve a Usage Report with a summary of clients and transactions,
and usage by client.
• You can run an Application Save to retrieve configuration about Arbortext PE
sub-processes.
• You can request All Available Information returns a zip archive containing all
the information available about Arbortext Publishing Engine listed in this
section, as well as the output from the sample PE applications in the testing
section and the Application Save zip archive.

Administer Arbortext Publishing Engine

• You can rescan the publishing configuration information and its cache for use
by Arbortext Editor clients.
• You can reload scripts and update cached stylesheets on the Arbortext PE
server for use by all clients.

Test Arbortext Publishing Engine

• You can convert a simple sample document to any of the supported output
formats listed.
• You can run Arbortext Publishing Engine sample test applications which
return basic information about server configuration. The source code for these
sample applications is available from your installation in PE_HOME\e3\

Arbortext Publishing Engine Installation 29

 samples, and they're described in the Programmer's Guide to Arbortext
Publishing Engine.
None of the actions available from the Arbortext Publishing Engine index page
are queued.

30 Installation Guide
 2
Installation Overview
Configuring a Servlet Container..................................................................................33
Setup Considerations for Arbortext Publishing Engine..................................................33
Upgrading from a Previous Release of Arbortext Publishing Engine ..............................36
Installing Arbortext Publishing Engine .........................................................................37
Configuring a User Account........................................................................................39

Arbortext Publishing Engine installation setup program places all the components
for Arbortext Publishing Engine on your web server machine. The installation
provides a pool of Arbortext PE sub-processes managed by the Arbortext PE
Request Manager. You must have Administrator privileges on the web server
machine to perform the installation. After the installation completes, the PTC
program group will include the shortcuts to Arbortext Publishing Engine programs
and documentation.
• Arbortext Help Center contains the entire set of documentation for Arbortext
Editor and Arbortext Publishing Engine.
• Arbortext Publishing Engine Configuration is a program that manages some of
the Arbortext Publishing Engine settings on Windows. For information, see
Configuration Guide for Arbortext Publishing Engine.
• Arbortext Diagnostics is a program for tracing and logging Arbortext
Publishing Engine activity. For information, see Configuration Guide for
Arbortext Publishing Engine.
• Arbortext Publishing Engine Interactive is used to edit e3config.xml and
for troubleshooting. For information, see Configuration Guide for Arbortext
Publishing Engine.
• Arbortext Publishing Engine Test Page tests web application server integration.
For information, see Testing Arbortext Publishing Engine Servlet Container
Integration on page 55.

31
If you are using Arbortext Publishing Engine as a publishing server for Arbortext
Editor clients, the release of Arbortext Editor on each workstation must be
supported by the release of Arbortext Publishing Engine on the server. A version
mismatch will be reported as an error. Refer to System and Software
Requirements for Arbortext Publishing Engine on page 22 for release
compatibility information.
The Arbortext Publishing Engine documentation is delivered in Help Center (Help
▶ Help Center). Refer to Arbortext Publishing Engine Documentation on page 14
for information.

32 Installation Guide
Configuring a Servlet Container
For information on setting up Tomcat, refer to Installing and Integrating Tomcat
on page 52.

Setup Considerations for Arbortext

Publishing Engine
Review the following sections to prepare for installing Arbortext Publishing
Engine.

Setting Up HTML Help

The HTML Help feature requires that the Microsoft HTML Help Workshop is
installed on the Arbortext PE server. The Workshop is a free download from:
msdn.microsoft.com/en-us/library/ms669985.aspx
When you install the HTML Help Workshop, you must start and close the HTML
Help Workshop application once before Arbortext Publishing Engine accepts its
first request for HTML Help publishing. Look for the hhw.exe in the directory
where you installed HTML Help Workshop.

Environment Variables
When you install Arbortext Publishing Engine, it runs under the Windows
SYSTEM account. For this reason, environment variables must be set as System
variables to be available to the Arbortext Publishing Engine and its Arbortext PE
sub-processes.

Note
The PTC_D_LICENSE_FILE Environment Variable on page 47, which must
contain the path to the Arbortext Publishing Engine license file, needs to be a
System variable. See Arbortext Publishing Engine Licensing on page 43 for
licensing information.

Running Arbortext Publishing Engine as a Specified

Account
The default Arbortext Publishing Engine LOCAL SERVICE user account doesn't
have network privileges, so it can't access any network resources such as a file
shared on another server or a remote printer. For example, if you were to write a

Installation Overview 33
custom Arbortext Publishing Engine application that sends a print job to a
network printer, you would need to configure Arbortext Publishing Engine to run
under a specified user account.
If Arbortext Publishing Engine needs to specify a file on a network using a UNC
path (uniform naming convention, which takes the form \\servername\
sharedir), the default Arbortext Publishing Engine LOCAL SERVICE account
wouldn't be able to access it. However, a user account can be configured to access
files specified by a UNC if the user account has the proper permissions and the
UNC file system shares the directories with the Arbortext Publishing Engine user
account.
To set up a different Windows user account for Arbortext Publishing Engine, see
Configuring a User Account on Windows on page 39.

Printer Setup Considerations

Printer setup considerations depend on your Arbortext Publishing Engine
implementation. How you set up Arbortext Publishing Engine to produce PDF and
PostScript determines which of the following sections you may find relevant to
your Arbortext Publishing Engine implementation. You may be producing
PostScript files that will be sent to a physical printer or some other location, or
you may be producing PDF output using either the built-in PDF feature of
Arbortext Publishing Engine. PostScript output relies on a PostScript printer
driver. The built-in PDF feature of Arbortext Publishing Engine does not use a
PostScript printer driver. Read the next sections for guidelines on fine-tuning
printer setup and configuration based on how your Arbortext Publishing Engine
configuration is producing the output.

Setting Up a Printer for a Specified Account

You can choose to run Arbortext Publishing Engine under a different user ID. If
you set up a separate user ID account for Arbortext Publishing Engine and you are
producing PostScript output you need to choose a default printer. You need to log
in as the Arbortext Publishing Engine user account and choose a PostScript
printer. Arbortext Publishing Engine will recognize this printer, but the Arbortext
Publishing Engine Configuration program will not display it. The Default Printer
field on the Setup panel displays (must set manually). For information on setting
up a user ID account for Arbortext Publishing Engine, see Configuring a User
Account on Windows on page 39.

PostScript Printer Performance Optimization

If you are producing PostScript output check some of the printer properties for
your PostScript printer. Several settings can optimize performance by reducing
system resource usage. Review the settings, making changes if necessary.

34 Installation Guide
1. Choose Printers and highlight the PostScript printer you will select for
Arbortext Publishing Engine.
2. Open the Printer Properties dialog box (right-click on the printer icon that will
be the default printer for Arbortext Publishing Engine and choose the
Properties menu item).
3. Click on the Ports tab and be sure that the box for FILE is selected as the port.
4. Click on the Advanced tab. Check the radio button for Print directly to the
printer and ensure it's selected.
5. Then click on the Print Processor button at the bottom of the Advanced tab. Be
sure the default datatype is RAW. Click OK to dismiss the Print Processor
dialog box.
6. Click OK to close the Properties dialog box.

Checking System Events for Printing

If you are producing PostScript output you should check some system event
entries that can be created in the system log for each print job. You can send
spooler errors, spooler warnings, and spooler information to the event log. In a
production environment, you don't want to send all ordinary print events to the
system log as it becomes much more difficult to locate errors and warnings in the
log. You should disable the ordinary printer spooler information; errors and
warnings can still be reported.
To check the event settings:
1. Choose Printers and navigate to the File ▶ Server Properties menu item.
2. In the Print Server Properties dialog box, choose the Advanced tab. Be sure the
check box next to Log spooler information events is clear.
Then, be sure the check box next to Notify when remote documents are printed
is clear.
3. Click OK to close the Print Server Properties dialog box.
4. You must reboot the system for the change to take effect.

Checking Server Print Spooler Configuration

If you are producing PostScript output you should check the print spooler service.
If you place a heavy load on Arbortext Publishing Engine for print, it's possible to
cause the print spooler to fail. You should change the print spooler service to
automatically restart upon failure.
1. Open the Administrator tool Services window.
2. Find the Print Spooler service and double-click it.
3. Choose the Recovery tab.

Installation Overview 35
4. Set the options for First failure, Second failure, and Subsequent failures to
Restart the Service.
5. Set Reset fail count after to 0.
6. Set Restart service after to 0.
7. Click OK to accept the changes.

Upgrading from a Previous Release of

Arbortext Publishing Engine
During an installation, you should be logged on with Administrator privileges to
ensure proper removal of all previous Arbortext Publishing Engine files and
registry entries. If the web server or servlet container are running, you need to stop
them before upgrading to release the Arbortext Publishing Engine files that may
be in use.
You should check the directories for files that you may have customized in case
you want to save them to reuse with your upgraded release.
• Look for custom files in the PE_HOME\custom subdirectory structure. The
uninstall feature leaves your custom files in the custom directory intact. You
can reuse the previous install path if you have files in the custom directory.
• The installation overwrites any existing file having the same name and path. If
you placed custom files in other install tree locations, be sure to make backup
copies of them as the installation could overwrite them.
• Be sure to save a copy of your current PE_HOME\e3\e3\WEB-INF\
e3config.xml file with your configuration settings to a backup location.
After you finish the installation, you can migrate your configuration settings to
the new e3config.xml file.

License Upgrade
You will need to obtain a new license for the Arbortext Publishing Engine 8.2
release. You must update your license each time you upgrade to a major Arbortext
Publishing Engine .0.0 release (maintenance releases or datecode updates would
not require a license update). For example, a license issued for 8.2 would work
with Arbortext Publishing Engine 8.2.2.0. A license issued for 8.0 would not be
compatible with 8.1, 8.2 and so on.
Licenses issued for previous releases (such as 8.1) will not work with Arbortext
Publishing Engine 8.2.
The license information is stored in the PTC_D_LICENSE_FILE environment
variable. If it does not exist or has an incorrect value, a license error will be
reported. See Arbortext Publishing Engine Licensing on page 43 for instructions
on obtaining and installing a license.

36 Installation Guide
Installing Arbortext Publishing Engine
To install Arbortext Publishing Engine you need to download the zip archive from
the PTC Support site.
Following installation alternatives are available to install Arbortext Publishing
Engine:
• Standard Installation – This method allows you to install using the Setup
Wizard user interface.
• Silent Installation – This method allows you to install silently without any user
intervention.
You must have Administrator privileges on the web server system to install
Arbortext Publishing Engine successfully.
The Arbortext Publishing Engine installation directory is referred to as PE_HOME.
If you happen to install Arbortext Publishing Engine before you install Tomcat,
you can still use Arbortext Publishing Engine Configuration later to set up the
integration between Tomcat and Arbortext Publishing Engine.
Standard Installation
To install Arbortext Publishing Engine:
1. After downloading the zip archive from the PTC Support site to a temporary
location on your system, locate it before you proceed. Extract the contents of
the zip file to the temporary directory.
Choose Run from the Start menu, browse to the file set, and choose
windows\PESetup.exe. Follow the instructions on the screens.
2. Review the license agreement. You need to Accept it to continue with
installation.
3. Select the directory for the installation. You can accept the default location
C:\Program Files\PTC\Arbortext PE or specify another by clicking
Change. If you specify a nonexistent directory, the Setup program will create it
for you.
If you choose an existing directory that is not empty, you’ll be notified that
you should choose a different location or uninstall the software and then
restart this installation.
4. Choose Install to copy files to your directory.
5. The setup program indicates that setup is complete. It provides you with an
option to Run Java Selection dialog after setup. This opens the Arbortext Java
Selection Tool dialog box and allows you to specify the path of the Java
Virtual Machine(JVM). Select the checkbox if you have installed Java on your
system. If you have not already installed Java in your system, you can clear

Installation Overview 37
 the selection and specify the JVM Path after installation in the Arbortext
Publishing Engine Interactive under Tools ▶ Administrative Tools ▶ Change
JVM Path.
6. Click Finish to complete the installation.
Silent Installation
For a silent installation of Arbortext Publishing Engine:
1. Download the zip archive from the PTC Support site to a temporary location
on your system.
2. Open an administrator command prompt in this folder and enter the following
command:
msiexec.exe /quiet /i "<msi path>\ArbortextPE.msi" JVM_PATH="<path to JVM DLL>\jvm.dll"
where the msi path refers to the folder path where ArbortextPE.msi is
located and JVM_PATH refers to the location of Java installation.
The JVM_PATH property is optional. If it is not added in the silent installation
command, the Java path can be provided in the Java Selection Tool after the
installation is completed.
After the silent installation is complete, you can locate the PTC program group
shortcuts for Arbortext Publishing Engine.
Post Installation Tasks
After the installation finishes, the Arbortext Publishing Engine Configuration
program launches and allows you to view and complete some other configuration
steps.
If you have already installed Tomcat and it is running as a service, Arbortext
Publishing Engine Configuration can automatically perform the integration for
you.
You can also run Arbortext Publishing Engine Configuration later from the shortcut
in your PTC program group.
Otherwise, follow the instructions in this manual for integrating your web server
application with Arbortext Publishing Engine.
For more information about using the Arbortext Publishing Engine Configuration
program, see the Configuration Guide for Arbortext Publishing Engine.

38 Installation Guide
 Note
Do not use a mapped or subst drive to browse for your Arbortext Publishing
Engine installation to run Arbortext Publishing Engine Configuration. Because
Arbortext Publishing Engine runs as the LOCAL SERVICE account by default,
a mapped drive will not be available to it, which then causes problems for the
COM server.

On the Start menu, you can locate the PTC program group shortcuts for Arbortext
Publishing Engine.
Arbortext PE sub-processes and Arbortext Publishing Engine Interactive need a
FlexNet node-locked license file to run. They look for the PTC_D_LICENSE_
FILE environment variable automatically when they start. If PTC_D_LICENSE_
FILE does not exist or has an incorrect value, a license error will be reported. See
Arbortext Publishing Engine Licensing on page 43 for instructions on obtaining
and installing a license.

Note
By default, Arbortext Publishing Engine runs under the Windows SYSTEM
account. If you start Arbortext Publishing Engine and PTC_D_LICENSE_
FILE does not exist or has an incorrect value, its Arbortext PE sub-processes
will report a license error.
If you try to start Arbortext Publishing Engine Interactive without a valid
PTC_D_LICENSE_FILE, you will see a Licensing Error dialog box
prompting you for license information. Because this dialog box will set the
variable as a User variable, Arbortext PE sub-processes will still be unable to
find the license. Be sure PTC_D_LICENSE_FILE is set as a System variable
in the server’s System Properties.

Refer to Troubleshooting Arbortext Publishing Engine Licensing on page 48 for

information on how to obtain licensing information from the Arbortext PE server.

Configuring a User Account

By default, Arbortext PE sub-processes run under a special user account called
LOCAL SERVICE that has restricted access. You may want to configure Arbortext
Publishing Engine to run under a specified user account.

Installation Overview 39
The default Arbortext Publishing Engine user account doesn't have network
privileges, so it can't access any network resources such as a file on another host
or a remote printer. For example, if you were to write a custom Arbortext
Publishing Engine application that sends a print job to a network printer, you
would need to configure Arbortext Publishing Engine to run under a specified user
account.
If Arbortext Publishing Engine needs to specify a file on a network using a UNC
path (uniform naming convention, which takes the form \\servername\
sharedir), the default Arbortext Publishing Engine LOCAL SERVICE account
wouldn't be able to access it. However, a user account can be configured to access
files specified with the UNC format if the user account has the proper permissions
and the UNC file system shares the directories with the Arbortext Publishing
Engine user account.
If Arbortext Publishing Engine is configured to run as a specified user account,
you must log in using that account if you want to run Arbortext Publishing Engine
Interactive. When Arbortext Publishing Engine is configured this way, Windows
doesn't allow Arbortext Publishing Engine Interactive to run under a different user
account for security reasons. However, any Administrator level user account can
run the Arbortext Publishing Engine Configuration program.
When you are configuring Arbortext Publishing Engine to run as a specific user
account on Windows, the Arbortext Publishing Engine user account:
• should have internet access as it handles HTTP traffic.
• should have an interactive login so that someone can log in to perform testing
and troubleshooting.
• should have a password that doesn't expire so that Arbortext Publishing
Engine won't suddenly terminate if the account is locked without warning. Of
course, passwords should still be changed regularly.
• should have a default printer selected in the Windows Printers window. The
default printer must be a PostScript printer if you will be producing PostScript.
• can be set up to access network resources using a UNC path, if needed.
• does not need to have local administrator privileges on the server that it's
installed on.
To set up Arbortext Publishing Engine as a specific user account:

Note
Your site may have security policies in place that require an IT administrator
familiar with those policies to perform these steps.

40 Installation Guide
You'll need to set permissions and restrictions for a specified Arbortext Publishing
Engine user account. The system administrator familiar with setting up user
accounts, especially your site's security policies and user privileges, may need to
perform the following steps.
1. You should be logged in with Administrator privileges on the host machine
where Arbortext Publishing Engine is installed.
2. In Administrative Tools, open Computer Management. In the Computer
Management window, find the Local Users and Groups folder and
display the Users folder under it. From the Action menu of the Computer
Management window, choose New User, In the New User window, create a new
account and its password. Set the properties you want for the password and
click Create.
3. In Administrative Tools, open Local Security Policy. In the Security Settings
window, display the Local Policies folder under it. Click the User
Rights Assignment subdirectory to display a list of possible settings.
Find Log on as a batch job in the Policy list and double click on it.
4. In the Log on as a batch job Properties dialog box, click the Add User or
Group button. In the Select Users or Groups dialog box, be sure the object type
includes Users and the Location is the local server machine. Enter the
Arbortext Publishing Engine user account name in the object name text box.
Click the OK button to return to Log on as a batch job Properties. Click OK to
save changes and close the dialog box.
Set any other privileges you want for this account.
5. In Administrative Tools, open Component Services and navigate to Computers
▶ My Computer ▶ DCOM Config. Find and display the Properties for the
Arbortext Editor entry by right clicking on the entry.
6. In the Arbortext Editor Properties dialog box, click the Identity tab.
Choose the This user option. Fill in the User and Password fields for the
Arbortext Publishing Engine account you created. You need to specify the
domain or computer name as well as the user name; enter the account name
and then click the Browse button to specify the User information.
7. Click OK to accept the changes to Arbortext Editor Properties. Click OK again
to exit.
8. You may need to check that the Arbortext Publishing Engine user account has
permission to write to some specific directories. For example, you will want to
be sure it can write to temporary or log directories of the Windows system and
other applications, such as the servlet container directories that store log files.
For instance, you would want to check permissions for the following:

Installation Overview 41
 • The temporary directory set by the System's environment variable.
• Java log and temporary directories for the servlet host application, for
example, Tomcat’s logs and temp directories. On the Arbortext
Publishing Engine index page, click the Java Properties link to retrieve the
JVM System Properies page. The java.io.tmpdir property value will display
the location.
• For Windows Server 2008, you should check the C:\ProgramData
directory.
• Check any file path specified in the e3config.xml file, such as the
transaction archive directory.
Right click on the appropriate directory and choose Properties. Choose
Security and check if the Arbortext Publishing Engine user account is in the
list and has Full Control. If not, you will need to add the Arbortext Publishing
Engine user account and give it Full Control for the folder.
9. Restart the system. The next time Arbortext Publishing Engine runs, it will run
as the Arbortext Publishing Engine user account you created.

Verifying the Specified User Account

You can verify that Arbortext Publishing Engine is running under the Arbortext
Publishing Engine user account. The Arbortext Diagnostics program displays
tracing information. You can launch it from the Arbortext Diagnostics shortcut in
your PTC program group. The Arbortext Diagnostics window contains the Module
List tab that displays the Arbortext PE sub-process information and the Trace Log
tab that displays tracing output. The Module List panel should display the
Arbortext Publishing Engine user account name instead of LOCAL SERVICE.

42 Installation Guide
 3
Arbortext Publishing Engine
Licensing
Licensing Prerequisites..............................................................................................45
Obtaining Licenses....................................................................................................45
Requesting Licenses .................................................................................................46
Receiving Your License Pack .....................................................................................47
PTC_D_LICENSE_FILE Environment Variable............................................................47
Troubleshooting Arbortext Publishing Engine Licensing................................................48

Arbortext Publishing Engine needs a node-locked FlexNet license to run. A node-

locked license is for use on a single computer. Your Arbortext Publishing Engine
node-locked license is customized for your site, and it enables specific features
you have licensed for your Arbortext Publishing Engine implementation. If you
have questions about what your license covers, consult your Arbortext account
representative.

Note
If you have a license file for a previous release of Arbortext Publishing Engine
(8.1 or earlier), you will not be able to reuse it for Arbortext Publishing Engine
8.2. With each new release, you will need to obtain a new license.

Arbortext software licenses are available online for customers covered by an

active maintenance agreement. You must have a PTC online account and a
Customer Number to get a license. If you do not already have one, you can
establish a PTC online account at support.ptc.com.
After the license file is installed, you'll be able to test your basic Arbortext
Publishing Engine configuration.

43
If your site has the Arbortext Import/Export option installed for use on Arbortext
Editor workstations or Arbortext Publishing Engine Interactive, Arbortext Import/
Export must also be licensed on your Arbortext Publishing Engine server. Refer to
the Arbortext Import/Export chapter of the Customizer's Guide for information on
configuring and using Arbortext Import/Export.

44 Installation Guide
Licensing Prerequisites
To license Arbortext Publishing Engine, you will need to:
• You must obtain your Arbortext Publishing Engine license from the PTC
support web site. Obtaining Licenses on page 45 provides more information
on obtaining a license.
• Request a license on the PTC Support site at support.ptc.com. Have your
customer login, password, customer number, and Host ID for the Arbortext PE
server. See Requesting Licenses on page 46 for instructions, particularly on
how to get the Host ID.
• Receive the license pack file containing your configured license. The license
pack file is a text file attached to an email from PTC License Management
([email protected]). Save the attached license pack file to a folder on the
Arbortext PE server. See Receiving Your License Pack on page 47 for
instructions.
You may not have to enter license information for Arbortext Publishing Engine if
a license administrator has already deployed license information to the Arbortext
PE server. License information is stored in an environment variable, explained in
PTC_D_LICENSE_FILE Environment Variable on page 47.

Obtaining Licenses
You will need to obtain a new license for the Arbortext Publishing Engine 8.2
release. You must update your license each time you upgrade to a major Arbortext
Publishing Engine .0.0 release (maintenance releases or datecode updates do not
require a license update). For example, a license issued for 8.2 would work with
Arbortext Publishing Engine 8.2.1.0. A license issued for 8.0 would not be
compatible with 8.1, 8.2 and so on.

What You Will Need

When you obtain your license, you will need your PTC support site login
information and customer number for the PTC support site. You will also need the
Host ID of the computer, explained in Requesting Licenses on page 46.
You can submit a request for help on the PTC Customer Support at support.ptc.
com, by choosing Create a New Support Case. You can also contact PTC License
management support by telephone.

Arbortext Publishing Engine Licensing 45

Requesting Licenses
Read the License Management chapter in your PTC Customer Service Guide
before you start configuring an PTC Arbortext license. The general instructions in
that chapter will prepare you for the licensing instructions that follow.
On the PTC Support web site, the licensing web tool steps you through the
process of configuring your software to your hardware. You need a PTC.com web
account login, your Customer Number, and your Host ID code unique to the
computer. You can get the Host ID:
• by running cpu_id.exe from a Windows command prompt (available from
the flexlm directory in the download zip file).
• the first time you run Arbortext software, if it can’t obtain a license. The
Licensing Error dialog box will prompt for license source information and
provide the Host ID for the system.
• by going to the following web page on the PTC support site for instructions:
https://www.ptc.com/en/support/article/CS341274
It’s possible that a license administrator has deployed the licensing information to
your Arbortext PE server. Information on the node-locked license file is stored in
the PTC_D_LICENSE_FILE Environment Variable on page 47. You may never
be prompted for license information unless you encounter a problem.
You will use the PTC License Landing Page to configure a license for your
Arbortext PE server:
1. Go to the PTC support page at support.ptc.com.
2. Choose Arbortext.
3. Choose Arbortext License Support and log in to your PTC account when
prompted. You will need your login name, password, and Customer Number.
4. Choose your Product Family from the list.
5. Choose the Version from the list. The Hardware Selection is then displayed.
6. Enter the PTC Host Id (available by following the directions at the beginning of
this section). If your computer is already in the system, you can Browse for it.
Enter the name for your computer in the Host/Triad Name.
The PTC Host Id and Host/Triad Name identify the Arbortext PE server
computer.
Click Continue.

46 Installation Guide
7. If the Host ID is not in the PTC licensing system, you will be asked to enter an
installation address and contact that will be associated with the Host ID.
8. Confirm the combination of Arbortext Publishing Engine and hardware for
your license. Then click Get License. You will get a call number for
confirmation of the request.
The license transaction is processed and the license file will be emailed to you,
usually within 10 minutes.

Receiving Your License Pack

After you have finished Requesting Licenses on page 46, a license pack file will
be sent to you by email from [email protected]. The attached license pack is a text
file with a file name of the form lm_xxxxxxxx_standard.txt. Save the
attached license pack file to a location on the Arbortext PE server.
You need to set the PTC_D_LICENSE_FILE environment variable to the file
path of the license file in the environment variable.

Note
By default, Arbortext Publishing Engine is installed under the Windows
SYSTEM account. Be sure PTC_D_LICENSE_FILE is set as a System
Variable in the server’s System Properties.

Refer to PTC_D_LICENSE_FILE Environment Variable on page 47 for

instructions.

PTC_D_LICENSE_FILE Environment
Variable
Arbortext Publishing Engine looks for the path to a FlexNet node-locked license
file in the PTC_D_LICENSE_FILE environment variable automatically when it
starts. If PTC_D_LICENSE_FILE does not exist or has an incorrect value, you
will need to specify it.

Arbortext Publishing Engine Licensing 47

 Note
By default, Arbortext Publishing Engine is installed under the Windows
SYSTEM account. If you start Arbortext Publishing Engine and PTC_D_
LICENSE_FILE does not exist or has an incorrect value, its Arbortext PE
sub-processes will report a license error.
If you try to start Arbortext Publishing Engine Interactive without a valid
PTC_D_LICENSE_FILE, you will see a Licensing Error dialog box
prompting you for license information. Because this dialog box will set the
variable as a User variable, Arbortext PE sub-processes will still be unable to
find the license. Be sure PTC_D_LICENSE_FILE is set as a System variable
in the server’s System Properties.

Refer to Troubleshooting Arbortext Publishing Engine Licensing on page 48 for

information on how to obtain a licensing report from the Arbortext PE server.
It’s possible that a license administrator has deployed the licensing information to
the Arbortext PE server by setting the PTC_D_LICENSE_FILE environment
variable. You may never be prompted for the information unless you encounter a
license problem.

Troubleshooting Arbortext Publishing

Engine Licensing
The Arbortext PE Request Manager itself does not need a license to run, but
Arbortext Publishing Engine Interactive and the Arbortext PE sub-processes do
require a license. A license error will report that the PTC_D_LICENSE_FILE
Environment Variable on page 47 is either missing or set to an incorrect value.
You can check the license information as long as the servlet container you are
using has been configured for Arbortext Publishing Engine. Refer to Server
Configuration on page 51 for servlet configuration information.
• The Arbortext Publishing Engine administrative web page has a License
link that returns the License Information report. The report lists basic
information about the installation, as well as the license source, the user under
which Arbortext Publishing Engine is running, and the number of processor
cores and packages on the Arbortext PE server. It also lists the optional
software components installed and whether they are licensed.
A license error report will be returned with the information that PTC_D_

48 Installation Guide
 LICENSE_FILE is either missing or set to an incorrect value (and the
incorrect value will be provided).
• The Arbortext Publishing Engine administrative web page has a Status link
that includes the system Environment Variables in the report.
If PTC_D_LICENSE_FILE is set, it will be included in the Environment
Variables report.
You can submit a request for help on the PTC Customer Support at support.ptc.
com by choosing Create a New Support Case. You can also contact PTC License
management support by telephone.
For information on the Arbortext Publishing Engine administrative web page,
refer to Monitoring and Reporting Using a Web Browser on page 27

Arbortext Publishing Engine Licensing 49

 4
Server Configuration
Installing and Integrating Tomcat ................................................................................52
Testing Arbortext Publishing Engine Servlet Container Integration ................................55
Configuring OWASP CSRFGuard utility ......................................................................55

The Arbortext PE Request Manager is a web application that uses two

configuration files. The PE_HOME\e3\e3\WEB-INF\web.xml file is a web
application deployment descriptor file. This file can specify servlet mappings and
authentication. The Arbortext Publishing Engine PE_HOME\e3\e3\WEB-INF\
e3config.xml file is used to define Arbortext Publishing Engine and
Arbortext PE sub-process configuration. Both of these configuration files are
explained in the Configuration Guide for Arbortext Publishing Engine guide.
If you are using Arbortext Publishing Engine as a publishing server for Arbortext
Editor clients, the release of Arbortext Editor on each workstation must be
supported by the release of Arbortext Publishing Engine installed on the server. A
release mismatch will be reported as an error. Refer to System and Software
Requirements for Arbortext Publishing Engine on page 22 for release
compatibility information.

51
Installing and Integrating Tomcat
You can choose to install the JVM and Tomcat before installing Arbortext
Publishing Engine to take advantage of the prompt to automatically integrate
Tomcat with Arbortext Publishing Engine at the end of the installation.

Installing a JVM
You'll need to install a JDK to provide Tomcat with a Java Virtual Machine.
This release of Arbortext Publishing Engine was tested using Tomcat running on
Oracle Java 21 and Amazon Corretto 21. If you choose a later release, it's likely to
work for Arbortext Publishing Engine, but it can't be verified without formal
testing.

Installing Tomcat
The Tomcat servlet container is called Catalina. In the Tomcat Catalina
documentation, you may see the installation directory referred to as CATALINA_
HOME. However, for Arbortext Publishing Engine, we'll refer to the Tomcat
Catalina installation directory as TOMCAT_HOME.
To install Tomcat on Windows
1. Uninstall your previous version of Tomcat.
2. Apache Tomcat servlet container for Arbortext Publishing Engine can be
obtained from the Apache Tomcat website. The version details of Apache
Tomcat that are tested with this release can be found in the Product Release
Calendar on PTC.com..
3. Install Tomcat in the location of your choice. You'll need to remember this
path as TOMCAT_HOME. You'll be prompted to confirm the location of the
Java Virtual Machine that Tomcat should use.
4. Make sure you choose to install Tomcat as a service. Keep the default
Windows service name to allow Arbortext Publishing Engine Configuration to
start and stop the service.
5. If you will be transmitting file names that contain non-ASCII characters to
Arbortext Publishing Engine for publishing, you will need to be sure the URLs
are properly encoded for UTF-8. You need to add the URIEncoding
attribute to each active Connector in the Tomcat server.xml configuration
file (such as the one that enables HTTPS support). Enter the attribute and
value URIEncoding="UTF-8", like the following example.
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8333" URIEncoding="UTF-8" />

52 Installation Guide
 Consult the Tomcat documentation for information on URI encoding.
6. Make sure you add following parameter in the Java 9 Options under Java tab
in Tomcat Properties dialog box:
--add-opens=java.base/java.util.regex=ALL-UNNAMED
This is to ensure that the CSRFGuard utility does not block Arbortext
Publishing Engine URLs.
7. All the other choices are optional for Arbortext Publishing Engine. Tomcat's
documentation and sample applications are optional but helpful.

Note
You must also ensure that Tomcat is configured in line with current security
best practices.

By default, the Windows service is named Tomcatn, where n is the major release
number of Tomcat (for example, Tomcat9). Do not rename the Tomcat service
because the Arbortext Publishing Engine Configuration utility will not be able to
find it. Having a different name prevents the ability of Arbortext Publishing
Engine Configuration to start and stop the service.
For more information about using Arbortext Publishing Engine Configuration to
manage integration with Tomcat, see the Configuration Guide for Arbortext
Publishing Engine.

Configuring Publishing Engine Post Installation

As of version 8.5-45 and later, the Tomcat server runs the SERVICE group as
default instead of the SYSTEM group. This restricts the Arbortext Publishing
Engine from successfully creating the Arbortext Editor subprocess. To enable
creation of the Arbortext Editor subprocess, the SERVICE group requires
permissions similar to the SYSTEM group.

Adding and Granting the Service group User Permissions

To add and grant the SERVICE group user permissions, follow these steps:
Run Dcomcnfg.exe to display the Component Services window.
1. Under Console Root, go to Component Services ▶ Computers ▶ My Computer ▶
DCOM Config.
2. Click No, to any DCOM Configuration warnings about recoding an Appid.

Server Configuration 53
3. Right click on the Arbortext Editor entry under DCOM Config and select
Properties.
4. Click Security within the Arbortext Editor properties window.

Adding Launch and Activation Permissions for SERVICE group

To add launch and activation permissions, follow these steps:
1. In the Launch and Activation Permissions window, select Customize and click
Edit.
2. Click Add. Type SERVICE in the object name Edit box and click Check
Names.
3. Ensure SERVICE group is highlighted and click OK. Click OK to save and
close the Select Users or Groups window.
4. Ensure SERVICE group is highlighted in the Group or user names section and
in the Permissions for SERVICE section ensure that Allow is checked for Local
Launch and Local Activation. Click OK.

Adding Access Permissions for SERVICE group

To add access permissions, follow these steps:
1. In the Access Permissions section, select Customize and click Edit.
2. Click Add. Type SERVICE in the object name Edit box and click Check
Names.
3. Ensure SERVICE group is highlighted and click OK. Click OK to save and
close the Select User or Groups window.
4. Ensure SERVICE group is highlighted in the Group or user names section and
in the Permissions for SERVICE group section ensure Allow is checked for
Local Access and click OK.

Finalizing Permissions for SERVICE group

To finalize the permissions, follow these steps:
1. Click Apply and then OK to save the changes and close the Arbortext Editor
Properties window.
2. Close the Component Services window.

54 Installation Guide
Testing Arbortext Publishing Engine
Servlet Container Integration
You can test Arbortext Publishing Engine integration with its servlet container by
following these steps.
1. Verify that Arbortext Publishing Engine and the web server are configured
properly by entering the URL that specifies Arbortext Publishing Engine in a
web browser. In the following example, substitute the server name and port the
web server is configured to listen on.
http://server:port/e3

The web browser will display the Arbortext Publishing Engine index page.
From there you can get more information about the state of Arbortext
Publishing Engine by clicking on the Status link to get a status report.
2. To test that Arbortext Publishing Engine can handle a request to do work, run
a sample application by clicking one of the ACL, Java, JavaScript, or VBScript
language links available from the Arbortext Publishing Engine index page. If
the application returns information about the Arbortext Publishing Engine
environment, then Arbortext Publishing Engine is working properly.

Configuring OWASP CSRFGuard utility

Cross-site request forgery (CSRF) is a web security vulnerability. An attacker
exploits this vulnerability to induce users to perform actions that they do not
intend to perform. It allows an attacker to partly circumvent the same origin
policy, which is designed to prevent different websites from interfering with each
other.
CSRFGuard utility, a token-based method is implemented in Arbortext
Publishing Engine to mitigate the risk of CSRF attacks.
You can find configuration of the CSRFGuard utility in
csrfguard.properties file located at PE_HOME\e3\e3\WEB-INF.
The CSRFGuard is enabled by default and protects all pages of the Arbortext
Publishing Engine administration application. Further configuration of the
CSRFGuard is possible via the csrfguard.properties file which contains
relevant instructions.
Protecting and unprotecting resources is achieved via a combination of updating
the section E3 Configuration: Parameters as URI endpoints and the
Unprotected Pages section. You can refer to the
csrfguard.properties file for more detailed information.

Server Configuration 55
 5
Troubleshooting
Troubleshooting Errors ..............................................................................................58
Getting Trace Information...........................................................................................58
Publishing Very Large Documents on Windows ...........................................................59
Glossary ...................................................................................................................59

There are several mechanisms and procedures to aid in troubleshooting. In the

following sections, learn more about how to check Tomcat logs, trace diagnostics,
and address an Out of virtual memory space error.
If you are having trouble with licensing, be sure to see Troubleshooting Arbortext
Publishing Engine Licensing on page 48.

57
Troubleshooting Errors
Review the information for how to use the tracing and logging parameters in the
e3config.xml file, as well as other tracing and logging tips. If you're
troubleshooting Arbortext PE sub-process startup problems, you can check the
transaction archive.
When you're troubleshooting Arbortext Publishing Engine, you may decide to run
Arbortext Publishing Engine Interactive. If you created a specific user account for
Arbortext Publishing Engine, be sure to log on the system with that user account
name to better simulate its environment.
Be sure to check all log and temporary directory folders used by the servlet
container and the Arbortext PE server. Some of these may be explicitly set in the
e3config.xml file. Check that the paths specified there exist on the system.
The Tomcat log files in TOMCAT_HOME\logs contains log messages written by
the Arbortext PE Request Manager. The pelog.xml file contains log4j
messages that can be used for troubleshooting.

Note
By default, the Tomcat Windows service is named Tomcatn, where n is the
major release number of Tomcat. If the Tomcat service has a different name,
Arbortext Publishing Engine Configuration can't start and stop the service.

Getting Trace Information

Arbortext Diagnostics tool is a program that displays tracing information. It tracks
identification information, requests and responses, and exceptional conditions.
You can launch it from the shortcut called Arbortext Publishing Engine
Diagnostics in your PTC program group.
When an Arbortext PE sub-process starts, it launches an agent that gathers
information from the Arbortext PE Request Manager and its Arbortext PE sub-
processes. The agent passes it to the Arbortext Diagnostics program which has two
tabs:
• Trace Log tab displays tracing messages.

Tracing messages about the Arbortext PE Request Manager and Arbortext PE

sub-processes are relayed to Trace Log.
On the Arbortext Diagnostics menu, you can choose File ▶ Edit Trace Log to
send the tracing messages to your default text editor. From the text editor, you

58 Installation Guide
 can save the log to a file. If you are reporting a problem, you should generate
and send this file with any other diagnostic information to Technical Support.
• Module List tab displays identification information about the Arbortext PE
sub-processes as well as:
○ Host machine name and user name
○ Status: running or busy (that is, no response in 1/10 second)
○ Process ID of the Arbortext PE sub-process
○ Build number of the Arbortext PE sub-process executable
○ Full path to the binary that was executed
From the Arbortext Diagnostics window, you can choose Options ▶ Preferences to
set the buffer size for the trace log and remember the window's screen position
when the program is restarted. You can choose Options ▶ Always On Top to keep
the Arbortext Diagnostics window on top of other application windows. Your
choices are saved to the directory where Arbortext Diagnostics started.
If Arbortext Diagnostics is not running, Trace Log information is discarded. After
you start Arbortext Diagnostics, subsequent tracing information is acquired and
displayed.

Publishing Very Large Documents on

Windows
When publishing very large documents to PDF on Windows, the publishing
process may fail with an Out of virtual memory space error message. This
situation can occur when the publishing process encounters a Windows 2GB
memory addressing limitation. You can update your Windows boot.ini file to
address 3GB of memory using the instructions provided on Microsoft's web site.

Caution
Ensure that you make the change exactly as described in the Microsoft
documentation. Incorrectly modifying system files can leave your workstation
in an unstable state.

Glossary
Glossary of terms for Arbortext Publishing Engine:

Troubleshooting 59
 Glossary

Arbortext
A Java object that implements the E3Initializer interface. This
Publishing object's init method is called after all other objects are
Engine initialized. An initializer can execute startup tasks, such as
Initializer retrieving and caching publishing configuration reports or
transforming and caching stylesheets.

Arbortext
Java object that implements the com.arbortext.e3.E3Notifier
Publishing interface. A notifier is called by the Arbortext PE Request
Engine Manager each time a transaction changes state. A notifier can be
Notifier implemented and configured to respond to a transaction state
change by performing an action, such as sending an email.

Arbortext
Java object that implements the com.arbortext.e3.
Publishing ArbortextQueue interface. The Arbortext Publishing Engine
Engine Queue Queue is a container of ordered transactions that are awaiting
execution. Transactions are placed on a queue by the Arbortext
Publishing Engine Queue Manager. The Queue Manager offers
the request to each queue in the order in which they are defined
in the Arbortext Publishing Engine e3config.xml
configuration file. When a queue accepts the request, it holds it
until the Queued Transaction Scheduler selects it for processing.
After completion, a queued transaction is deleted from its queue.

Arbortext
Java object that implements the com.arbortext.e3.
Publishing QueueManager interface. The Arbortext Publishing Engine
Engine Queue Queue Manager determines whether an HTTP request should be
Manager queued. Arbortext PE Request Manager offers the request to
each queue manager in the order in which they are defined in the
Arbortext Publishing Engine e3config.xml configuration
file. When a queue manager accepts the request, Arbortext PE
Request Manager waits for the response from the Queue
Manager and passes it to the client.

61
Arbortext
A Java object that implements the E3RequestContext interface.
Publishing The Arbortext Publishing Engine Request Context provides
Engine services and information about resources available to the context
Request and writes to log files.
Context
The Request Context object is created by the Arbortext PE
Request Manager init method. It provides information to each
Arbortext Publishing Engine Request Handler, Arbortext
Publishing Engine Request Selector, Arbortext PE sub-process
pool, Arbortext Publishing Engine Cache Manager, Arbortext
Publishing Engine Queue Manager, and Arbortext Publishing
Engine Initializer.
The Request Context provides information about the Arbortext
Publishing Engine environment such as parameter values, and
about services such as the location of an Arbortext PE sub-
process pool. It can also write to a servlet log and permit custom
code to modify the global state of the Arbortext Publishing
Engine environment.

Arbortext
A Java object that implements the E3RequestEvaluator
Publishing interface. The Arbortext Publishing Engine Request Evaluator
Engine can be defined in the TestSet section for each
Request SubprocessPool, QueueManager, Queue, and
Evaluator Notifier defined in the Arbortext Publishing Engine
e3config.xml file.
The wrapper TestSet object can combine a set of defined
Arbortext Publishing Engine Request Selector tests to create test
criteria. Two or more tests can be combined using AND and OR
logic to form more complex criteria. For example, a TestSet
might have a test to detect a particular content-type header
and another test to detect a particular query parameter with a
specific value. If an HTTP request meets this criteria, the
Arbortext Publishing Engine Request Evaluator returns a
boolean value of TRUE and the request would be accepted for
processing.

Arbortext
A Java object that implements the E3RequestFunction
Publishing interface. The Arbortext Publishing Engine Request Handler is
Engine configured to map query parameters from the request to
Request Arbortext Publishing Engine Request Functions. Each built-in
Function Arbortext Publishing Engine function is mapped to a
corresponding built-in Arbortext Publishing Engine Request
Function. For example, the f=status function is mapped to
the com.arbortext.e3.FunctionStatus interface.

62 Installation Guide
 The Request Handler distributed with Arbortext Publishing
Engine can be customized to add custom function names and
mappings without writing a new Arbortext Publishing Engine
Request Handler.

Arbortext
A Java object that implements the E3RequestHandler interface.
Publishing The Arbortext PE Request Manager passes an incoming request
Engine to each defined Request Handler to determine which one is
Request configured to service it.
Handler
A custom Arbortext Publishing Engine Request Handler must
implement the init, destroy, and service methods. The init
method is called during Arbortext PE Request Manager
initialization, and it receives the Arbortext Publishing Engine
Request Context object and the parameters from the Arbortext
Publishing Engine configuration file (e3config.xml). The
service method is called to process a client request, creating a
request object and a response object. The Arbortext PE Request
Manager goes to each Request Handler, in the order they're
defined in e3config.xml, looking for a response that
signifies whether it can process the query in the request. The
Arbortext PE Request Manager calls the Request Handler's
destroy method during termination.

Arbortext PE
The Arbortext Publishing Engine Java servlet that handles all
Request HTTP requests and responses for document conversion and
Manager manipulation. It implements the standard init, service, and
destroy methods of a servlet.
Incoming requests are passed to active Arbortext Publishing
Engine Request Handlers according to configured criteria. When
a response is returned to the servlet, the Arbortext PE Request
Manager conveys the response to the servlet container, which
returns the response to the client making the request.

Arbortext
A Java object that implements the E3ApplicationRequest
Publishing interface and contains all information being submitted in an
Engine HTTP request to Arbortext Publishing Engine.
Request
Object

Arbortext
A Java object that implements the E3ApplicationResponse
Publishing interface and contains the response to be transferred to the
Engine HTTP client making a request.

Glossary 63
Response
Object

Arbortext
A Java object that implements the E3RequestSelector interface.
Publishing Each Arbortext Publishing Engine Request Selector object
Engine applies test criteria to a request to help determine routing. If the
Request request matches a predefined condition, the request is accepted
Selector by its Arbortext PE sub-process pool for processing.
A Request Selector has an init and a test method. The init
method is called during Arbortext PE Request Manager
initialization; and it receives the information in the Arbortext
Publishing Engine Request Context object and the parameters
from the Arbortext Publishing Engine configuration file
(e3config.xml). The test method is called when the
Arbortext PE Request Manager needs to evaluate a request
against a set of tests associated with an Arbortext PE sub-
process pool. For example, a request selector could test a request
for an HTTP header content-type: text/xml and return
TRUE or FALSE.
Request Selectors can be logically combined using AND and OR
statements in the TestSet defined for each Arbortext PE sub-
process pool in e3config.xml.

Arbortext PE
A Java object that implements the com.arbortext.
sub-process E3SubprocessPool interface and controls a group of Arbortext
PE sub-processes that are identical and interchangeable.
Arbortext PE Request Manager evaluates an HTTP request
against the parameters for each Arbortext PE sub-process pool
in the order they're defined in e3config.xml.
Each Arbortext PE sub-process pool is uniquely identified and
has its own parameters, such as minimum and maximum number
of processes, time-out values, and so on. If you have more than
one Arbortext PE sub-process pool, each one must have an
Arbortext Publishing Engine Request Evaluator TestSet
defined in e3config.xml that specifies the criteria for
accepting HTTP requests.
One Arbortext PE sub-process pool must always be configured
as the default pool. The default pool allocates an Arbortext PE
sub-process to service any HTTP request that no other pool can
accept. Because a request is assigned to the first Arbortext PE
sub-process pool with matching criteria, the order in which
pools are defined is important. You must define the default pool
last to be sure that all other enabled pools are evaluated first.

64 Installation Guide
 The Arbortext PE sub-process pool can't be customized.

Arbortext PE
A Java object that implements the E3SubprocessContext
sub-process interface. The Arbortext PE sub-process Context object contains
Context any parameters specified in the SubprocessContext
element for a SubprocessPool, along with the Arbortext PE
sub-process pool name and the Arbortext PE sub-process
number (taken from the range of configured minimum to
maximum number of Arbortext PE sub-processes).
The Arbortext PE sub-process Context serves two purposes:
• An Arbortext Publishing Engine Request Handler can
retrieve the information provided by the Arbortext PE sub-
process Context.
• The Arbortext PE sub-process Context object is passed to
the individual Arbortext PE sub-process taking the request,
making it available to Arbortext Publishing Engine custom
ACL, Java, JavasScript, and VBScript applications.

Arbortext
A transaction is a request and response pair of objects that are
Publishing processed by Arbortext Publishing Engine. The transaction
Engine includes the request transmitted to Arbortext PE Request
Transaction Manager by a client, the response that’s returned to the client,
and any intermediate files or logs generated when producing the
response. The transaction is created upon receiving the request,
and associated files are placed in the active transaction directory
to wait for processing. There are two types of transactions:
• an immediate transaction
Arbortext PE Request Manager transmits the response to the
waiting client immediately after processing is complete. The
immediate transaction will then be deleted from the active
transaction directory. You can configure an immediate
transaction to be archived in the Transaction Archive
directory afterward.
• a queued transaction
Arbortext PE Request Manager places a transaction on a
queue (provided the request meets queuing criteria) until it
can be processed. After the transaction is processed, the
client can retrieve the resulting output from the active
transaction directory using the transaction ID. The
transaction will be deleted from the active transaction

Glossary 65
 directory according to the configuration settings for duration
and retrieval by the client. You can configure a queued
transaction to be archived in the Transaction Archive
directory afterward.

Request
A Java object that contains all the information from a client
object HTTP request. A servlet is configured to handle it by evaluating
a portion of the URL for routing.

Response
A Java object that's created in conjunction with the Request
object object and constructed to handle the returned results. A custom
application uses its methods to specify the information to be
returned as the HTTP response.

Servlet
A web component, managed by a servlet container, that
generates dynamic content. Servlets interact with web clients
using a request and response model implemented by the servlet
container. This request and response model is based on the
behavior of the Hypertext Transfer Protocol (HTTP).

Servlet
A servlet container deploys the web application into its runtime
container environment. It loads and manages a servlet throughout its
lifecycle using the servlet context. When the servlet container
initializes the servlet, it creates the servlet context object which
contains information about the servlet's runtime environment.

Servlet
A Java object that manages the runtime state of a servlet for the
context servlet container. It defines the servlet's view of the web
application it's running in.

Web
A collection of servlets, JavaServer Pages, HTML documents,
application images, archives, or other data.

66 Installation Guide
 Index

A user account, 33-35

default printer for Windows user
adapters
account, 33-35
using with PE, 33-35
printers, 33-35
administrative skills needed for
setting up environment variables,
Arbortext Publishing Engine, 7
33-35
Arbortext Import/Export
setting up HTML Help, 33-35
licensing, 43
testing
Arbortext Publishing Engine
on Windows, 55
upgrading licenses, 45
using repository adapters, 33-35
Arbortext Publishing Engine
Windows
configuration
printers, 33-35
testing, 27
Windows user account, 39, 42
Arbortext Publishing Engine
contacting technical support, 7
integration
testing, 27
Arbortext Publishing Engine licensing, D
43 documentation
Arbortext Publishing Engine trace Javadoc, 14
information, 58 organization, 14
Arbortext Publishing Engine PDF manuals, 14
troubleshooting, 58 documentation and other resources, 14
archive contents, 13

F
B
feature list, 12
browser support
administrative web page, 22, 24-26
web clients, 22, 24-26 H
HTML Help setup, 33-35
C
configuring Arbortext Publishing I
Engine information resources, 14
testing, 27 integrating Arbortext Publishing
configuring PE Engine
default printer for Windows testing, 27

67
J printer recommendations on Windows,
33-35
Java interfaces
product support contact information, 7
documentation for PE, 14
PTC_D_LICENSE_FILE
Javadoc
setting for licensing, 47
for PE interfaces, 14
JRE support, 22, 24-26
R
L recommendations
print events, 33-35
licenses
print spooling, 33-35
prerequisites, 45
Windows print events, 33-35
receiving, 47
Windows print spooling, 33-35
requesting, 46
Windows printer, 33-35
licensing
repository adapters
setting PTC_D_LICENSE_FILE, 47
using with PE, 33-35
licensing Arbortext Publishing Engine,
requirements
43
disk space, 22, 24-26
list of
archive contents, 13 system, 22, 24-26
features, 12
information resources, 14 S
skills needed for Arbortext Publishing
P Engine, 7
SOAP
PDF support, 22, 24-26
with Tomcat, 52
PE configuration, 39, 42
support contact information, 7
default printer for Windows user
system requirements, 22, 24-26
account, 33-35
printers, 33-35
setting up environment variables, T
33-35
testing Arbortext Publishing Engine
setting up HTML Help, 33-35
configuration
testing
using Arbortext Publishing Engine
on Windows, 55
index page, 27
using repository adapters, 33-35
testing PE configuration
Windows
on Windows, 55
printers, 33-35
Tomcat
platform support, 22, 24-26
with Arbortext Publishing Engine,
print events, 33-35
52
print events on Windows, 33-35
trace information Arbortext Publishing
print spooling on Windows, 33-35
Engine, 58

68 Installation Guide
troubleshooting Arbortext Publishing
Engine, 58

U
upgrading
Arbortext Publishing Engine
licenses, 45
upgrading a previous release
Windows, 36
user account for PE, 39, 42
user account for PE on Windows
default printer, 33-35

W
web browser support
administrative web page, 22, 24-26
web clients, 22, 24-26

Index 69