A Guide to QuarkXPress Server 2018

Getting started with QuarkXPress Server

QuarkXPress Server lets you render QuarkXPress projects in a variety of formats.

QuarkXPress Server architecture

The QuarkXPress Server architecture is shown in the following diagram.

QuarkXPress Server architecture diagram

Understanding QuarkXPress Server

QuarkXPress Server helps automate the generation of QuarkXPress layouts to a variety of output formats—including JPEG, Portable Document Format (PDF), and PostScript®—all from a centralized Web application. To send a request to QuarkXPress Server, all you need to do is enter a URL into your Web browser's address field. For example, the following URL instructs the QuarkXPress Server application named "QXPServer" to return the file "MyProject.qxp" as a PDF file:

http://QXPServer:8080/pdf/MyProject.qxp

The QuarkXPress Server application receives these requests, renders (creates) the requested projects in the requested formats, and then returns the rendered file to the client application—the Web browser in this case.

The format of QuarkXPress Server URL requests is described in detail in "Creating URL requests".

You can also create custom applications that communicate with a QuarkXPress Server application using HTTP, Simple Object Access Protocol (SOAP), or another protocol.

You can think of QuarkXPress Server as a special version of QuarkXPress that runs on a server with the following main differences:

  • Instead of accepting input from a keyboard and mouse, QuarkXPress Server accepts input in the form of URLs and other types of requests.

  • Instead of sending a project to a printer, QuarkXPress Server renders (creates) output in a particular format and sends the rendered file to a client.

Server templates and static projects

QuarkXPress Server can open, render, and serve two types of projects:

  • Static projects are QuarkXPress projects that can be rendered and served as-is in a variety of formats by the QuarkXPress Server application. For example, you might make a product manual available as a static project and allow customers to download that manual in a variety of formats.

  • Server templates are QuarkXPress projects that can be manipulated by the QuarkXPress Server application before being rendered and served. For example, you might make a sales piece available as a server template so that each person who downloads it receives a personalized copy.

QuarkXPress Server can open QuarkXPress documents, projects, and templates created in any language edition of QuarkXPress 7.0 or later. QuarkXPress Server can save and export projects in QuarkXPress 8.x, 9.x and 10.x format.

The document pool and the Streaming Document Provider

QuarkXPress Server has two main ways to find or receive content for rendering.

  • The document pool

  • The Streaming Document Provider

QuarkXPress Server can read templates and static projects from a directory called the document pool. The document pool can be any directory that is available to QuarkXPress Server through a file system or an FTP server. You can use any of the following methods to place files in the document pool:

  • Drag the files to the document pool directory.

  • Use the Add Files command in the Document Pool screen of the QuarkXPress Server Web interface.

  • Upload the files using FTP to the document pool directory.

  • Use Telegraph XTensions® software to upload the files to the document pool from within QuarkXPress. (For more information about Telegraph XTensions software, see "Telegraph XTensions software.")

For more information about the document pool, see "The QuarkXPress Server User Interface."

The document pool directory cannot be an encrypted directory.

QuarkXPress Server can also receive templates, projects, and other files as part of a multipart HTTP request. For more information, see "Using the Streaming Document Provider."

In addition, QuarkXPress Server can serve documents from a database, a content management system, or other sources. Collectively, the document pool and any other source of files to be served are referred to as document providers.

Projects and layouts

QuarkXPress projects can contain one or more layouts, and only one layout can be rendered at any given time. If you do not specify a layout when you send a rendering request, QuarkXPress Server renders the first layout in the project.

Job Jackets and resources

In QuarkXPress, resources are things such as style sheets, colors, H&Js, output styles, and item styles. Resources are stored in a Job Jackets structure, which can be either embedded in a project or stored in a separate Job Jackets file.

QuarkXPress Server uses a default Job Jackets file to make a default set of resources available to all projects handled by QuarkXPress Server, regardless of whether they are included in the projects and articles you render. You can update this file in two ways:

Once you've downloaded the default Job Jackets file, you can update its resources using QuarkXPress. For more information, see "Job Jackets" in A Guide to QuarkXPress.

The location of the default Job Jackets file is stored in the QuarkXPress Server preferences folder. For more information, see "QuarkXPress Server preferences."

Caching

To maximize efficiency, QuarkXPress Server uses cached versions of all rendered projects whenever possible. You can configure projects so that they are never cached, so that they are cached for a particular amount of time, or so that they are rendered every time they are served.

