Getting Started > Creating an External Activity Stream

Version 21

     

    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