Understanding Jive Resource Links

Version 1

    Introduction

    The Jive platform can be used in many differnt scenarios, from corporate intranets to external support communities and everything inbetween. Because of the varying requirements that each of these uses, Jive is a highly configurable platform. There are a number of platform capabilities that can be "turned off" if they are not used. In addition, constructs inside the platform, there are constructs, e.g. social groups, that will have different capbilities. For example, one social group may support blogs while another does not. In the Jive programming model, these capabilities manifest themselves as resource links. Understanding resource links and how they affect what's available on a JavaScript object will affect how application code is developed.

     

    What is a resource link?

    A resource link represents a named capability of the platform that can be accessed or worked with programatically via the API. (Resource links are available only on objects returned from the Jive Core API. At present, OpenSocial does not have the notion of resource links.) Resource links are represented as a name, an reference path (URL framgement), and a set of permissions, represented as HTTP verbs. Lets look at a concrete example: User.

     

    Here's a rough snipit of code that will return the Jive User object for the person currently logged in.

    osapi.jive.core.users.get({id: "@viewer").execute(<callback function>)

     

    Here's the JSON that's returned from that call:

    {

        "id": 2009,

        "creationDate": "2010-11-16T17:51:08.776+0000",

        "resources": {

            "reports": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/reports"

            },

            "manager": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/manager"

            },

            "privateDocuments": {

                "allowed": [

                    "GET",

                    "POST"

                ],

                "ref": "/my/private/documents"

            },

            "self": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009"

            },

            "connections": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/connections"

            },

            "activities": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/activity"

            },

            "avatar": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/avatar"

            },

            "blog": {

                "allowed": [

                    "GET"

                ],

                "ref": "/blogs/1158"

            },

            "colleagues": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/colleagues"

            },

            "privateDiscussions": {

                "allowed": [

                    "GET",

                    "POST"

                ],

                "ref": "/my/private/discussions"

            },

            "mentions": {

                "allowed": [

                    "GET"

                ],

                "ref": "/my/mentions"

            }

        },

        "enabled": true,

        "lastName": "Weitzel",

        "username": "mark.weitzel",

        "level": {

            "resources": {

                "image": {

                    "allowed": [

                        "GET"

                    ],

                    "ref": "/images/status/statusicon-48.gif"

                }

            },

            "name": "Novice",

            "points": 216,

            "imageURL": "https://app-sandbox.jivesoftware.com/api/core/v2/images/status/statusicon-48.gif"

        },

        "email": "mark.weitzel@jivesoftware.com",

        "name": "Mark Weitzel",

        "modificationDate": "2011-11-01T16:08:46.947+0000",

        "firstName": "Mark",

        "reports": {},

        "manager": {},

        "privateDocuments": {},

        "self": {},

        "connections": {},

        "activities": {},

        "avatar": {},

        "blog": {},

        "colleagues": {},

        "privateDiscussions": {},

        "mentions": {},

        "avatarURL": "https://app-sandbox.jivesoftware.com/api/core/v2/users/2009/avatar",

        "follower": {}

    }

     

    Notice the field "resources". These represent all of the configurable capabilities available on my user. Looking more closely at "privateDiscussions".

    • Name: "privateDiscussions"
    • Refenece Path: "/my/private/discussions"
    • Permissions: Read (GET) / Write (POST)

         "privateDiscussions": {

                "allowed": [

                    "GET",

                    "POST"

                ],

                "ref": "/my/private/discussions"

            },

    In addition, when an object is created, the Jive framework will create a "helper method(s)" that make it easy to access the resources. In this case, the user object would have a "privateDiscussions" function. This function exists because the user has the ability to create private discussions. This enables developers to write code like this:

    user.privateDiscussions.get.execute(<callback function>);

     

     

    Availability of Resource Links

    The important thing about resource links is that they may not always be present on the object you are working with. For example, it's possible for Jive to have only the notion of users and relationships without any kind of corporate structure. The result is that the methods in Jive used to fetch org chart information will not be present. If org chart was turned off in Jive, then the Jive user object would look similar to the following:

    {

        "id": 2009,

        "creationDate": "2010-11-16T17:51:08.776+0000",

        "resources": {

            "privateDocuments": {

                "allowed": [

                    "GET",

                    "POST"

                ],

                "ref": "/my/private/documents"

            },

            "self": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009"

            },

            "connections": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/connections"

            },

            "activities": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/activity"

            },

            "avatar": {

                "allowed": [

                    "GET"

                ],

                "ref": "/users/2009/avatar"

            },

            "blog": {

                "allowed": [

                    "GET"

                ],

                "ref": "/blogs/1158"

            },

            "privateDiscussions": {

                "allowed": [

                    "GET",

                    "POST"

                ],

                "ref": "/my/private/discussions"

            },

            "mentions": {

                "allowed": [

                    "GET"

                ],

                "ref": "/my/mentions"

            }

        },

        "enabled": true,

        "lastName": "Weitzel",

        "username": "mark.weitzel",

        "level": {

            "resources": {

                "image": {

                    "allowed": [

                        "GET"

                    ],

                    "ref": "/images/status/statusicon-48.gif"

                }

            },

            "name": "Novice",

            "points": 216,

            "imageURL": "https://app-sandbox.jivesoftware.com/api/core/v2/images/status/statusicon-48.gif"

        },

        "email": "mark.weitzel@jivesoftware.com",

        "name": "Mark Weitzel",

        "modificationDate": "2011-11-01T16:08:46.947+0000",

        "firstName": "Mark",

        "privateDocuments": {},

        "self": {},

        "connections": {},

        "activities": {},

        "avatar": {},

        "blog": {},

        "privateDiscussions": {},

        "mentions": {},

        "avatarURL": "https://app-sandbox.jivesoftware.com/api/core/v2/users/2009/avatar",

        "follower": {}

    }

     

    Best Practice: Always check for Resource Links

    Because applications will be used across a wide variety of Jive instances, the presence of resource links on an object can't be guaranteed. Therefore, it's a best practice to check for the existence of resource links before invoking one of the dependent methods. For example, in the case of social groups, you should check for the existence of the "blog.get()" prior to invoking it. Failure to do so will result in an error in your application with unexpected (and often bad) consequences.