Document Use Cases

Handling visibility of a document

Documents can be visible to everyone at Jive, to some users or just to the owner of the document. Use thevisibility field to define the visibility of the document. To make things easier, Jive will use smart defaults if none was specified. The following visibility defaults will be used:

place - if parent was defined and points to the URI of a place (e.g. group). Visibility is defined by the rules of a place.
people - if users was defined and points to the URI of users that can see the document.
all - if parent and users are not define. Everyone can see the document.

Besides the above 3 possible visibility values, we have hidden. When specifying hidden as the visibility, we are indicating that the document will only be visible to the owner of the document. Here we see an example:

   {"visibility": "hidden",
    "subject": "Document for only me",
    "content": {"type": "text/html", "text": "<body><p>Description of the document</p></body>"},
    "tags": [one, two, three],
    "type": "document"}

Including attachments in documents

Documents, like many other content in Jive, can include attachments. When creating a document it is possible to include files that will become attachments for the document. This is accomplished by doing a "multipart/form-data" POST request to /contents. Here we can see a simple example using CURL.

   curl -i -u admin:admin
        -F "file1=@presentation_demo.ppt"
        -F 'json={"type": "document", "subject": "Document with Attachment", "content": {"type": "text/html", "text": "hello world!"}};type=application/json'
        https://example.jiveon.com/api/core/v3/contents

For existing documents, it is possible to manage its attachments using the /attachments service. When updating a document, it is possible to replace all existing attachments with the new ones being passed. This is accomplished by doing a "multipart/form-data" PUT request to /contents/{contentID}.

Restricting comments on a document

Under some rare circumstances, you might want to restrict comments on a document. If a document already has comments, then existing comments will be displayed but new comments will not be allowed. It is possible to restrict comments when you create a document or when updating it. The following JSON example shows how to restrict comments:

   {"subject": "Document with comments restricted",
    "content": {"type": "text/html", "text": "<body><p>Description of the document</p></body>"},
    "restrictComments": "true",
    "type": "document"}

Create comments on a document

It is very simple to create a comment on a document, or any piece of content. All you need to do is a POST to /contents/{contentID}/comments. Here is a JSON example for the body request:

   {"content":
       {
       "type": "text/html",
       "text": "<body><p>This is a new comment</p></body>"
       },
    "type": "comment"}

Documents that restrict authors (i.e. who can edit the document) allow authors to privately comment on the document. To create an author comment, you just need to include a query param author with value true