---
title: "Task upload"
source: https://dev.pageseeder.com/guide/publishing/ant_api/tasks/task_upload.html
description: "The ps:upload task enables Ant scripts to upload files to a PageSeeder server, supporting features like unzipping, validation, indexing, and workflow creation with customizable notifications and document properties."
last_updated: 2026-09-14T13:54:28+10:00
tokens: ~2139
---

# Task upload

This task lets the Ant Script go through the files referenced by the fileset and upload them on a PageSeeder server.

> **Note:** This task is available in PageSeeder v5.8115 and higher.

## Definition

Minimal definition:

```xml
<ps:upload group="[groupname]">
  <fileset dir="[source]" />
</ps:upload>
```

 Full definition:

```xml
<ps:upload
    group="[groupname]"
    folder="[folder]"
    doclabels="[label1,label2]"
    docidisfilename="[true|false]"
    overwrite="[true|false]"
    overwriteproperties="[true|false]"
    unzip="[true|false]"
    deletezip="[true|false]"
    resolve="[true|false]"
    index="[true|false]"
    validate="[true|false]"
    saveuris="[file path]"
    syncfolder=="[true|false]"
    parseuris="[true|false]"
    failonerror="[true|false]"
    pollinginterval="[milliseconds]"
    config="[config name]">
  <notification subject="[subject]"
                content="[content]"
                labels="[label3,label4]"
                notify="[silent|normal|announce]" />
  <workflow status="[status]"
            priority="[priority]"    
            assignto="[member id]"
            due="[due date]"
            content="[content]"
            labels="[label3,label4]"
            notify="[silent|normal|announce]" />
  <fileset dir="upload"
           includes="*.psml"/>
</ps:upload> 
```

## Attributes

| **Attribute** | Description | Required | Default |
| --- | --- | --- | --- |
| **group** | The name of the group to upload to | Yes |  |
| **folder** | The folder for the upload relative to group (default is group root folder). *As of PageSeeder v5.9802, this can be the full URL to the folder.* | No |  |
| **doclabels** | A comma-separated list of labels to apply to all documents | No |  |
| **docidisfilename** | If `true`, sets the doc id to the filename of the uploaded document (without the extension) | No |  |
| **overwrite** | Overwrite existing files | No | `false` |
| **overwriteproperties** | Overwrite existing document properties (title, docid, labels, publication id/type, description) and metadata - requires `overwrite=true` | No | `false` |
| **unzip** | If `true`, unzip any .zip files that are uploaded | No | `false` |
| **deletezip** | If `true`, delete a zip file after unzipping it | No | `true` |
| **resolve** | If `true`, cross-references and images found in the content are resolved | No | `true` |
| **index** | If `true`, uploaded files are indexed | No | `true` |
| **validate** | If `true`, uploaded files are validated using their default.sch schematron if defined | No | `true` |
| **parseuris** | If `true` parse URI ID of uploaded files and set in ANT property `ps.upload.uriids` as comma-separated list. *Requires PageSeeder v6.3 or higher.* | No | `false`  |
| **saveuris** | If specified, save the URIs uploaded to this path as XML | No |  |
| **syncfolder** | If `true` synchronize the destination folder by archiving any documents not in the upload. *Requires PageSeeder v6.3 or higher.* | No | `false` |
| **failonerror** | If `true`, stop ANT build script on error | No | `true` |
| **pollinginterval** | The number of milliseconds between each check to see if the upload is complete | No | `5000` |
| **config** | Universal PS config name | No | `default` |

## Elements

### Element \<notification\>

If specified, set the notification message details.

| **Attribute** | Description | Required | Default |
| --- | --- | --- | --- |
| **subject** | The subject of the message | Yes |  |
| **content** | The content of the message | Yes |  |
| **labels** | A comma-separated list of labels for the message | No |  |
| **notify** | Can be one of the following: `silent` – no email notification.`normal` – send email notification to the group.`announce` – send email notification to ALL group members. | No | `silent` |

### Element \<workflow\>

If specified, create a workflow step for all documents uploaded.

> **Note:** If there are more than maxWorkflowNotifications (default 20) documents uploaded, then notify is forced to silent.

