Service: zimbraMail
Namespace: "urn:zimbraMail"
SaveDocument SOAP Command

Save Document

One mechanism for Creating and updating a Document is:

  1. Use FileUploadServlet to upload the document
  2. Call SaveDocumentRequest using the upload-id returned from FileUploadServlet.
A Document represents a file. A file can be created by uploading to FileUploadServlet. Or it can refer to an attachment of an existing message.

Documents are versioned. The server maintains the metadata of each version, such as by who and when the version was edited, and the fragment.

When updating an existing Document, the client must supply the id of Document, and the last known version of the document in the 'ver' attribute. This is used to prevent blindly overwriting someone else's change made after the version this update was based upon. The update will succeed only when the last known version supplied by the client matches the current version of the item identified by item-id.

Saving a new document, as opposed to adding a revision of existing document, should leave the id and ver fields empty in the request. Then the server checks and see if the named document already exists, if so returns an error.

The request should contain either an <upload> element or a <msg> element, but not both. When <upload> is used, the document should first be uploaded to FileUploadServlet, and then use the upload-id from the FileUploadResponse.
When <m> is used, the document is retrieved from an existing message in the mailbox, identified by the msg-id and part-id. The content of the document can be inlined in the <content> element. The content can come from another document / revision specified in the <doc> sub element.
Examples:

Saving a new document:
     <SaveDocumentRequest xmlns:ns0="urn:zimbraMail">
       <doc>
         <upload id="18baa043-394f-42ae-be8a-110b279cb696:cc2f2fdf-7957-4412-aa83-6433662ce5d0"/>
       </doc>
     </SaveDocumentRequest>

     <SaveDocumentResponse xmlns:ns0="urn:zimbraMail">
       <doc ver="1" id="574" name="PICT0370.JPG"/>
     </SaveDocumentResponse>
 
Updating an existing document
     <SaveDocumentRequest xmlns:ns0="urn:zimbraMail">
       <doc ver="1" id="574" desc="rev 2.0">
         <upload id="18baa043-394f-42ae-be8a-110b279cb696:fcb572ce-2a81-4ad3-b55b-cb998c47b416"/>
       </doc>
     </SaveDocumentRequest>

     <SaveDocumentResponse xmlns:ns0="urn:zimbraMail">
       <doc ver="2" id="574" name="PICT0370.JPG"/>
     </SaveDocumentResponse>
 

Authorization token required true
Admin Authorization token required false

SaveDocumentRequest

    <SaveDocumentRequest> ## SaveDocumentRequest
        <doc [name="{file-name}"] [ct="{content-type}"] [desc="{description}"] [l="{folder-id}"] [id="{item-id}"]
                [ver="{last-known-version} (Integer)"] [content="{inlined-document-content-string}"]
                [descEnabled="{desc-enabled} (0|1)"] [f="{flags}"]> ## DocumentSpec
            <upload [id="..."] /> ## Id
            <m id="{message-id}" part="{part-id}" /> ## MessagePartSpec
            <doc id="{id}" [ver="{version} (Integer)"] /> ## IdVersion
        </doc>
    </SaveDocumentRequest>

The following table describes elements and attributes you can define within a <SaveDocumentRequest> element:

XPath Required / Optional Description
/doc Required (only 1) Document specification
/doc@name Optional (0 or 1) Type:String
File name
/doc@ct Optional (0 or 1) Type:String
Content Type
/doc@desc Optional (0 or 1) Type:String
Description
/doc@l Optional (0 or 1) Type:String
Folder ID
/doc@id Optional (0 or 1) Type:String
Item ID
/doc@ver Optional (0 or 1) Type:Integer
Last known version
/doc@content Optional (0 or 1) Type:String
Inlined document content string
/doc@descEnabled Optional (0 or 1) Type:0|1
Desc enabled flag
/doc@f Optional (0 or 1) Type:String
Flags - Any of the flags specified in soap.txt, with the addition of "t", which specifies that the document is a note.
/doc/upload Optional (0 or 1) Upload specification
/doc/upload@id Optional (0 or 1) Type:String
ID
/doc/m Optional (0 or 1) Message part specification
/doc/m@id Required (only 1) Type:String
Message ID
/doc/m@part Required (only 1) Type:String
Part ID
/doc/doc Optional (0 or 1) Information on document version to restore to
/doc/doc@id Required (only 1) Type:String
ID
/doc/doc@ver Optional (0 or 1) Type:Integer
Version

SaveDocumentResponse

    <SaveDocumentResponse> ## SaveDocumentResponse
        <doc id="{id}" ver="{version} (int)" name="{name}" /> ## IdVersionName
    </SaveDocumentResponse>

The following table describes elements and attributes you can define within a <SaveDocumentResponse> element:

XPath Required / Optional Description
/doc Optional (0 or 1) Details of saved document revision
/doc@id Required (only 1) Type:String
ID
/doc@ver Required (only 1) Type:int
Version
/doc@name Required (only 1) Type:String
Name