A Guide to QuarkXPress Server 2019

QuarkXPress Server Manager

QuarkXPress Server Manager is a server application that efficiently routes rendering requests in an environment that uses one or more QuarkXPress Server applications. QuarkXPress Server Manager uses load-balancing methods to determine which server in the QuarkXPress Server pool can best process a document request, and uses caching to improve speed and efficiency. QuarkXPress Server Manager also provides failsafe capability by reliably resubmitting failed requests, either to the same QuarkXPress Server instance or to a different one (depending on the error message returned by the server instance).

QuarkXPress Server does not require QuarkXPress Server Manager, but a QuarkXPress Server Manager server can coordinate multiple QuarkXPress Server applications so that they work together with maximum speed, reliability, and availability.

QuarkXPress Server Manager also provides a Web services interface that allows developers to use QuarkXPress Server features without having to use the HTTP interface.

To configure a QuarkXPress Server Manager server application, you must use the QuarkXPress Server Manager Web client. The topics below explain how the QuarkXPress Server Manager Web client works and provide examples for using it.

Understanding QuarkXPress Server Manager

Before you begin, take time to review the topics below so that you understand how this chapter is structured and how you can get the most out of it.

Load balancing

Load balancing ensures that each rendering request is sent to a server that is likely to be able to handle it quickly. QuarkXPress Server Manager lets you use choose from three load-balancing settings:

  • Dynamic Load Balancer: The QuarkXPress Server Manager server considers file size and throughput requirements for each request. For example, assume the following series of requests is sent to QuarkXPress Server Manager in an environment that uses two QuarkXPress Server instances:

    Request

    Size

    1

    8MB

    2

    1MB

    3

    2MB

  • Random Load Balancer: Each rendering request is sent to a random server.

  • Round-robin Load Balancer: Requests are sent to servers in a set order. For example, if you have three QuarkXPress Server instances and QuarkXPress Server Manager receives ten rendering requests, the requests are distributed as follows:

    Request

    QuarkXPress Server instance used

    1

    1

    2

    2

    3

    3

    4

    1

    5

    2

    6

    3

    7

    1

The first request is assigned to server #1, and the second request is assigned to server #2. When the third request arrives, QuarkXPress Server Manager checks the loads that the two servers are already handling and assigns the task to the server with the smallest load — in this case, server #2.

If a request fails because a server stops responding or because of a "File Not Found" error, QuarkXPress Server Manager does not resubmit that request to that server.

The Dynamic setting is typically the most efficient setting for environments with more than one QuarkXPress Server instance.

For information about choosing a load-balancing setting, see "Controlling load balancing."

Request timeout interval

QuarkXPress Server Manager attempts to send each request to a QuarkXPress Server instance that can promptly handle that request. However, in some situations a QuarkXPress Server instance might be unable to process a request in a reasonable amount of time (for example, if the server is working on a large rendering job, or if the server computer has stopped functioning). If you specify a certain period of time as the request timeout interval, QuarkXPress Server Manager will wait for the response until that period of time elapses, and then send the request to a different QuarkXPress Server instance. This ensures that a request does not get "lost" if its assigned QuarkXPress Server instance does not become available promptly.

For information about setting a request timeout interval, see "Using other global settings."

If a client request fails despite being sent to multiple QuarkXPress Server instances, QuarkXPress Server sends the end user a customizable error message or exception so that the end user can appropriately handle the failure. A QuarkXPress Server Manager server can also automatically send e-mail to an administrator in the event of a problem; for more information, see "Generating automatic e-mail messages."

Determining QuarkXPress Server instance availability

QuarkXPress Server Manager uses two methods to determine the availability of a QuarkXPress Server instance: ping and ping document.

Ping

QuarkXPress Server Manager periodically sends a ping request to all of its QuarkXPress Server instances to determine whether they are available. Ping requests use the following format:

http://[Server]:[Port]/getprocessid

Ping document

QuarkXPress Server Manager periodically sends a render request to all of its QuarkXPress Server instances to determine whether they can render a document. Ping document requests use the following format:

http://[Server]:[Port]/[PingDocumentName.qxp]

You can specify the document to be used for this render request. To avoid long ping document rendering times, use a simple document.

