Creating Runbooks in Azure and Calling Them from SharePoint Using Webhooks and Flow

Runbooks are a feature of Azure Automation that allow you to execute workflows from within Azure or remotely to automate processes.

To give an example, lets say you have a script that monitors an Azure service every 5 minutes to see if it is running or not. The script, will test and see the status of an Azure App Service. If it tests the site, and does not get the HTTP 200/OK message, then it triggers an alert, creates a ticket, and now someone has to go recycle the Azure App Service. If this can happen frequently, then it is something you would look to automate.

In comes the Azure Automation Runbook. You create a PowerShell script that is hosted in Azure (a Runbook), and when your script detects that the service is not responding, it makes a call out to a URL, and the URL runs the Runbook, which restarts the Azure App Service. The monitoring script then runs again, sees that the service is back up, and the appropriate steps are taken.

This might seem like a lot of extra work, but, if you are, say, connecting in through a VPN to manage an Azure environment, it can be quite time consuming just to restart a service.

However, we are not using that as our working example in this article. That was just to give you an idea of the kinds of things that can be done using Runbooks. In this article, we will be showing you how to create a Runbook, and call it from SharePoint, using Microsoft Flow. It will not be a real exciting example either, but, it will show you how to do all this, so you can do more on your own!

Prerequisites

This article assumes the following:

• You have an Azure subscription. If you do not, you can get one here for free to play around
• You have SharePoint Online

Creating an Azure Automation Account

Before we can create our Runbook, we need to create an Azure Automation Account. Login into the Azure Portal, click on New > Monitoring + Management > Automation

Configure the following settings for your Automation Account:

• Name: What are you going to call it?
• Subscription: Select the subscription to use
• Resource Group: Either create a new one, or, use an existing.
• Location: Which Azure region should this run in? I am using East US 2… since I’m in the East US.
• Create Azure Run As account: This is not needed for our test, but, if you’re doing anything in Azure with your runbooks, you will want to configure this. For more information, visit: https://docs.microsoft.com/en-us/azure/automation/automation-offering-get-started#authentication-planning

Then press Create.

It’ll take a moment while this deploys…

Once done… access it either by the Automation Accounts blade on the left side, or, via the Notifications link Go to resource once its done deploying.

And you will be brought to the landing page for your Automation Account, AutomationTest

Creating an Azure Automation Runbook

Now that we have our Automation Account, we need to create our runbook. From within the Automation Account, click on Runbooks under Process Automation on the left hand side.

Then click Add a runbook at the top of the runbooks dashboard

Click on Quick Create / Create a new runbook

Fill in the details

• Name: Check-Website
  Give your runbook a name
• Type: PowerShell
  You can also choose Python 2, Graphical, PowerShell Workflow, and Graphical PowerShell Workflow
• Description: Check the status of a website
  Enter in a description for the runbook

Then click on Create

And viola! Your runbook has been created!

It doesn’t do anything yet, so, we will need to add code. Click on Edit at the top of the dashboard.

Here is where we will type out, or paste in our PowerShell code for the runbook.

NOTE: Do not use Write-Host, there is no “host” per-say to write to. Instead, ensure all output is written using Write-Output

Let’s add the following code to test if Google is up and running…

Function OutputStatus($type,$status) {
    Write-Output "$type | $status";
}

Function Get-HTTPSStatus($url,$type) {
    $HTTPSStatus = Invoke-WebRequest $url -Method Get –UseBasicParsing
    if ($HTTPSStatus.StatusCode -eq "200") {
        return OutputStatus -type $type -status "Success"
    } else {
        return OutputStatus -type $type -status "Error"
    }
}

Get-HTTPSStatus "http://www.google.com" "Google Website"

Click on Save

Now lets test it…click on Test pane

Click on Start

You will see a message that it is being submitted

You can then see that it gets queued

And finally, we see the status and the output displayed

Pretty neat!

Now, lets say we want to add some parameters to our script, so we can specify the input… and not have it statically set as just “http://www.google.com” as the site, and “Google Website” as the description. Let’s update the code with some parameters…

To get back to your code, click on Edit PowerShell Runbook in the breadcrumb navigation at the top

Update our code with the parameters $Site and $Description, and then Save, and then go back on over to the Test pane

You can now see we have two fields for Site and Description under Parameters. Fill those out…

And run the script again…

Looks good! Now… we can do this all day from within Azure… but remember way back to the start of this article, I mentioned calling this from Microsoft Flow from within SharePoint? To do that… we’re going to need to make a change to our script, as well as create a webhook.

