---
title: "Publishing"
source: https://dev.pageseeder.com/guide/publishing.html
description: "Publishing explains how PageSeeder outputs to different formats using multi-stage batch processing via the Ant-based Publish Engine, including components, parameters, messages, and Ant tasks for document transformation."
last_updated: 2026-09-08T20:11:27+10:00
tokens: ~2698
---

# Publishing

This section explains how PageSeeder can output to different formats and applications.

## Overview

Some publishing situations need multiple processing stages in order for resolved values to be available for other parts of the process. 

This is similar to the way a conventional typesetting app must first compose the individual pages, then insert page numbers in the Table of Contents (TOC) then adjust all page numbers based on how many pages the fully resolved TOC is.

Examples include:

- Creating the navigation and content of a website.
- Transforming, then generating pages and cross-reference values for PDF.

Multi-stage, batch processing is available through the PageSeeder publish function. Using the [PageSeeder Ant API](/reference/glossary/pageseeder_ant_api.md), Publish leverages [Apache Ant](https://ant.apache.org/), an open source technology that is available on most operating systems.

To get the most out of Publish, needs an understanding of Ant. While there are many sources of Ant reference and learning material, the focus of this site is how PageSeeder interacts with Ant. 

More information on batch processing is available through [publish scripts](/reference/glossary/publish_script.md). To modify the user interface or configure different options, *see* [\<publishing\>](/guide/configuration/psml/psml_document_config/document_publishing.md). For example publish scripts, *see* [PSML Ant scripts](/guide/configuration/psml/psml_ant_scripts.md).

## Publish Engine components

**Publish Engine** communicates with the PageSeeder Core using HTTP. The [publish script](/reference/glossary/publish_script.md) is an Apache Ant build script.

After the script is instantiated, the Publish Control passes a request to the Publish Engine for the following actions:

- **query** – the engine processes the script, returning a list of user-selectable options, such as the following:


  - generate Table of Contents.
  - use hi-resolution images.
- **publish** – executes the script and selected options.
- **check** – displays the status of selected publishing task.
- **cancel** – cancel the current task.

Depending on the actions initiated, the response is passed back to the Publish Control, processed by XSLT and rendered on the user screen. The architecture is outlined in the following diagram:

![Website-Engine-Overview1.png](/content/images/guide/website_engine_overview1.webp)

## Publish parameters

> **Note:** These parameters are accessed in ANT using the [Task config](/guide/publishing/ant_api/tasks/task_config.md).

The following table lists the parameters passed to the Publish Ant Script**:**

| **Parameter** | **Description** | **Example** |
| --- | --- | --- |
| ps-jsessionid | The user’s jsessionid in PageSeeder |  |
| ps-host | The webSiteAddress from `global.properties` |  |
| ps-port | The webSitePort from `global.properties` |  |
| ps-servletPrefix | The servletPrefix from `global.properties` *DEPRECATED in v6.3 use ps-sitePrefix plus `/api` instead.* |  |
| ps-sitePrefix | The sitePrefix from `global.properties` |  |
| ps-groupId | id of group initiating the publish | `12` |
| ps-groupName | Name of group initiating the publish | `acme-demo` |
| ps-groupFolder | Path of default group folder | `/ps/acme/demo` |
| ps-groupFolderNoPrefix | Path of default group folder with no site prefix | `/acme/demo` |
| ps-groupHost | Host of default group folder | `mycompany.com` |
| ps-groupPort | Port of default group folder | `80` |
| ps-groupTemplate | Template for group (or default group if URI) | `acme` |
| ps-globalTemplate | globalTemplate name from `global.properties` | `acmedefault` |
| ps-style-owner | Template for group (or default group if URI). *DEPRECATED in v5.99 use ps-groupTemplate instead.* | `acme` |
| ps-customFolder | globalTemplate name from `global.properties`. *DEPRECATED in v5.99 use ps-globalTemplate instead.* | `acmedefault` |
| ps-working | Path to local unique working folder for this `group/document` |  |
| ps-workingRoot | Path to root for all local working folders |  |
| ps-workingDownload | Whether “Allow download of the working files” was ticked. *Requires PageSeeder v6.3 or higher.* | `false` |
| ps-documentsRoot | Path to PageSeeder documents folder only if Publish Engine is installed on PageSeeder server) |  |
| ps-webRoot | Path to the root for result files (see `ps-sessionfolder`) |  |
| ps-engineUrl | The external URL used to contact the Publish Engine  | `http://mycompany.com/ps/publisher` |
| ps-sessionfolder | A unique folder name for the current PS user session to copy result files to using `${ps-webRoot}/session/${ps-sessionfolder}`  | `NIxqYLywyyKqQI4b0e5f8k` |
| ps-username | `username` of the current user | `jsmith` |
| ps-userId | `ID` of the current user | `123` |
| ps-userFirstname | Given name of the current user | `John` |
| ps-userSurname | Family name of the current user | `Smith` |
| ps-userToken | The  access token for the current user (only if script was started using an access token) |  |

Following are the parameters for a **Document** being published. These are not applicable for a **Group** or **Batch** being published or a document in the [Loading Zone](/reference/glossary/loading_zone.md):

