As I discussed in the first part of the series, my goal is to find all the sales opportunities in a Site Collection and process them based on their characteristics. To do this I’ve created a Site Workflow – SharePoint 2013 flavor – that makes a set of REST calls to traverse the Site Collection to get the items we want to process.
Figure 1: Simple hierarchy of the SharePoint 2013 Site Collection we’ll work through in this article series. The workflow will run in the management site only.
I’m working in a Site Collection with a fairly simple hierarchy, most of which I inherited. There’s a root site, of course, then a number of subsites – one per business partner – and one subsite for application management (figure 1). The workflow will run in the management site (only Site Owners are allowed in there) and reach out across the rest of the sites in the Site Collection.
Looking at the details of a workflow like this right off the bat is probably a little too detailed, so let’s look at a conceptual picture (figure 2). If you’ve used SPServices or REST calls to traverse sites before, this may not seem too complicated for you. If not, it may look like a nice picture (maybe – the colors are a little much!), but otherwise not make a lot of sense.
Figure 2: Conceptual picture of the workflow we’ll explore in this article series.
The orange boxes represent App Steps. App Steps are only available to us if we give the workflow app permissions, as we did in the previous article. We need the App Steps so that we can make REST calls into sites other than the one where the workflow is running. When I tried to run my workflow without setting up the app permissions, each of the REST calls (now contained in App Steps) failed due to an authorization issue.
Stage: Get Authorization info
The first thing we’re doing is getting a digest token, which amounts to a way to authenticate the workflow when it does writes back to any of the lists. When we read information in the workflow, we don’t need this authentication info, but we do if we want to write anything. I’ve included the step in my workflow because I’m pretty sure I’ll want to be able to update some of the sales opportunities based on their status.
Stage: Get Webs
The next stage is where we make a REST call to retrieve the list of subsites (also known as Webs) that sit directly below the root site of the Site Collection. To do this, I need to make a call to the Webs REST endpoint. This is why we needed to set the workflow up with app permissions at the Site Collection level.
Stage: Process Webs
Once we have the list of subsites we can loop through them to process them.
Loop: Process Web
This loop contains the logic I use to process anything I need within each subsite. In the first few actions in this loop, I parse out the details about each subsite (title, relative URL, etc.) into variables.
Step: Process Opportunities
Using the variables I set up in the beginning of the Process Web loop, I make a REST call into the subsite to see if the Opportunities list is there and has sales opportunities in it that meet our criteria. (For example, we might filter out the opportunities that are already sold.)
Loop: Process Opportunity
If I do get a list of opportunities back from the call above, I process each of the individual opportunities in the Process Opportunity loop. This loop is where the “meat” of the workflow lives. All of the other steps simply exist to get us here so that we can take actions on each of the opportunities that meet whatever criteria we have defined. As the business process gels more (we’re designing it as we build the workflow), we may end up with multiple loops like this. For instance, we could have one loop that sends out emails about opportunities that are late; another loop to alert the sales team about big opportunities of note; and another loop that bumps up the commission percentage based on the quality of the opportunity, etc.
Building and Debugging
Thinking through how your workflow should work at a high level like this is sometimes useful. I’m more of an iterator, though. I tend to build one part of things and test it, then bolt on some more logic and test it, etc.
One thing I’m a huge fan of is emitting some sort of debugging messages along the way. This probably harkens back to the good old days where that was the only debugging technique we really had.
In any case, each of the phases, steps, and loops above emits something into the workflow history list using the Log to History List action (figure 3).
Figure 3: In each step of the workflow, I emit a message into the workflow history list to help with debugging.
As I build up the workflow, having a clear log of what’s happening in the workflow history list is a great debugging tool. Figure 4 shows the kind of thing I tend to do.
Figure 4: Message logs are very handy for debugging as you build the workflow and (later when you forget how it works).
In this case, I can see that I found 15 subsites. Then when I processed the first subsite, I found 3 opportunities to work with. For each opportunity, I can see the customer name (this is test data, of course!), and so on.
The workflow will get more and more complex, but by emitting these messages, I have a fairly decent way to see what’s going on. Debugging these workflows is not a lot of fun – it’s slow going and sometimes hard to see what’s gone wrong – but at least I can look at my log and see where things might have failed.
In the next few articles, we’ll look at each of the phases, steps, and loops I’ve outlined above to see what’s going on in more detail.