First, lets change our script. You know how we just added parameters? Well, when calling a webhook, we’re going to be making a REST call to a URL. We cannot pass in parameters like we just did to the script. That is good for running within Azure itself… in order to pass parameters to our runbook via a webhook… we need to change the parameters. We will be passing in an object called WebhookData (or whatever else you want to call it). Which will be the JSON data sent along with the REST call. So, let’s update our code to this:

We will then parse out the Site and Description name/value pairs from that and pass it into our script from the $WebhookData object.

The code for the above is here:

Param (
    [object]$WebhookData
)

Function OutputStatus($type,$status) {
    Write-Output "$type | $status";
}

function Get-HTTPStatus($url,$type) {
    $HTTPStatus = Invoke-WebRequest $url -Method Get –UseBasicParsing
    if ($HTTPStatus.StatusCode -eq "200") {
        return OutputStatus -type $type -status "Success"
    } else {
        return OutputStatus -type $type -status "Error"
    }
}

if ($WebhookData -ne $null) {
    Get-HTTPStatus $WebhookData.RequestHeader.Site $WebhookData.RequestHeader.Description
} else {
    Write-Error "No data received in webhook call."
}

We need to Publish it first before creating the webhook. Go back to the code view, and click on Publish

It will prompt you to confirm, click Yes, and it’ll be published.

Now that we’ve got that straightened out… let’s move on to creating our webhook.

Creating a Runbook Webhook

From our runbook Dashboard, click on Webhook at the top of the dashboard

Click on Webhook – Create a new webhook

Then give it a name, and an expiration date, and if it should be enabled or not…

Now… notice the big warning sign at the top of this screen…

See? Now… copy and paste that URL at the bottom, and save it somewhere. There is no way to get this URL once the webhook has been created.

Once you have done that, click OK

Then click on Parameters and run settings and then click OK there

Then click Create at the bottom of the form. Until you do that, you can still get the webhook URL…

Ok… now what? Let’s call it from PowerShell, since we need to do a POST to access it.

We can see in the Content section of the output, we are given a JobId of 4164eb1f-57ba-41c3-a7cb-2f556652e9ad

In our runbook, if we go to Jobs under Resources

We can see that a job successfully ran

Click on it, and we can see the status, and you will see the JobId matches what we got from the call from Invoke-WebRequest

You will see there were errors… because we didn’t actually send any data along with it. We just called it directly. But now that we have it… we can move on to SharePoint and Flow.

Creating a Flow to Call our Webhook from SharePoint

Now that we’ve gone through the meat an potatoes of this project… let’s look at linking at all together with SharePoint and Flow.

Log into your SharePoint Online tenant… and lets create a new list.

I’ve got a basic custom list called Flowtest

Now… once created, in the Modern interface… click on Flow > Create a flow

Click on See your flows at the bottom, because we’re going to create a brandy-new one…

Click on + Create from blank at the top of the page

Click on Search at the bottom of the next screen, and search for SharePoint created… we want to add a trigger for when a new item is created in our list.

Select SharePoint – When an item is created

Select your SharePoint Online site from the list, or, enter in the URL, then select the list… in this case, we’re using Flowtest

Then click + New step > Add an action

Click on HTTP under Connectors

Choose HTTP – HTTP

Then fill out the details…

• Method: POST
• Uri: The URL we copied when we created our webhook
• Headers
  Site: http://www.google.com
  Description: Google’s Website (FROM SHAREPOINT!)

And then click on Save Flow

Also… don’t forget to give your flow a name

You should now see your Flow

Now… open a new window, and go back to your list, and create a new item…

And if you check back on your flows…

You will see one succeeded!

Clicking on it will give you the breakdown of the flow run (which is one of the more awesome features of Flow… over IFTTT IMHO FWIW YK?)

Now… let’s go check Azure…

If we look at the jobs for our Runbook… we’ll see a new one in there…

Click on it, and then click on the output

It worked!

Now… let’s make this a bit more functional. Go back to your list settings in SharePoint

I’ve changed the Title field to URL, and added a field called Description as a single line of text.

Now, let’s go back to our Flow…

And edit the HTTP step

Edit the values for Site and Description, and then select the corresponding Site and Description values from the Dynamic Content list that pops up to the right. See what we’re doing here?

Let’s run our Flow… create a new list item, passing in a URL and Description…

and check the status…

It worked! It’s a day of miracles people! While this is not a really exciting example, it shows how to use Azure Runbooks and Webhooks, and how they can be accessed remotely to do a specific task.

What sort of cool things are you doing or have you done with Flow and Runbooks, if anything?

Resources and References

• Create your Azure free account today
• Get Started with Azure Automation
• Azure Automation User Documentation
• Create an Azure Automation account
• Create an Azure Automation runbook
• Starting an Azure Automation runbook with a webhook
• Runbook input parameters
• Pass a JSON object to an Azure Automation runbook
• Microsoft Flow