​Update 1/8/2016: For the latest info on authoring runbooks in Azure Automation, see this blog post.

Introduction

Thanks to the new Automation service of Microsoft Azure, DevOps are now able to automate their repetitive, time-consuming, and error-prone tasks that span systems and processes to decrease time to value for their Azure operations. The way Azure Automation is able to provide this value is through a concept called runbooks – PowerShell Workflows that contain the logic to automate your IT and business processes. While runbooks can be intimidating at first, with a little training they can be easily mastered. In this blog post, we’ll go into depth on some of the features Azure Automation provides to help you write and use runbooks more effectively, as well as some best practices and common gotchas to help you reach true runbook nirvana. If you don’t have a background in Automation or Automation runbooks already, make sure to take a peek at the Azure Automation //Build Announcement, and the Runbook Concepts article for some introductory info, and then continue on below.  

The Runbook Lifecycle

Before discussing the runbook creation and editing features Azure Automation provides, let’s talk about how to manage runbooks so that you or your colleagues don’t accidently run a work-in-progress runbook in production. Azure Automation runbooks have the concept of “Published” and “Draft” versions. When you create a new runbook, import a runbook, or simply want to make a current production runbook better, the runbook you work with is a “Draft” version. You can work on a runbook draft as much as you like, save it, close the browser, and come back later to work on it some more, all without the worry that your colleague (or your forgetful self) might try to execute it against production resources. Once you’ve determined that the runbook draft is ready for primetime, you publish it, at which point it becomes the version of the runbook that will be executed when this runbook is started from the portal, cmdlets, or from another runbook. One thing to note is that when you publish a draft for a runbook which already had a published version, any runbook job that is already being executed will continue to use the old published version that it was started with, even if that job is suspended and resumed. Only new jobs for this runbook, started after the point of publishing the draft, will use the newly published version so as to not break any existing jobs currently being processed. While Azure Automation does continue to store old published versions of your runbooks behind the scenes in our backend, we don’t currently expose a way to revert your runbooks to an older published version. However, if you really need access to an old published version of a runbook, you can find an old job that used it in the Azure portal, click on the job’s “History” tab, and view the source of the runbook version executed for that job by clicking “View Source.” The screenshot below shows the Runbooks view with runbooks in three states – “New,” “In edit,” and “Published.” “New” means the runbook only has a draft and has no production version (likely you recently created or imported this runbook). “Published” means the runbook has only a production version and no draft version being worked on right now. “In edit” means the runbook has a production version and a draft version that someone is currently working on. Notice how the selected runbook is in “New” state, and so has the “Start” button disabled since it has no published version to run. “Published” or “In edit” runbooks can be started because they have a published version that has been certified as working by a runbook author.   When you drill into a runbook and select the Author tab, notice how you can view both the published and draft versions of a runbook, but you can edit and publish only the draft (screenshots below). If this runbook is started from anywhere other than the “Test” button on the authoring page (ex: started using the “Start” button, started via a schedule, started using the cmdlets, invoked inline as part of another runbook), the published version of the runbook will run.   If your draft runbook uses child runbooks, the published version of these child runbooks will be run even when you execute this draft parent runbook using the “Test” button on the authoring page. For this reason, when you are updating a set of parent / child runbooks and you need to make changes to each of them, as a best practice, update, test, and publish your child runbooks first so that when testing the parent runbook it will use the updated child runbook. Also, since publishing this child runbook draft will cause this newly-published version to be run everywhere this runbook is called, make your child runbooks backwards compatible so they won’t break the existing published version of any runbook calling this child runbook.  

Concurrent Editing

Now you may be asking yourself “But Joe, what if someone else tries to edit my draft runbook while I’m working on it!” Good question. We anticipate multiple users sharing an Azure subscription and Azure Automation account, and did some work to mitigate this problem. While we don’t stop a person from trying to edit a runbook someone else is working on, we clearly display when a runbook is “in edit” on the runbooks view (see first screenshot in this blog post). As a best practice, don’t work on the draft of a runbook that is shown as “in edit” if you are not the person who created the runbook draft, placing it in “in edit” state. Either wait for the runbook to enter “Published” state, which means it has no draft and you can start working on a new version of this runbook, or ask your fellow automators who owns the runbook draft and work with them to either get the updates you need into their draft, or to discard their draft so you can make your updates.  

Runbook Authoring Features

Alright, now let’s open up the authoring page of a runbook and take a look at all the goodies it provides to simplify runbook authoring.   As you can see from the above image, the draft tab of the authoring page is divided into four parts:

