Task upload

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

This task is available in PageSeeder v5.8115 and higher.

Definition

Minimal definition:

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

Full definition:

<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]"
    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`
saveuris	If specified, save the URIs uploaded to this path as XML	No
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.

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 element must be used to specify the files to be uploaded.

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.
servlet.prefix – servlet prefix for connecting to PageSeeder – default /ps/servlet.
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.

<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

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

<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)

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

<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>

<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

<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

scheme=https
host=ps.example.com
port=443
servlet.prefix=/ps/servlet
site.prefix=/ps
username=acmesystem
password=thepassword

When a password is in a file like this it is more secure to configure it as an API account in case someone gets a copy of the file. API accounts can only access PageSeeder from specified IP addresses and can be configured by adding the following properties for example to the global.properties :

apiAccountUsernames=acmesystem
apiAccountIPs=192.123.0.7

In PageSeeder v6 or higher it is recommended to use the OAuth client.id and client.secret properties instead of username/password as these are more secure and don’t require the configuration of an API account.

Created on 4 March 2016, last edited on 12 August 2025 at 14:36

Publishing