You can specify the interval between pings and ping documents in the Other Settings pane in the Global Settings pane of the QuarkXPress Server Manager window (see "Using other global settings").

Logging with QXP Server Manager

QuarkXPress Server Manager logs all interactions with QuarkXPress Server instances. QuarkXPress Server Manager log files contain the following information:

  • Render requests

  • QuarkXPress Server responses

  • Information about events (such as alerts) that occur during the render-request process

  • Details about requests that were sent to a different QuarkXPress Server instance after the first assigned QuarkXPress Server instance was unable to process the request

Within the logs, each QuarkXPress Server instance is identified by its IP address and port number.

You can export log files in XML (Extensible Markup Language) or comma-separated values (CSV) format.

Caching

To increase speed and efficiency, QuarkXPress Server Manager caches information in memory. If the response to a render request, URL request, or file request is included in the QuarkXPress Server Manager memory cache, QuarkXPress Server Manager returns the response from the disk cache instead of sending the request to a QuarkXPress Server instance. For more information, see "Managing the cache."

Requests that contain a binary parameter and multipart responses are not cached, regardless of whether global caching or command-specific caching is enabled.

When the QuarkXPress Server Manager server application receives response data from a QuarkXPress Server instance, QuarkXPress Server Manager can return that response directly or write it as a file and return the file's URL. The second approach maximizes efficiency for SOAP-based clients, because SOAP transfers binary data very slowly. Cached response files have names that begin with "TMP_", and they are removed when they reach the age specified in the cache settings (see "Managing the cache"). QuarkXPress Server Manager uses the cache file this way regardless of whether caching is turned on or off; however, you can override this behavior by setting the responseasurl parameter to false for every request.

Web services

QuarkXPress Server Manager provides a Web services interface that makes it easy for developers to create applications that use QuarkXPress Server. This Web services interface provides the same functionality that is available through the QuarkXPress Server HTTP interface.

Working with QuarkXPress Server Manager

