Jive Developer Introduction (early draft)

Version 39

    THIS DOCUMENT IS OUT OF DATE. PLEASE REFER TO https://developer.jivesoftware.com/intro/ FOR THE CURRENT INTRODUCTION.

     

     

     

    Introduction to the Jive Development Platform

     

    The current enterprise landscape often involves disparate systems with disparate interfaces. There are engineering servers, content management systems, supply chain management systems, version control systems, customer relationship management systems, and so on. These systems communicate with each other in varying degrees of effectiveness—both through automation and through manual processes—but they often remain separate silos of information.

     

    Jive recognizes this problem and helps unify these disparate experiences. Not only does the Jive platform make it easy to bring content into Jive, it also brings Jive to these other systems.

    02-devintro.png

    Some of these connections are provided today with out-of-the-box solutions. No coding necessary. For example:

     

    • StreamOnce brings systems, such as Email, Facebook, Twitter, LinkedIn, Evernote, Yammer, Dropbox into Jive as activity streams. This activity behaves just like activity initiated from within Jive itself.
      03-streamonce.jpg
    • The Jive for Outlook connector brings Jive into Outlook. Collaboration can occur without ever leaving Outlook.
      04-jive-outlook.PNG
    • The Jive Anywhere browser extension allows you to discuss anything on the web using a browser sidebar that shows existing Jive discussions related to the current page. You can also create new discussions with Jive Anywhere.
      05-jive-anywhere.png

    These are just a few of the tools provided with Jive to help your organization collaborate more effectively.


    Sometimes, however, these built-in solutions are not enough. In order to solve your particular business-specific problems, Jive provides a broad development platform so that you have this same deep integration into the Jive system as the Jive developers who created these out-of-the-box tools.


    The Jive Platform is a collection of APIs and SDKs to help you put together great solutions to solve different business problems. The Jive Platform is divided into distinct categories, each one targeted for different use cases. You won’t need them all, but you may need more than one.

    06-gem-picture-small.png


    • Tile, Streams, Templates: Push up-to-the-minute information into Jive places and let the user act on this information without ever leaving Jive.
    • REST API & Webhooks: Comprehensive, bidirectional interaction with the Jive community through RESTful APIs and webhooks.
    • Apps: Extend the Jive UI with your own custom application and access this app from targeted areas of the Jive user interface.
    • Analytics: Rich analytics information about your Jive community through a RESTful API.
    • Cartridges: Customize the browser experience and curate Jive discussions for sites that are relevant to your business.
    • External Storage Framework: Connect Jive to an external storage system with seamless, bidirectional integration.
    • Mobile: Bring Jive content and capabilities into a native mobile app.

     

    This page provides you with a deeper understanding of each category to help you decide which ones are best suited for your needs.

     

    Tiles, Streams, & Templates

    07-tile-gem.png

    Jive gives you several ways to bring content into your Purposeful Place. This can be done with tiles that reside on the right pane of a page, with activity streams that are threaded alongside native activity streams, and with templates that allow you to replicate a layout made up of tiles and streams.

     

    Why use this solution? Tiles, streams, and templates allow you to highlight specific, up-to-the-minute information that relates to a particular group or project. Not everybody in the organization has (or wants) access to these external systems, but they may need to see some of the content within them. Now you can bring more visibility to this content. And you can send relevant information back to those external systems.

     

    Tiles

     

    Tiles represent the elements on the right side of a place.

    08-docs-place-tile.png

    Many types of tiles are already available to you, such as the list of featured content, or the list of top contributors. This built-in functionality is achieved by using tiles. But you can create your own tiles. There are five different types of tiles available to you.

     

    tile-collage-8c4.png

     

    After the basic registration process, the core communication between your tile service and the Jive server involves you pushing JSON data to the tile when the data changes. You provide the content; Jive is responsible for displaying the content. Here is a JSON sample:

     

    "data": {
        "title": "My Great List",
        "contents": [
            {
              "text": "A cat",
              "icon": "http://localhost:8090/images/cat.png",
              "linkDescription": "This is a cat."
          },
          {
             "text": "A dog",
             "icon": "http://localhost:8090/images/dog.png",
             "linkDescription": "This is a dog."
          }
        ],
        "config":
        {
            "listStyle": "contentList"
        }
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    The above JSON content would create the following list:

    10-tile-simple-example.png

    This information does not need to be read only. You can connect the data to actions, and these actions can either take the user to another system, or you can display a UI directly within Jive.

    11-tile-action.png

    For a deeper discussion about tiles, refer to Tiles and Tile Styles.

    For a Tile tutorial, refer to Getting Started > Creating a List Tile with the... | Jive Community.

    For links to other Tile-related content, refer to Tiles, Templates & Streams - Developer Resources.

     

    Streams

     

    Streams are another type of dynamic content you can push to a Purposeful Place. With streams, you can add content directly to the activity stream of that place. The activity you push to a place is threaded alongside natively created activity. As with native activity, your activity is searchable from the search field.

    12-streams-example.png

    Similar to tiles, the essential communication involves a JSON-based data push to Jive.

     

    "activity": { 
         "action": {
             "name": "posted",
             "description": "task"
         },
         "actor": {
             "name": "James Bond",
             "email": "007@jivesoftware.com"
         },
         "object": {
             "type": "website",
             "url": "http://www.007.com/task/12345678",
             "image": "http://localhost:8090/102x102",
             "title": "Pay Odd Job",
             "description": "James Bond created a note in Pay Odd Job."
         },
         "externalID": "1012345678"
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Jive provides a mechanism for two-way synchronization of this activity data. This way, actions that occur within Jive (such comments or likes) can be passed back to the source system.

     

    For a Stream tutorial, refer to [TO DO: getting started stream tutorial].

    For links to other Stream-related content, refer to Tiles, Templates & Streams - Developer Resources.

     

    Templates

     

    Jive templates provide a reusable way to organize a group of tiles and activities to solve a particular problem. A general team collaboration place has different needs than a customer support place. You can create specific templates to be used as the basic organizing principle behind these types of places.

    13-template.png

    Templates, tiles, and streams, are provided to help you put more purpose to your Purposeful Places.

     

    Apps

     

    13z-app-gem.png

    Apps allow you to extend the Jive UI with your own business-specific application. An app UI can contain content from an external system, and it has access to Jive's open social API so that you can connect Jive information with information from your own external systems.

     

    Why use this solution? Apps allow you to bring your own UI with your own content into the Jive experience.


    The screenshot below displays the SmarterPath app, which allows a user to run through a set of training courses.

    14-app-example.png

    Apps can be accessed from the Apps menu, as shown below.

    15-app-menu.png

    But in addition to accessing your app through the Apps menu, you can provide context-specific access to your app through "application action contributions". In this way, a user can access your app from within the contexts that make the most sense. Some locations for app actions include the sidebar, project tabs, the create menu, and even within the text area when creating content.

    16-app-actions.png

    A Jive App is written in HTML and JavaScript, or using another web-based scripting language. Application actions are defined within elements of the HTML content. The excerpt below illustrates how you might wire up an application action to the sidebar wherever content is displayed.

     

    <Require feature="actions">
      <Param name="action-contributions">
       <![CDATA[
                <action id="com.jivesoftware.contentaction"
                  path="jive/actions/content/*"
                  label="My Content Action"
                  view="contentview"/>
        ]]>
        </Param>
    </Require>
    
    <Content type="html" view="content view" href="view.html" preferred_height="400" />
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    This code results in the following application action available whenever a user views content.

    17-content-action.png

    For an App tutorial, refer to Getting Started > Creating an App with the Jive Node SDK.

    For documentation on how to implement App actions, refer to App Action Contribution Reference.

    For links to other App-related content, refer to Jive Apps (OpenSocial) - Developer Resources.

     

    REST & Webhooks

    18-rest-gem.png

    The Jive REST API gives you comprehensive functionality for interacting with your Jive community. Webhooks allow you to subscribe to Jive community activity so that you are notified when relevant activity occurs.

     

    Why use this solution? While previously discussed solutions involve presenting an interface within the Jive community, the REST API and Webhooks are about interacting with Jive from the outside. The REST API allows you to query the Jive community and perform the same actions that a user can perform manually from within the UI. Webhooks allow your external system to receive Jive activity information in an event-driven manner, rather than having to poll repeatedly for information.


    REST API


    The REST API gives you powerful access to the Jive community. Most user actions within Jive can be performed with the REST API. Some of the major categories of REST APIs include:

    • /contents for interacting with content types (documents, discussions, posts, polls, announcements)
    • /places for interacting with  places (spaces, projects, groups, blogs)
    • /people for interacting with user information
    • /activities for retrieving and manipulating a user's activity stream

     

    For example, in order to create a discussion within the Jive community, you could use this curl command:

     

    curl -v -u username:password
           -k --header "Content-Type: application/json"
           -d '{"visibility": "people", "content": {"type": "text/html",
                "text": "<body><p>Here comes the discussion.</p></body>"},
                "subject": "My private discussion", "tags": [one, two, three], "type": "discussion"}'
                "https://sandbox.jiveon.com/api/core/v3/contents"
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    


    A few notes about this example:

    1. Replace "username" and "password" with your username and password.
    2. This example uses the Jive Developer Sandbox (https://sandbox.jiveon.com). You can replace this URL with whatever Jive server you are testing on.
    3. The REST API supports both OAuth and basic access authentication. This example uses basic access authentication for simplicity.
    4. This example creates a private discussion so that you can test it against a Jive server without others seeing. You can make the discussion public by removing "visibility": "people" from the JSON data.

     

    When the discussion is created, Jive responds with information about the newly created content. Below you can see an abridged version of a sample JSON response:

     

    {
    "id" : "15583",
    "resources" : {
    ...
    "author" : {
       "id" : "2688",
       ...
       "displayName" : "Display name here",
       "jive" : {
         ...
         "username" : "Username here"
       },
       ...
       "type" : "person"
    },
    "content" : {
       "text" : "<body>
                    <!-- [DocumentBodyStart:a20db05a-f7d1-4e0a-826f-56dd0bc08466] -->
                    <div class=\"jive-rendered-content\">
                      <p>Here comes the discussion.</p>
                    </div>
                    <!-- [DocumentBodyEnd:a20db05a-f7d1-4e0a-826f-56dd0bc08466] -->
                 </body>",
       "editable" : false,
       "type" : "text/html"
    },
    "status" : "published",
    "subject" : "My private discussion",
    ...
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    For complete REST API documentation, refer to the Jive v3 REST API.

    For links to other REST API-related content, refer to REST API & Webhooks - Developer Resources.


    Webhooks


    Webhooks are user-defined HTTP callbacks that allow you to be notified when events occur in your Jive community. You can use webhooks to synchronize your external content to the Jive community without the need to poll the Jive community. This is valuable, for example, if you are trying to do bidirectional commenting with another system.

     

    Jive supports two types of webhooks:

    • Content webhooks. These cover events related to content changes. For example, notification when someone comments on a document.
    • System webhooks. These cover system events unrelated to specific content. For example, notification when a user profile changes.

     

    The example below illustrates a request for webhooks related to activity within a particular place (with ID "1020"):


    curl -i -u {CLIENT_ID}:{CLIENT_SECRET}
             -X GET "https://sample.jiveon.com/api/core/v3/webhooks"
             -H "Authorization: Bearer {ACCESS_TOKEN}”
             -H "Content-Type: application/json"
             -d'{
                  "events" : "document",
                  "callback": "http://{YOUR_SERVICE_URL}/webhooks",
                  "object" : "https://sample.jiveon.com/api/core/v3/places/1020"
                }'
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Below you can see an abridged version of the JSON you might receive in a callback if someone were to post a status update within the specified place:

     

    { webhook: 'http://localhost:8080/api/core/v3/webhooks/{WEBHOOK_ID}',
      activity:
      {  content: '<a href="http://sample.jiveon.com/people/admin/status/1013">Hello World!</a>
                 in <a href="http://sample.jiveon.com/groups/test-group>My Test Group</a>',
         title: 'Hello World!',
        ...
         verb: 'jive:created',
         updated: '2014-05-13T15:57:26.479+0000',
         target:
          { id: 'http://sample.jiveon.com/api/core/v3/places/1020',
            ...
            displayName: 'My Test Group',
            published: '2014-03-13T15:12:58.880+0000',
            objectType: 'jive:group',
            url: 'http://sample.jiveon.com/groups/test-group' },
         ...
         actor:
          { id: 'http://sample.jiveon.com/api/core/v3/people/1',
            ...
            displayName: 'Administrator',
            published: '2014-02-26T23:52:23.001+0000',
            objectType: 'jive:person',
            url: 'http://sample.jiveon.com/people/admin' },
         object:
          { id: 'http://sample.jiveon.com/api/core/v3/contents/1058',
            summary: 'Hello World!',
            updated: '2014-05-13T15:57:26.410+0000',
            displayName: 'Hello World!',
            published: '2014-05-13T15:57:26.410+0000',
            objectType: 'jive:update',
            url: 'http://sample.jiveon.com/people/admin/status/1013' },
         published: '2014-05-13T15:57:26.479+0000',
         url: 'http://sample.jiveon.com/people/admin/status/1013'
      }
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    For an introductory tutorial, refer to Getting Started > Using Webhooks with the Jive Node SDK.

    For Jive Webhooks reference information, refer to the Jive v3 Webhooks API.

    For links to other Webhooks-related content, refer to REST API & Webhooks - Developer Resources.

     

    Cartridges

    19-cartridge-gem.png

    Before understanding the potential of Jive cartridges, let's first discuss Jive Anywhere. Jive Anywhere is a browser extension that allows you to open a sidebar and see the conversations in your Jive community that relate to the currently viewed web page.

    20-jive-anywhere-intro.png

    Jive Cartridges allow you to take this context-based conversation further. With a cartridge, you can fine-tune how Jive Anywhere searches for related material within your Jive community using information within the currently viewed page. You can also control what is clipped from the page by default when creating new discussions.

    22-cartridge.png

    Why use this solution? A cartridge is an easy way to connect activity on the web with activity in your Jive community using added intelligence to the process based on what you know about a website. It extends the functionality of the Jive Anywhere browser extension by allowing you to fine-tune how you associate a web page to Jive discussions.

     

    With a cartridge, you can even use JavaScript to manipulate the DOM of the current web page to include content within that page. In the below screenshot, a Gmail cartridge has added a button on the page for creating a Jive discussion from an email.

    23-Gmail_Cartridge_3-3.png

    Cartridges can be created quickly using JavaScript. The following JavaScript extracts the username for the LinkedIn cartridge:

     

    this.onGetUrlSearchResults = function (searchData, callback) {
       // invoked when community search occurs
       // extract the visited profile from page title
       var userName = extractUserName();
    
        if (userName != null) {
           // search results by quering profile name
           var query = "\"" + userName + "\"";
           ModuleContext.connectionContexts.activeConnection.clientFacade.
                         search(query, searchData.offset, searchData.limit,
                         searchData.sortBy, searchData.isAscending, callback);
       }
       else {
           // just run normal search
           callback(null);
       }
    };
    
    var extractUserName = function () {
       // extract the visited profile from page title
       var title = ModuleContext.pageInfo.title;
       var index = title.indexOf("| LinkedIn");
       if (index > -1) {
           return $.trim(title.substring(0, index));
       }
        return null;
    };
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    For an introductory tutorial, refer to Getting Started > Creating a Cartridge with the Jive Node SDK.

    For the Jive Anywhere Software Development Kit (SDK), refer to Jive Anywhere 2.1 SDK.

    For links to other cartridge-related content, refer to Cartridges (Jive Anywhere) - Developer Resources.

     

    External Storage Framework

    24-esf-gem.png

    External Storage Framework (ESF) is a powerful solution for connecting a Jive place to an external storage system. To the user, there is seamless integration between systems: if a file is uploaded via Jive, it will appear on the external system; if a file is uploaded via the external system, it will appear within Jive. Under the hood, all binary data is stored within this external system. However, this content is treated like a first-class content type within Jive: you can edit it, you can search for it, you can comment on it. Commenting on either system can work bidirectionally, if desired. Existing ESF solutions include Box, Google Drive, Dropbox, and others.

     

    Why use this solution? ESF is the best way to link Jive to an external storage system. You can provide bidirectional support for files, and for related comments. You can control membership as well.

    25-esf-box.png

    ESF is implemented as a REST service between Jive and the external storage system.

    26-esf-diagram.png

    Your code can implement the following endpoints, depending on how much functionality you choose to support:

    • /register to associate a place with external storage
    • /uploadFile when a user uploads a file within Jive
    • /downloadFile when a user wants to download a file within Jive
    • /addComment when a user comments on a file

     

    For an overview on ESF, refer to Building External Storage Provider.

     

    There is a Jive Node SDK example that you can run by executing the following command after installing the jive-sdk:

    jive-sdk create example-filestorage
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    


    For links to other ESF-related content, refer to External Storage Framework - Developer Resources.


    Analytics

    29-analytics-gem.png

    Jive provides near-time access to analytics data using the Jive Analytics API. You can acquire activity information in JSON or CSV formats via REST-based APIs.

     

    Why use this solution? The Analytics API is an effective way to extract activity data from your Jive community.

     

    This data can easily be integrated into an analytics tool. For example, the following screenshot illustrates a Splunk integration implemented by Pokeshot:

    30-analytics-pokeshot-splunk.png

    In order to access analytics information, you need to acquire a client ID and secret from the administrator of your Jive community. With this information, you can request an access token using an API call. This access token is necessary to perform activity requests.

     

    The following command requests two activity items, beginning with index number two:

     

    curl -i "api.jivesoftware.com/analytics/v1/export/activity?count=2&startIndex=2"  

     

    Below is an abridged response example:

     

    {
       "paging": {
           "next": "http://api.jivesoftware.com/analytics/v1/export/activity?startIndex=4&count=2",  
           "previous": "http://api.jivesoftware.com/analytics/v1/export/activity?startIndex=0&count=2",  
           "itemsPerPage": 2,
           "totalCount": 1968999,
           "currentPage": 2,
           "totalPages": 984500
       },
       "list": [
           {
               "name": "ACTIVITY_UNLIKE_MESSAGE",
               "timestamp": 1403210186028,
               ... (other information) ...
           },
           {
               "name": "ACTIVITY_STATUSPOINTSMODIFIED_COMMUNITY",
               "timestamp": 1403208266865,
               ... (other information) ...
           }
       ]
    }
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    The Analytics API can be a powerful tool when analyzing activity in your community.

     

    For more detailed documentation on the Analytics API, refer to Using the V2 Jive Data Export Service (Analytics).

    For a tutorial video, refer to Jive Developer Series - Exploring the Data Export API.


    Mobile

    mobile-gem.png

    With the Jive Mobile SDK, you can bring Jive content and capabilities into your iOS app. This SDK is the very same SDK used by Jive to create its own mobile experience. You can build a full-blown Jive experience or simply connect with the subset of features relevant to your use case.

    28-mobile-screenshot.jpeg

    Why use this solution? The Mobile SDK allows you to interact with the Jive community from within your iOS app.

     

    This iOS7-compatible SDK is based on the Jive REST API, includes JSON-Object mappings, and is designed using an intuitive class hierarchy. The following sample code illustrates what it is like to use the SDK get information about the user's inbox:

     

    JiveInboxOptions *unreadInboxOptions = [JiveInboxOptions new];
    unreadInboxOptions.unread = YES;
    unreadInboxOptions.count = 10;
    
    [communityInstance inbox:unreadInboxOptions
                  onComplete:^(NSArray *inboxEntries, NSDate *earliestDate, NSDate *latestDate)
      {[self showInboxEntries:inboxEntries from:earliestDate to:latestDate];}
                     onError:^(NSError *error) {[self handleInboxError:error];}];
    
    [communityInstance contentFromURL:entryItem.contentURL
                           onComplete:^(JiveContent *content) {[self displayContent:content];}
                              onError:^(NSError *error) {[self handleContentFromURLError:error];}];
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    For an introduction to the Jive iOS Mobile SDK, refer to Developing with the Jive iOS SDK - In the beginning.

    For links to other Jive Mobile SDK-related content, refer to Mobile - Developer Resources.