Getting Started > Creating an External Activity Stream

Document created by yuval.z Employee on Oct 2, 2014Last modified by yuval.z Employee on Apr 27, 2015
Version 21Show Document
  • View in full screen mode

 

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.

sample-activity.png

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

activity stream.png

FieldTypeRequiredDescription
activityObjectYesContains fields for describing the activity

action

activity.actionObjectYesContains information about this activity action
activity.action.nameStringYesName of this activity action; must be set to "posted"
activity.action.descriptionStringNoDescription of this activity type; not shown in the UI

actor

activity.actorObjectNoPerson associated with this activity
activity.actor.nameStringNoName of the person
activity.actor.emailEmailNoEmail address of the person; name will display in activity if this email is associated with a user in the community
activity.actor.avatarURLNoURL for the avatar image of the person
object
activity.objectObjectYesDetails about the activity
activity.object.typeStringYesType of activity; uses the Open Graph protocol; typically just use "website"
activity.object.urlURLNoURL associated with this activity
activity.object.imageURLYesLocation of the activity image; this image is shown on the activity page
activity.object.titleStringYesTitle text for the activity; shown in the UI
activity.object.descriptionStringNoThe description text for this activity; shown in the UI if specified
jive
activity.jiveObjectNoAdditional Jive-specific content
activity.jive.appObjectNo

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:

  1. Install the Jive Node SDK on your development system. Installation instructions are described at Getting Started > Installing the Jive Node SDK.
  2. 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.
  3. 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:

  1. Browse to an empty directory where you want your code for this tutorial to reside.
  2. Create an activity stream sample using the Jive Node SDK:

    jive-sdk create activity-stream

    This creates a project with all the code necessary to build a simple activity stream. The provided stream sends a new activity every five seconds. The Jive Node SDK uses built-in OAuth 2.0 authentication for stream registration.
  3. Update all node package dependencies.

    npm update

  4. If you want to change the display name of your activity stream, modify the "displayName" property found in tiles/{stream-name}/definition.json.
  5. 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.
  6. Once you've deployed the add-on, you can test out the stream by going to a Place and adding a stream.
    1. Browse to a Place (i.e. a project or group).
    2. Select Settings from the Manage submenu.
      install-tile-1.png
    3. Click "Add a stream integration".
      add-stream.png
    4. Select "sample-activity-stream" (or whatever you named your stream).
    5. This stream has a sample configuration page. Turn on the activity from the configuration page and click Submit.
    6. Click Save at the bottom of the Place.
      install-tile-5.png
    7. 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.

stream.png

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

 

Attachments

    Outcomes