QuarkXPress Server preferences

When you launch QuarkXPress Server, the application creates preferences files that are functionally and structurally equivalent to the preferences files created by QuarkXPress. These preference files reside in the QuarkXPress Server "Preferences" folder. QuarkXPress Server also creates a "QuarkXPress Server.prf" file in the "Preferences" folder. This file contains preference settings that are specific to QuarkXPress Server.

QuarkXPress Server uses these preferences the same way QuarkXPress uses them. If an XTensions module creates a project in QuarkXPress Server, that project draws its settings from the QuarkXPress Server preferences just as a new QuarkXPress project draws its settings from the QuarkXPress preferences.

Preferences files are stored in the following locations:

  • macOS: [User]/Library/Preferences/Quark/QuarkXPress Server Renderer/

  • Windows: C:\Windows\System32|config\systemprofile\AppData\Roaming\Quark\QuarkXPressServer Renderer [version]

For more information about preferences, see the "Administration menu."

Quark License Administrator

To prevent unauthorized use, launching QuarkXPress Server requires the presence of a Quark® License Administrator (QLA) server. QuarkXPress Server follows the configuration and control rules that are enforced by QLA. For more information about QLA, see the QLA documentation included with QuarkXPress Server.

Master-renderer environment

Requests for project renders are stored in a connection queue. The requests in the rendering queue can be processed by a single QuarkXPress Server application, or by a master QuarkXPress Server application and several renderers (additional instances of QuarkXPress Server). The master QuarkXPress Server application launches the available number of renderers and then passes the requests in the connection queue to those renderers as they become available. The number of renderers available for launch is determined by the number of licenses available from the QLA server.

The master QuarkXPress Server process and all the renderers it launches share the following elements:

  • The same application preferences (each renderer has its own preferences files, but QuarkXPress Server keeps them synchronized)

  • The same document cache in memory

  • The same memory cache

  • The same server XTensions modules (a separate instance of each XTensions module runs with each renderer)

  • The same server document pool (if defined in the QuarkXPress Server preferences or if a document provider is used in place of the document pool)

If a renderer unexpectedly quits, the master QuarkXPress Server restarts the renderer without requiring any action from you.

Changing logging levels in "log4j2.xml"

You can change the logging levels for QuarkXPress Server. Options include ERROR, INFO, WARN, DEBUG, and TRACE.

  • ERROR = includes messages that indicate disrupted and failed requests.

  • INFO = includes messages that indicate the state of services.

  • WARN = includes non-critical service error messages

  • DEBUG = includes messages that indicate server resource usage.

  • TRACE = includes messages according to activity related to requests.

Refer to Java documentation for more information about logging levels.

To change logging levels:

  1. Open the "conf" folder in your QuarkXPress Server folder.

  2. Open "log4j2.xml" in a text-editing application.

  3. To define the logging level for QuarkXPress Server errors, scroll to <logger name=com.quark.qxps. The structure is as follows:

    <logger name="com.quark.qxps">
      <level value="ERROR" />
    </logger>
  4. To define the logging level for QuarkXPress Server transactions, scroll to <logger name=QXPSTransactionLogger. The structure is as follows:

    <logger name="com.quark.qxps" additivity="false">
      <level value="INFO" />
      <appender-ref ref="QxpsTransactionFileAppender" />
    </logger>
  5. To define the logging level for other activity, scroll to the <root>. The structure is as follows:

    <root>
      <priority value="ERROR" />
      <appender-ref ref="QxpsServerAsyncAppender" />
    </root>
  6. Save and close "log4j2.xml."

Understanding QuarkXPress Server XTensions software

QuarkXPress Server ships with a collection of XTensions software that adds capabilities to QuarkXPress Server. For example, PDF Export XTensions software lets QuarkXPress Server serve content in PDF format; Modifier XTensions software lets you retrieve, manipulate, and reconstruct XML representations of projects; and QuarkCopyDesk® Renderer XTensions software lets you create QuarkCopyDesk articles. Telegraph XTensions software works with QuarkXPress to allow designers to name boxes in template files so that those boxes can be addressed by URLs.

For more information about XTensions software included with QuarkXPress Server, see "XTensions software" and "Telegraph XTensions software."

The QuarkXPress Server XTensions API

In addition to the XTensions modules included with QuarkXPress Server, developers can create custom XTensions software that add features. The complete server XTensions Application Programming Interface (API) documentation is available in the QuarkXPress Server XTensions Developer's Kit (XDK).

