Binary Data Storage Usage

Version 1

    This is a doc on how accessing binary data storage works in Jive.

     

    1. Use Cases

    There  are use cases for binary data storage in a JAF app that contains  embedded logic in a technology such as Flash or Silverlight, which want  to persist binary data in the Jive instance, where that binary data is  actually computed by the embedded logic (rather than being stored in a  file on the client's machine, which could be uploaded as a file  attachment).  While such logic can use the appropriate JavaScript Bridge  to make Jive Core API and Jive Connects API calls (and not have to  worry about authentication), this is not convenient for binary storage.   Hence, we are introducing a Jive Binary API to cover the following  scenarios:

    • Storage and retrieval of binary data items in a  standalone binary data store in the Jive instance that is private to a  particular application running on behalf of a particular user.
    • Storage and retrieval of binary attachments to Jive Core documents, messages, and blog posts.
    • Creation of binary documents in a Jive place (space, social group, or project).

     

    The  Jive Binary API provides mechanisms for an embedded application to  acquire a URL that can be used, a single time, for uploading,  downloading, or deleting named binary data items that have been stored  in the Jive server.  Standalone data items are uniquely identified by a  "name" (think "a filename stored in a particular directory"), and are  visible only to the application that stored the data,  running on behalf of the user that stored the data.  Attachment  visibility is based on the visibility of the Jive object (document,  message, post) that the attachment is connected to.

     

    2. Standalone Binary Data Item Work Flows

     

    2.1 Upload a Binary Data Item (Create or Update)

    2.1.1 Acquire a One-Time-Use URL

     

    The  first step required is that the embedded application must acquire a  one-time-use URL that can be used, from the native HTTP stack of the  native technology, to upload the content (and associated HTTP headers,  as described below) of a binary data item.  This is accomplished by  utilizing the appropriate JavaScript bridge for the embedded technology,  and making the following JavaScript call:

     

    osapi.jive.binary.token({

      duration : 5,

      name : 'foo.png',

      verb : 'POST'

    }).execute(function(response) {

      // ... Process the response ...

    });

     

     

    The options that can be sent to the token command include:

     

    Option NameData TypeDescription
    durationIntegerThe  number of seconds that the returned URL should be valid.  Absolute  minimum and maximum values will be based on system configuration entries  by the Jive System administrator, but will typically be on the order of  a few seconds.  If not specified, the default value is 5 seconds.
    nameStringA  unique name for this binary data item, used to distinguish data items  stored by the same app, for the same user.  If you specify the name of  an existing binary data item that was previously uploaded, the contents  of that binary data item will be replaced.  This option is required.
    verbStringThe  HTTP verb that will be used on the subsequent HTTP request from the  embedded application, which depends on what you want to do for this  binary data item.  In this case, we are creating a new binary data item  (or updating an old one), so we want to do a 'POST'.  Other choices are  'GET' (the URL will be used to download the binary data item content) or  'DELETE' (the binary data item should be removed from the server).  If  not specified, the default value is 'DELETE'.

     

     

    The response returned by the osapi.jive.binary.token() method will look something like this (if there was no 'error' property):

     

    {

      expirationDate : "2010-10-28T18:10:06.712+0000",

      url : "http://jive.example.com/api/binary/v1/data/xxxxxxxxxxxxxxxxxxxxxxx/foo.png",

      verb : "POST"

    }

     

    which  provides to your application the expiration date/time of this URL (in  the same date/time format as is used in the Jive Core API), a URL  itself, and the verb for which this URL will be valid for a single request, and the HTTP verb that will be allowed on that request.  The  format of the URL should be considered opaque (from the viewpoint of the  embedded application), but will include the name you specified as the  final path segment.

     

    2.1.2 Peform a Native HTTP POST Request

     

    Given  the returned URL, the embedded application can now perform a POST  request (using its native HTTP stack), with the following  characteristics:

    • The URL contains embedded information  identifying the calling user and application, so no additional  authentication credentials are required.
    • Jive will capture and  store metadata from the following HTTP headers (if any) included in the  request:  Content-Encoding, Content-Language, Content-Length,  Content-Location, Content-MD5, Content-Type.
    • The body of the HTTP request will be presumed to contain the binary content to be stored for this binary data item.

     

    The  captured metadata, and the binary content, will be stored (in a  persistent manner) inside the Jive instance.  Jive system administrators  will have configuration options to define the maximum size of stored  binary data items, as well as the ability to specify throttling controls  to manage the volume of such calls.

     

    After a successful POST, the response HTTP status will be 200, and the response body will be a JSON structure describing the metadata saved for this binary data item; something like:

     

    {
      name : "foo.png",
      contentType : "image/png",
      contentLength : 12345

    }

     

    2.2 Download a Binary Data Item

     

    The  steps for an application to retrieve a previously stored binary data  item are very similar to those for creating (or updating) one -- acquire  a one-time-use URL, and then perform an HTTP GET call against that  URL.  Again, use the JavaScript Bridge for your embedded technology to  make a JavaScript call like this:

     

    osapi.jive.binary.token({

      name : 'foo.png',

      verb : 'GET'

    }).execute(function(response) {

      var url = response.url;

      // Return the "url" to your embedded application

    });

     

    followed  by an HTTP GET call (using the native HTTP stack of the embedded  technology) to this URL.  The response to this GET will include HTTP  "Content-XXXXX" headers that were captured and stored on the original  POST, and the response body will be the binary content of this binary  data item.

     

    2.3 Delete a Binary Data Item

     

    Once  an application determines that a previously stored binary data item is  no longer required, it should delete that item from the Jive server.   Again, we follow the same pattern of acquiring a one-time-use URL:

     

    osapi.jive.binary.token({

      name : 'foo.png',

      verb : 'DELETE'

    }).execute(function(response) {

      var url = response.url;

      // Return the "url" to your embedded application

    });

     

    after  which the embedded application can issue an HTTP DELETE request to  remove this binary data item (both the binary content and the associated  metadata) from the Jive instance.

     

    2.4 Retrieve Metadata About Existing Binary Data Items

     

    This  Jive Binary API call lets you retrieve information about previously  uploaded standalone binary data items created (or updated) by this  application, for this user.

     

    osapi.jive.binary.metadata({

      name : [ 'foo.png', 'bar.gif' ]

    }).execute(function(response) {

      // response will be an array of metadata objects matching the name(s) you specify

    });

     

     

    where the name property can be a single binary data item name, an array of specific  binary data item names, or omitted to retrieve metadata about all  previously stored binary data items for this application and user.  The  response will be an array of metadata objects that match the specified  names, formatted like this:

     

    [

      {

        name : 'foo.png',

        contentType : 'image/png',

        contentLength : 1234,

        contentMD5 : 'xxxxxxxxxxxx'

      },

      {

        name : 'bar.gif',

        contentType : 'image/gif',

        contentLength : 4321,

        contentEncoding : 'gzip'

      }

    ]

     

    where the name property identifies which binary data item is being described, and the contentXxxxx properties return whatever Content-Xxxxx headers were included when this binary data item was created or last updated.

     


    3. Binary Attachments Workflows

     

    There  are two supported approaches to creating binary attachments -- indirect  and direct -- that are described in the following sections:

     

    3.1 Creating a Binary Attachment Indirectly

     

    In  a manner similar to the Jive Core API support for standard attachments,  the idea here is to upload a binary attachment into a temporary space,  receiving back an "attachmentURI" that can be used when creating a  document/message/post later.  The mechanism for this is very similar to  creating a standalone binary data item as described in Section 2.1, with  an additional ref property which states that we want to create a temporary attachment instead:

     

    osapi.jive.binary.token({

      duration : 5,

      name : 'foo.png',

      ref : '/attachments',

      verb : 'POST'

    }).execute(function(response) {

      // ... Process the response ...

    });

     

     

    When  the application performs a POST using the URL it received with the  access token, the uploaded data will be stored in a special temporary  area, and you will receive back an Attachment object, similar to what appears in the attachments array on an existing document/message/post that contains attachments.  It will look something like this:

     

    {
      contentType : 'image/png',
      id : 1234,
      name : 'foo.png',
      ref : '/xxxxxxx',
      size : 12345
    }

     

     

    The ref value returned for this attachment can be used in the attachmentURIs property when you later create (or update) a document/message/post, and  will cause the temporarily stored attachment data to become attached to  the document/message/post you are creating or updating.  If you fail to  connect a temporary attachment to a Jive object in this way, it will be  deleted by the system after a period of time.

     

    When  creating a document, this technique has the advantage that the  attachment will be performed on the initial version of the document --  unlike the direct approach (described in the next section), which causes  the document version number to be incremented.

     


    3.2 Creating a Binary Attachment Directly

     

    The  indirect approach requires three steps (get an access token, create the  attachment, then create/update the Jive object that will contain it).   If you do not care about document version numbers, or if you are  creating attachments to an existing document/message/post, the direct  approach accomplishes this in two steps instead.

     

    First, get an access token that references the Jive object to which the attachment should be connected:

     

    osapi.jive.binary.token({

      duration : 5,

      name : 'foo.png',

      ref : '/documents/xxxxx',

      verb : 'POST'

    }).execute(function(response) {

      // ... Process the response ...

    });

     

     

    In this case, the ref property contains the reference value for the Jive document, message,  or post to which the attachment should be added.  The simplest way to  acquire the correct value is to retrieve the document/message/post, then  refer to its resources.self.ref property.

     

    When  you POST to the URL returned in the access token, your attachment will  be added directly to the document/message/post referenced by the  previous step.  In the case of documents, adding an attachment in this  way causes the document version number to be incremented.

     


    3.3 Downloading a BInary Attachment

     

    This is similar to downloading a standalone binary data item, except that you add a ref parameter to your access token request, passing in the reference to the document/message/post containing this attachment:

     

    osapi.jive.binary.token({

      duration : 5,

      name : 'foo.png',

      ref : '/documents/xxxxx',

      verb : 'GET'

    }).execute(function(response) {

      // ... Process the response ...

    });

     

     

    Again, the ref property value to use is most easily acquired by getting the document/message/post itself, then using its resources.self.ref property as the value to be entered.

     

    Performing  a GET against the URL you receive with your access token will retrieve  the binary content of the attachment with the specified name.

     

    4. Create Binary Document Workflow

     

    In addition to creating a binary attachment to an existing HTML document, you can also create a binary document directly.  This is similar to the workflow in the standard Jive UI  where you choose to upload a file instead of edit a document's content  with a rich text editor.

     

    FIrst, you will need the  JavaScript object that corresponds to the Jive place (space, social  group, or project) into which you wish to create a new document.   Alternatively, if you want to create a user private document, use the  Jive Object for that user instead.  Use the standard Jive Core APIs  (osapi.jive.core.space, osapi.jive.core.group, and  osapi.jive.core.project, osapi.jive.core.user) to retrieve such an  object.  The reference value you will need is the value of the resources.self.ref property of this object.

     

    Next, as we have seen in other workflows, you will request a one-time access token, but this time the ref value you pass will reference the Jive place (in this example, a social group) into which you want to create the new document:

     

     

    osapi.jive.binary.token({

      duration : 5,

      name : 'foo.png',

      ref : '/groups/xxxxx',

      verb : 'POST'

    }).execute(function(response) {

      // ... Process the response ...

    });

     

     

    Next,  do a POST to the returned URL, with a Content-Type header identifying  the media type of the uploaded data, and the request body being the  uploaded data itself.  The name of the newly created document will be  whatever you passed in the name property above, and Jive will  associate the uploaded binary data with the content type you specify on  the POST request, which can trigger things like automatic preview  generation, just as if you had uploaded the document manually through  the Jive UI.