Using Yammer Open Graph in .NET - Part 1
I've already written about using the Yammer APIs from a .NET client application here: http://blogs.technet.com/b/speschka/archive/2013/10/05/using-the-yammer-api-in-a-net-client-application.aspx. This post is the next logical step in that journey, which is working with Yammer Open Graph items from .NET. A little background is probably in order though, like what is this Yammer Open Graph thing and how or why would I use it? Well, the Open Graph object in Yammer is in many ways kind of analogous to a placeholder representing some URL-addressable content. For example, it could represent a web site, a document in SharePoint, or anything else that you can refer to by Url.
What's cool about Open Graph objects (OGO) is that you can have a full blown discussion associated with them, just like you would a Yammer group. You can also Follow an OGO so you can be alerted to updates on it, and you can Share an OGO too. Within the discussion area for an OGO you can also create all of your typical Yammer content - uploads, polls, praises, events and announcements. Probably the biggest difference between an OGO and a Yammer group is that there isn't the same notion of security - there aren't public and private OGOs and you don't join them: you just choose to follow them or not. Creating OGO also creates an entry in the user's activity stream as well, so they will see that when going to the Yammer home page.
From a data standpoint, what's also interesting about OGO is that they provide a much richer data structure than a typical Yammer group. An OGO allows you to associate the Url I mentioned earlier, as well as an Actor (kind of like who owns this OGO); the OGO is then linked to the Actor's profile in Yammer. Each OG write activity also includes an action - like Create, etc; in practice I've found that the Create and Update actions are the only ones that consistently do "something". You can also associate one or more users with an Activity, which really just means that you can choose to notify them when you apply your OGO action. In addition to the URL you can also provide a title, description and image for the OGO.
So with that bit of background on what an OGO is, let's talk about how one can actually work with it in a .NET application. First, as I mentioned above, you want to start with the the code I included in my original post on using Yammer with .NET that I referenced above; all of my Yammer code just continues to build off of that. I've added some new classes to serialize and deserialize the data for OGO in the sample application, and I've added those classes to the attachment for this post. The object model I built for OGO then looks something like this:
- Open Graph Item
- Type (I use document, but it can be page, place, person, department, team, project, folder, file, document, image, audio, video, or company)
- Users (this is a list of the Actor type above)
To actually create a new OGO then I just create an instance of my OGO .NET class that I described above and start setting properties.
YammerGraphObject go = new YammerGraphObject();
go.Activity.Actor = new YammerActor("Steve Peschka", "email@example.com");
go.Activity.Message = "This is for the new vacation policy document.";
go.Activity.Action = "create";
So I've created the object I'm going to send to Yammer and plugged in the Actor (me!) who will be the contact for it. Now I'm going to add a couple of other people that I want to notify about the new OGO:
go.Activity.Users.Add(new YammerActor("Anne Wallace", "firstname.lastname@example.org"));
go.Activity.Users.Add(new YammerActor("Garth Fort", "email@example.com"));
The next thing I'm going to do is really create the "meat" of the OGO - the content - and then associate it with my OGO:
YammerGraphObjectInstance jo = new YammerGraphObjectInstance();
jo.Url = "https://www.foo.com/vacation.docx";
jo.Title = "Vacation Policy";
jo.Description = "This document details our corporate vacation policy.";
jo.Image = "http://www.travelofix.com/wp-content/uploads/2012/03/vacation.jpg";
jo.Type = "document";
go.Activity.Object = jo;
Now the rest of it is going to be very similar to what I showed in my previous posts. To create the OGO, I need to do a POST to the Yammer REST endpoint. That means I need to create some forms data to send to the endpoint out of my OGO. Fortunately, in my class I override the ToString() method so you can just call that to create your forms data then post it up to Yammer. I also get to reuse the same MakePostRequest method that I created in my original .NET classes for working with Yammer...like this:
string postData = go.ToString();
response = MakePostRequest(postData, graphPostUrl, accessToken, "application/json");
The Url that I'm posting to - "graphPostUrl" - is covered in the Yammer Open Graph documentation, which can be found at http://developer.yammer.com/opengraph/. For OGO that endpoint is https://www.yammer.com/api/v1/activity.json.
With that, you have it - you've just created a new Yammer Open Graph item. In Part 2 I'll explain how to read and create new postings to the newsfeed for the OGO.