Introduction to the Javascript API

Contents

1. Overview
2. App Setup
3. Organization
4. Authentication
5. Important Features
   • Jive Request Objects
   • Paginated Lists
   • Date Format
   • Filters and Searching
6. Versioning

Overview

The purpose of the v3 Javascript API is to provide powerful functionality for interacting with your Jive instance from within a Jive App. The v3 API provides far more features than the previous v2 API. Almost any action that can be performed through the user interface can be done programmatically using the v3 API. The API also exposes some functionality of the Admin Console. Extensive metadata about the available Classes and Static Methods can be obtained with the metadata  static class.

All requests and responses use JSON data with attached javascript methods. The JSON format for different Jive objects is given in the Classes section (see sidebar). Fields marked as required must be specified when creating and updating objects. Optional fields can be specified on create and update, but the request will succeed whether or not they are provided. Fields marked as read-only are returned as data in responses. Read-only fields will be ignored for create requests. When updating an entity, fields marked as required and optional can be modified, but read-only fields should not be modified. As an example, the Document page describes the full JSON format for a document. The documents static method page gives the minimum JSON for creating a new document.

The most important types and methods in the API fall into four categories:

• Content
• Places
• People
• Activity

Content includes the Classes Document, Discussion, Poll, and Post  (see "Classes" in the sidebar.) Static classes to manipulate content include contents, discussions, polls, etc. These must be prefixed with namespace osapi.jive.corev3. The contents static class is special in that it can perform any static functionality provided by the more specific static classes (e.g. discussions). The type field must be provided when using the contents static class.

Place Classes include Blog, Group, Project, and Space. Static classes for manipulating places include blogs, places, groups, and projects. The places static class can perform any functionality provided by the other static place classes.

People, or Jive users, are manipulated with the Person Class and the people Static Class. The Member Class and members  Static Class are used for adding users to groups.

Classes related to Activity include Action, Activity, InboxEntry, and StreamEntry. Similar to Content, Places, and People, there are corresponding static classes.

App Setup

<ModulePrefs>
...
    <Require feature="jive-core-v3" />
...
</ModulePrefs>

Organization

The v3 Javascript API is organized into three main sections:

• Static Classes
• Classes
• Extendable

Static Classes

The artifacts that are listed under "Static Classes" are collections of static functions that are used as entry points into the API. These methods are generally used to obtain instances of the non-static classes; however, there are some operations that can be done directly with the static functions.

For example, to get a person, the following code can be used:

// get the request that will fetch a person by username
var request = osapi.jive.corev3.people.get({username: 'admin'});
// execute the request
request.execute(function(response) {
  if (response.error) {
    var code = response.error.code;
    var message = response.error.message;
    // present the user with an appropriate error message
  } else {
        var person = response;
        // use the person object as appropriate
  }
});

Classes

The artifacts that are listed under "Classes" provide an object oriented view of the Jive system. Instances of these classes are never constructed directly. They are obtained through calls to one of the static class methods. Once an instance is obtained, the properties and methods of that class can be accessed in the standard Javascript fashion.

For example, if a person is obtained as described above, that person's blog can be obtained directly from the person object:

// ensure that blog is accessible
if (person.getBlog)
  // get the request that will fetch the user's blog
  var request = person.getBlog();
  // execute the request
  request.execute(function(response) {
    if(response.error) {
      var code = response.error.code
      var message = response.error.message
      // present the user with an appropriate error message
    } else {
      var blog = response;
      // use the blog object as appropriate
    }
  });
}

Extendable

The artifacts that are listed under "extendable" are not first class elements in the Core API. That is, they can not be instantiated or manipulated directly. Instead they are used to add compound fields to the non-static classes. For example, the ContentBody item is used to encapsulate the content body of a Jive content object, which in turn has type and text fields.

Authentication

In order to use the Core API, the user running the app needs to be authenticated with the Jive container. The way that this happens is outside of the scope of this API. It is generally done by logging into Jive via the web UI. Once this is done, the app and all of its Core API calls run with the permissions of that logged in user.

If the current user does not have permission to perform an action, then the corresponding method will be undefined. For example, if the current user does not have permission to delete a person, then the destroy function will be undefined on that person entity.

Important Features

Jive Request Objects

How they work

{
   "error":{
      "code":400,
      "message":"Invalid date format 2012-07-05"
   },
   "status":400
}

1. Setup the JSON required to perform the request, e.g. see announcement creation  for the minimal JSON required to create an announcement. See documentation on individual entities for fields that can be used on create and update.
• In the case of updating an entity, use the existing entity. Modify the fields to be updated before obtaining the request object with var request = someEntity.update().
2. Obtain a request object
3. Call execute() on the request object, passing in the required callback

Batch requests

