Programmatic Creation of App Artifacts

Version 1

    Overview

     

    As part of Jive's !App Experiences (OpenSocial's Embedded Experiences), a developer may now call a JavaScript API which will produce the correct Jive specific macro markup given the appropriate arguments. The purpose of this API is to shield app developers from having to manually construct the macro anchor tag, which could be an error prone process when done manually.

     

    Developers can access this API by calling a static method osapi.jive.core.container.artifacts.create(). The arguments for .create() will mirror exactly what is currently supported for .closeApp(..), as described in the Alternate Experiences document (read about opensocial 2.5 compliance and also compliance with App Selection and Embedded Context Spec), with the addition of a callback parameter.

     

    The signature for the .create(..) method is as follows:

     

    osapi.jive.core.container.artifacts.create( artifact_metadata, rte_editor_action_id, markup_callback_function, suppress_image_upload_flag );

     

    Parameter

    Description

    artifact_metadata

    JSON structure, compliant with the Opensocial 2.5 embedded activity spec and the jive legacy format. The arguments for .create() will mirror exactly what is currently supported for .closeApp(..).

    rte_editor_action

    Artifact markup may only be created for apps which are !able, eg. they contain an app action with the path jive/actions/rte. The value for this field will be the value of the id parameter of that app action.

    markup_callback_function

    A callback function with a single results parameter, a JSON object structured as follows:

     

    Value

    Description

    markup

    String, optional. If markup was able to be created, it will be placed here.

    error

    String, optional. If an error has happened during markup processing, it will be placed here.

     

     

    which will be invoked with the raw text of the markup, if it is successfully produced given the other inputs of the function.

    suppress_image_upload_flag

    If set to true, the artifact function will not attempt to upload local copies of the icon or preview images described in the artifact_metadata. if set to true, there is a risk of mixed content warnings and orphaned images. App developers may wish to suppress automatic image uploading if they acquire an alternate Jive locally hosted image in some other fashion (eg. via the attachment service API).

     

    Example: Create an app artifact using OpenSocial 2.5 spec compliant arguments

     

    var artifactJson = {

      display: {

         "type": "image",

         "previewImage":"http://apphosting.jivesoftware.com/apps/dev/rtejsondropper/images/dropper-128x128.png",

         "label":"JAF Delux Productions"

      },

      target: {

         "type": "embed",

         "view":"embedded",

         "context":{

      "id":"EDIT_ME_ID",

      "lastUpdated":"2012-Jan-23"

         }

      }

    };

     

    osapi.jive.core.container.artifacts.create(response, 'org.jivesoftware.rte.generator', function (artifactMarkup) {

        var artifactJson = response.markup;

        // v3

        var request = osapi.jive.corev3.spaces.get({});

     

        // execute the request

        request.execute(function (response) {

            if (response.list && response.list.length > 0) {

                var space = response.list[0];

                var date = new Date();

                var jdoc = new osapi.jive.corev3.contents.Document();

                jdoc.visibility = "place";

                jdoc.parent =  space.toURI();

                jdoc.subject = 'Document created at ' + date;

                jdoc.content = {text:'<p>Document body content created at ' + date + ' using V3 with ' + artifactMarkup

                    + ' created programmatically</p>'};

     

                request = osapi.jive.corev3.documents.create(jdoc);

     

                // Execute the request

                request.execute(function (response) {

                    console.log("SAVED_DOC", response.content.text);

                });

            }

        });

    });

     

    In the example above, invocation of the .create() is invoked passing the artifact metadata (artifactJson) and a callback (the anonymous function). The callback will define an artifact argument (artifact in the example) which is the plain-text markup for an embedded experience app marco. Because the suppress upload images flag is ommitted, the markup will contain Jive-local copies of any remote icons or preview images specified in the artifact metadata.

     

    Developer Usecases

     

    Developers may control the origin of the images used in the app artifact, by toggling the image upload suppression flag (described above).

     

    By suppressing image upload, developers may rely on the default behavior of the .create() method -- by automatically uploading a local copy of their app icon or app preview image. The best usecase for this is when the source image (for either icon or preview image) is publicly hosted somewhere and is easily accessible to the target Jive instance. This is a good choice for artifacts using icon-based images, or for preview based artifacts, where the preview image is stored remotely. Developers interested in using the app itself to upload an image (and thereby acquire a jive-locally hosted image) should forgo this and instead op to suppress the automatic image upload.

     

    Use case 1: A text artifact where artifactJson.display.type = "text"

     

    1. Build the artifact metadata structure specifying a remote icon source
    2. call osapi.jive.core.container.create( ..., callback )
    3. build HTML body of content from what was returned in #2 via the callback
    4. POST content with the built HTML that contains the artifact mark-up using core API

     

    Use case 2: An image artifact where artifactJson.display.type = "image", with easily accessible remote image source

     

    Same as use case 1, except that the JSON markup for specifying preview image should be used instead of icon.

     

    Use case 3: An image artifact where artifactJson.display.type = "image", but the app wishes to upload the image source bytes

     

    Call v2 or v3 API eg. /api/core/v3/images and upload preview image, and on upload success:

    1. Build artifact JSON structure using #1 providing the URL returned, to populate the artifactJson.display.previewImage field
    2. Invoke call osapi.jive.core.container.create( ..., callback, true )  -- suppressing automatic image upload
    3. build HTML body of content from what was returned via callback
    4. POST content with the built HTML that contains the artifact mark-up using core API.