1. The editor pane is the area where you author your runbook textually using PowerShell Workflow.
2. The output pane shows the status and output of the last test job for this runbook draft.
3. The command bar provides commands that help with authoring your runbook.
4. The runbook list shows all runbooks in your Automation account, and allows you to navigate between the authoring pages of different runbooks quickly.

Using the authoring page command bar, you have access to the following tasks:

• Manage – If you realize you need a certain asset for your runbook that doesn’t exist yet, this lets you import a module or create a setting, without having to leave the authoring environment.
• Insert – Insert an activity, runbook, or setting into the runbook definition. We’ll talk more about this task later in this post.
• Save – Save the runbook draft so that if you leave the page and come back your latest draft will be available to pick up where you left off.
• Discard Draft – You realize you actually don’t need to update this runbook. Deletes this draft so someone else can work on their own draft of this runbook. Technically, anyone that has access to the Azure subscription containing this Automation account can discard a draft of a runbook, it is not limited to the author of that draft. But you should follow the best practice described earlier in this blog post in the “Concurrent Editing” section, and not go around deleting drafts of runbooks you know you didn’t author.
• Test – Kick off a run of this draft runbook as if it were running in production. This will cause the runbook draft to execute and report output in the output pane. Note that tests aren’t hypothetical, they will actually do whatever the runbook is supposed to do against whatever resources it is running against. For this reason runbook tests should only be run against non-production resources. We’ll talk a bit more about testing later in this post.
• Publish – Certify this runbook as done and working; publish the current draft as the new published version of this runbook.

 

The Runbook Editor

Most of your time on the authoring page will be spent using the editor pane. The editor pane provides a powerful authoring tool built on the Visual Studio Online “Monaco” control. Using this editor, you can write your runbooks in the browser as if you were using the PowerShell ISE. The editor provides PowerShell syntax coloring, automatic indentation, bracket matching, reference highlighting, autocomplete, development keyboard shortcuts, and limited intellisense. Some quick tips on using the editor pane:

• When you start typing, you may notice the word you were typing may be autocompleted by the editor. You can press Tab to cycle through autocomplete options, right arrow to accept the autocompletion, or Ctrl + Space to bring up a list of all autocompletion options where you can scroll through and select the one you want.

• Clicking on a word in your code will highlight every place in your runbook that word is used so you can easily view all references to it.

