---
title: "Task export"
source: https://dev.pageseeder.com/guide/publishing/ant_api/tasks/task_export.html
description: "Exports PageSeeder documents to Universal Portable Format. Supports selecting documents by URI, path, or folder with filtering, cross-reference following, image inclusion, and version comparison capabilities."
last_updated: 2026-09-08T14:04:00+10:00
tokens: ~2652
---

# Task export

This task is used to export individual, or multiple, [documents](../../../../reference/glossary/document.md) to the [Universal Portable Format](../../../../psml/universal_format/universal_portable_format.md). The output of this task is a list of files and their metadata.

Documents are selected in the following order:

If `srcuris` is specified, select documents with those URI IDs.

Otherwise if `src` or (`context` and `group`) are specified, select the document with that path, or if a folder then:

if `<filter>` specified, search for documents within that folder.

if `includes` or `excludes` is specified, also use that to filter the documents.

If `xrefdepth` or `<xrefs>` is specified, apply them to selected files and add referenced documents.

If `loadimages="true"`, add referenced images.

> **Note:** Unless `allurls="true"` URLs are only exported if they are referenced in the exported documents, `xrefdepth` is 1 or more and xref types includes `link`.

## Definition

Minimal definition:

```xml
<ps:export src="[source]" dest="[destination]"/>
```

 Full definition:

```xml
<ps:export src="[source]" or srcuris="[uriids]"
           dest="[destination]"
           group="[group name]"
           context="[context]"
           allurls="[true|false]"
           includes="[patterns]"
           excludes="[patterns]"
           xrefdepth="[forward xref depth]"
           version="[version]"
           compareto="[compare version]"
           publicationid="[publication ID]"
           position="[position in publication]"
           processpublication="[true|false]"
           independent="[true|false]"
           interpublicationxrefs="[true|false]"
           metadataonly="[true|false]"
           loadimages="[true|false]"
           loadalternates="[true|false]"
           binarymetadataonly="[true|false]"
           failonerror="[true|false]"
           config="[config name]">
  <filter with="[facet values]"
          since="[modified date]"
          ranges="[range values]"
          indexcomplete="[true|false]" />
  <xrefs forward="[forward xref depth]"
         reverse="[reverse xref depth]"
          types="[xref types]" />
</ps:export>
```

## Attributes

| **Attribute** | Description | Required | Default |
| --- | --- | --- | --- |
| **src** | The PS source document/folder path (e.g. /ps/acme/specs/documents) | Yes, if srcuris and (context or group) not specified |  |
| **srcuris** | Comma-separated list of PS URI Ids to download | Yes, if src and (context or group) not specified |  |
| **dest** | The destination file system folder or if a path ending with .zip, only a zip of the files is saved | Yes |  |
| **group** | Name of group for logging and searching (if not specified uses the src URIs default group or 1st accessible group) | Yes, if filter `indexcomplete=true` |  |
| **context** | The PS [context path](../../../../reference/glossary/context_path.md) – defaults to the source folder or parent folder of the source document (e.g. /ps/acme/specs) | Yes, if src not specified |  |
| **allurls ** | Whether to export all URLs used in the group (ignored if no `group` attribute). *Requires PageSeeder 5.99 or higher.* | No | `false` |
| **includes** | A comma-separated list of patterns matching documents/folders to include. When not specified, all documents/folders are included. The format is similar to other Ant tasks file pattern selection. Here are some examples: \*.doc,archive,folder1/\*.psml \*.jpg,\*\*/\*.jpg,????/\* | No |  |
| **excludes** | A comma-separated list of patterns matching documents/folders to exclude. When not specified, no documents/folders are excluded. The format is similar to other Ant tasks file pattern selection. Here are some examples: \*.doc,archive,folder1/\*.psml \*.jpg,\*\*/\*.jpg,????/\* | No |  |
| **xrefdepth** | The maximum depth of forward xrefs to follow from the source files to find the export set | No | `0` |
| **version** | A decimal number, ISO 8601 date or non-number version used to export a version equal to (or if a number/date less than) this version. *If version is not found the original uploaded version is exported. If version is empty or 'current' the current version is exported.* | No |  |
| **compareto** | A decimal number, ISO 8601 date or non-number version used to compare a version equal to (or if a number/date less than) this version with the downloaded version. *If version is not found the original uploaded version is compared. If compareto is 'current' the current version is compared.* | No |  |
| **publicationid** | The publication ID for processing and versions. | No |  |
| **position** | The position in the publication for processing. *Requires PageSeeder 6.1 or higher.* | No | `1` |
| **processpublication** | If `true`, process publication TOC, numbering and placeholders. *Requires PageSeeder 6.1 or higher - see Note.* | No | `false` |
| **independent ** | If `true`, remove the `_` from `_local` and `_external` folders so they can be uploaded, making the export self-contained. *Requires PageSeeder 6.2 or higher.* | No | `false` |
| **interpublicationxrefs** | If `true`, resolve `{parentnumber}`, `{prefix}` and `{heading}` templates of xrefs between publications. Uses the **default** publication of the target. *Requires PageSeeder 6.0004 or higher.* | No | `false` |
| **metadataonly** | If `true`, only export metadata (`manifest.xml` and metadata for non-PSML), do not download files | No | `false` |
| **resolveimages** | If `true`, also export all images referenced in PSML documents (requires `metadataonly=false`) ***OBSOLETE** as of PageSeeder v6 use `loadimages` instead.* | No | `true` |
| **loadimages** | If `true`, also export all resolved images referenced in PSML documents (requires `metadataonly=false`) | No | `true` |
| **loadalternates** | If `true`, also export targets of all xrefs with type=`alternate` (requires `metadataonly=false`) | No | `true` |
| **imagemetadataonly** | If `true`, export PSML files but only metadata for resolved images, not image source files. ***OBSOLETE** as of PageSeeder v6 use `binarymetadataonly` instead. * | No | `false` |
| **binarymetadataonly** | If `true`, export PSML files but only metadata for non-PSML, not binary source files. *Requires PageSeeder v5.99 or higher.* | No | `false` |
| **failonerror** | If `true`, stop build process on error | No | `true` |
| **config** | Universal PS config name | No | `default` |