function createAnnouncements() {
    var announcement1 = {
        subject : "A test announcement 1",
        content : {text:"<p>Test Announcement 1</p>"}
    };
    var announcement2 = {
        subject : "A test announcement 2",
        content : {text:"<p>Test Announcement 2</p>"}
    };
    var announcement3 = {
        subject : "A test announcement 3",
        content : {text:"<p>Test Announcement 3</p>"}
    };

    var batch = osapi.newBatch();
    batch.add("announcement1", osapi.jive.corev3.announcements.create(announcement1));
    batch.add("announcement2", osapi.jive.corev3.announcements.create(announcement2));
    batch.add("announcement3", osapi.jive.corev3.announcements.create(announcement3));

    batch.execute(function(data) {
        if (data.error) {
            //handle error
        }
        console.log("First announcement's subject: " + data["announcement1"].subject);
        console.log("Second announcement's subject: " + data["announcement2"].subject);
        console.log("Third announcement's subject: " + data["announcement3"].subject);
    });
}

// get the request to retrieve a list of places, 1 per page
var request = osapi.jive.corev3.places.get({count: 1});
// execute the request
request.execute(function(response) {
  if (response.error) {
    var code = response.error.code;
    var message = response.error.message;
    // present the user with an appropriate error message
  } else {
      var place1 = response.list[0];
    // process the first place returned
  }
});

  {   
   "startIndex":0,
   "links":{
      "next":"places?sort=titleAsc&fields=%40all&count=1&startIndex=1"
   },
   "itemsPerPage":1,
   "list":[
      {
         "type":"blog",
         "status":"Active",
         "parent":"/people/2355",
         "contentTypes":[
            "post"
         ],
         "id":"1195",
         "visibleToExternalContributors":false,
         "updated":"2012-08-10T15:52:59.707+0000",
         "description":"Description of some blog created on  Fri Aug 10 2012 08:52:59 GMT-0700 (PDT)",
         "name":"Blog created at Fri Aug 10 2012 08:52:59 GMT-0700 (PDT)678245",
         "displayName":"Some_blog_872404",
         "published":"2012-08-10T15:52:59.707+0000",
         "followerCount":1,
         "viewCount":0
      }
   ]
}

//Argument: a request object that returns a Jive list
function processListByPage(request) {
    //Execute the request to get a list
    request.execute(function(response) {
        if (response.error) {
            var code = response.error.code;
            var message = response.error.message;
            // present the user with an appropriate error message
        } else if (!response.list) {
            alert("Error: response is not a list!");
        } else {
            for (var i = 0; i < response.list.length; i++) {
                //Process each element in this page
            }
            if (response.getNextPage) {
                var requestNextPage = response.getNextPage();
                processListByPage(requestNextPage);
            }
        }
    });
}

Date Format

var request = osapi.jive.corev3.documents.get();
request.execute(function(docs) {
    var firstDoc = docs.list[0];
    var datePublished = osapi.jive.corev3.parseDate(firstDoc.published);
    console.log("Parsed a document's publish date from Jive: " + datePublished);
});

var endDate = new Date();
endDate.setUTCDate(endDate.getUTCDate() + 10);
var dateString = osapi.jive.corev3.formatDate(endDate);

var announcement = {
        subject : "A test announcement to expire in 10 days",
        content : {text:"<p>Test Announcement</p>"},
        endDate: dateString
    };
var request = osapi.jive.corev3.announcements.create(announcement);
request.execute(function(created) {
    console.log("Created this announcement", created);
});

 function formatJiveDate(date) {

    if (Date.prototype.toISOString) {
        return date.toISOString().replace(/Z$/, "+0000");
    }

    function pad(number) {
        var r = String(number);
        if ( r.length === 1 ) {
            r = '0' + r;
        }
        return r;
    }

    return date.getUTCFullYear()
        + '-' + pad( date.getUTCMonth() + 1 )
        + '-' + pad( date.getUTCDate() )
        + 'T' + pad( date.getUTCHours() )
        + ':' + pad( date.getUTCMinutes() )
        + ':' + pad( date.getUTCSeconds() )
        + '.' + String( (date.getUTCMilliseconds()/1000).toFixed(3) ).slice( 2, 5 )
        + '+0000';
}

var dateRegex=/(\d\d\d\d)-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)\.(\d\d\d)\+0000/;

function parseJiveDate(dateString) {

    //First try to match the strict date format from Jive
    var match = dateRegex.exec(dateString);
    if (!match) {
        //On fail, fall back to default date parsing
        return new Date(dateString);
    }
    var year = parseInt(match[1]);
    var month = parseInt(match[2]) - 1; //javascript expects a month between 0 and 11
    var day = parseInt(match[3]);
    var hour = parseInt(match[4]);
    var min = parseInt(match[5]);
    var s = parseInt(match[6]);
    var ms = parseInt(match[7]);

    var d = new Date();
    d.setUTCFullYear(year, month, day);
    d.setUTCHours(hour, min, s, ms);

    return d;
}

Filters and Searching

Versioning

Some classes and methods have a Since label that identifies which iteration of the Core API this feature was added in. Items with no Since label have been available in Jive Cloud since the Summer 2012 refresh. Other values have the following meaning:

• Since: 3.0 - Available in Jive 6.0, and late 2012 in Jive Cloud.