• 9 min read

Azure Automation: Graphical and textual runbook authoring

In Azure Automation in the new Azure portal you can author runbooks using graphical or textual authoring experiences.

In Azure Automation in the new Azure portal you can author runbooks using a graphical tool and a graphical programming model, with little or no code required. Simply insert activities from the library to the canvas, link them together into a workflow, and configure the properties in order to create useful runbooks that automate your IT processes.  Users of System Center Orchestrator will be familiar with this intuitive method of creating visual runbooks.

In addition, for those who author native PowerShell or PowerShell Workflow scripts the textual authoring workspace has a large editing pane plus library and testing experiences shared with graphical authoring. The graphical and textual authoring tools are complementary, and you can use either tool or both depending on your requirements.

In this post, I will walk you through the features that highlight the graphical and textual authoring experiences in the Azure portal.

Graphical authoring

For those of you who like to author runbooks with System Center Orchestrator or who prefer an editor where you can build visual workflows intuitively, the Automation team has released its first cloud-based, graphical runbook editor and graphical programming model for Azure Automation.

The graphical authoring workspace is a full-screen, in-browser experience with four main components:

  • Library: Where your cmdlets, runbooks and global assets can easily be found
  • Canvas: Where you build your workflow
  • Configuration pane: Where you configure properties and parameters for each activity and link
  • Test pane: Where you test and debug your runbooks during authoring

Graphical Authoring Workspace

Library

The library, located on the left side of the authoring workspace, contains the activities that you use to build your runbooks. In the library you have access to all of the cmdlets, runbooks, and global assets in your Automation account. In addition, the library provides you with a couple of key runbook control activities to help complete the graphical authoring toolkit. You can browse through the library to find the activity you need, or if you know the name or part of the name of the activity you can search and quickly find it. Simply click on an activity to chose to add it to the canvas.

The items in the library are:

Cmdlets

  • These are the core objects in the library, and are what allow you to manage any service or system that has a REST API and/or PowerShell module.
  • You can import PowerShell modules to the library to extend the number of systems you can integrate with.
  • Organized by module name, then cmdlet name

Runbooks

  • These are where you have encapsulated your custom tasks in a reusable, modular manner that you can use to create higher-level runbooks.
  • Organized by tag (not available yet), plus the “All” category

Assets

  • These are the Automation assets where you store the variables, credentials, connections, and certificates that you use in your runbooks.
  • For all assets you can “Get” the asset value; for variable assets you also can choose to  “Set” the value.
  • Organized by asset type, then asset name.

Runbook control

  • These are special activities provided by Azure Automation to enable important scenarios.

Junction

  • The Junction activity will wait for all incoming branches to finish before continuing to the next activity in the workflow.

Workflow script

  • This is a general-use activity that allows you to insert any PowerShell workflow script into the runbook.
  • It is useful for situations that require custom script; for example, you can configure this activity to contain an InlineScript block.

Authoring Library Cmdlets

 

Authoring Library Detail

 

Authoring Library Search

Canvas

One of the key features in graphical authoring is the authoring canvas, located in the center of the graphical authoring workspace (see the first screenshot above). The canvas is where you assemble the pieces of your runbook.

The canvas allows you to:

  • Add activities
  • Move activities around
  • Link activities together
  • Delete activities and links
  • Select an activity or link for configuration
  • Select a group of activities and links
  • Scroll vertically and horizontally
  • Zoom in or out

Activity configuration

The configuration pane, located on the right side of the graphical authoring workspace, is where you configure each activity and link in your runbook. This is where you will spend a lot of your time when you author a graphical runbook, so we are making it as simple and intuitive as possible.

The basic activity configurations include the label, which will display custom text on the activity in the canvas and which is the unique identifier for the activity in the runbook, and a comment, which you can use to document how this activity is being used.

You can also make these configurations for activities:

  • Set values for the named input parameters for the activity
  • Set values for any additional parameters, such as PowerShell common parameters
  • Retry the activity until some condition is met
  • Checkpoint the runbook after the activity completes

Graphical Runbook Activity Configuration

It is easy to configure the input parameter values for an activity. If an activity has parameter sets, first you select the parameter set you want to work with. Then you configure the parameters that make sense for your use. In the UX you can see the type of each parameter, whether it is mandatory or optional, and if it has a default value.

For each activity input parameter, depending on the parameter type, you can chose from a large list of data sources (see screenshot below):

  • Constant value: Set a custom value to be used.
  • Runbook input: Chose a parameter value that was input to the runbook.
  • Activity output: Select to use the output of a previous activity in the runbook.
  • Asset: Use the value of an Automation variable, credential, connection, or certificate asset.
  • PowerShell expression: This is a flexible option that allows you to use the output from any PowerShell script as the input for the parameter.
  • Empty string or Null: You can even set these as parameter values if you want.

Activity Configuration Data Sources 

Link configuration

For each link that connects activities in your runbook there are key configurations you can make. You can decide if a link will be a Pipeline or Sequence type and also whether you need to define conditions for data flow across the link. In addition, you can leave a comment for later reference.

The type of link you choose is very important, because the link type affects how activity output data is made available and also how output from the previous activity will affect the actions of the next activity.

Pipeline link

  • Next activity runs once for each output object from previous activity
  • If no output from previous activity, then next activity will not run
  • Output from previous activity available as individual objects

Sequence link

  • Next activity always runs exactly once
  • Output from previous activity available as an array of objects

