Purpose of this Blog Post & Primer for this Post
This post follows up on a previous post below where we discussed Workflows in SharePoint 2013 through the eyes of SharePoint Designer 2013 and Visio Professional 2013. Part 1 is linked below, this is Part 2
In the above post (this one) I will go about showing you the tooling and various simplistic but apropos examples designed solely to drive the usage home, in Part 2 we will use everything in a practical REAL WORLD sense
Part 2 – Put it all together with HTTP Service Calls via REST and the Dictionary Object/ Variable
In this post I will take a Publicly Available REST API probably the Weather API or Twitter API and use the HTTP Web Request along with the Dictionary Variable in SPD 2013 to surface it in a SharePoint Promoted Links App (List)
What is the Dictionary Object/ Variable
Simply put a Dictionary Variable is an Array i.e. a collection of related items that is indexed/indexable but in more detail it is a container designed to hold a collection of other variables which can be of a different data types. Specifically we have the following actions out of Dictionary
- Build Dictionary
- Count Items in a Dictionary
- Get an Item from a Dictionary
Now before we get too deep into The Dictionary Variable/Object, lets take each of these actions one at a time in a simple scheme and see what they do exactly; kick the tires so to speak, in our real world example we will NOT be creating the Dictionary Object as much as consuming JSON data and dumping the JSON data inside a dictionary object. You get it right? JSON data usually comes across as a JSON Array or JSON object, in our case we want that JSON array, even if it is one item, the Dictionary Object/Variable EXPECTS to see an array, I actually wrote a blog post http://fabiangwilliams.wordpress.com/2012/12/31/limitations-when-using-sharepoint-2013-workflows-to-return-json-data/ explaining that issue, which i think is a BUG that should be handled by the SharePoint Team. But lets leave that on one side for the moment and get back into our intended post.
It is ALL explained Here
As mentioned earlier, a Dictionary Object may be considered a collection of related items. Now to drive this point home lets use what we have at our disposal, in fact we will use two (2) examples, the first of which is to simply build on what we did in Part 1 using the Bank of Fabian Example. You see, there are ALOT of post out there that do a good job of explaining to you how to get Weather Data, Twitter Data, ITunes Data, you know all the public REST JSON available stuff, and granted I will do one here as well in example number two in the spirit of being complete. However, what you don’t often see is showing how to use SharePoint own REST OData examples, so I will do one here. Lets set it up for you.
Our Use Case
Now I’m a big believer in Use/Business cases when doing Demos’ and not doing parlor tricks for the sake of “Hey! Look at this cool new stuff I can do”, so The idea here is that
1. You can consume data from ANY SharePoint List as long as you have an account that has permission or an App that does, and then act on or manipulate data from inside your Site Collection [assuming a Site Workflow here]
2. You want to expose data/information to an audience that doesn’t have access to certain data or hosted elsewhere
Web Site: http://adotob.sharepoint.com (this is my Office 365 Dev Site)
List Instance: https://adotob.sharepoint.com/_layouts/15/start.aspx#/Bank%20of%20Fabian
So from the above we can tell that we have a list called …/bank%20of%20fabian and it has currently 5 items inside it yes? Ok, good. Now in order for us to get to that data we can call on our SharePoint oData service located here
Now you should understand that SharePoint 2013 REST APS doesn’t understand the $json options so, it will render its result in XML, however there are quite a few tools out there that can convert your XML to JSON. In fact if you adjust your request header on your call yourself in Fiddler or in browser extension such as Chrome or FireFox, you can get the visual effect you are looking for as well. So lets see what happens when you click on the link here for the REST API call
Now that is NOT going to be useful to us, so I will use this Chrome extension called ChangeHTTPRequest and after putting in my header i need which is
I get the below
Now admittedly that is also difficult to read, so you should invest in the FREE JSON Viewer I always use and its Waaayyy cleaner, just cut and past the entire content and you can see what I mean.
So now that we have established some “Trust but Verify” credibility, next lets look at what we need to do in SharePoint Designer 2013 (SPD2013) to move this forward. We will be Demonstrating the following Capabilities in this Example
- How to use Dictionary Variable/Object
- We will build a Dictionary Variable to hold our HTTP Header information so we can get JSON Data
- We will Count Items in a Dictionary Variable so we can get the “Count” value of all items in there to assist us in our “Loop” that we may iterate through all the items in the Dictionary
- Get Items from the Dictionary that we may use to (as in our case) Write to the Log History so we can see what we are consuming, but in our Part 2 Example coming up using PUBLIC REST JSON data we will use that data to load into a ListItem
- Call a HTTP Web Service
- We will call that webservice we discussed above to get oData back
- We will discuss the other Dictionary Variables we will need in Support of this Call such as our ResponseContent and our subset of Data we want to inspect
- Do a Loop
- We will use the total items count that we got from our “Count Items in a Dictionary” Action as our loop counter max value in our Loop construct
Lets Build out our Workflow
The first thing we will do is create a Site Workflow
So in keeping with “Fabian’s
Best Better Practice” we will stub out our Stages and Get some basic Logic out of the way
Once that is done the first thing we will do is build a Dictionary Variable to hold two items we need in order to get JSON data to be returned; we need to set the Accept and Content-Type HTTP header so the browser knows what we expect. We click Action then under Core Actions you will find Build Dictionary, because I use it a lot it is in my Recent Actions also
Once you click on ‘Build Dictionary’ you will get…
1 – You will then click on ‘this’ which will open up the dialog in  and in turn you will click the Add button. In doing so you will enter two Variables into this Dictionary Variable of String Data Type as aforementioned, in  I am showing you how i do it for the Accept header attribute.
When you are done, click the Ok Button. AND NOW YOU HAVE SEEN HOW TO CREATE A DICTIONARY VARIABLE and an acceptable use of it.
Next we will “Call the HTTP Service” by again clicking Actions in the Ribbon and then…
So again by clicking  ‘this’ we get the dialog box to enter the information about our HTTP REST Service which in this case we click on the ellipse  and put our workflow variable we created earlier that holds our URI, then we click  the OK Button.
Oh… i forgot something, but we can do that now… so you see in the above figure the second line has the (Output to Variable:dictionary) right? so I like to tidy up my Variable name, so what I do is click on the word ‘dictionary’ and create a NEW variable called RequestHeaders 
Now that that is done, we want to further configure the Service Request Call so we will ‘Right Click’ on our ‘Call’ and then Click on Properties..
Then I want to set the “RequestHeaders” Property to my Dictionary Variable “RequestHeaders”
and then click the OK Button.
Next we will need to ALSO create another Dictionary Variable to actually HOLD the data that’s coming back, if I haven’t said it before, that data comes back in the form of a JSON Array and the Dictionary Variable is the only object suitable to accept that data. So
and we name it ‘JSONResults’ so if we inspect the properties again you will see that we have everything we need now to call out to our HTTP Service and get meaningful results back
So now we can actually got GET the DATA now, by using yet another Action in the SPD2013 Ribbon, this time its the ‘Get Item from Dictionary’ Action
Once we do that we will want to click the ‘item by name or path’ link and give it the SUBSET or WHOLE path to the data we inspected in our JSON Viewer or whatever tooling you have to determine what you need. In our case we want the “d/results” subset then we will use the Index variable to get each line item. Furthermore we will want to store this information AS WELL into another Dictionary Variable.
So in  you have me setting the path based on what i want from evidence in the JSON Viewer, then in  I am showing you the relationship of use getting the values from the HTTP Call made earlier and finally  I’m dumping that data into another Dictionary Object.
if you forgot here is what i need to build that path take a look above at , then  to get my Array. In  I will use that below using the Index Variable inside a Loop Construct.
So that brings us to the last unique item we will be doing in our Dictionary Item and that is to get a COUNT of all the items in the Dictionary We Need. So again we go to the SPD2013 ribbon
and we now need to tell the action which Dictionary Item to count, REMEMBER we want the one that we did the Subset of, not the one returned from the Service Call.
Above  we are referencing our Subset Data and we are creating a new Variable of Integer type  to put that Number in. NOW this is an important distinction as well because what we have here is our UPPERBOUND number in the Array for out Loop Counter 🙂 smart huh LOL
Next we will enter the Stage “Loop and Write out our Data we Need” and put a Conditional Loop inside there that will use the Index value of 0 to start and STOP when we have reached the UPPERBOUND value of items in the array
Now when that’s all done, WE are done, one more Screen Shot and some guidance and you can take a mental break..
Now admittedly its a bit busy, and yes, its been hours now since I started on this blog and fatigue is setting in 🙂 but I think i can capture everything I need to say here, and I will wrap up as usual with a video. So we are setting the Initialize and Upper bound of our Loop counter in  and  respectively. In  we are actually going to WRITE OUT TO THE LOG the information garnered from the above two lines and the remainder is the Loop Counter which you saw in Part 1, so now time for the video of it all.
So this blog post is long enough, what I will do for the External Data Call is do it in another Post and I will Link to it here. Hope you learned something new.
Up Next – Addendum to Part 2 showing an External HTTP Service Call using REST/JSON [Hyperlink forthcoming]