Skip to main content

 Services

Web services from /about to /webhooks

upload

/upload [POST]

com.pageseeder.load.servlets.LoadingZoneUpload

Description

Uploads one or more files using a multipart request.

You can use /upload PUT to upload files. The main difference is that PUT only lets you upload a single file in the body of the request. And using autoload, you can specify the title, description, document ID and labels as parameters which isn’t possible with POST.

Administrators can upload on behalf of another member using the member parameter.

There are two modes of operation depending on whether the autoload parameter was used.

By default, the files are uploaded into the loading zone. When the autoload  parameter is true, the files are uploaded directly into the target folder of the specified group.

Some limitations are controlled by global properties:

  • The maximum upload size is defined by the maxUploadSize global property.
  • The maximum number of attachments to a comment are defined by the maxAttachmentNumber global property.
  • The maximum number of workflow notifications is defined by the maxWorkflowNotifications global property.

Loading zone upload (default)

The loading zone is a temporary container for files on the server before they are loaded into PageSeeder.

There is a separate loading zone for each member on each group. Within a group, a member can have multiple loading zones by specifying a unique uploadid or xlinkid for each one. An xlinkid is used to upload attachments to a draft comment before it is submitted (the xlinkid is the same as the comment ID).

After files have been uploaded, the various load services can be used to modify, unzip them and start loading them into PageSeeder.

Direct upload (autoload)

When autoload parameter is true , the files are loaded directly into the target group and folder using a default configuration.

You can specify the target location using the url or the folder parameter. If neither is specified, the file is uploaded into the root folder of the group.

Use the overwrite-properties parameter if you want to update the title, description, labels or metadata of the target URI if it exists. This parameter has no effect if overwrite is not set to true.

You cannot use autoload for attachments to comments, so specifying autoload=true with an xlinkid parameter returns an error.

Autoload is synchronous only if a single file is uploaded. When multiple files are uploaded, PageSeeder creates a thread and returns a HTTP 202 status code.

Parameters

NameDescriptionRequiredTypeDefault
autoloadWhether the upload bypasses the loading zonenobooleanfalse
file-[n]The nth file to upload as a multipart parameter (required)yesstring
folder-[n]The folder to upload the nth file to as a multipart parameter (relative to loading zone root)nostring
folderThe folder the files should be uploaded into (relative to the root of the group - used with autoload only, ignored if url is specified)nostring
groupThe name of the group the file should be uploaded intoyesstring
memberID or username of a member to upload on behalf of (for admins only)nostring
overwriteWhether the uploaded file should overwrite an existing file (in loading zone and PageSeeder)nobooleanfalse
overwrite-propertiesWhether the uploaded file should overwrite existing URI properties (autoload only)nobooleanfalse
uploadidAn ID to uniquely identify this upload (max 100 chars, overrides xlinkid)nostring
urlA URL pointing to the folder the files should be uploaded into (autoload only)nourl
xlinkidA comment ID used to build an upload ID (for comment attachments’ loading zone - no autoload).nolong

Permission

The permission required depends on the target context.

When attaching a file to a comment, the user must be a member of the group. Otherwise, the user must have edit permissions on the target folder (contributor and higher).

An Anti-CSRF-Token token is required to use this service.

Response

The response depends on whether the autoload parameter was used and if multiple files were uploaded at once, in which case it starts an asynchronous process.

Loading zone upload (default)

By default, this service returns the details of files that were uploaded:

<upload member="[member ID]" [uploadid="[uploadid]"] max-workflow-notifications="20">
  <file name="[filename]" path="[path]" type="file" ... />
   ...
</upload> 

Direct upload (autoload)

If autoload is true and only one file is uploaded, this service returns the details of the URI created as a result of the upload in a <uri> element:

<upload member="[member ID]" [uploadid="[uploadid]" status="[failed|completed]"]
        max-workflow-notifications="20">
  <message>[explanation or error]<message>
  <uri id="[uri id]" ... />
</upload> 

If autoload is true and multiple files are uploaded, this service returns the details of the thread created in a <thread> element:

<upload member="[member ID]" [uploadid="[uploadid]"] max-workflow-notifications="20">
  <thread id="[thread ID]" ...>
    [thread XML]
  <thread>
</upload>

Error handling

HTTP codeError condition
400The Content-Type request header is not multipart/form-data 
400The parameter group is not specified or does not match an existing group
400The selected destination folder or URL is invalid
400The parameter xlinkid or uploadid is not valid
400The parameter member doesn’t match an existing member ID or username
400Attempting to upload a PSML document to a comment (xlinkid parameter is specified and the filename ends with .psml)
400Maximum number of files has been reached when attaching to a comment (default is 20)
409One of the files already exists and overwrite parameter is set to false
413One of the files exceeds the maximum upload size (default is 100MB)

If the response is asynchronous, it returns HTTP 202 and might not return an error in the response. Look at the thread status with /thread/{threadid}/progress or logs with /thread/{threadid}/logs.

Created on , last edited on