As of version 8.0, the QuarkXPress Server XDK is Unicode-compliant.

The QuarkXPress Server XDK lets you create XTensions modules that provide the following abilities:

  • The ability to register request handlers.

  • The ability to register project providers.

  • The ability to register new render formats.

  • The ability to add items to the list of response properties, cookies, and HTTP header items.

  • The ability to log messages in log files.

  • The ability to initiate a new transaction to be processed by the server.

  • The ability to completely control how projects are processed by the server.

In addition, QuarkXPress Server XTensions software can register for the following basic callbacks:

  • Pre-processing

  • Content loading

  • Layout modification

  • Post-processing

  • Removing slugs while running the QuarkXPress project renderer

  • Analyzing the server after a transaction is complete

  • Pre and post-transaction callback

Configuring QuarkXPress Server for launch

To configure QuarkXPress Server prior to launch, open the file [QuarkXPress Server application folder]/conf/ServerApp.properties folder) and modify it as follows:

  • To make the server run without loading any network interface, use the -nonetwork option with the qxpservercore.serverRendererParameters. In this mode, the only transactions a server can run are those passed to it by another process.

  • To control whether renderers are monitored, set qxpservercore.monitorrenderers.value to true or false.

  • To specify the query interval for monitoring renderers, set qxpservercore.monitorrenderers.queryinterval.value to a value in seconds.

  • To specify the number of retries for monitoring renderers, set qxpservercore.monitorrenderers.noofretries.value to an integer. If a renderer process has been attempting to fulfill a request for the specified number of retries (with the specified query interval in seconds between retries), the renderer monitor recycles that process.

  • To control how many renderers the master process launches, specify a number for qxpserver.subrenders. Note that the number of renderers you can launch depends on your license.

  • To force the renderers to restart on a periodic basis, specify a value in hours for qxps.render.recycle.interval. The default value is 24, or 24 hours. Decimal values are permitted. Renderers restart serially, so one renderer doesn't restart until the other is finished restarting. If a renderer is busy, the master process waits for 15 minutes, and then if the renderer is still busy, postpones the restart until the next interval elapses. Set this value to zero to turn the automatic restart feature off.

  • The request timeout at Renderer lets you specify the timeout value for rendering. It is set to 10 minutes by default.

    qxpserver.renderer.request.timeout.name = requestTimeout

    qxpserver.renderer.request.timeout.value = 10

  • To control whether the server should collect performance metrics, set qxpserver.CollectPerformanceMetrics=true to collect and false to not collect metrics.

  • To set the number to transactions after which performance metrics data will be flushed to file: qxpserver.CollectPerformanceMetrics.flush.transactioncount = 100

  • To send JMX notifications when performance metrics change set: qxpserver.CollectPerformanceMetrics.sendjmxnotifications = true

  • Enable this flag to automatically refresh admin ui through JMX notifications qxpserver.CollectPerformanceMetrics.adminui.autorefresh = true

  • To  reset metrics on every launch of qxps. If set to true, the QuarkXPress Server will clear old metrics and start capturing fresh metrics on every launch. qxpserver.CollectPerformanceMetrics.resetmetricsonserverlaunch = false

  • To accelerate the time to troubleshoot a failed rendering request, QuarkXPress Server creates the rescue folder and collects the data for failed and timed out transactions by default into a folder name QXPSRescuedata<ver> relative to doc pool.

    Setting this value to false means the rescue folder will not be created and no data will be collected.

    qxpserver.rescuefolder.manage=true 

  • Specify the rescue folder path for failed transactions. If no value is given here, the document pool path would be considered by default: qxpserver.rescuefolder.path = <Specify custom folder path>

Launching QuarkXPress Server

On Windows, you can install QuarkXPress Server as an application or as a service (Quark recommends that you always run it as a service). On macOS, QuarkXPress Server always runs as an application.

If you install QuarkXPress Server on Windows as an application, you can launch it using the Start menu or by double-clicking the "ServerStartup.bat" in the QuarkXPress Server application folder.

For information on launching QuarkXPress Server in a separate Tomcat installation, see "Deploying QuarkXPress Server externally" in the QuarkXPress Server Getting Started.

QuarkXPress Server offers a browser-based user interface instead of a conventional user interface.

Quitting QuarkXPress Server

To quit QuarkXPress Server, press Control+C.