Skip to main content

 Services

Web services from /about to /webhooks

upload

/upload [PUT]

com.pageseeder.load.servlets.LoadingZoneUpload

Description

Upload a single file to PageSeeder with the contents of the file in the body of the request.

If you need to upload multiple files at once, use /upload POST. However, when using autoload, you won’t be able to specify the title, description, document ID, or labels as parameters.

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 file is uploaded into the loading zone. When the autoload  parameter is true, the file is upload 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 file is 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, document ID, labels, or metadata of the target URI if it exists. This parameter has no effect if overwrite is not set to true. The title, description, docid, and labels can be specified as parameters on the request.

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

Parameters

NameDescriptionRequiredTypeDefault
autoloadWhether the upload bypasses the loading zonenobooleanfalse
descriptionThe description of the file contained in the upload (autoload only)nostring
docidThe document ID of the file contained in the upload (autoload only)nostring
filenameThe name of the file to upload (required if  no X-File-Name header)maybestring
folderThe folder the files should be uploaded into (relative to the root of the group –autoload only, ignored if url is specified)nostring
groupThe name of the group the file should be uploaded intoyesstring
labelsA comma-separated list of labels to attach to the file contained in the upload (autoload only)nostring
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
titleThe title of the file contained in the upload (autoload only)nostring
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.

Loading zone upload (default)

By default, this service returns the details of the file that was uploaded:

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

Direct upload

If autoload is true, 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>

Error handling

HTTP codeError condition
400The file name is not specified using the X-File-Name HTTP header or the filename parameter
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)
409Destination file already exists and overwrite parameter is set to false
411HTTP header Content-Length is required
413The content length exceeds the maximum upload size (default is 100MB)

Created on , last edited on