The general process for using QuarkXPress Server Manager is as follows:

  1. Install QuarkXPress Server Manager software.

  2. Launch one or more QuarkXPress Server instances on your network.

  3. Launch the QuarkXPress Server Manager Console server application (see Starting the Manager server application").

  4. Launch the QuarkXPress Server Manager Web client (see Starting the Manager Web client").

  5. Use the Manage Servers pane to add QuarkXPress Server instances, specify information about those servers (see "Configuring QuarkXPress Server instances"), and choose a load-balancing method (see "Controlling load balancing").

  6. Configure proxy server settings, automatic e-mail settings, and various other settings in the Global Settings pane (see "Using a proxy server," "Generating automatic e-mail messages," and "Using other global settings").

  7. As necessary, delete cache items and clear the QuarkXPress Server Manager server cache using the Manage Cache pane (see "Managing the cache").

Starting QuarkXPress Server Manager

Each QuarkXPress Server Manager server can handle multiple QuarkXPress Server instances.

QuarkXPress Server Manager diagram
Starting the Manager server application

To launch the QuarkXPress Server Manager server application:

  • macOS: Open the QuarkXPress Server Manager/Server folder inside the applications folder and double-click "QXPSMServerStart.command."

  • Windows (if you have not installed QuarkXPress Server Manager as a service): Choose Start > Programs > QuarkXPress Server Manager 9 > Start QuarkXPress Server Manager. Alternatively, open the "Server" folder in the QuarkXPress Server Manager application folder and double-click the "QXPSMServerStart.bat" file as an administrator.

You can access API documentation in HTML format by navigating to http://[server]:[port], where [server] identifies the computer on which QuarkXPress Server Manager is running and [port] identifies the port it is running on.

Starting the Manager Web client

To launch the QuarkXPress Server Manager Web application, click Open Admin Client on the QuarkXPress Server Manager home page. The QuarkXPress Server Manager administration Web client displays.

The QuarkXPress Server Manager Web client

Request handler binding

When you add a QuarkXPress Server instance to QuarkXPress Server Manager, you can choose to bind that server instance to particular rendering type or request type. When QuarkXPress Server Manager receives a matching request, it will send the request to only those server instances that are bound to that rendering type or request type. If multiple server instances are bound to a particular rendering type or request type, QuarkXPress Server Manager balances the load of such requests between the server instances.

An instance of QuarkXPress Server Manager that is not bound to any specific type of request is called a generic server. If a request is not bound to a particular server instance, QuarkXPress Server Manager sends that request to a generic server. If more than one generic server is available, QuarkXPress Server Manager balances the load of such requests between them.

You can bind a server to more than one rendering type or request type.

Configuring QuarkXPress Server instances

The Manage Servers pane lists the QuarkXPress Server instances the QuarkXPress Server Manager server is handling. You can use this pane to add QuarkXPress Server instances, edit the description of existing QuarkXPress Server instances, delete QuarkXPress Server instances, and choose a load balancing method.

Manage Servers pane

To configure an individual QuarkXPress Server instance, click Manage under the icon for that instance. The QuarkXPress Server Web interface for that instance displays.

Adding and enabling a QuarkXPress Server instance

When you add and enable a QuarkXPress Server instance in the Manage Servers pane of the QuarkXPress Server Manager interface, the QuarkXPress Server Manager server begins routing rendering requests to that QuarkXPress Server instance.

If you add and enable a QuarkXPress Server instance in this pane, be sure that clients are no longer sending rendering requests directly to that QuarkXPress Server instance; otherwise, the server will be handling both direct requests and routed requests, and the server might become overly busy. Note also that requests sent directly to such a QuarkXPress Server instance do not benefit from QuarkXPress Server Manager features such as load balancing, caching, and logging.

To add and enable a QuarkXPress Server instance:

  1. Display the Manage Servers pane of the QuarkXPress Server Manager interface.

  2. Click Add Server. The Add QuarkXPress Server dialog box displays.

    Add QuarkXPress Server dialog box
  3. Enter the QuarkXPress Server instance's DNS name or IP address in the Name/IP Address field.

  4. Enter the QuarkXPress Server instance's port number in the Port Number field.

  5. If the QuarkXPress Server instance is running with the HTTPS protocol, check HTTPS.

  6. To specify an alternate name for the server, enter a value in the Alias field. The Alias value displays in the Manage Servers pane of the QuarkXPress Server Manager interface.

  7. If you choose to use a particular ping document for this server (see "Ping document"), make sure the project file is in the QuarkXPress Server instance's document pool and then enter the project's file name in the Ping Document field. The ping document is used only if the global Ping Type is set to Ping Document (see "Using other global settings"). Note that if you do not set a ping document here, and no global ping document is set (see "Using other global settings"), an error message might display to indicate that the server is registered but inactive.

  8. Enter the QuarkXPress Server instance user name and password in the Admin User and Admin Password fields.

  9. To specify that QuarkXPress Server Manager should begin sending rendering requests to this QuarkXPress Server instance, check Enable.

  10. To restrict this server to one or more particular types of rendering, check the appropriate boxes in the Request Binding area. To add additional render types (for example, render types provided by QuarkXPress Server XTensions software), check Other and enter the appropriate namespaces in the corresponding field as a comma-separated list. For more information, see "Request handler binding."

  11. Click OK.

Editing a QuarkXPress Server instance

To edit the description of a QuarkXPress Server instance, display the Manage Servers pane of the QuarkXPress Server Manager interface, select the server in the list, and then click Edit Server. You can also display the Edit QuarkXPress Server dialog box by hovering the mouse cursor over the server and then clicking the Edit Server button on the upper left.

The options in the Edit QuarkXPress Server dialog box are the same as the options in the Add QuarkXPress Server dialog box (see "Adding and enabling a QuarkXPress Server instance").

Enabling and disabling routing to QuarkXPress Server instances

The Status field for each server in the Manage Servers pane of the QuarkXPress Server Manager interface shows the status of each QuarkXPress Server instance.

The status fields are not updated automatically. To update the Status field for all servers, click Refresh.

To enable or disable routing to a QuarkXPress Server instance, select the server, click Edit Server to display the Edit QuarkXPress Server dialog box, check or uncheck Enable, and then click OK. You can also enable or disable a QuarkXPress Server instance by hovering the mouse cursor over the server and then clicking the Enable the Server button or Disable the Server button on the upper left.

Manage Servers pane
Controlling load balancing

Load balancing ensures that each rendering request is sent to a QuarkXPress Server instance that is most likely to be able to handle it quickly. To define a load-balancing setting for the QuarkXPress Server Manager server, display the Manage Servers pane of the QuarkXPress Server Manager interface and click Load Balancer Method Settings. The Load Balancer Method Settings dialog box displays.

Load Balancer Method Settings dialog box

QuarkXPress Server Manager lets you use choose from three load-balancing settings:

  • Dynamic Load Balancer: Sends requests to servers based on file size

  • Random Load Balancer: Sends each rendering request to a random server

  • Round-robin Load Balancer: Sends requests to servers in a set order

For more information about these load-balancing settings, see "Load balancing."

Deleting a QuarkXPress Server instance

To delete a QuarkXPress Server instance from the list of available servers in the QuarkXPress Server Manager interface, display the Manage Servers pane, select the server name or IP address, and then click Delete. You can also delete a server by hovering the mouse cursor over the server and then clicking the Delete the Server button on the upper left.

Deleting a QuarkXPress Server instance from this dialog box does not shut down the QuarkXPress Server instance, but it does prevent the QuarkXPress Server Manager server from routing rendering requests to the QuarkXPress Server instance.

Managing the cache

Each QuarkXPress Server Manager server has an in-memory cache (in which it stores the keys to recently accessed items) and a disk-based cache (in which the items themselves are stored). If a request for a recently used item arrives, and a QuarkXPress Server Manager server has that request in its memory cache, the server can simply return the response from its disk cache instead of having to send the request to a QuarkXPress Server instance.

To manage the QuarkXPress Server Manager cache, display the Manage Cache pane of the QuarkXPress Server Manager interface.

Manage Cache pane

Requests are stored in the cache only if the cache is turned on. For more information, see "Configuring cache options."

The cache stores only the results of requests that do not deliberately bypass the cache.

Viewing a QuarkXPress Server Manager server cache

To view QuarkXPress Server Manager cache information, display the Manage Cache pane of the QuarkXPress Server Manager interface. For each file in the cache, this pane lists the command, URL, size, and time and date it was generated. To view a cache file, double-click the file name in the list.

Deleting files from the cache

There is usually no need to manually delete files from a QuarkXPress Server Manager server's cache. When the cache reaches 95% of its capacity, QuarkXPress Server Manager automatically begins deleting the least recently used files in the cache to make room for new files. However, you can also manually clear files from the cache.

To manually delete cache files:

  1. If you want to delete specific files, select those files in the list.

  2. Click Clear Selected Cache. The Clear Cache alert displays.

  3. Click OK.

Configuring cache options

To configure cache options, display the Manage Cache pane in the QuarkXPress Server Manager interface, then click Cache Settings. The Cache Settings dialog box displays.

Manage Cache pane
  • To set the maximum number of files allowed in the cache, enter a value in the Cache Count field. When the number of files in the cache reaches the number you set here, QuarkXPress Server Manager begins deleting the least recently used files to make room in the cache.

  • To set the maximum disk cache size, enter a value in the Cache Disk Size field. When the disk cache reaches this size, QuarkXPress Server Manager begins deleting the least recently used files to make room in the cache.

  • To specify an interval after which the cache should be periodically cleared, enter a value in the Cache Cleanup Interval field.

  • To specify where cache files for the QuarkXPress Server Manager server should be stored, enter a path in the Cache Folder field.

  • The Cache radio buttons let you control caching for the QuarkXPress Server Manager server. To turn caching on, click On. To turn caching off, click Off.

Managing logs

A QuarkXPress Server Manager server maintains logs of all of the requests it receives, the responses from the QuarkXPress Server instances, information about events (such as alerts) that occur during the render-request process, dates and times, and details about each request that was sent to a different QuarkXPress Server instance after its first assigned QuarkXPress Server instance was unable to process the request.

To control what information is stored in the logs, use the Manage Logs pane of the QuarkXPress Server Manager interface. For more information, see "Configuring logging options."

Manage Logs pane
Viewing log file details

To view information about a specific log file, display the Manage Logs pane of the QuarkXPress Server Manager interface, then choose the log file name from the Select Log File drop-down menu.

Deleting log files

To delete a log file:

  1. Display the Manage Logs pane of the QuarkXPress Server Manager interface.

  2. Choose the target log file from the Select Log File drop-down menu.

  3. Click Clear Log.

To clear all log files, click Clear All Logs.

Configuring logging options

To configure logging options, click Log Settings pane in the Manage Logs pane of the QuarkXPress Server Manager interface. The Log Settings dialog box displays.

Log Settings dialog box

To set the maximum log file size, enter a value in the Max Log FileSize field. When a log file reaches this size, the current log file is closed and a new log file is created.

To specify the maximum number of log files to keep, enter a value in the Max Rolling Count field. When the number of log files reaches this limit, QuarkXPress Server Manager deletes the oldest log file each time a new log file is created.

To specify the root name of the log file for the QuarkXPress Server Manager server, enter that name in the Log File field. To place the log file in a particular directory, precede the file name with an absolute path. QuarkXPress Server Manager appends numbers to this name to create consecutively named log files.

To control how much information is stored in the log files, check a box in the Logging Level area:

  • Debug: Stores information such as the commands executed and the servers where those commands are executed. Also stores all of the information that is stored when Information, Warning, and Error are checked.

  • Information: Stores informational messages such as startup messages and command-retry messages. Also stores all of the information that is stored when Warning and Error are checked.

  • Warning: Stores warning messages. Also stores all of the information that is stored when Error is checked.

  • Error: Stores error messages and stack traces for exceptions.

The Debug and Information settings produce large logs that grow rapidly, so you might want to use these settings for troubleshooting only.

Using a proxy server

Some networks route network traffic through a proxy server for reasons of efficiency or security. To use a proxy server for all requests and responses between QuarkXPress Server Manager and QuarkXPress Server:

  1. Display the Proxy Server Settings tab of the Global Settings pane of the QuarkXPress Server Manager interface.

    Proxy Server Settings tab
  2. Check Use a Proxy Server for LAN.

  3. Enter the proxy server's DNS name or IP address in the Address field.

  4. Enter the proxy server's port number in the Port Number field.

  5. Enter the proxy server's user name in the User Name field.

  6. Enter the proxy server's password in the Password field.

Generating automatic e-mail messages

You can configure a QuarkXPress Server Manager server to automatically generate and send e-mail messages if particular events occur. To configure the QuarkXPress Server Manager server to automatically send e-mail messages:

  1. Display the SMTP Settings tab of the Global Settings pane of the QuarkXPress Server Manager interface.

  2. Enter a valid SMTP server name or IP address in the SMTP Server field and then enter the corresponding port number in the Port Number field.

  3. Enter the e-mail address to which messages should be sent in the Admin Email ID field.

  4. If this SMTP server requires validation, enter a valid user name in the User Name field and a valid password in the Password field.

SMTP Settings pane

Two events can cause QuarkXPress Server Manager to generate an e-mail message:

  • If Inactive Host E-mail Notification is checked (see "Using other global settings"), a message is sent when a QuarkXPress Server instance goes from the active state to the inactive state.

  • If you have set up custom error messages (as described in "Using custom error messages"), certain QuarkXPress Server errors result in e-mail messages.

Using other global settings

To configure other global settings, display the Other Settings tab of the Global Settings pane of the QuarkXPress Server Manager user interface.

Other Settings tab of Global Settings page
  • Max Retries: To specify the maximum number of times the QuarkXPress Server Manager server should submit a request to the QuarkXPress Server instances, enter a value in this field. When QuarkXPress Manager has unsuccessfully submitted a request this many times, the application returns an error message.

  • Request Timeout: To specify the maximum number of minutes the QuarkXPress Server Manager server should wait for a response from a QuarkXPress Server instance, enter a value in this field. When this time has elapsed, the QuarkXPress Server Manager server retries the request (unless the Max Retries value has been reached).

  • Connection Timeout: To specify the maximum number of seconds the QuarkXPress Server Manager server should spend attempting to establish a connection with a particular QuarkXPress Server instance, enter a value in this field.

  • Max Connections Per Host: To specify the maximum number of connections the QuarkXPress Server Manager server should open for a particular QuarkXPress Server instance before it begins queuing requests, enter a value in this field.

  • Max Total Connections: To specify the maximum number of connections the QuarkXPress Server Manager server should open for all hosts before it begins queuing requests, enter a value in this field.

  • Ping Interval: To set the amount of time the QuarkXPress Server Manager server should wait between ping attempts (see "Determining QuarkXPress Server instance availability"), enter a value in this field.

  • Ping Type: To indicate whether QuarkXPress Server Manager should use a simple ping or a ping document to test a QuarkXPress Server instance, choose an option from this drop-down menu.

  • Ping Document: To indicate which QuarkXPress project the QuarkXPress Server Manager server should use for ping document requests, enter the project file name in this field. Make sure a copy of the project file is in each QuarkXPress Server instance's document pool. Note that individual QuarkXPress Server instances can override this value by providing another document name. Note also that a ping document is used only if Ping Type is set to Ping Document.

  • Common Document Pool Usage: Check this box if all managed QuarkXPress Server instances are using the same document pool. If this box is checked, then upload, delete, and saveas requests are sent to one of the available servers. If this box is unchecked, then upload, delete, and saveas requests are sent to all managed servers. Note that you must manually set each server to point at the common document pool.

  • Platform-specific Rendering: A QuarkXPress Server Manager server can send requests that involve macOS project files to a macOS-based QuarkXPress Server instance, and send requests that involve Windows project files to a Windows-based QuarkXPress Server instance. Setting up the server in this manner can be desirable if the project files involved use fonts that are available on only one platform or the other. To enable platform-specific rendering for the QuarkXPress Server Manager server, check this box.

  • Inactive Host E-mail Notification: To automatically generate an e-mail message when a QuarkXPress Server instance becomes inactive, check this box. The e-mail message is sent to the address specified in the SMTP Settings pane.

Saving a server configuration

Changes that you make to a server configuration in the QuarkXPress Server Manager client are not made to the QuarkXPress Server Manager server until you click Save All Settings in the Global Settings pane of the QuarkXPress Server Manager interface.

To discard any changes you have made since logging on to the QuarkXPress Server Manager server, click Refresh. The configuration of the QuarkXPress Server Manager server remains as it was.

Disabling or enabling a QuarkXPress Server instance from the QuarkXPress Server Manager client is not considered a configuration change.

Using custom error messages

You can control which errors cause the QuarkXPress Server Manager server application to send e-mail messages to the address specified in the SMTP Settings pane (see "Generating automatic e-mail messages"). You can also define which messages are sent when such errors occur. The first step is to create a custom error code that corresponds to a QuarkXPress Server error code. After you set up this custom error code, you can specify whether that code generates an e-mail message and then create custom error messages.

Creating a custom error code

To create a custom error code:

  1. On the computer where the QuarkXPress Server Manager server application is running, open the following file in a text-editing application:

    [application folder]\server\conf\Manager_Server_ErrorCodeMapping.properties
  2. Create a new line containing a QuarkXPress Server specific error code for which you want to generate automatic e-mail messages (with or without a custom text message). Follow the error code with an equals sign, a unique custom error code, and a return.

  3. Save and close the file.

This change will not take effect until you quit and restart the QuarkXPress Server Manager server application.

Flagging an error code to generate an e-mail message

To specify that a custom error code should cause an e-mail message to be generated:

  1. Create a unique custom error code for the target QuarkXPress Server error. For more information, see "Creating a custom error code").

  2. On the computer where the QuarkXPress Server Manager server application is running, open the following file in a text-editing application:

    [application folder]\server\conf\ManagerErrorCodeMailOption.properties
  3. Create a new line containing the unique custom error code you defined in step 2. Follow the custom error code with a tab, enter a 1 (to send the message) or a 0 (to suppress the message), and then press Return.

  4. Save and close the file.

This change will not take effect until you quit and restart the QuarkXPress Server Manager server application.

Creating custom error text

To define the text that should be sent in an e-mail message when an error occurs:

  1. Create a unique custom error code for the target QuarkXPress Server error (as described in "Creating a custom error code").

  2. On the computer where the QuarkXPress Server Manager server application is running, open the following file in a text-editing application:

    [application folder]\server\conf\ManagerErrorCodeMessage.properties
  3. Create a new line containing the unique custom error code you defined in step 2. Follow the custom error code with a tab and then enter the custom text to be returned for that error.

  4. Save and close the file.

This change will not take effect until you quit and restart the QuarkXPress Server Manager server application.

Sending requests from a browser

Like QuarkXPress Server, QuarkXPress Server Manager lets you send requests from a Web browser. This capability helps to ensure that you need to make only minimal changes when you update an application so that it sends requests to a QuarkXPress Server Manager server instead of a QuarkXPress Server instance.

Assume that a QuarkXPress Server instance expects requests in the following format:

http://[QXPServer]:[port]/[request]?[request_parameters]

If this is the case, a QuarkXPress Server Manager server will expect requests in the following format:

http://[QXPSManagerServer]:[port]/qxpsm/request/[request]?[request_parameters]

In other words, a QuarkXPress Server Manager server accepts requests in a format that is similar to the request format used with a QuarkXPress Server instance. That means you can get the benefits of QuarkXPress Server Manager without having to completely rewrite your applications.

Additional parameters

In addition to request-specific parameters, QuarkXPress Server Manager accepts the following request parameters. These parameters can be submitted in the standard QuarkXPress Server GET format joined by an ampersand (&) with the other parameters in the body of the request.

  • qxpsm_bypassfileinfo: When QuarkXPress Server Manager receives a request, it executes a fileinfo request on the document to get the document's size and last-modified date and time. These values are used for load balancing and for determining whether to serve the document from the cache. If the value of this parameter is set to true, the fileinfo request is not made, file size is considered to be zero for load-balancing purposes, and the document in the cache is considered to have changed.

  • qxpsm_context: Set this value if you need to use it in a custom load balancer.

  • qxpsm_maxtries: This parameter lets you specify a maximum number of retries for a specific request. If this parameter is absent or set to 0, the global maximum retries value is used. To disable maximum retries for a request, use the value –1.

  • qxpsm_password: The value of this parameter, if supplied, is used as the "Admin Password" value when the request is forwarded to a QuarkXPress Server instance.

  • qxpsm_responseasurl: By default, QuarkXPress Server Manager writes responses as temporary files in the cache folder and returns a URL to the client. This approach prevents the performance degradation that can result from sending binary data using SOAP. However, you might want QuarkXPress Server Manager to return the response directly if you are creating an application that processes that response (simple or multipart) with its own logic. To make QuarkXPress Server Manager send a response to the browser rather than the URL of the temporary files in the cache, set this value to false. (Note that setting this value to false might result in decreased performance.)

  • qxpsm_responseredirect: If you use servlet methodology to send a request to QuarkXPress Server Manager with qxpsm_responseasurl=true, QuarkXPress Server Manager returns a frameset page with one or more frames. If the response is not multipart, the frameset contains a single page with a URL pointing to a response file in the temporary cache. This can be problematic if, for example, you want to use the returned URL as an image link in an HTML page. In such situations, submit the request with both qxpsm_responseredirect=true and qxpsm_responseasurl=true. If you do this, QuarkXPress Server Manager returns the URL of the rendered file in the temporary cache instead of returning a frameset page. Note, however, that if the request results in a multipart response (such as the response returned by the boxes parameter), QuarkXPress Server Manager ignores the qxpsm_responseredirect=true parameter and returns the frameset page.

  • qxpsm_servername: By default, the target QuarkXPress Server instance for each request is determined by the QuarkXPress Server Manager server's load-balancing system. To send a request to a specific QuarkXPress Server instance, set this parameter to the name or IP address of that QuarkXPress Server instance. Note that if you use this parameter with an IP address, you must also submit the port number using the qxpsm_serverport parameter.

  • qxpsm_serverport: If you use the qxpsm_servername parameter with an IP address, supply the corresponding port number as this parameter's value.

  • qxpsm_timeout: This parameter lets you specify a timeout (in milliseconds) for a specific request. If this parameter is absent or set to 0, the global timeout value is used. To disable timeout for a request, use the value –1.

  • qxpsm_usecache: If you set this value to false, the request will be rendered regardless of whether it is cached and regardless of whether caching is enabled at the global level.

  • qxpsm_username: The value of this parameter, if supplied, is used as the "Admin User" value when the request is forwarded to a QuarkXPress Server instance.

  • qxpsm_userpassword: The value of this parameter, if supplied, is used as the "Admin User" password when the request is forwarded to a QuarkXPress Server instance. Default value is null, which means no password information. If this is not null, you must also provide qxpsm_username.