> **Note:** - If `processpublication="true"` then transcluded content (`transclude/math` xrefs) will be included in documents (except if `compareto` specified), however `transclude` should still be specified under `<xrefs>` to follow any xrefs in the transcluded content (e.g. `embed` xrefs). If `compareto` is specified publication number is not compared. - If images are not under the folder you are exporting they will end up under `_local` or `_external` in the `.zip` file and will not import back into a PageSeeder. In that case you need to set a context path in the export which is above both the documents and images (e.g. /ps/acme/specs).

## Elements

Elements can be used to specify more detailed options than their attribute equivalent. It is an error if both the attribute and element are specified.

### Element \<filter\>

> **Note:** As the filter relies on the group index it is recommended to set indexcomplete=true to ensure large indexing jobs are complete before exporting.The filter only works when exporting a folder or a group and only searches the single group specified or calculated (see group attribute in preceding table).

| **Attribute** | Description | Required |
| --- | --- | --- |
| **with** | Comma-separated list of facet:value pairs to filter source documents (e.g. pslabel:cars,psdocumenttype:spec) | No |
| **since** | ISO date/time to return source documents modified after this (e.g. 2010-10-25 or 2010-10-25T12:26+10:00) | No |
| **ranges** | Comma-separated list of ranges to filter source documents (same format as `ranges` parameter on [Service: /groups/\{group\}/search \[GET\]](../../../../api/services/group-search_get.md) e.g. `ranges="pslastediteddate:[2017-12-06;2017-12-20],psxrefcount:[1;]"`) | No |
| **indexcomplete** | If `true`, then wait until no jobs are in the indexing queue for the group before exporting (`@group` attribute must also be specified) | No |

### Element \<xrefs\>

> **Note:** This task only downloads an xref’s target document. It won’t embed or transclude the content inline. For that you need to use [Task process](task_process.md).

| **Attribute** | Description | Required | Default |
| --- | --- | --- | --- |
| **forward** | The maximum depth of forward xrefs to follow from the source files to find the export set (`@xrefdepth` must not be set). | No |  |
| **reverse** | The maximum depth of reverse xrefs to follow from the source files to find the export set (`@xrefdepth` must not be set). | No |  |
| **types** | Comma-separated list of xref types to follow (that is, `none`, `math`, `transclude`, `embed`, `link` ) | No | `none, math, transclude, embed,link` |

## Environment

This task uses the following PS config environment properties:

- **scheme** – scheme for connecting to PageSeeder.
- **host** – host for connecting to PageSeeder.
- **port** – port for connecting to PageSeeder.
- **site.prefix** – site prefix for connecting to PageSeeder – default  /ps.
- **username** – username of member for export
- **user.token** or **jsessionid** or **password** – access token or jsessionid or  username’s password for connecting to PageSeeder.
- **uri.host** or **group.host** – host for **src** documents.

## Errors

Possible errors are:

- Required attribute or environment property missing.
- Attribute or property invalid.
- Src not contained in context.
- Download access denied.
- Resolve image access denied.
- Resolve image not found.
- Image URI ID not found.
- Download not found.

## Examples

```xml

<ps:export src="/ps/acme/specs/documents/spec.psml"
           dest="c:\working\export"
           xrefdepth="2" />
```

```xml

<ps:export src="/ps/acme/specs/documents"
           dest="c:\working\docs"
           xrefdepth="1"
           version="2.0">
  <filter since="2012-08-31" />
</ps:export>
```

```xml

<ps:export src="/ps/acme/specs/documents"
           dest="c:\working\docs"
           xrefdepth="1">
  <filter with="psstatus:Approved" indexcomplete="true" />
</ps:export>
```

```xml

<ps:export src="/ps/acme/specs/website/content/books/book1"
           dest="c:\working\"
           context="/acme/specs/website/" />
```