Over the last several months, we've been working with a number of our partners to build Jive Apps for the market. For some of our partners, this was their first time really working with and understanding Jive and building an application, let alone, one designed to run within a social platform. This document is not intended to be a technical "how to"--there will be links to supporting documents that will provide more in depth details that are targeted for developers. Rather, this is written for project managers and developers in order to familiarize you with the high level architecture of Jive and the Apps Market and present the concepts of building an application that is integrated with the Jive social platform.
First Class Apps
Rather than "bolt" apps on as an after thought, Jive has integrated them as a core part of the platform. This integration manifests itself in two primary ways. First, apps are available directly from the primary navigation bar. When this menu option is selected, the user will be taken to their "apps dashboard" where they can use the apps they've chosen to install. Second, the application APIs make available virtually all of the content inside of the Jive instance. For all intent and purposes, this allows application developers to take advantage of everything inside of the Jive instance. From the enterprise social graph, to content such as documents and discussions, and the What Matters stream, it's all available to use within your application.
A key differentiator for Jive Apps is the ease in which users can add applications to their dashboard. Because Jive has taken on much of the complexity of managing an enterprise market, e.g. simplifying the billing process by being the merchant of record, the first 10 seconds of getting an application is the same for all applications--even those developed by IT departments that build specialized line of business apps. From the perspective of a third party app developer, an application is added to the dashboard only after the user has gone through the market's purchase flow. This means that your app should be able to automatically provision users based on a signed fetch from Jive (signed fetch is what provides the unique userID@jiveInstanceID identifier).
It's worth noting that the Apps Market is a cloud based service that is available to version 5.x (and above) of Jive. This means that there is only one Jive Apps Market that serves all the instances of Jive. However, each Jive instance will have its own "view" into the market. For example, when a company develops Jive Apps for use within their enterprise, only people with their Jive instance will see the listing for that app. In addition, because Jive recognizes the importance of IT control, administrators have the ability to prevent applications from being installed should their business needs or IT policies require it.
Regardless of if you are developing a third party application for sale in the Jive Apps market, or a specialized line of business app, a recommended best practice is to use "Application Life Cycle Events" to capture when your application is added or removed from a user's dashboard. Life cycle events are defined by the OpenSocial specification and represented by "Link" elements in the application definition file, the app.xml. When one of these events occurs, Jive will make an HTTP call to the URL specified in the Link element. To uniquely identify the user & Jive instance, these should be signed using 2-legged OAuth. Given that apps are first class citizens in the Jive social business platform, and that it's extremely easy for a user to find and install an app, what do you need to know about actually building an app?
Building on a social platform
The first thing to understand when you start building your app is that Jive is a social business platform. Jive contains a rich set of information about the user, including their profile, "friends" (who they are following and who follows them), org chart, which groups they participate in, the content they've created, and their activities. The amount of information available to the developer through the APIs has broad implications for the design of the app. Leveraging Jive's social capabilities enables a completely new dimension that can be added to your app. It's this deep integration with the underlying Jive social business platform that unlocks significant new value.
One of the most common shortfalls that application developers will intitially make is trying to force fit an existing service that is made available via a collection of Web pages into a Jive app. This is done by using a Jive App, which is rendered as an iFrame within the browser, to simply "wrap" a set of existing Web pages. While this might get something out quick and dirty, the main problem with this approach is that it lacks Jive's social context. This pattern, known as the "iFrame black hole". Consider the following example. Many Web based systems will attempt to connect employees of the same company, and will display a form like the one below.
However, when you are building a Jive app, it's important to realize that the user is already inside of a company, and already has access to the enterprise social graph. Rather than complementing the platform, "iFrame black hole" integration often results in a duplication of information, redundant capability, and, most importantly, a poor user experience. With only a very few exceptions, this level of integration is not recommended and should be avoided.
Avoiding the "Jump of Faith": Staying inside of your Jive App
We strongly recommended avoiding the 'iFraming" of an existing web page. The primary reason for this is because of the lack of integration with the base platform and a less than optimal user experience. However, there are scnearios where existing, stand alone business logic that should be surfaced to the user. A typical pattern is to "launch" the user to a new browser window. The downside of this is that it causes a "jumpy" and confusing user experience. OpenSocial makes it very easy to encapsulate an existing URL in an app. This can be done either by creating a "URL style view", that is, a view with a type of "URL", or by simply including an iFrame with a src attribute in an existing view. This is preferable to launching a new browser window because you can remain inside the app rather than "jump out" to a new browser window. However, if, after careful consideration, you choose to open a new browser window, this should be done in a manner where the user is already logged in to whatever application context is appropriate on your backend server.
Design with purpose: Understanding and using views
When you build your Jive App, you will have the ability to create different views for your application. A view is an area of real estate in the browser where the application will manifest itself. Typically, for security reasons, views are rendered as iFrames. The content of the view comes from the application definition, the app.xml file. This file is compliant with the OpenSocial specification, and because it defines an OpenSocial gadget, is sometimes referred to as the "gadget.xml". The concept of views is defined in the OpenSocial specification. There are two primary views that you will use when you build your app, "Home" and "Canvas", however there are specialized use cases where you may choose to define additional "sub-views", e.g. to display availability information if your app is in maitenance mode.
In Jive, you can access applications on the Apps Dashboard. When the user first opens the dashboard, their applications will be rendered together in "home" view. "Home" is a smaller view of your application, typically around 400 pixels. In this mode, your application will be among several that are on the user's dashboard. Below is an example dashboard that has three apps on it, Rypple, SurveyGizmo, and Gliffy, each in Home view.
There are a number of important design considerations when you designing the Home view of your app.
Design with a purpose
Each of the applications shown above provides an extremely informative and feature rich user interface in home view. Since your application will be competing for space on the dashboard, it's important that you provide a clean and purposeful interface. Your home view is the first impression that your app makes to a user.
- Rypple: The user can quickly recognize someone in their Jive community.
- SurveyGizmo: Get information about their survey's immediately. Each of the icons in the list will display more detailed information, e.g. pie chart.
- Gliffy: Quickly navigate to the latest document the user created or create a new one.
A "Chicklet" is a simple button or icon whose sole purpose is to launch the app into canvas view. While this works fine on your mobile phone, this kind of launcher view is highly discouraged and will fail the app approval process. The home view should be used to allow the user to quickly accomplish the most common task that your app provides.
A key motivation for Jive Apps is to provide the ability for app to complement and extend Jive's core platform with innovative new capability that builds on top of the enterprise social graph. Apps are often very interactive, and require a larger area than the recommended 400 pixels of the home view. Because of this, Jive provides a "Canvas" view for all applications. Like its name implies, an app's Canvas view will be take up the maximum area in the dashboard. An app is in Canvas view is the only visible application on the page. Here are a few examples of applications that take full advantage of the canvas view. Each application has two navigation icons located in the right of it's title bar. Click on the righter-most button in the application's chrome will navigate the user to "Canvas" view. Here are two examples of applications in "Canvas" view, SurveyGizmo and Gliffy.
SurveyGizmo has a rich canvas interface. They carry over the same metaphor from their Home view and use that over to be a navigation control in Canvas. Notice that the social information about the user is displayed across the top, as well as in the side bar.
Gliffy is a tool that lets you quickly designed flow charts, Venn diagrams, SWOT analysis charts, and pretty much anything else you can think of. In this case, the editor and the rest of the application code are hosted on the insfrastructure provided by Jive as part of the SDK. This is commonly referred to as "apphosting", in part because that's the root of the URL. When you open the canvas view, their entire editor is loaded from the hosted environment into the dashboard and voila!, you can create and share amazing diagrams right inside of Jive!
Other View Considerations
While Jive provides built in navigation to home and canvas views from the app's chrome, it's also possible to navigate among views programmatically, In fact, you are not limited to just home and canvas. You can define as many "sub-views", e.g. "home.specialize", as you need for your application. You can easily pass parameters between these views as well to maintain context. For example, one use of views can be to display a friendly message to users when your app is undergoing maintenance.
As much as it's recommended that your application always be available, there may be times where the app will have to undergo maintenance cycle. It's imperative that you communicate this back to your users. One way to do this is by using a custom sub-view for a "maintenance" mode. For example, you could define "home.maintenance" as the view to display information to your users when your app will be available again. When the app is rendered, you could perform a status check to your home server (this could be preloaded as well to avoid a round trip to the server or stored as a hidden user preference). Based on the result of this status check, the application can programmatically navigate itself to "home.maintenance".
Custom User Preferences
Each application may have settings that need to be configured by the user. In OpenSocial, these are called user preferences, or user prefs for short. These are defined in the application XML file, and when present, Jive will automatically create a view and a new menu option called "Your Settings" on the application's drop down menu. The Jive Application Framework allows you to override the default and provide your own view definition. This is a helpful and convenient way to quickly customize your application.
Jive is committed to providing, as much as possible, an API to information that is based upon open, community driven standards. OpenSocial is one of the key standards, and Apache Shindig, an open source reference framework is a fundamental underlying technology. However, the breadth and depth of the Jive platform goes beyond what's defined in OpenSocial. For this reason, and because part of the Jive programming interface existed prior to OpenSocial, there are two aspects of the Jive API. These are often referred to as "Jive Core" and "OpenSocial." For example, OpenSocial does not currently have the concept of "content", e.g blogs, documents. To get a user's blog posts, you need to use the "Jive Core" part of the API. Jive is committed to open technologies and is actively working within the OpenSocial and Apache communities to broaden the API, increase adoption, and strengthen the open ecosystem. In fact, several of the features that are in recently released OpenSocial 2.0 specification were led by Jive.
It is also worth noting that Jive exposes information via a complementary set of REST APIs as well. This allows for server to server integration between systems. However, these types of integration typically happen behind the firewall. Therefore, if you are a third party application provider that is targeting your app for use within the confines of corporate community, you should design your application in such a way that it does not rely on access to the REST APIs. IT developers creating services for use within their company should verify ahead of time that the REST APIs will be available as part of the application programming model.
However, one thing that will be necessary is to "map" a user from your system with one that comes from Jive. The strategy for user mapping should be thought about and implemented early in the process of building your app because it has implications on account provisioning and billing. One thing to realize is that the unique identifier for a Jive user is more than just the user ID. It's the user ID plus the Jive instance ID. The e-mail address of the user is NOT a good identifier because it's possible for a user to use the same e-mail in multiple Jive instances. While it's not the most prevalent use case, it is not uncommon either. In fact, as Jive apps become used in more places, namely in external public communities, this scenario is more likely to occur.
The best way to get this information is using a signed fetch, common known as two legged OAuth. In a nut shell, the way signed fetch works is that an AJAX request is made to an endpoint on your home server. Jive will sign this request using the OAuth credentials unique to this app. Your responsibility is to verify the signature. Part of the information that is sent to you is the person that made the request, in OpenSocial terms, the @viewer. The @viewer identifier is jiveUserId@jiveInstanceId. There's more details on this pattern in the doc Methods for authenticating Jive users against home servers.
Application Lifecycle Events
There are several points in time when this user mapping can be done. This first is when the user adds the application to their dashboard. This can be triggered by an event within the dashboard. If you configure your app properly, you can setup an endpoint that listens for when your app is installed (or removed). This kind of event is called a "web hook", and in order for to receive the user ID & Jive instance ID, it will need to be signed by Jive.
Using the life cycle events as the initialization to provisioning has a few considerations. First, web hooks are not guaranteed delivery. It's possible that an event could leave Jive and get lost in the ether. Granted, this is not a common occurrence, but it's possible. Second, the only identifying information you get is the instance Id and the Jive Id. A more complete profile will need to be built up outside of the life cycle event. When the Jive apps dashboard loads the application, it should have a way to determine if the app has been configured. If not, then the user should be walked through any setup & configuration necessary to provision the account on your back end and setup the app.
Auto-provisioning User Accounts
Jive apps are intended to be "self service". We would like any user at any time to be able to buy and install any app. In reality, dogs and cats don't often live nicely together and the "self serve" model isn't always practical because it doesn't fit with the way some existing applications are billed and sold. For example, some existing infrastructures often have the idea of a company or an account that must be setup prior to the application being used. In the case of Jive, it's possible that a user from a company that you've never worked with before will find your app in the market and install it. Therefore, you should be prepared to provision not only the user, but potentially, a new company account as well. Jive's billing platform and app framework are flexible enough to accommodate most existing models. It just might mean a few conversations with the Jive Apps team and maybe some extra hands on integration work. If you are in a situation where the self service model isn't an exact fit, drop us a note and we'll work with you to figure out the proper integration points.
Understanding the enterprise social graph
One of the things that makes Jive essential to changing the way business is done is the fact that the platform surfaces, and makes available to developers, the enterprise social graph (ESG). It's important not to confuse the enterprise social graph with a simple API layer on top of LDAP or Active Directory. While Jive does expose "traditional" information like the organization chart, the real power is the information that is built up over time as the user interacts wtih the Jive. How you leverage this within your app is the key to making your app truly social and will have a direct result on user adoption.
Who are you?
Most applications have some concept of a user profile. This is typically setup by the user when they come into their account for the first time and involves filling out their name, e-mail, uploading a picture (avatar), etc. When you build a Jive App, you already have profile information available. There is no need to ask the user for this information when you can simply ask Jive for the profile information when you need it. The one exception to this is a user's e-mail address. In Jive, e-mail is known as a "privacy field" and may not be available via the API. Your application logic should never assume that just because you ask for the e-mail address via the API that it's actually returned. Likewise, you should not use the e-mail address as the unique way to identify a Jive App user. In addition to the typical profile fields, you can retrieve other information about the user as well, such as their status level inside of Jive, when the user profile was created, and when it was last updated.
In general, you should not need to store profile information on your home servers because it lives in Jive. The one case where duplicating profile information makes sense is if you allow access to your service from outside the Jive App, e.g. via a web page or mobile device. In this case, you might want to duplicate some of the information from Jive and provide a mechanism in the app for the user to "update" or "sync" with your home server. You should also perform an automatic check periodically to see if anything has changed.
We're all connected to Kevin Bacon...
A big part of the power of Jive is that it understands how people are connected to each other. These relationships manifest themselves in direct ways, e.g. I choose to follow you, and in indirect ways, e.g. we are both part of the same social group.
Jive helps connect people in the organization and break down some of the barriers between groups and people within large companies. A big part of Jive's power is that it understands how people are connected to each other. These relationships manifest themselves in direct ways, e.g. I choose to follow you, and in indirect ways, e.g. we are both part of the same social group. Let's look at the direct relationships.
When Jive is used to improve corporate productivity and collaboration, part of the corporate structure, specifically, the organization chart, is typically made available. Jive surfaces the org chart through the core API. Your application can find the user's manager, everyone that reports to the same manager (colleagues), and their direct reports. While OpenSocial defines a "network distance" parameter, so you can traverse to a specific level of depth on one query, Jive does not support this option.
In addition to the org chart, Jive maintains a distinction between who is following a person and who that person follows (connections). It is also possible to determine bi-directional relationships, i.e. I follow you and you follow me back, through the concept of OpenSocial "friends".
Through these relationships, Jive helps connect people in the organization and break down some of the barriers between groups and people within large companies. How you use these relationships is completely up to your business logic. It's important that you don't make any assumptions about who a person might want to share information or collaborate with. In many cases, collaboration happens outside of the bounds of an explicit relationship. It's for this reason that Jive offers an API and a "People Picker" that allows you to select anyone in the company. A typical pattern is to retrieve who the user is following, or their "friends" and then give them the option, via the people picker, to select anyone.
People are also connected implicitly. A great example of this is belonging to the same social group. Social groups, typically just referred to as "groups", can be set up as part of a formal structure, e.g. "West Coast Sales", or ad-hoc, "Around the Water Cooler". The implied relationship in Jive occurs because two users may not be following each other, but they could both be part of the same group, e.g. "West Coast Sales".
Typically, groups can be setup by any user of the system. They can be open for everyone to participate, members only, private, or secret. The visibility rules also apply to the content in the group, as well as any activity that flows onto the What Matters stream. You can use the OpenSocial API to find all the members of a particular group. Regardless of the kind of relationship, incorporating how people are connected is a key part of making your app more social.
What Matters, not Whatever.... Using the Activity Stream
The metaphor of an activity stream is now well engrained in how people interact with each other. Popularized by the Facebook "wall", it seems that every software package has some stream like interface. Many of these offerings indiscriminately post everything onto the stream. This approach effectively renders the stream useless. Jive recognized the importance of making the stream an important collaboration tool, rather than a register of anything and everything that happened in the system. When designing you application, understanding the actions within Jive that will result in information being placed on the stream will help you determine when to post an activity from your app, send a notification to an individual, or create an action for the user to take.
As a user interacts with Jive, many of the actions they perform will result in an activity being placed onto the activity stream. For example, suppose I create a document in the "Sales Leads" group. The result will be an entry in the activity stream that is visible to everyone in the group, everyone that is following me, and depending on visibility rules, the general activity stream. (Note, this assumes the group is public. If the group has restricted visibility, for example it's a secret group, then my followers who are not part of the group will not see the entry in their stream.)
In Jive, there are three "kinds" of entries that get posted to a user's What Matters stream, Activities, Actions, and Notifications.
The first is the "Activities", represented by the icon on the left. Activities can be thought of as "awareness"--things that are going on in Jive that you are interested in. Notice that there are a number of advanced capabilities that Jive offers to a user, including sophisticated filtering based on "learning" what should be important to the user ("Matters Most"), the ability to "hide" or tune out posts that may not be of immediate interest, and views of only status updates.
Understanding how Jive's What Matters Activities work has a direct impact on the design of your app. Many of the common actions that a user performs will be reflected in the activity stream. Since your application can do these same actions via the API, e.g. create a document, careful consideration needs to be taken when you post an activity. For example, if your app creates a document, an activity will be automatically placed on the stream. Your app should not duplicate this information with a post that, essentially, directs redundant information at the user.
Example: Content Creation, Apps, and What Matters Activities
Gliffy is a great example of creating a document with in Jive. In this end-to-end example, notice that only one activity stream entry is placed on the stream.
Step 1: Create a Gliffy Diagram.
From Gliffy's "Canvas" view, the user creates a new diagram.
Step 2: The What Matters Activity notification
Because Gliffy has chosen to save their diagrams as a documents, Jive automatically posts and activity onto the user's What Matters stream.
Step 3: Opening the document
From the What Matters stream entry, the user can then click on the link and be taken directly to the document. Notice that Gliffy has also included a link back to the application directly in the document content (Edit this diagram in Gliffy). This will allow all users who have visibility to the document to quickly navigate back to the application. It's also one other way in which applications will spread virally throughout an enterprise.
Using Activities: Giving your app a social life
What Matters Activities provide a great way to give "traditional" systems a "social life". In the case of integrating with different, non-social systems, e.g. Jira, the set of users working in them is significantly smaller than the number working in Jive. Placing an activity in the What Matters stream increases the visibility of the user's work and increasing the opportunities for collaboration. Also, Jive will add a link to the application in the activity. When someone clicks on the link, Jive will navigate them to the application in the dashboard or to the app's market listing if they don't have the app installed. Let's look at the Jira for Jive application from AppFusions. This app provides integration with Jira right in the Jive dashboard. Using this app, you can search for issues and create new ones.
When you create an issue using the app, an activity will be placed on the What Matters stream. Notice that when an application creates an activity Jive automatically creates a "deep link" that will take the user back to the application (see "via JIRA in Jive").
Actions & Notifications
While What Matters Activities can be used to bring awareness of things going on in Jive, it is sometimes necessary to target a user directly and ask them to perform a specific action or bring something important to their attention. Jive has extended activity streams to include the concepts of "actions" and "notifications".
Your app can use Jive What Matters to direct the user to take a specific action. Actions entries are listed in a separate tab in Jive. Each action can have up to three "links" that manifest themselves as buttons in the entry. "Action Links" can be used in several ways. First, they can be used to create a "deep link" back to your application. The typical pattern is that when the user clicks on the button, then app will open in canvas view, with the context of the action loaded. In the example below, Andi is using the RoundPegg application to map out her working style. She wants to compare her style with mine, so she has "invited" me to use the app and fill out the profile assessment. RoundPegg has created a simple workflow, based on What Matters Actions to implement invitations to use their app.
Actions are not limited to navigating a user back to the application. Your application can call out to an HTTP endpoint on your home server to invoke an action. These should be signed using 2-legged OAuth (signed fetch) so that you know the user and the Jive instance that originated the request. Jive What Matters Actions are a simple and effective way to add light weight workflow to your application.
Notifications are used to bring a specific user's attention to an important event that has occurred in Jive. Let's look at Rypple as an example of how notifications can be used effectively. Rypple allows users in Jive to "Thank" each other by awarding a "badge". Rypple is creating the new way to perform employee reviews because the recognition provided in the Jive community be used as feedback in the employee review process. In this example, Andi has recognized Mark (me!!) for doing an awesome job with Jive Apps. This shows up in the What Matters Activity Stream.
However, Rypple also will send the receipeint of the badge a notification. This is information that only the targeted user will see. Here is what the entry looks like in the What Matters Notifications stream.
The Jive What Matters activity stream is a powerful tool that your app can use to interact with the user. It's advanced capabilities provide a multitude of options that can bring awareness to your application, target the a user to perform specific actions, and bring attention to important events that have occurred in your app. Even if those events occur outside of Jive, you can post information back to the stream. Using What Matters effectively is a key adoption point for you application. However, there are several overall design considerations that you should be aware of, especially if you are adapting an existing service to work as a social application.
What Matters Notifications & E-Mail
Many existing services use e-mail as the primary means of communicating with users. This is typically because there is no "social container" in which the service runs inside. The user makes a conscious decision to open a browser and navigate to the service. E-mail is really the only way to provide out of band communications with a user. When compared to e-mail, Jive What Matters Notifications offer a more consistent and expected path of communication from the application. This does not imply that you should never use e-mail in conjunction with an app. There are still plenty of valid scenarios where this makes sense. However, you now have there are multiple avenues of communicating with a user, and your app should take holistic approach to ensure the right information is sent at the right time, via the right channel. More often than not, when working with an app, the user will expect communication to flow through the What Matters stream.
Don't "spam" with e-mail
In order to get the app onto their dashboard, the user has gone through the market to install the application. For third party consumer apps, this means there has already been a purchase decision made. The last thing the user wants is unexpected emails appearing in their inbox. Design your app so the user explicitly "opts-in" to receive any e-mail from the application. This is especially true with "freemium" applications. This decision can be recorded with a simple flag in user preferences or an initial configuration flow when the app is installed.
Eat Food. Not too much. Mostly Plants.
Michael Pollan, author of the Omnivore's Dillema once summed up eating healthy as "Eat Food. Not too much. Mostly Plants." [link] Building a truly social app is much more than just simple iFraming of existing Web pages. Understanding the Jive platform, especially What Matters, is fundamental to making thoughtful decisions about how to effectively integrate your application into the platform in a seamless and complimentary manner. Your application, when thoughtfully integrated with Jive, will create a delightful user experience that will truly change the way work gets done in the enterprise. Drawing on inspiration from Mr. Pollan, "Build Apps. Integrate with the Platform. Leverage What Matters."