• You can use keyboard shortcuts like in a regular development environment, including:
  • Find / replace (Ctrl + F)
  • Select all (Ctrl + A)
  • Cut (Ctrl + X)
  • Copy (Ctrl + C)
  • Paste (Ctrl + V
  • Undo (Ctrl + Z)
  • Redo (Ctrl + Y)
  • View all autocomplete options for current word (Ctrl + Space)
• Once you have opened the Find menu with Ctrl + F, you can open the Replace menu by clicking in the grey area to the left of the Find textbox. Press the Enter key to cycle through matches. You can close the Find menu using the Esc key.

  One thing to note is that the intellisense that provides the options shown via autocomplete is aware of only the content in the editor and not PowerShell in general. This means it will only consider code you have already used in this runbook as candidates for potential autocomplete suggestions. For example, if you look at the screenshot above that shows the dropdown autocomplete menu, you can see all of the autocomplete options are previously used in the runbook. Even though PowerShell provides a “Write-Progress” cmdlet that fits the conditions so that it should have shown up in this autocomplete dropdown, it did not, because that cmdlet was not previously used in the runbook. We are working to improve the intelligence of our intellisense for future releases.  

The Output Pane

You will probably also spend a fair amount of time using the output pane. During runbook authoring, it will be common for you to test the contents of your runbook draft using the test button in the command bar. The output pane shows the status of and output from the latest test for this runbook draft. Because the output pane is provided on the same page as the runbook editor, you can start a test and continue authoring while that test runs. Once the test completes, you can view its output and modify your runbook draft as needed, without having to switch pages. And you can expand and collapse the output pane by clicking on the blue bar at the top of the pane so that you see it when you want to, but have more screen space for authoring when you don’t.   We worked to make the output pane look as similar to the PowerShell console as possible. As you can see above, it shows the stream output of the runbook, color coding different streams similarly to how the PowerShell console colors them. You can also stop or suspend the runbook if needed, and resume the runbook if you previously suspended it or if it had an exception causing it to suspend. Just like in the editor pane, clicking in the output pane and pressing Ctrl + F brings up the find menu to help you quickly search for the runbook output you’re looking for. For advanced use of the output pane for testing and troubleshooting your runbook drafts, wait for our upcoming blog post on runbook testing and troubleshooting. Can’t wait? You can read up on Runbook Testing and Troubleshooting for Service Management Automation, which is Azure Automation’s locally-installable counterpart. Since Service Management Automation and Azure Automation are basically the same service, just delivered in two different ways, the content is mostly the same!  

Runbook, Activity, and Setting Discovery and Insertion

Another useful command bar option is “Insert”. In the screenshot below you can see that you can insert a runbook, activity, or setting.   You may be asking yourself, what are all these different words? Assets, settings, activities, cmdlets, integration module, PowerShell module, etc. Before we go on, let’s spend a second clarifying terms. The terms are grouped with similar terms you might confuse them with.

• Asset – A dependency one or more runbooks rely on. This could be an integration module, credential, schedule, connection, certificate, or variable. Look out for Ravi’s blog post coming soon for more information on the different types of assets.
• Setting – An asset that contains one or more pieces of information that are used within a runbook by one or more activities. Credentials, connections, certificates, and variables are settings. The other two asset types – integration modules and schedules, are not.

 

• PowerShell Workflow activity – If you were talking to a pure PowerShell person, by “activity” they mean a PowerShell Workflow activity. PowerShell Workflow activities are different from PowerShell cmdlets in that cmdlets can be called from functions and inline scripts within your runbooks, while PowerShell Workflow activities cannot. In Azure Automation, almost everything you’ll use is implemented as a cmdlet or both a cmdlet and PowerShell Workflow activity, so you won’t need to distinguish between them in use. However, all of the activities in the RunbookConstructs integration module, which are pretty core to runbook development, are implemented as only PowerShell Workflow activities, so they cannot be used within inline scripts or functions within your runbooks. For more information on PowerShell Workflow activities, check out this article by Don Jones. The full list of these Automation-provided PowerShell Workflow activities is as follows:
  • Get-AutomationCertificate
  • Get-AutomationConnection
  • Get-AutomationPSCredential
  • Get-AutomationVariable
  • Set-AutomationVariable
• Azure Automation Activity – A piece of functionality within a runbook. In the context of Azure Automation, when you hear the term “activity” it is referring to a PowerShell cmdlet or PowerShell Workflow activity. The term “activity” originated in System Center Orchestrator, was carried forward to System Center Service Management Automation, and now to Azure Automation.

 

• PowerShell module – A group of PowerShell cmdlets and PowerShell Workflow activities that can be used from PowerShell scripts, workflows, and runbooks.
• Integration module – A PowerShell module which optionally contains a metadata file specifying an Automation connection type to be used with this module’s activities in runbooks. We Azure Automation folks often refer to these as just “modules” for short, since they are basically just PowerShell modules with an optional extra file. The term “Integration module” comes from a combination of the term “Integration Pack” from Orchestrator, and “PowerShell module,” from PowerShell. Look for a blog post sometime soon covering Azure Automation integration modules in detail (or check out the Service Management Automation blog post on this topic which is much the same content).

  Now, back to our insert capability. You can use the “Insert” task to discover all of the runbooks, settings, and activities that can be used in your runbooks, and have the syntax for using them inserted for you to make authoring easier. For example, the following screenshot shows the insert setting wizard, where I have selected a variable named “TestVariable” to add to my runbook. As you can see the description and value of the setting are shown:   Clicking the checkmark will insert the syntax for retrieving this setting at runtime into my runbook, at the current spot of the cursor:   The wizard for inline runbook insertion is similar to the wizard for setting insertion:   However, clicking the next arrow will show you the runbook syntax, to help you decide if this is truly the runbook you meant to use:   When you click the checkbox, the full syntax is inserted into the runbook so you can easily fill in its parameters and call this runbook inline within the runbook you are editing:   Last, but certainly not least, we have the activity insertion wizard, which lets you view all modules in your Azure Automation system, and all activities for the selected module:   While the wizard doesn’t provide a built-in search capability, you can use your browser’s search feature (Ctrl + F) to search for the exact cmdlet you need. This can be done in the setting and runbook insertion wizards as well:   Clicking an activity will bring up its description and help link if they have been specified in the PowerShell module for this cmdlet.   Clicking “View detailed help” will open up the online help page for this cmdlet, which provides lots of juicy details on its use. A small portion of the help page is shown below:   Clicking the next button in the insert activity wizard shows a menu similar to the insert runbook wizard’s syntax view. If there are multiple parameter sets for this activity, you should choose the one you want to use in the runbook, as only the syntax for that parameter set will be inserted.

 

Summary

Hopefully this post has enlightened you on the many useful features Azure Automation provides to help you author great runbooks as quickly and easily as possible, in an environment with multiple runbook authors and operators working concurrently. With this knowledge under your belt, you’re well on your way to becoming an Automation runbook guru! Just getting started with Azure Automation?  Learn about the service here, and follow Azure Automation on Twitter. Want to get in contact with me, personally? Reach out via my blog or follow me on Twitter.