Developing Your Own Simple Stream Integrations

Version 18

    Starting with the 2015.2 Jive Cloud Release, you can easily build your own activity stream integration with a 3rd party service.

     

    (Refer to Creating an External Activity Stream for information about activity streams in general.)

     

     

    Overview

     

    A Simple Stream Integration allows a developer to wire up an integration between a third party service (via their webhooks) and a Jive activity stream. It is a one-way communication stream FROM the third party service TO Jive (e.g. have all GitHub issues appear in Jive as activity). It doesn't require any middleware or integration service. This feature has lots of potential for creating a bunch of integrations between third party services and Jive. To implement a simple stream integration, a developer needs to write a little bit of JavaScript within their activity stream code to transform the event info from the third party format to Jive's activity stream format. Once this activity stream is installed as an add-on to a community, ANY group or project admin can place this new stream into their group and it will automatically convert the 3rd party event into a Jive activity object.

     

    For instance, let's say you want to be notified whenever someone creates an issue in a GitHub repository... You can build an activity stream by writing a JavaScript function that transforms the contents of a GitHub webhook into a Jive activity stream payload, bundle it as an add-on, and install it into your Jive community.

     

    Now anyone can place this activity stream into a group or project, grab the URL specified in the config page for the new stream...

    github-integration.png

    ...and then subscribe to GitHub webhooks using the URL that Jive gives you...

    github-webhook.png

    Your activity stream will now automatically convert all events from GitHub-speak to Jive-speak and you'll see real-time activity in that group...

     

    Let's walk through how to do this...

     

    Create a Simple Stream Integration Using Our Form

     

    You can easily create a simple stream integration using a form that auto-generates the integration package for you (in the form of a Jive add-on). All you need to do is write the transform function in JavaScript. Once you have the add-on package, you can upload it to your Jive community.

     

    1. Use the Simple Stream Integration Generator form to build an add-on. Create the transform function directly from within the form. Refer to the JSON schema below as a reference when building the resulting output to your function.
    2. Download the add-on from the form. If you'd like to inspect or modify the add-on, unzip the package, modify it, and the zip it back up. If you plan to repackage the add-on don't forget to ensure that the meta.json and definition.json files reside in the root directory of the zip (and not in a subdirectory).
    3. Install the add-on, as described in Installing an Add-on into Your Community.
    4. Manage the settings for a group or project, add a stream integration, select your new stream, and then copy the URL from the config page:

    simple-stream-integ-config.png
    Use this URL for the 3rd party service that you're integrating with. For instance if you were creating an integration with GitHub, you'd go to the webhook settings for your GitHub repository and plug in the URL when setting it up:

    github-webhook.png

    Save the settings for that group or project, and that's it! Whenever the third party service sends a webhook, you'll see it in your Jive community.

     

    Check out the section below for more details about what is going on under the hood.

     

    Create a Simple Stream Integration Manually

     

    Attached to this document is a simple add-on template you can use as a starting point. There are just a few "TO DO" items that you have to update before installing this add-on into your community. Each section below itemizes these TO DO steps.

     

    Update meta.json

     

    This file is a standard meta.json file required for any add-on package. Refer to Building a Jive Add-On for information about meta.json.

     

    TO DO: If you are using the attached add-on template, be sure to replace the "id" field with a unique GUID for this add-on. You can also update the "name" and "description" fields with better descriptions for this add-on package. Keep in mind that this information describes the add-on package and not the activity stream itself (which is defined in definition.json).

     

    Update definition.json

     

    This file is similar to a typical definition.json file that includes an activity stream. Refer to Building a Jive Add-On - definition.json for information about a basic definition.json file.

     

    The main difference with this definition is that it specifies the location of the transform function. For example:

     

    "transform": {
        "script": "xform.js"
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    The script name is the file that should reside in the data subdirectory of your add-on package.

     

    TO DO: If you are using the attached add-on template, update the "displayName", the "name", and the "description" fields.

     

    Create Transform Function

     

    The transform function must reside in the file specified by the "transform" field in definition.json. The function must have the following signature:

     

    function transform(body, headers, options, callback)
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    In this function, you can parse through the body and headers of the incoming webhook and then build a JSON payload that maps to the Jive activity JSON schema (see next section for schema details).

     

    NOTE: The transform function has a maximum execution time of 2000ms before it will quit. It is advised to not make outbound HTTP requests inside your transform function to avoid issues with it timing out.

     

    TO DO: The example provided in the attached add-on template contains sample content to get you started. The function is found inside data/xform.js.

     

    function transform(body, headers, options, callback)
    {
        /*
         * TO DO: Parse 'body' arg based on incoming event from 3rd party system
         */
    
        parsedBody = body.toString();
    
        /*
         * TO DO: Replace the dummy code below with your own transformation code.
         */
    
        // Build activity object.
        var activityInfo = { actor: {}, object:{} };
    
        // Optional name of actor for this activity. Remove if n/a.
        // activityInfo.actor.name = "Jane Doe"
    
        // Optional email of actor for activity. Remove if n/a.
        // activityInfo.actor.email = "janedoe@example.com"
    
        // Optional URL for this activity. Remove if n/a.
        activityInfo.object.url = "http://developer.jivesoftware.com"
    
        // Required URL to the image for this activity. Remove if n/a.
        activityInfo.object.image = "http://bit.ly/1wYwajm"
    
        // Required title of the activity.
        activityInfo.object.title = "Name of Event"
    
        // Optional HTML description of activity. Remove if n/a.
        activityInfo.object.description = "Received this content: "+parsedBody+"
    "
    
        /*
         * Call the callback function with our transformed activity information
         */
    
        callback({ activity: activityInfo });
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    If you don't change a thing in this script, it will create a dummy event using the raw contents of the incoming body as the activity stream's description.

     

    Comply with JSON Schema

     

    The JSON schema that you send to the callback within your transform function is a simplified version of the default schema using by an external activity stream.

     

    FieldTypeRequiredDescription
    activityObjectYesContains fields for describing the activity

    action

    activity.actionObjectNo*Contains information about this activity action
    activity.action.nameStringNo*Name of this activity action; by default this value is 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.typeStringNo*Type 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.

     

    *These values are required by regular activity streams but not required for these Simple Stream Integrations.

     

    Refer to Getting Started > Creating an External Activity Stream for information about external activity streams.

     

    Miscellaneous Tasks

     

    TO DO: If you are using the attached add-on template, update the "extensionID" function within public/common.js so that it returns the correct GUID for the add-on package that you previously specified in the meta.json file.

     

    Package and Deploy Your Add-on

     

    To package your add-on, you'll have to zip up the package. Be sure that you package it so that definition.json and meta.json are at the root level of the package (and not within a subdirectory).

     

    To deploy the add-on, follow directions specified by Installing an Add-on into Your Community.

     

    Test Your Add-on

     

    Manage the settings for a group or project, add a stream integration, select your new stream, and then copy the URL from the config page:

    simple-stream-integ-config.png

    Use this URL for the 3rd party service that you're integrating with. Alternatively, if you just want to directly call your stream to test it, you could use the cURL command and send whatever payload you know your stream can handle.

     

    curl -i -X POST {http-post-url} -H 'Content-type: text/plain' -d 'This is pretty cool!'
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Hopefully this document helps you see the possibilities for how you can use this activity stream feature.