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

Version 2

Created by GaryAJ on Oct 9, 2012 3:55 PM. Last modified by GaryAJ on Oct 9, 2012 4:01 PM.

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.

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 Type

What Matters Location

App install

Activity / Communications *

Stream update - single

Activity / Communications *

Stream update - grouped

Activity / Communications *

Notification

Actions > Notifications

Action

Actions > Action Alerts

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

App installs (Activity)

Stream update - single item (Activity)

Stream update - grouped

Notifications

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

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.

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.

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

"displayName": "John Roberts"

}

}

Example result in stream

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)

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

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.