Another useful configuration you can set on a link is the Condition. Within the Condition expression you write a PowerShell script statement that returns true or false.

  • If the condition evaluates to true:
    • The downstream activity will run
    • The downstream activity will have access to the data from the upstream activities
  • If the condition evaluates to false:
    • The downstream activity will not run

By default, if you do not set any link condition, the link will act the same as if it has a condition that evaluates to true.

Graphical Link Configuration

Runbook input parameters

When you are ready to define the input parameters for a runbook, you can click Input and output in the top command bar. For each input parameter you can define the name and type (string, int32, int64, decimal, Boolean, datetime, or object) for each one. In addition, you can define if a parameter is mandatory or optional, and set a default value.  To help with documentation you can provide a description for each parameter.

Graphical Runbook Input Parameters

Textual authoring

For those of you who like to author runbooks using PowerShell or PowerShell Workflow script, Azure Automation has a textual authoring workspace that helps you with your online authoring work. Included are a large editing pane, an integrated library of cmdlets, runbooks and assets in addition to an integrated test experience.

Editing pane

The editing pane gives you line numbering, context highlighting, some intellisense, and search in a large editing window which allows you to see more of your script without scrolling.

Textual Authoring Workspace

Library

The textual authoring workspace shares the library component with graphical authoring. From the library you can find the cmdlets, runbooks, and assets that you have in your system, and you can then  insert the ones you need into the textual editor.

Testing experience

Graphical and textual authoring share similar testing experiences. Key features are:

  • Parameter value input pane that persists values between test runs, when you keep the test window open, so you don’t have to re-input parameter values with each test.
  • Large test output window with standard PowerShell formatting
  • Color-coding of workflow data streams: Output, Verbose, Warning, Error
  • Tests continue even if the test blade is closed; and the output state is maintained with you re-open the blade.
  • Start, Stop, Suspend, Resume commands
  • Option to run the test in Azure or on your hybrid runbook worker

Graphical authoring also gives you the option of enabling activity-level tracing (set in the runbook configuration) to display the start time, end time, input data, and output data for each activity to help you troubleshoot runbook issues.

Authoring Test Pane

 

Tracing in Graphical Runbook Test

Graphical and textual authoring models

The graphical and textual authoring models are different, each with important characteristics that I list below. Some of you will prefer one over the other, and some will take advantage of both depending on the scenario. In general, Graphical Runbooks are ideal for high-level processes where you want to tie together several specific activities and be able to visualize the workflow. Textual runbooks (PowerShell Runbooks and PowerShell Workflow Runbooks) are useful for working with details of the PowerShell language.

Graphical

  • Visual insert-link-configure authoring model
  • Focus on how data flows through the process
  • Visualize IT processes and systems affected
  • Higher level language to increase productivity
  • Include PowerShell script as needed
  • Familiar to System Center Orchestrator users
  • Designer is cloud-based

Textual

  • PowerShell or PowerShell Workflow script authoring model
  • Lower-level language, so more versatile
  • Can use existing PowerShell scripts
  • Familiar to PowerShell users
  • Designer is cloud based or client (ISE)

Things you should know

Below are some useful tips and known issues. We are continually releasing updates to Automation, so you will see the issues disappear over time.

Tips

  • Within the PowerShell expression editors in the graphical authoring experience you can reference the output of previous activities like this:
    $ActivityOutput[‘activity label’]
    $ActivityOutput[‘activity label’].Property1
    
  • Similarly, you can reference runbook input parameters like this:
    $InputParameterName
  • In graphical authoring it is important to understand the difference between Pipeline and Sequence link types.
    • Pipeline
      • The next activity runs once for each object output from the previous activity. If the previous activity produces no output, then the next activity does not run.
      • Output from previous activity available as individual objects
    • Sequence
      • The next activity runs exactly once
      • Output from previous activity available as an array of objects
  • The output for a graphical runbook is the output from the last activity in the runbook. This behavior differs from that for textual runbooks where runbook output can come from any activity in the runbook.

Issues

  • Jobs for PowerShell-Workflow-based runbooks that contain child runbooks, can take minutes to get to running state. This is an issue with how PowerShell Workflow compiles runbooks before execution. For textual runbooks you can avoid this by creating native PowerShell runbooks; for graphical runbooks we are working on a fix. None of the job start-up time is included in your Automation usage and bill, only the time that the job is actually in running state.
  • By design in graphical runbooks the Junction activity can have multiple incoming Sequence links but at most only one incoming Pipeline link. However, in the canvas currently you are able to hook multiple Pipeline links to a Junction without getting a warning at design time. We are working on giving you the warning at design time.
  • You cannot run child runbooks in parallel branches. For any PowerShell-Workflow-based runbook, we discovered unpredictable output behavior if a child runbook is run in parallel with another child runbook, cmdlet, or activity. This is an issue with PowerShell Workflow, not Automation. Thus, for now, to help you with authoring we added a check in graphical runbooks that will fail the runbook at startup, with useful error message, if this case is present.
  • During authoring, when you modify runbook input parameter definitions and then want to test the change, you need to save the draft and close and re-open the test pane to assure that the modified parameters appear in the test pane.

Summary

This has been a quick overview of the graphical and textual runbook authoring experiences in Azure Automation in the new Azure portal. These tools enable you to efficiently author runbooks that you use to automate processes. The Automation team is continuing to improve the authoring experiences with new features that increase the value and ease of use.

Remember, Azure Automation is a single automation portal for all of your cloud (Azure, AWS, and other) and on-premises IT management.

Just getting started with Azure Automation? Learn about the service here, and follow Azure Automation on Twitter.