Using the Jive Activity API: How to create activities, notifications and actions from your app

Version 2

    Jive 5 is optimized for consuming and understanding the information that flows into each user's activity stream. Because most activity streams can rapidly fill up with irrelevant data, Jive 5 features What Matters, an interface designed to deliver the information that matters most--to you. In Jive 5, the applications are able to post to the different parts of the stream. Leveraging "What Matters" within your app greatly increases its effectiveness and reach into an organization. In the screen capture below, the three icons that are circled represent different parts of "What Matters". From left to right, these icons represent the Activity, Communications, and Actions areas of What Matters. This document provides some instructions for integrating your App into the Jive What Matters interface.

     

    wm.png

     


    Entry types


    When you create an App, you can inject the following kinds of entries into the What Matters interface. Different entry types show up in different pages within What Matters.

     

    Entry TypeWhat Matters Location
    App installActivity / Communications *
    Stream update - singleActivity / Communications *
    Stream update - groupedActivity / Communications *
    NotificationActions > Notifications
    ActionActions > Action Alerts

     

    * If the app activity is being tracked, it can appear in both places.


    1. App installs (Activity)
    2. Stream update - single item (Activity)
    3. Stream update - grouped
    4. Notifications
    5. Actions

     

    Which one you choose depends on what you want your app to accomplish within Jive.

     

    1. App Installs

     

    When a user installs an App, a notification is fired off into the stream. The notification template is generated automatically from data gathered from the Jive Apps Market (JAM).

     

    JSON Components required from Apps to generate this entry


         None - All this information is gathered automatically.

     

     

    Example of an App install in the What Matters: Activity stream

    app-install-entry.png

     

    2. Stream Update - Single Item

     

    Most Apps will use this type of entry to display activity. The stream entry looks very much like a native Jive status update or microblog entry. It flows into the What Matters: Activity stream, and is visible to the entire community.

     

    JSON Components required for Apps to generate this entry


    body - A brief description of the activity. Include the @actor and, if specified - a @target. Brief is the key here. You can use the object:summary to expand on the content of your entry.

     

    Use the following structural patterns as a guide:

    [Actor] [verb]

    [Actor] [verb] [Target]

    [Actor] [verb] [Target] [noun]

     

    Examples:

    "${@actor} posted" will produce: "John Smith posted" [Actor] [verb] 

    "${@actor} answered ${@target}'s question" will produce "John Smith answered Jane Doe's question" [Actor] [verb] [Target] [noun]

     

    Avoid making your body entry any longer, because it will look unbalanced next to other stream updates and create a bad user experience for your App.

     

    icon - Path to a 16x16 app activity icon to display in the entry. Can be png, gif, or jpg format.

     

    source - Usually auto generated. This is the link back to your app

     

    object:summary - Usually, the text of an entry. This element can contain basic html, but cannot exceed 200 characters (or 6 lines). Accepted HTML tags are: <a> (links), <br>, <strong>, <em>, <p>. No inline styles/attributes are allowed except href for anchor tags. HTML outside these restrictions is removed.

     

    Optional JSON components

     

    title - If specified, this will create a bold header above the summary, which will become that App activity's permalink within Jive. Otherwise, the timestamp will act as the permalink to the activity.

     

    object:mediaThumbnail - URL to specify a thumbnail image to display in the stream. The maximum height/width is 160px, and the Jive Apps Framework provides any required resizing. . So, if you upload an image that is 320px by 80px, the thumbnail will be resized to 160px by 40px.

     

    object:mediaFullURL - URL to a larger version of the media, a file, or a video on YouTube. If you choose to link to a file, we suggest that you always pair this with a a representative mediaThumbnail, instead of going with the default Jive behavior (to show an icon and a link). The result tends to be more visually pleasing.

     

    Example JSON

    {

        "title": "Bessie is leaving us",

        "body": "${@actor} sold Bessie the Cow to ${@target} for $75.00",

        // In the example, it resolves to "Amy Stewart sold Bessie the Cow to John Roberts for $75.00" line.

        "icon": "http://example.org/icon/animal_sale.jpg",

        // a 16x16 icon (png, gif, jpg) that appears in the entry. Here, it displays to the lower right of the @actor's avatar

        "verb": "post",

        "object": {

            "objectType": "article",

            "summary": "<strong>Adieu, Bessie.</strong><br/>I'm sure you will make one fantastic hamburger.",

            // keep the summary short. Under 200 characters (not including html tags), and no more than 5 lines of text.

            "mediaLink": {

                "mediaType": "photo",

                "url" : "http://example.org/photos/bessie.jpg"

                // A link to attached media, thumbnails are automatically generated.

            }

        },

        "target": {

            "id": "urn:jiveObject:user/1234",

            // A jiveObject URN for a user that will generate a user profile link when displayed.

            "displayName": "John Roberts"

        }

    }


    Example result in stream

    app-entry-post.png

     

     

    Stream Update - Grouped

     

    App developers have an additional option to group similar kinds of activity together in the stream. If you expect that your App will be "noisy," generating a lot of activity in quick succession, consider using a grouped activity template so that people don't end up ignoring--or worse, uninstalling--your App.  Grouped stream items also flow into the What Matters: Activity stream, and are visible to the entire community.

     

    JSON Components required for apps to generate this entry

     

    All the JSON is the same as the single entry template, with two exceptions:

     

    jiveDisplay - Set this value to "grouped" for a grouped entry

     

    verb - The verb needs to match between grouped entries, and should be fairly unique

     

    Optional JSON components

     

    Same as single entry template

     

    Example JSON of a single Grouped item (items with the same verb and the jiveDisplay: grouped flag set will roll up together)

    {

        "title": "Photo Album: Jive New Way Tour, 2011",

        "body": "${@actor} added a photo to$ {@target} album",

        "icon": "http://example.org/icon/photo-album-16x16.png",

        // a 16x16 icon (png, gif, jpg) that appears in the entry. Here, it displays at the very top of the entry next to the Title    

        "jiveDisplay": "grouped",

        // invoke the grouped template

        "verb": "(verb_to_group_on)",     

        // define the verb to group on, in this example it might be "posted to album 12345". 

        // NOTE: this needs to match other items in the grouped entry

        "object": {

            "objectType": "article",

            "summary": "<strong><a href="path/to/photo">Chicago - Mainstage</a></strong><br/>Really great session and 

                                  good energy during the mainstage presentation.",

            // keep the summary short. Under 200 characters (not including html tags), and no more than 5 lines of text.

            "mediaLink": {

                "mediaType": "photo",

                "url" : "http://example.org/photos/chicago-mainstage.jpg"

                // A link to attached media, thumbnails are automatically generated.

            }

        },

        "target": {

            "url": "path/to/album",

            "displayName": "Jive New Way Tour, 2011"

        }

    }

     

    Example result in stream (collapsed and expanded)

     

    app-grouped.png

     

    Note that after someone comments on a grouped entry, it will look and behave like a single entry from that point on.

     

     

    4. Notifications


    Notifications are messages that can be sent from an App to a specific person. These messages are only visible to the targeted person. They are surfaced in the Notification tab of the What Matters: Actions page. You should use notifications sparingly. An App that sends too many notifications runs the risk of being perceived as irritating.

     

    JSON Components required for Apps to generate this entry

     

    All the JSON is the same as the single entry template, with one additional flag:

     

    deliverTo - The user ID of the person the notification is intended for. Please note that this property exists at a level above the activity object.

     

    Optional JSON components

     

    Same as single entry template

     

    Example JSON

    var postData = {

        activity: activity_object_from_above,

        deliverTo: "12345"

    }

     

     

    5. Actions

     

    Actions are notifications that include action links, enabling the user to take immediate action without necessarily opening the App. Actions are surfaced in the Action Alerts tab of the What Matters: Actions page.

     

    JSON components required for Apps to generate this entry

     

    All the JSON is the same as the Notification template.

     

    Optional JSON components

     

    Same as single entry template

     

    Example JSON

    {

        ...

        object: {

            ...

            actionLinks: [ // May contain up to 3 action links, that are presented as buttons to the user

                {

                    // a button that performs an HTTP GET to the home server

                    title: "Make it so",

                    url: "http://my.domain.com/http/get/this.url?may_contain=a-query-string#server-expects-a-200-response-to-indicate-success"

                },

                {

                    // A button that opens the app with a deep link; the app is responsible for dismissing the action; requires the user to have the app installed

                    title: "Show details",

                    url: osapi.jive.core.activities.createDeepLink("canvas.sub.view", {key: "value",context: "more view param data"})

                },

                {

                    // A button that dismisses without taking any action

                    title: "Dismiss"

                }

            ]

        }

    }

     

     

    Example result in What Matters: Actions:


    app-notification.png

    5.1 Signed Actions

    It is possible to digitally sign action links that make requests to public servers. Simply add authz=signed to the query string of the URL.

     

    Example JSON

    {

        ...

        object: {

            ...

            actionLinks: [ // May contain up to 3 action links, that are presented as buttons to the user

                {

                    // a button that performs an OAuth signed HTTP GET to the home server

                    title: "Make it so",

                    url: "http://my.domain.com/http/get/this.url?may_contain=a-query-string&authz=signed#server-expects-a-200-response-to-indicate-success"

                },

                ...

            ]

        }

    }

    What Matters, Not Whatever

     

    A great deal of design work went into ensuring that What Matters isn't  simply a regurgitation of "whatever" is happening within the enterprise. Instead, What Matters has been carefully crafted to manage your stream so as to create an effective and efficient tool for communicating and collaborating within the enterprise. Apps should take full advantage of the capabilities of What Matters and leverage its advanced capabilities to ensure a first-class user experience that is fully integrated into the Jive platform.