Overview
External Activity Streams, like tiles, allow you to push activity stream events to Jive groups and projects when there is new information. The difference between a tile and an activity is that a tile is a single, fixed UI element on a page whereas an external activity stream involves distinct activity events that accumulate on an activity page. These external activity stream events accumulate in the activity stream for a group or project alongside the other native events that occur within Jive.
Once an external activity stream is registered (see Tile Registration and Data Push), you need to send an HTTP POST request to Jive with a JSON payload containing information about each new activity event.
This document describes the activity stream JSON payload and runs you through a simple activity stream example using the Jive Node SDK.
JSON Payload Info for an Activity Stream
This section shows an example of a JSON payload for external activity events and then describes the JSON schema for this payload.
JSON Example
{ "activity": { "action": { "name": "posted", // Required "description": "Changed the deal size", // Not in UI }, "actor": { // Optional "name": "John Doe", // Not in UI "email": "john.doe@jivesoftware.com" }, "object": { "type": "website", // Default Open Graph type; Required "url": "http://www.google.com" "image": "http://some.domain.xyz/image.jpg" "title": "New Activity Title", // Title that is displayed "description": "The informative description to my new activity" // Subtitle; Optional } } }
If you are using a Jive Node SDK example, refer to /tiles/{stream-name}/backend/datapusher.js to see the JSON payload that gets pushed to Jive.
JSON Schema
Field | Type | Required | Description |
---|---|---|---|
activity | Object | Yes | Contains fields for describing the activity |
action | |||
activity.action | Object | Yes | Contains information about this activity action |
activity.action.name | String | Yes | Name of this activity action; must be set to "posted" |
activity.action.description | String | No | Description of this activity type; not shown in the UI |
actor | |||
activity.actor | Object | No | Person associated with this activity |
activity.actor.name | String | No | Name of the person |
activity.actor.email | No | Email address of the person; name will display in activity if this email is associated with a user in the community | |
activity.actor.avatar | URL | No | URL for the avatar image of the person |
object | |||
activity.object | Object | Yes | Details about the activity |
activity.object.type | String | Yes | Type of activity; uses the Open Graph protocol; typically just use "website" |
activity.object.url | URL | No | URL associated with this activity |
activity.object.image | URL | Yes | Location of the activity image; this image is shown on the activity page |
activity.object.title | String | Yes | Title text for the activity; shown in the UI |
activity.object.description | String | No | The description text for this activity; shown in the UI if specified |
jive | |||
activity.jive | Object | No | Additional Jive-specific content |
activity.jive.app | Object | No | Information associated with an app you want to embed inside the activity stream event
Example of an embedded app inside an activity stream: "activity": { ... "jive": { "app": { "appUUID": "f53abced-f56e-5073-87bb-2fa88abc3b49", "view": "canvas", "context": { "sample-info": "some specific context related to this event" } } } }
For more documentation on embedding an app inside an activity stream, refer to How to embed an app within an external stream object. |
Jive Node SDK Example for an Activity Stream
In this Getting Started tutorial, we will use the Jive Node SDK to create a simple activity stream. An activity stream can be used to push information into the "Recent Activity" section of a Jive place.
The instructions below should take under 15 minutes.
Prerequisites
Before running this tutorial:
- Install the Jive Node SDK on your development system. Installation instructions are described at Getting Started > Installing the Jive Node SDK.
- You need to be able to install add-ons on the Jive server being used for this tutorial. This will require you to be an administrator, a community manager, or have the sandbox property turned on to enable the installation of add-ons for personal use (property name: jive.extension.sandbox.enabled). Registered developers can use the Jive Developer Sandbox, which has the sandbox property turned on.
- Your development system must be accessible to the Jive server. If your system is not accessible to the Jive server (e.g. behind a firewall), consider using a cloud-based IDE for this tutorial. See Using Nitrous.IO with the Jive Node SDK for one type of cloud-based solution.
Instructions
To create an activity stream:
- Browse to an empty directory where you want your code for this tutorial to reside.
- Create an activity stream sample using the Jive Node SDK:
jive-sdk create activity-stream
- Update all node package dependencies.
npm update
- If you want to change the display name of your activity stream, modify the "displayName" property found in tiles/{stream-name}/definition.json.
- To test what is provided out of the box, follow instructions for deploying your project at Getting Started > Deploying a Jive Node SDK Project as an Add-On.
- Once you've deployed the add-on, you can test out the stream by going to a Place and adding a stream.
- Browse to a Place (i.e. a project or group).
- Select Settings from the Manage submenu.
- Click "Add a stream integration".
- Select "sample-activity-stream" (or whatever you named your stream).
- This stream has a sample configuration page. Turn on the activity from the configuration page and click Submit.
- Click Save at the bottom of the Place.
- Wait five seconds for the activity stream to start sending activity and then refresh the page of your group or project.
The activity stream should now be sending activity events every five seconds.
You can now dig into the code to modify the activity stream example. Refer to /tiles/{stream-name}/backend/datapusher.js to see the JSON payload that gets pushed to Jive.
For More Information
- For information about embedding an app inside an activity stream, refer to How to embed an app within an external stream object.
- For other Jive Node SDK tutorials, refer to Getting Started with the Jive Node SDK.
Comments