Service: zimbraMail

Command: SaveDocument
Namespace: urn:zimbraMail
Description: 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>
 
Properties:
Authorization token required true
Admin Authorization token required false

SaveDocumentRequest

    <SaveDocumentRequest> ## SaveDocumentRequest
        <doc [name="..."] [ct="..."] [desc="..."] [l="..."] [id="..."] [ver="(Integer)"] [content="..."]
                [descEnabled="(0|1)"] [f="..."]> ## DocumentSpec
            <upload [id="..."] /> ## Id
            <m id="..." part="..." /> ## MessagePartSpec
            <doc id="..." [ver="(Integer)"] /> ## IdVersion
        </doc>
    </SaveDocumentRequest>

elements and attributes you can define within a <SaveDocumentRequest> element:

XPath Required / Optional Description
/doc Required (only 1)
/doc@name Optional (0 or 1) Type: String
/doc@ct Optional (0 or 1) Type: String
/doc@desc Optional (0 or 1) Type: String
/doc@l Optional (0 or 1) Type: String
/doc@id Optional (0 or 1) Type: String
/doc@ver Optional (0 or 1) Type: Integer
/doc@content Optional (0 or 1) Type: String
/doc@descEnabled Optional (0 or 1) Type: 0|1
/doc@f Optional (0 or 1) Type: String
/doc/upload Optional (0 or 1)
/doc/upload@id Optional (0 or 1) Type: String
/doc/m Optional (0 or 1)
/doc/m@id Required (only 1) Type: String
/doc/m@part Required (only 1) Type: String
/doc/doc Optional (0 or 1)
/doc/doc@id Required (only 1) Type: String
/doc/doc@ver Optional (0 or 1) Type: Integer

SaveDocumentResponse

    <SaveDocumentResponse> ## SaveDocumentResponse
        <doc id="..." ver="(int)" name="..." /> ## IdVersionName
    </SaveDocumentResponse>

elements and attributes you can define within a <SaveDocumentResponse> element:

XPath Required / Optional Description
/doc Optional (0 or 1)
/doc@id Required (only 1) Type: String
/doc@ver Required (only 1) Type: int
/doc@name Required (only 1) Type: String