| **Parameter** | **Description** | **Example** |
| --- | --- | --- |
| ps-uriId | URI id | `123` |
| ps-uriScheme | URI scheme | `http` |
| ps-uriHost | URI host | `mycompany.com` |
| ps-uriPort | URI port | `80` |
| ps-uriPath | URI path | `/ps/acme/demo/minutes/2006-12-08.xml` |
| ps-uriPathNoPrefix | URI path without prefix | `/acme/minutes/demo/2006-12-08.xml` |
| ps-uriPathNoGroup | URI path without group prefix | `/minutes/demo/2006-12-08.xml` |
| ps-uriFolder | URI folder | `/ps/acme/demo/minutes` |
| ps-uriFolderNoPrefix | URI folder with `/ps` prefix | `/acme/demo/minutes` |
| ps-uriFolderNoGroup | URI folder without group prefix | `/minutes` |
| ps-uriFilename | Filename | `2006-12-08.xml` |
| ps-uriFilenameNoExt | Filename without extension | `2006-12-08` |
| ps-uriExtension | File extension | `xml` |
| ps-uriDocumentId | URI docid (optional) | `mydoc1` |
| ps-uriPublicationId | The ID of the publication that URI is the root of (optional) | `mypub1` |
| ps-uriPublicationType | The type of the publication that URI is the root of (optional) | `report` |
| ps-uriPublicationConfig | The path to the `publication-config.xml` file for publication that URI is the root of (optional). *Requires PageSeeder v6.3 or higher.* |  |
| ps-uriWordExportConfig | The path to the `word-export-config.xml` file for publication that URI is the root of (optional). *Requires PageSeeder v6.3 or higher.* |  |
| ps-uriWordExportTemplate | The path to the `word-export-template.docx` file for publication that URI is the root of (optional). *Requires PageSeeder v6.3 or higher.* |  |
| ps-style-config | URI document type | `definition` |

The following parameters are for processing a **Batch** of documents *(requires PageSeeder v5.98 or higher)*:

| **Parameter** | **Description** | **Example** |
| --- | --- | --- |
| ps-batchIds | A comma-separated list of URI IDs in the batch | `123,456,789` |
| ps-searchQuestion | The search question used to select the batch IDs from (optional) | `green` |
| ps-searchQuestionFields | The search question fields used to select the batch IDs from (optional) | `pstitle,pscontent,psfilename,psdocid,psid` |
| ps-searchFilters | The search filters used to select the batch IDs from (optional) | `psdocumenttype:product,pslabel:simple` |
| ps-searchRanges | The search ranges used to select the batch IDs from (optional) | `psproperty-title:[A;C},ranges=psxrefcount:{50;]` |

The following parameters are for processing a **Document** in the **Loading Zone:**

| **Parameter** | **Description** | **Example** |
| --- | --- | --- |
| ps-uploadPath | Document path | `/minutes/2006-12-08.xml` |
| ps-uploadFolder | Document folder | `/minutes` |
| ps-uploadFilename | Document filename | `2006-12-08.psml` |
| ps-uploadFilenameNoExt | Filename without extension | `2006-12-08` |
| ps-uploadExtension | File extension | `xml` |
| ps-uploadConfirmed | If script is run before displaying the Upload confirmation, the value is **`false`**, otherwise it’s **`true`**. |  |

## Publish messages

> **Tip:** In PageSeeder v6.2 or higher use the [\<ps:progress\>](/guide/publishing/ant_api/tasks/task_progress.md) task instead of `<echo>` or `<echoxml>` tasks to simplify the code and use new special messages `<reload>`, `<uriLink>` and `<displayPanelPath>`.

Generally all messages output from an Ant script are logged by PageSeeder, but the following special Ant messages are also recognized:

```xml
<echoxml><progress percent="[n]" /></echoxml>
```

- where n is an integer from 0 to 100, displays progress on the Publish Page (not logged by PageSeeder).

```xml
<echoxml><displayUriPath>[url]</displayUriPath></echoxml>
```

- where url is a URL beginning with /, http:// or https://, displays the content of \[url\]?t=\[timestamp\] in a new window when the Publish is complete.

```xml
<echoxml><displayPanelPath>[url]</displayPanelPath></echoxml>
```

- where url is a URL beginning with /, http:// or https://, displays the content of \[url\]?t=\[timestamp\] in the panel when the Publish is complete. *Requires PageSeeder 6.2 or higher.*

```xml
<echoxml><previewPath>[path]</previewPath></echoxml>
```

- which displays the PSML at this path on the Publish Engine as HTML where path is to start with ‘/session/$\{ps-sessionfolder\}’ (PageSeeder does the translation to HTML). *Only supported for upload preview ANT scripts using `target/@previewname`.*

```xml
<echoxml><publisherPath>[path]</publisherPath></echoxml>
```

- which displays the file at this path on the Publish Engine where path is to start with ‘/session/$\{ps-sessionfolder\}’. If using a Publish Engine on a different PageSeeder server, this can be used to proxy the request using the local PageSeeder URL; however, it is more efficient to use the direct Publish Engine URL with `<displayUriPath>`.

```xml
<echoxml><downloadLink>[url]</downloadLink></echoxml>
```

- where url is a URL beginning with /, http:// or https://, displays a link to \[url\] when the Publish is complete.

> **Note:** As of PageSeeder v6 you can't access documents using path info, for example in `<displayUriPath>` and `<downloadLink>`. In v6 use the `path` parameter (or `docPath` in v5 or v6). For example instead of `/ps/acme/specs/my.psml` use `/ps/uri?path=/ps/acme/specs/my.psml`

## PageSeeder Ant tasks

The PageSeeder External API defines a few Ant tasks that are useful to connect and interact with the PageSeeder Server. For details, *see* [Ant API](/guide/publishing/ant_api.md) and [Using Ant](/guide/publishing/using_ant.md).