So, you have an enterprise SaaS app and Yammer would be the perfect place to integrate. Follow this guide to integrate your app with Yammer and connect to over 10 million verified enterprise cloud users in more than 300,000 companies.
So, you have an enterprise SaaS app and Yammer would be the perfect place to integrate. Follow this guide to integrate your app with Yammer and connect to over 10 million verified enterprise cloud users in more than 300,000 companies.
Before you start implementing your Yammer integration, there are a few things to consider in terms of architecture:
Before you can start integrating with Yammer, you'll need to get yourself a Yammer network. To do that, go to https://www.yammer.com/ and sign up your SaaS company.
Keep in mind that you'll need to use your company e-mail to sign up. This is fine, as you need a Yammer account in order to create your Yammer app.
Follow these instructions on the Yammer site to create an app.
Some tips:
Once you've created your Yammer app, it's time to start thinking about how you're going to integrate.
In Yammer, the main integration point is activities. An activity in Yammer will show up in the activity feed on the sidebar and will update users on what's going on in your SaaS app.
Keep in mind that, although activities are a straightforward way to integrate your app into Yammer, they're not the only way to integrate your app. Yammer has a full-featured REST API that includes a sophisticated messaging system that can be used to great effect (more on that later).
It's important to understand that activities in Yammer revolve around Open Graph (OG) objects. An OG object is used to represent your app's objects inside Yammer. The URL of the OG object acts as its identifier, and you can also use that OG object URL to update your objects in Yammer.
Furthermore, you can post messages to OG objects, which can be a useful integration point for SaaS apps.
In Process.st, we decided that we wanted to represent to push checklists created in Yammer-linked accounts to Yammer. Each time a checklist was started or updated, we wanted that information to appear in the activity feed.
An OG object in Yammer typically has the following fields:
Only the url field is required, and most of the other information can be pulled by Yammer if the URL is publicly accessible.
All checklists in Process.st have a permanent link with the following format:
https://app.process.st/checklists/{{ checklist_id }}
Since it's permanent, it's suitable for the OG object URL.
Since all checklists have names, choosing the title was straightforward.
The description, however, was a bit tricker. Should it be the checklist's template's description? Should it be the template name?
Ultimately, we went with the template name, as every checklist is guaranteed to have one set, and it gives much more valuable contextual information.
Next up, we needed to choose a type. These are the built-in types from the Yammer documentation:
page (default)
place
person
department
team
project
folder
file
document
image
audio
video
company
From my experience, the type doesn't have a huge effect on how Yammer renders your activity, other than the noun used to describe it. Since none of the built-in types were closed enough to a "checklist", we decided to create our own OG type called ps:checklist. It also seems that when you create a new OG object type, all apps (including your development and test apps) can make use of them, so they only need to be defined once, ideally in your production app.
Since there wasn't a natural image for our checklists, so we decided to leave this blank (and have it default to the Process.st logo). However, if our checklists had a cover page, that could've been a good candidate. Another option could've been a generic checklist image.
If you leave the image field blank, it'll show your app icon.
Imagine in Process.st we started a new checklist named "John Smith" using the template "Employee Onboarding". This is an example of the OG object for that checklist in JSON:
{ "url": "https://app.process.st/checklists/uanul6FqWCzqVhRp8aNDiw", "type": "ps:checklist", "title": "Process.st Yammer Integration", "description": "Template: Integrating your SaaS app with Yammer" }
The Yammer documentation heavily pushes the use of activities in Yammer apps. That makes sense, as almost any app has some activity that they can push.
However, if your app has comments or attachments, and these are attached to some sort of object, they're a perfect candidates for integration with the Yammer message system.
The advantages of using Yammer messages over activities (where appropriate) include:
If you do decide to use messages in your integration, keep in mind that by default messages will be posted to "All Company" if no group or user is specified. This is not a good default in most cases, and it is recommended that you add a mechanism that allows users to specify a group to post to.
It is also recommended that when integrating with the Yammer message system that you let the user know somewhere that they will be posting to Yammer as well.
In Process.st, users can post comments to checklists. Since comments are attached to checklists, it seemed to be a natural fit that we model comments as messages in Yammer.
A message in Yammer has the following format:
In addition to the message fields, there are several OG object fields. This is how you associate a message with an OG object.
Consider our example of the onboarding John Smith from before. In that case, the URL for the checklist was:
https://app.process.st/checklists/l1lNS--_hTQle6DEkBtM-A
Now, imagine during the checklist, Cameron posts a comment:
The resulting Yammer form data would be:
body="I think we should use messages to model Process.st comments in Yammer" og_fetch="false" og_url="https://app.process.st/checklists/uanul6FqWCzqVhRp8aNDiw"
And that's it! The message will be attached to the checklist I previously sent to Yammer and to the group "All Company".
Once you've chosen all the integration points for pushing to Yammer, you need to determine what sort of information you can pull from Yammer to give your users a better experience.
In fact, by integrating with Yammer, you are automatically pulling information already: single sign-on (SSO). This is already super handy for Yammer users as that way they don't need to manage two accounts and two passwords.
Beyond that, the most likely integration point for the majority of apps will be autocompletion. The Yammer autocomplete endpoint allows you to ask Yammer for users, groups, topics, etc. that have a given prefix.
Some examples of autocompletion integrations are:
In Process.st, we integrated with Yammer by using their user autocomplete in our invitation flow.
The autocomplete endpoint in Yammer is pretty straightforward. It has the following parameters:
In our particular situation, we simplify sent the the particular email address. So if the user were looking for "[email protected]" and started typing "vic", our query string would look like this:
?prefix=vic&models=user:10
Also, as recommended by the endpoint documentation, we wait for the user to stop typing for at least 500 ms before sending our request and we cache it for 5 minutes. This helps to prevent us from hitting the rate limit.
Now that we've gone over how to design your Yammer integration, here's a checklist to use to make sure you've covered everything (based on this checklist in Yammer's documentation)
Use Yammer as your authentication and identity mechanism. Be sure to have a "Login with Yammer" button on your app's login page.
Once you have authenticated a Yammer user, make sure to push their activity from your app in Yammer’s activity feed.
During your app's invitation process, you should use Yammer’s REST API to identify additional members that can be invited to use your app.
Typically this means using the autocomplete endpoint.
Test your app to make sure it works as expected.
Especially pay attention to the case where multiple Yammer users need to be in the same team in your app.
Add buttons to your website that give the option to login with Yammer.
Yammer requires that all apps have a dedicated Yammer landing page that outlines the benefits of using your app with Yammer.
For example, here is the Process.st + Yammer landing page.
Complete the App Directory Configuration section for your Yammer app.
Submit your app to Yammer for App Directory approval by deploying to Global App Directory. A member of the Yammer platform team will reach out with next steps.