Yammer – SharePoint , beyond the Yammer App for SharePoint – Impersonate Yammer users in SharePoint Workflows

Hi,

If you didn’t read my previous blog posts on integrating Yammer and SharePoint, I encourage you to do so. In this post, we’re going to create a SPO SPD workflow in order send a private message to a Yammer reviewer. We’ll make it as easy as possible to illustrate the impersonation capabilities of Yammer and to highlight some potential business scenarios.

We’ve seen in this post how to retrieve a Yammer Global Admin AccessToken (GAT). Now, we’re going to use that guy from a workflow. As I said in my previous post, it’s better to avoid using GAT in Javascript since it could be easily reversed engineerd by simply debugging the code with the developer tools. So, the best thing to do once you have a GAT, is to use it from a server-side component in order to protect the GAT from being stolen and make sure to use it only on encrypted connections. That said, what we’re going to do as a demo in this blog post is to create a workflow with SharePoint Designer that does the following:

  • Expose an initiation form where the user can input the e-mail of the reviewer
  • In an App Step, read the GAT from a SharePoint list in SPO
  • Get the author Yammer user id using the list item author e-mail
  • Get the author Yammer user AccessToken in order to impersonate him later on
  • Get the reviewer Yammer user id
  • Send a Yammer private message to the Yammer reviewer on behalf of the item author

This scenario is quite basic but shows the important steps. Once you have these basic building blocks, you can start thinking of more complex things. So, let’s get started and perform a few basic steps first:

  • Create a list in SPO
    In SharePoint Online (SPO), create a list called Yammer, give this list unique permissions so that nobody can see it except site collection admins. Add a column to the list that you call AppId. Create an item and set the GAT value to the Title field and your AppId (client id of the yammer app) that you got from the registration process (see my previous post if you don’t know how to do that. The idea here is simply to store the GAT & AppId information in a secured list that can only be accessed by site collection administrators. That’s why we’ll need an App Step in our workflow to read those values.
  • Activate the site (web scope) feature named Workflows can use app permissions. This will ensure our workflow can perform App Steps
  • In SharePoint Designer, create a new list workflow, call it Yammer Review and associate it with a document library of your choice

Let’s see now how this will work from a functional perspective. When a user will start the workflow, he will be prompted to input the e-mail of the reviewer who should be notified via a private message in Yammer :

yammerwf1
The workflow will perform all the steps mentioned earlier and the reviewer will receive a private message in Yammer :
yammerwf3
We could have imagined a more complex workflow that creates a task and sends the link to the task edit form via private message but that wouldn’t have served our purpose here which is simply to demonstrate Yammer related functionailty. For sake of simplicity, I didn’t include error handling in the workflow (what we’ll see right after) but of course, you should do it. The first step of the workflow is to create the initiation form. Once you’ve created your workflow, just click on the Initiation Form Parameters button that’s available in SharePoint Designer. Create a parameter named ReviewerEmail. The first stage of the workflow to retrieve the GAT from our list. We’ll simply use SharePoint’s REST API to do so, the step is divided in several operations:

  • Build a dictionary containing the Accept & Content-Type HTTP headers
  • Call _api/web/lists/YammerList/items(1)?$select=Title,AppId to retrieve the list item that holds the GAT and the App Client Id
  • Extract the GAC and the AppId from the JSON response
  • Log the Token in the history since we are still debugging. This step must of course be removed from a production system to make sure the GAC doesn’t get revealed to end users

To build the dictionary, you just need to type “build” in SD and it will propose the Build a dictionary option. Put the following values into it:
yammerwf4
each key has the value of application/json;odata=verbose, name the dictionary RequestHeaders. Then you can type call to launch the Call HTTP Web Service operation, in the URL, type https://yoursitecollection/_api/web/lists/YammerList/items(1)?$select=Title,AppId. We know that we’ll have only one item in that list and we ask the system to retrieve item ID=1 and to bring back only the Title and AppId properties. Right-click on the call operation ==> properties ==> and assign the previously build dictionary to the RequestHeaders property. Set the ResponseContent property to a new variable that you call OAuthResponseIt’s time to extract the returned token from the response. Just type Get to launch the Get an item from a dictonary operation and input d/Title in the value and chose OAuthResponse as the source dictionary, store the extracted value into a new variable named Token. Do the same for the AppId value and store it in a variable named AppId. Finish by logging the token value to the history list. Overall, you should have something like this:
yammerwf5
Now create another step that you call GetYammerUserId. This step is necessary to retrieve an AccessToken in order to act on behalf the author of the document in Yammer. SharePoint has its own user ids but they don’t mean anything to Yammer. Instead, we can use the e-mail address of the user and ask Yammer to return the corresponding user ID. In order to retrieve an impersonation token from Yammer, it is required to call a specific endpoint the following way:Call tokens.json?consumer_key=yourappid&user_id=targetuserid. If you don’t know what consumer_key is all about, go read my previous blog post. Ok, let’s now build this step:
Start by building a dictionary with the same headers as previously (Accept & Content-Type) but this time, you’ll add an extra header as shown below:
yammerwf6
,name this dictionary YammerHeaders
Call the yammer endpoint the following way:

yammerwf7

and make sure you assign the YammerHeaders dictionary to the corresponding property. Extract and log the user id value as shown below:
yammerwf8
Now, it’s time to get the user token corresponding to the user id we’ve just retrieved. You can directly call the endpoint as follows:

yammerwf9

and assign the YammerHeaders to the headers property. Extract the token value into ImpersonateToken as shown below:

yammerwf10

Now, before being able to send the private message, we first need to retrieve the Yammer user ID of the reviewer using th e-mail address that was passed in the initiation form. Create a stage named GetTargetYammerUserId and call the following endpoint:
yammerwf11

again, you need to associate the YammerHeaders to the Headers property of the web request. Then you can extract the returned user ID ((0)/id) into TargetUserId. Overall, this stage should look like this:

yammerwf12
The final stage is to send the private message to reviewer. This HTTP request is of type POST. You need to build a dictionary that will hold the HTTP POST body with two parameters. These are body and direct_to_id. Build the body key the following way:
yammerwf13
and the direct_to_id like this:
yammerwf14
In the body part, we just include the encoded absolute URL to the document. The parameter direct_to_id refers to the user ID of the reviewer that we extracted earlier. Now, in order to make this request on behalf of the document author, we need to make use of the ImpersonateToken which will become our Bearer to send the message. So, you need to build a new dictionary named SendMessageHeaders with the usual suspects which are Accept and Content-Type plus an Authorization header which has this time the value of :
yammerwf15
Last but not least, it’s time to build the HTTP request itself. Create a call operation to which you assign the SendMessageHeaders of type HTTP POST whose the URL should be https://api.yammer.com/api/v1/messages.json. The full declaration of that call operation is as highlighted below:
yammerwf16
After that, you should be able to save, publish and test your workflow.

Happy Coding!

Advertisements

About Stephane Eyskens

Office 365, Azure PaaS and SharePoint platform expert
This entry was posted in Office 365, SharePoint Online, Yammer and tagged , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s