Azure Automation is continually upgrading its runbook authoring features. In this post, we introduce the latest authoring tools and features that allow you to create sophisticated runbooks either with a graphical authoring model or with a PowerShell script authoring model.

Important Note: For up-to-date information see this new blog post: Azure Automation: Graphical and textual runbook authoring

In Azure Automation in the Azure portal you can author runbooks using a graphical tool and a graphical programming model, with 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 runbooks. In addition, for those who like to author PowerShell Workflow scripts we have updated the textual authoring workspace to give it a larger editing space and new library and testing experiences shared with graphical authoring. The graphical and textual authoring tools are complimentary, and you can use either tool or both depending on your requirements. In this post, I will walk you through the key features of the new authoring experiences and hopefully pique your interest so that you will go give them a try in the new 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 visualize the workflow, the Automation team has released its first cloud-based, graphical runbook editor and graphical programming model for Azure Automation. The new graphical authoring workspace is a full-screen, in-browser experience with four main components:

the library, where your cmdlets, runbooks, and assets can easily be found via browse or search
the canvas, where you build your workflow
the configuration pane, where you configure properties and parameters for each activity and link
the 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 new library you have access to all of the cmdlets, runbooks, and global assets in your Automation account. In addition, we provide some key runbook control activities to help complete the graphical authoring toolkit. 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.
- Organized by module name, then cmdlet name
Runbooks
- These are where you have encapsulated tasks in a 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 throughout your runbook inventory.
- 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.

Graphical Authoring Library

Graphical Authoring Library Detail

Canvas

One of the key features in graphical authoring is the new canvas, located in the center of the authoring workspace, where you build your runbook. The canvas allows you to add and remove activities, move activities around, link activities together, select an activity or link for configuration, select a group of activities and links to move or delete, scroll vertically and horizontally, and zoom in or out (coming soon).

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 tried to make it as simple and intuitive as possible. The basic configurations include the label, which will display 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 leave notes for later reference about how this activity is being used. You can also set the values of the named input parameters for the activity, as well as any additional parameters, such as PowerShell common parameters.

Activity Configuration

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

Activity Configuration Input Parameters

For each parameter, depending on the parameter type, you have a list of data sources to choose from:

Constant value
- You can set a custom value to be used
Activity output
- You can select to use the output of a previous activity in the runbook or a property of the output of a previous activity
Runbook input
- You can select to use one of the runbook input parameters
PowerShell expression
- This option allows you to use the output from any PowerShell script as the input for the parameter
Automation asset: variable, credential, connection, certificate
- You can select to use a pre-defined Automation asset
Empty String
Null

Activity Input Parameter Configuration Data Sources

Activity Input Parameter Configuration Data Source: Activity Output

Link Configuration

For each link in your runbook there are a couple of important configurations you will need to make. You’ll need to decide if a link will be a Pipeline or Sequence type and whether you need to define conditions for data flow across the link. In addition, you’ll want to 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
- If no output from previous activity, then next activity will not run
- Output from previous activity available as individual objects
Sequence link
- Next activity runs exactly once
- Output from previous activity available as an array of objects

One useful configuration you can set on a link is the Condition. Within the Condition expression you set a PowerShell script block that returns true or false. (Coming feature: a UX control to help you build the expression)

Condition evaluates to true
- The downstream activities will run
- The downstream activities will have access to the data from the upstream activities
Condition evaluates to false
- The downstream activities will not run

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, and use a visual editor to create the parameters. You can create as many input parameters as you need, and define the name and type (String, Int32, Int64, Decimal, Boolean, Datetime, Object) for each one. In addition, you can define if a parameter is mandatory or optional, and for some types set a default value if you want. To help with documentation you can provide a description for each parameter.

Configure Runbook Input Parameters

Textual Authoring

For those of you who like to author runbooks using PowerShell Workflow script, we bring you an updated textual authoring workspace that should make your online authoring work easier. Included in this release are a larger editing space, an integrated library, and a more user-friendly test experience – all to help you increase productivity while authoring workflow script.

Larger editing pane

The editing pane still gives you line numbering, context highlighting, and search; however, the big win is the significant increase in the size of the editing window, which now 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 many aspects of the new testing experience. Key features are:

Parameter value input pane that persists values between test runs, so that you don’t have to re-input parameter values with each test
Large test output window with standard PowerShell formatting
Separate window for test job status and exception messages
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
Ability to select to run a test on a hybrid runbook worker

Graphical runbook tests also have activity-level tracing, where the start and end times of each activity are displayed in the test output pane. Soon the input and output objects for each activity will be displayed as well to enable quick debugging.

Test Pane

Graphical and Textual Authoring Models

The graphical and textual authoring models are distinctly 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 need.

Graphical

Visual drag-drop-link-configure authoring model
Focus on how data flows through the process
Can visualize IT processes and systems affected
Higher level language, so could increase productivity
Can include PowerShell script as needed
Familiar to System Center Orchestrator users
Designer is cloud based

Textual

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. This is a Preview release, so we expect there to be some issues still to be worked out; however, we are continually releasing updates to Automation, so you will see the issues disappear over time.

Within the PowerShell expression editors in the graphical 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
```
Understand the difference between Pipeline and Sequence link types.
- Pipeline
  - Output from previous activity available as individual objects
  - 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.
- Sequence
  - Output from previous activity available as an array of objects
  - The next activity runs exactly once
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.
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.

Some known issues
- Test jobs, especially for runbooks that contain child runbooks, can take up to a minute or more to get to running state. This is frustrating, and we are working to improve the start-up performance. 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, the Junction activity can have multiple incoming Sequence links, but at most only one incoming Pipeline link. The issue is that we currently still allow you to hook multiple Pipeline links to a Junction without warning. You will be able to Save and Publish the runbook, but when you try to start the runbook it will fail.
- You cannot run child runbooks in parallel branches. For both graphical and textual runbooks, we discovered unpredictable ouput behavior if child runbooks are run in parallel branches. This is an issue with PowerShell Workflow. Thus, we added a check for graphical runbooks that will fail the runbook at startup, with a useful error message, if this case is present.
- We have not implemented looping/retry on activities yet; but this is high on our list for coming features.

Summary

This has been a quick overview of the new graphical and textual runbook authoring experiences in Azure Automation. The goal of these tools is to enable you to efficiently author runbooks that you use to automate your IT processes. With this Preview release we are offering a rich tool set, and with each subsequent release we will be adding features that increase the value and ease of use. Don't forget that Azure Automation is a single automation portal for all of your cloud (Azure and other) and on-prem IT management. Just getting started with Azure Automation? Learn about the service here, and follow Azure Automation on Twitter.