| **Attribute** | Description | Required |
| --- | --- | --- |
| **status** | The document status to set (e.g. Initiated, In Progress, Complete) | Yes |
| **priority** | The priority of the workflow (e.g. Low, Medium, High) | No |
| **assignto** | The member ID to assign the workflow to (a positive integer) | No |
| **due** | The due date of the workflow in ISO date format (e.g. 2016-10-25) | No |
| **labels** | A comma-separated list of labels for the message | No |
| **notify** | Can be one of the following (default `silent`): `silent` – no email notification.`normal` – send email notification to the group.`announce` – send email notification to ALL group members. | No |

### Element \<fileset\>

The standard ANT [fileset](https://ant.apache.org/manual/Types/fileset.html) element must be used to specify the files to be uploaded.

## Environment

This task uses the following [ps:config](/guide/publishing/ant_api/tasks/task_config.md) 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.
- **user.token** or **jsessionid** or **username/password** – access token or jsessionid or  username/password for connecting to PageSeeder.

## Save URIs format

Following is the XML format used to save the uploaded URIs if `saveuris` is specified.

```xml

<uris>
  <uri id="[id]"
       scheme="[scheme]"
       host="[host]"
       port="[port]"
       path="[path]"
       decodedpath="[decodedpath]"
       external="[true|false]"
       [archived="true"]
       [folder="true"]
       [docid="[docid]"]
       [mediatype="[mediatype]"]
       [documenttype="[documenttype]"]
       [title="My Document"]
       [created="[created]"]
       [modified="[modified]"]>
    <displaytitle>My Document</displaytitle>
    [<description>This is my document</description>]
    [<labels>mylabel1,mylabel2</labels>]
  </uri>
  ...
</uris>

```

## Errors

Possible errors are:

- Document already exists and overwrite is disabled.
- Validation errors.
- No source URIs belong to specified group.
- Failed to load URI with ID.
- A source URI is not within the specified context.

## Examples

### Stand alone script examples

```xml
<ps:upload group="acme-demo"
           folder="documents">
  <fileset dir="c:\ps\upload"
           includes="**"/>
</ps:upload>
```

```xml
<ps:upload
    group="acme-demo"
    folder="documents/demo"
    overwrite="true"
    overwriteproperties="true"    
    unzip="true"
    resolve="false"
    saveuris="c:\ps\uris.xml">
  <notification subject="New demo"
                content="This demo was just uploaded"
                notify="normal" />
  <workflow status="In Progress" />
  <fileset dir="zip">
    <include name="demo.zip"/>
  </fileset>
</ps:upload>
```

###  Publish script examples (within PageSeeder)

```xml
<ps:upload
    group="${ps.config.default.group.name}"
    folder="documents">
  <fileset dir="${ps.config.default.working}/upload"
           includes="**"/>
</ps:upload>
```

```xml
<ps:upload
    group="${ps.config.default.group.name}"
    folder="documents/demo"
    overwrite="true"
    overwriteproperties="true"    
    unzip="true"
    resolve="false"
    saveuris="${ps.config.default.working}/uris.xml">
  <notification subject="New demo" 
                content="This demo was just uploaded"
                notify="normal" />
  <workflow status="In Progress" />
  <fileset dir="${ps.config.default.working}/zip">
    <include name="demo.zip"/>
  </fileset>
</ps:upload>
```

```xml
<zip destfile="${ps.config.default.working}/upload.zip"
     basedir="${process}"/>
    
<ps:upload
    group="acme-specs"
    folder="website${ps.config.default.uri.path.no.group}"
    unzip="true"
    overwrite="true"
    overwriteproperties="true"
    validate="false">
  <fileset file="${ps.config.default.working}/upload.zip" />
</ps:upload>
```

#### Uploading to another PageSeeder server

```xml
<ps:config name="destination"
           file="staging.properties"
           load-default="false"/>
    
<ps:upload
    config="destination"
    group="acme-specs"
    folder="documents"
    unzip="true">
  <fileset file="${ps.config.default.working}/upload.zip" />
</ps:upload>
```

**staging.properties**

```properties
scheme=https
host=ps.example.com
port=443
site.prefix=/ps
client.id=87ff810b199f0636
client.secret=8G8gVEjxcGbWKLuCEYErxg
```