Alas, it was getting a bit busy on the blog post to cram so much Information so this Post follows on the 2 that were already done.
- Part 1 – Stages, Steps, Loops, and Visio Professional 2013
- Part 2 – Put it all together with HTTP Service Calls via REST and the Dictionary Object/ Variable
This post will look specifically at making those REST API Calls in SharePoint Designer 2013 (SPD2013) on Web Sites “other” than SharePoint i.e. those FREE API’s that are out there. This one will use the Free Weather Online API. You can get an account here and get a Key Just for you 🙂
So..What’s our Story
Well we will endeavor to create a Site Workflow that will run every 24 hours and 5 minutes and display using a Promoted List in SharePoint 2013 the Weather Forecast for the specific Office Location in our Fictitious company. Now, I’ve done a presentation at a SharePoint Saturday or two that discussed creating a Custom Action that would take a parameter (text box field) holding Zip Code so one could customize/personalize this Workflow.
We begin by creating a new Site Workflow
As all good post go, we tell you how to start, so Fire up your SharePoint Designer 2013 and connect to your SharePoint 2013 site, this can be On Prem or in Da Cloud. Click on Workflow then New Site Workflow
Next you Stub out your Workflow, this time you should know all of my bag of tricks now to make life easier so I am including as much as possible here below, if you don’t know or haven’t been following the series, take a look at the other two links in the top of this post.
I now do my magic for the HTTP Call, get the Sub-Set of Data I need and then Iterate through the values
Above is the Fiddler Call I use to inspect my results so I know what to put in my SPD2013 Get Item From Dictionary Action, once you have that bit of information, then the rest, you have seen be do before. So…
Basically we make our HTTP call, put it in our data Sub-Set, and Get each individual element inside our loop, the ONLY thing different in this example is that I am doing a Create List inside the loop to add the current record to my Promoted Link List and you will see that later on below.
Once you invoke the workflow it does its job and remains in a Paused state for 24 hours and 5 minutes then runs again. To the user they will see below if all goes well when they view the list or we can have it as a Web Part or App on a page
So there you go, you are now knighted as SPD2013 Workflow professionals, go thee forth and conquer!
So, my good buddy Chris @givenscj Givens, a really brilliant fellow said that doing this series in Visual Studio would be a benefit. I will take a few days to do that, but I promise I will, need to go back to billable work now 🙂
We hit the FiveFecta with Workflows
Our horse came in, that is SharePoint Designer has given us Five winning items in this iteration of the product, our five items are
- Dictionary Object/Variable
- HTTP Service Calls
With all this you have the means to create atomic unit of work, conditional statements as well as the ability to make external calls to REST-full Service returning JSON data. The last piece of the puzzle is the addition of Visio Professional 2013 and the Stencils it brings to both author and report on the activities of the Workflow Activities.
Purpose of this Blog Post & Primer for this Post
This post well explore various usage scenarios of our Five Fecta through commentary, discussions and demo/screen shots. I am considering breaking this up into sections but perhaps it will just be one big post that covers a single solution, I’m still toying with the idea, either way its genesis is still fluid. If indeed i do break these up, I will put the various parts in this section.
Part 1 – Stages, Steps, Loops, and Visio Professional 2013
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
In the above 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’s new with Workflows
Some things that you must know about Workflows in SharePoint 2013 is that unlike SharePoint 2010 that was built on the platform of Windows Workflow Foundations 3.0 (WWF3) this version of SharePoint is built on Windows Workflow Foundation 4.0 (WWF4) and .NET Framework 4.5, it also employs a new Installer/Manager called Workflow Manager 1.0. Now you have the ability to design and create complete declarative workflows, REST and Service Bus messaging. You should also be aware that the SharePoint 2013 features and capabilities only comes available to you and your tooling after you download and install the Workflow Manger 1.0 Service and configure it to communicate with your Site Collection. For more on the Workflow Manager 1.0 please see Start: Set up and configure SharePoint 2013 Workflow Manager Finally with Visio Professional 2013 add-in provides you with a Visual Workflow Development experience both inside SPD2013 and outside inside Visio Professional 2013.
<RANT>The one thing that I have as a gripe (but I totally understand why) is that Reusable Workflows are GONE in SharePoint 2013 Workflows </RANT>
But that is somewhat disingenuous because while you certainly cannot do it in SharePoint Designer 2013 if you create your workflow in Visual Studio 2013 and make a reference to the Workflow Manager 1.0 you can attach to the GUID of the Content Type.
This is what I mean, open up SPD2013 and fire up a Reusable Workflow and you will notice that you cannot bind a Content Type that you are used to doing in SPD2010 to this Workflow
but if you change the platform to SharePoint 2010 Workflow as seen below you can change the Content Type and make a selection to bind it accordingly.
But lets get back on track.
Stages – What is it, Why do we need it, What Problem does it Solve
Stages are new and introduced into SharePoint Designer 2013 (SPD2013), a stage can accommodate any number of shapes inside Visio and Action/Activities inside SPD2013. There has to be at least one (1) stage in every SharePoint 2013 Workflow and there can only be one path in and one path out of a stage, although while inside the stage they may branch. I will provide a demonstration of that below through a parallel process. You may NOT nest stages, if you want to have nesting capability, you should use a “Step” within a “Stage” in fact it is quite neater for others to follow even from a design standpoint. As you exit a stage, you select what other stage it will transition to, and within that transition step you may also employ conditional logic to determine what path it should take as it exits the current stage. Upon completion of a workflow you should set the transition to End Workflow. Below are some examples of what I just mentioned
Stub out your Stages as a Best Practice
Now as a Object Orientated Developer that is used to Modeling/Prototyping my Classes/Modules, it is just natural for me to see ‘Stages’ in that same fashion, I first consider the ‘Start’ OR ‘End’ of what i need to do and either work forwards or backwards thinking about all the pieces that will make the effort succeed, in the same vein, when I am building a SharePoint Designer 2013 Workflow I pause to consider what my Stages will be, and HOW I will transition between them, that way once I get that thought process out of the way, I am free to just put the logic I need inside my stages and my work becomes so much easier, or at the very least, I have a plan of action that anyone can follow. One more secret about doing it that way is that I can do a Visual Layout of my Stages and take that to a Business Analyst (BA) or Business Decision Maker (BDM) and validate what I am intending to build.
Step 1: Create a Workflow (in this example I am doing a List Workflow)
Once you fill out the necessary fields and click OK, you will be taken into the Active Workflow Design pane, and a Stage will already be present and waiting for your actions.
As denoted in callout 1, we have a default stage created for us, it is called “Stage 1”, but obviously you should change that to something more meaningful, in fact, the names of Stages are by default going to be the Status Messages that you see when your workflow is Running under the Status field in the Document Library or List, so you should think carefully about how you define and layout your stages as well as the nomenclature. This is yet another reason why I elect to stub out my Stages before anything else.
In callout 2, you will see the transition to stage area where you can direct the flow of the workflow, as previously mentioned but worth calling out here:
- there is one way into a stage and one way out
- you may directly tell the stage to progressively move to another stage, or use conditional statements to drive it dynamically or End the Workflow in that area
In callout 3, you will notice Stage is grayed out, but that is because at the point of me taking the screen shot, i was in the active stage and as i mentioned before you cannot NEST stages inside stages therefore the option to create another stage was not provided.
Once you have stubbed out your Stages as I have done below, you will have something similar to what is below, notice I am showing you what a Stage Transition looks like as well as showing you in the “Wrap Up” stage, that the workflow will terminate there.
If we check out our document library we will treat it as a Bank of sorts. We will use a Document Library because it represents a slip of paper that will authorize a transaction, a Credit or Debit, so for instance
We have a Metadata Column that will hold current balance after a Credit or Debit transaction is applied. Coming back to SPD2013 now we have to set up variables to hold these values in order to do our mathematical computations ergo
Looking at Basic and Conditional Stage Transition
Now that we have Variables in place and mind you, we could have just read from the Metadata columns, but I prefer to create variables so i have an assurance of the Data Type I need to use, we will now create some logic to demonstrate how we can transition through stages. I will not go into much detail here because the idea of this exercise is to demonstrate some of the ways you can transition through stages. In the first one we will just move to a different stage, whereas in the second, we will be checking for a condition
In the above figure “1” and “3” are basically logic to take some action or capture some variables from the Current Item, your focus here is Stage Transitions. Notice in “2” we are simply just calling the Stage we need to go to, In “4 ‘we are checking to see first (a) what type of transaction this is, if it is a Debit, then.. does the individual have enough money to do what he/she wants to do, it he/she doesn’t then go to the Stage “IF Crap Hits the Fan” otherwise, if the criteria is met or this is a Credit Transaction, go to “Process Calculation” Stage.
Looking at Internal Mechanics of Stages
So, lets take a look at what can happen inside Stages, for this example we will just look at Parallel Blocks and additional Conditional Logic
So what we have in the above is an example of a Branch in a Stage, we accomplish this by having a Parallel Block  and we have two steps inside that block  which will be run in parallel. You will see proof of that via the Visio Diagram and in the Workflow History Log, and you will notice that what is inside each Step runs in ‘Sequence’ 
Next we will look at how we “Process Calculation” and “Wrap Up” Stages
In the above illustration you will see that we are not doing anything special here that we haven’t done before, we are using conditional logic in both the stage and transition step to determine the path. you will also notice I make heavy use of the Log to History action, I do this to simplify my working area but these steps can be other stages or other actions, for me I am using it to convey messages to you about what is going on.
Below are some examples of what you would expect to see under differing scenarios
Scenario 1 – Add Money to The Account
We will look at the ‘You got Paid’ ledger under the Workflow History
Above you can see that in the log that the current balance was $30, but after crediting $100 it is $130 from the prior image showing the Document Library. Now lets look at a Debit.
Now lets take out more money that they can handle and see what happens in the video below pay attention to the last entry.
Summary on Stages
Hopefully the images and video demonstrates some of what is possible when using Stages in SharePoint Designer for SharePoint 2013 Workflows. If I didn’t already say it, its worth emphasizing that Stage Names become the Status Fields by default in your Library or List being acted upon, but you can also set your own Workflow Status Message.
A more meaningful Look at Steps
So, in the example of Bank of Fabian doing Debits and Credits, you saw “Steps” being used within a Parallel Block, but I want to build on that, and show how steps can really organize your Workflow. In this scenario lets take the approach of “Opening a Bank Account” so we will need to
- Run persons Credit
- Check Source of Initial Funding for Opening of Bank Account
- Run them through ChexSystems
- Verify them against Government Regulatory Checks
- Do a Approval Process for Opening of Account
- Open the Account if they Pass all the Above, Reject if they Don’t
Now off the bat, some of these steps can be done in Parallel; I would say steps 1 through 4 can be done all at once, then we do 5 and then 6, lets look at that
Stubbed out this is what it looks like
Now if we add just a little bit of logic in there it could potentially shape up to be like the below
What does Visio Professional 2013 Bring to the Table
So, thus far we have looked at:
- Internal Mechanics
- Conditional Statements Within
- Overall Organization
- Placement and Usage
Its ample time we look at how this effort looks like Visually in Visio Professional 2013, I cannot overstate how much this is important
to both TDMs, BDMs, and the Developer/Architect. Now you can approach the problem from either end. In one hand you can have a BA or End User mock up a Visio Diagram of what the process should be like and give that to the Dev/Architect, on another hand like I do, i often will stop after I stub out the process and put in the transitions and ASK the BDM’s .. “Is this what you want?” inside the Visio Diagram which is a lot friendlier than SharePoint Designer Text Based Viewer. So based on our examples above lets move forward.
Example 1 – Bank of Fabian
What you have above is the complete process flow of the Workflow in Visio Stencil, now lets dissect it.
In the above you can see how Visio represents the shapes for SharePoint 2013 Workflows and ANYONE can do this, the stencil legend is below
The above represented the Visual Designer View which is all well and good, but there is even a simpler view that you can see that is called the Stage Outline view and that i believe you can take to anyone and they can really understand at a 10000 feet view what is going on, and you as the Developer / Architect can have some assurance you are on the right path.
End of Part 1 Summary
I am actually glad that I have broken this out, because it truly is a lot of content. It is my hope that the above illustrations, video and explanation will help you understand that it is a Brave New World out there for SharePoint Designer 2013 and this is just the scraps of it, Chicken feed, in PART 2 of this Blog, I will use what we have here and really open your eyes up on how you can make a ROBUST process engine that can make External Calls, be “State Machine – esque” and totally be NO CODE where before you certainly had to use CODE or a Third Party Product.
I struggled with the title for this blog; dare i say, after spending almost two days trying to make SharePoint Designer 2013 and Visual Studio 2012 Workflow return data from a few notable providers [YouTube, Twitter, iTunes] using the Dynamic Value / Dictionary Data Type in JSON format, and not being able to as documented, i was frustrated to say the least. I would have been Ok, if it wasnt for the fact that the same exact Logic/Process works for other providers such as [FreeWeatherOnline, etc] returning data in JSON format, the key difference being the structure of the JSON data being returned.
This is for a few SharePoint Community Events that I have been scheduled to present this material. So after beating my head against the wall, sending out S.O.S tweets, and pinging a few folks that are versed on the topic, I ended up doing my Demos with the REST API provider that returns the JSON data in the way that works OOB and documented in both SharePoint Designer 2013 (SPD2013) and Visual Studio 2012 (VS2012). Nevertheless, this was going to haunt me if i cant get it to work, so i went back at it and with the help of Bart @bart_tubalinal Tubalinal who is the self professed and "fabian validated" Pound for Pound Undisputed Developer in the World, we proved out that if you altered the return JSON data from the providers that didn’t work as expected, and then make a call from SPD2013 and VS2012 using the DynamicType / Dictionary variable, it worked as expected.
I will describe the process we used to determine this below…
Below, I will show you three data calls to REST API providers returning in JSON format, showing you both in the browser and in the JSON viewer, I call your attention especially to the JSON viewer and the hierarchy.
Screen clipping: Google YouTube API Above
Screen clipping: FreeWeatherOnline API Above
Screen clipping: Twitter API Above
Screen clipping: YouTube JSON Data Returned Above
Screen clipping: FreeWeatherOnline JSON Data Returned Above
Screen clipping: Twitter JSON Data Returned Above
What we found out is that if you have anything under the Root of the JSON node other than a JSON Array, for example as in the case of a few, the Version Number [returned as a JSON Object], although it works perfectly in a browser, or JSON Viewer, or Fiddler, it doesn’t make the right call when using SPD2013 or VS2012. If after modifying the data output and removing anything that is NOT a JSON Array from the Root of the Node, it should work as expected.
The first thing to prove it out is to have SPD2013 or VS2012 make a call to a URI that returns JSON, so that can easily be accomplished via Visual Studio Project to create a new Site, and then drop a file with the removing anything in the root that is not a JSON Array (Collection) and calling that Web Site from inside for example SPD2013 then it should return the requisite data than can be consumed by the Dictionary Object.
To begin, the first thing we need to do is remove the "appVersion: 2.1" JSON object out of the data returned, below is what is looks like without any adjustment
after you remove it, the raw file looks like below
just to verify, ill put it into a JSON Viewer to make sure it is what i want
then drop that raw file into a text document and place it at the root of the newly created Visual Studio Project Web Site
verify that you can get to it from a browser call
Now, below I will show you WITHOUT adjustment how the FreeWeatherService REST API works right off the bat, you will recall above that the only thing at the JSON root node is the JSON Array. So we put it into SharePoint Designer as below
Screen clipping: See the URI and Process Above
Screen clipping: Above you’ll notice the return data goes to the Dictionary DataType
So after you publish the Site Workflow and run it on the Site, you get what you expect to see below
Screen clipping: SharePoint Promoted Links List with JSON Data Returned
Showing the YouTube Working with the Mods to the Data Set and Without the Mods
So, below you will see how we make a call to the Virtual ASP Visual Studio Site [look at the URI call line you will see it set to localhost and port number]
Screen clipping: SPD2013 WF with the Modded JSON data call Above
After publishing the Site Workflow to the Promoted Links List we can see the output works as expected.
Screen clipping: Promoted Links List showing the Top 10 YouTube Videos displayed with Modded JSON data Call
Now Showing it NOT working as Expected
Below you will see the same code as in the one that worked, except the URI is set to the Google YouTube REST API and no Mods will be done to this data set.
Screen clipping: Above the same Logic/ Process except this call is made directly to the YouTube REST API
Now pay attention to the logging above, you will see that when the Workflows is published and deployed and ran, that the line for the call fails.
Screen clipping: Above is me executing the Site Workflow
Below you will see the Workflow status showing that the process halted
Screen clipping: The Workflow Status showing it didnt work
So, I originally called this a BUG, but for now it is just an observation. Ill be happy to know from our community folks, MVPs, MCMs, and other folks that come across this blog your thoughts. Sadly, I have turned off comments on my blog, but you can always shoot me a tweet at @fabianwilliams
Other Notables but I wont write it up, you can discern yourself
See me making it work in a Custom Action and also Not working using one REST API result that is in the format I said will work, and the other with it not.
Screen clipping taken: 12/31/2012 3:32 PM
Screen clipping taken: 12/31/2012 3:32 PM
Screen clipping taken: 12/31/2012 3:34 PM