advertisement
KELVERION
RUNBOOK STUDIO
User Guide
Version 1.2
Kelverion Runbook Studio
TABLE OF CONTENTS
Kelverion Runbook Studio 1.2, User Guide 2
Kelverion Runbook Studio
Kelverion Runbook Studio 1.2, User Guide 3
INSTALLATION AND SETUP
Kelverion Runbook Studio
SYSTEM REQUIREMENTS
The Kelverion Runbook Studio has the following system requirements:
Microsoft Windows 8.1, Windows 10, Windows Server 2012 R2 or Windows Server 2016
Microsoft .NET Framework 4.6 or higher
Microsoft Azure Automation Graphical Authoring SDK
Azure Subscription containing one or more Automation Accounts.
50 MB of disk space.
MICROSOFT AZURE AUTOMATION GRAPHICAL SDK
The Microsoft Azure Automation Graphical Authoring SDK enables developers to create and edit
Graphical Runbooks for use with the Azure Automation Service. The Kelverion Runbook Studio uses the Graphical Authoring SDK to integrate with Azure Automation.
The Graphical Authoring SDK is currently not available for redistribution and must be downloaded and installed before you install the Runbook Studio. You can download the Azure Automation
Graphical SDK from
https://www.microsoft.com/en-us/download/details.aspx?id=50734
.
INSTALLING RUNBOOK STUDIO
Once you have determined that your computer satisfies the installation requirements, you can follow these steps to install the Kelverion Runbook Studio on your computer.
1. Launch the Kelverion Runbook Studio installer (Kelverion.RunbookStudio.Installer.msi). The
Kelverion Runbook Studio Setup Wizard appears.
2. Click Next.
3. On the End-User License Agreement page, read the Kelverion License Terms and select I
accept the terms in the License Agreement.
4. Click Next.
5. Click Next to install Runbook Studio to the default folder.
6. Click Install.
7. Click Yes to allow the files to be installed.
8. Click Finish to exit the installer.
RUNBOOK STUDIO LICENSE
When you launch Runbook Studio, you will be asked to provide a valid license file if one has not been provided already.
Kelverion Runbook Studio 1.2, User Guide 4
Kelverion Runbook Studio
To add a new license click Add License and select the license file (*.kasl) that you want to use and then click OK. If the license that you provide is valid, Runbook Studio will continue; otherwise it will close.
If you need to request a new Runbook Studio license, click the Copy button and then paste the copied text into the body of your e-mail message to Kelverion.
If you need to manage your license file(s) at a later date, Runbook Studio stores license files at the following location: C:\Users\<User>\AppData\Local\Kelverion\Runbook Studio.
REGISTERING RUNBOOK STUDIO WITH AZURE
Before you can connect Runbook Studio to Azure you must first register Runbook Studio with your
Azure Active Directory.
DISCOVER YOUR TENANT ID
1. Login into your Azure Portal.
2. Select Active Directory from the resource pane on the left side of the portal. If Active Directory is not available, click Browse.
3. Click Classic Portal at the top of the page.
4. Your Tenant ID is embedded in the URL, which has the format
http://manage.windowsazure.com/<Your Tenant Name>#Workspaces
/ActiveDirectoryExtension/Directory/<Your Tenant ID>/ directoryQuickStart.
5. Record the Tenant ID so that you can enter it in Runbook Studio.
REGISTER KELVERION RUNBOOK STUDIO WITH ACTIVE DIRECTORY
1. Login into your Azure Portal.
2. Select Active Directory from the resource pane on the left side of the portal. If Active Directory is not available, click Browse.
3. Click Classic Portal at the top of the page.
4. Click the Name of the active directory where you want to register Runbook Studio.
5. Click the Applications tab.
6. On the menu at the bottom of the screen, click Add. The Add Application wizard appears.
7. Click Add an application my organization is developing.
8. In the Name box type Kelverion Runbook Studio.
9. For Type select Native Client Application.
10. Click the Next button
Kelverion Runbook Studio 1.2, User Guide 5
Kelverion Runbook Studio
11. In the Redirect URI box, type
http://localhost/runbookstudio
12. Click the Complete button.
13. After the application has been added, click the Configure tab.
14. Record the text in the Client Id box so that you can enter it in Runbook Studio.
15. Under Permissions to other applications click Add application.
16. Select Windows Azure Service Management API and click the Add button.
17. Click the Complete button.
18. Select Windows Azure Service Management and in the Delegated Permissions box, select the
Access Azure Service Management checkbox.
19. Click Save.
1. OOVER
Kelverion Runbook Studio 1.2, User Guide 6
Kelverion Runbook Studio
OVERVIEW OF RUNBOOK STUDIO
Runbook Studio is an on-premises Windows application that provides users with an interactive environment for authoring automation runbooks and for managing content in Azure Automation.
The Runbook Studio is organized into three main areas, the Library Pane, Runbook Canvas and
Properties Pane.
RUNBOOK CANVAS
The Runbook Canvas is where you design and build your runbooks. You can open as many runbooks as you need and quickly switch between them by clicking the appropriate tab at the top of the canvas. File operations, such as Save and Publish Draft are applied to the runbook that is currently being displayed on the canvas.
You add activities from the nodes in the Library and then connect them with links to define the logic of a runbook. When you click on an activity or link on the canvas the properties used to configure the selected runbook element are displayed in the Properties pane. If you click on an empty area of the canvas, the properties used to configure the runbook are displayed in the Properties pane.
When you click on an activity node in the canvas and hold the mouse button down, you can drag the activity, or group of activities, to a new position on the canvas. The position of an activity on the
Kelverion Runbook Studio 1.2, User Guide 7
Kelverion Runbook Studio canvas does not have any effect on its behavior, although it can help to understand its function within the runbook.
When you make changes to a runbook the name displayed in the tab at the top of the canvas will be appended with an asterisk (*) to indicate that you need to save your work. To help ensure that you do not lose any unsaved work, Runbook Studio will prompt you to save your work when you try to close a runbook that has been changed.
ACTIVITY STATUS
To assist with runbook authoring, Runbook Studio provides visual feedback on the status and configuration of the activities in the runbook. For example:
Valid Invalid Valid with Checkpoint enabled
Valid with Retry enabled
In addition, when you hover the cursor over an invalid activity, Runbook Studio will display a tool tip to help you identify and resolve the problem.
LINK STATUS
The runbook canvas also provides visual feedback on the state of the links that connect the activities in your runbook. Valid links are blue and invalid links are red. When you hover the cursor over an invalid link, Runbook Studio will display a tool tip to help you identify and resolve the problem.
Runbook Studio supports pipeline and sequence links, which are discussed in detail in the Activity
Links section of this guide, and they are displayed differently on the runbook canvas. Sequence links end with an Open Arrow, whereas Pipeline links are thicker and end with a Filled Arrow.
Pipeline Link Sequence Link
Kelverion Runbook Studio 1.2, User Guide 8
Kelverion Runbook Studio
Links can also have conditions applied to them and these are displayed differently as well. Links without a condition are drawn with a solid line and links that have a condition are drawn with a
dashed line.
Pipeline Link with
Condition
Sequence Link with
Condition
ZOOM CONTROL
When you hover the cursor over the bottom right corner of the canvas, the zoom control window is displayed. You can zoom out or into the canvas by clicking the minus and plus buttons or by dragging the slider.
You can quickly set the zoom level to 100% by clicking the 1:1 button and you can view the entire runbook by clicking the fit to screen button .
DRAG AND DROP INTERACTION MODES
The Runbook Canvas has two interaction modes, called Pan and Select and you can switch between them by clicking either the Hand or Pointer button on the toolbar.
When Pan is enabled, the cursor changes to a hand . When you click and hold the mouse button in pan mode you can reposition (or pan) the entire runbook canvas. This is helpful when working on large runbooks and you need to reposition the canvas to view a specific area of the runbook.
When Select mode is enabled, the cursor changes to a pointer . When you click and hold the mouse button in select mode you can drag a selection box around a group of runbook elements to select them all. You can then move all of the selected elements together as a single group.
When Select mode is enabled, you can select one or more runbook canvas elements and click the Cut or Copy button in the main toolbar to copy the elements to the clipboard. You can then click the
Paste button to paste the elements in any runbook that is currently open. However, when cutting or copying activities and links from one runbook to another you may have to resolve any runbook resources, such as runbook input parameters, that are not available in the destination runbook.
It is important to note, that when you paste runbook activities into a new runbook, some parameters values, in particular those that use Activity Output or Runbook Input data sources, may no longer be appropriate and as a result will be reset. For example, if one of the activities that is being copied has a parameter that is assigned and Activity Output data source that references an activity that is not being copied then the value assigned to that parameter will be reset.
Kelverion Runbook Studio 1.2, User Guide 9
Kelverion Runbook Studio
LIBRARY PANE
The Library pane is where you select the activities that you add to your runbook and also where you can view and manage the assets in your Azure Automation Accounts. The Library Panel has two tabs, which represent your On-Premises Library and the Azure Library. When you are not connected to
Azure the Azure Library tab is empty.
ON-PREMISES LIBRARY
When Runbook Studio launches, it automatically identifies all of the
PowerShell cmdlets that are available on your computer and organizes them by module in the On-Premises tab of the Library Pane.
If the On-Premises tab does not display a particular cmdlet that you would like to add to your runbook you should ensure that the location of the module that contains the cmdlet is specified in the PSModulePath environment variable.
To quickly find a particular cmdlet or set of related cmdlets, type a keyword in the search box at the top of the On-Premises tab. For example, to find all of the cmdlets in the Azure module type the keyword
Azure in the search box. To clear the search and display all of the available cmdlets, click the X button to the right of the search box.
To add a command activity to your runbook, you can drag and drop the cmdlet from the Library onto the runbook canvas or right click the activity and click Add to Runbook.
AZURE LIBRARY
When you connect to Microsoft Azure, Runbook Studio automatically identifies the available
Automation Accounts and organizes them by Subscription in the Azure tab of the Library pane.
Runbook Studio lets you work with the following types of global assets.
Certificates
Credentials
Connections
Runbooks
Variables
To use an asset in your runbook you can simply drag and drop it onto the runbook canvas.
You can also use the Azure tab to manage the global assets and runbooks in your Automation Accounts. This is particularly helpful when you need to add or edit an asset that is required by the runbook that you are currently building in Runbook Studio.
Kelverion Runbook Studio 1.2, User Guide 10
Kelverion Runbook Studio
Right click on an asset to view the editing options that are available.
Right click on the Certificates, Connections, Credentials or Variables nodes and click Add to add the respective asset type.
You can also open your Azure runbooks in Runbook Studio or download them to your computer.
When you open a runbook from Azure, Runbook Studio opens an on-premises copy of the runbook. If you make changes to an Azure runbook that you opened in Runbook Studio you need to explicitly publish the runbook to make the changes available in Azure.
PROPERTIES PANE
The Properties pane is where you configure the activities in your runbook and the links that connect them. The Properties pane is also where you assign a name to your runbook, and if necessary add input parameters to control the runbook when it runs.
The options that are available on the Properties pane depend on which element, if any, is currently selected on the runbook canvas. For example, when you select a cmdlet activity on the canvas, the Properties pane will display options for selecting a parameter set and for assigning parameter values.
When no runbook elements are selected, the Properties pane will provide you with options that you can use to configure the runbook itself, such as its name, description and input parameters.
The properties pane is organized into tabs, with each tab containing a set of related options. To access the options in a particular tab, simply click the appropriate tab at the bottom of the Properties pane.
Kelverion Runbook Studio 1.2, User Guide 11
CONNECTING TO AZURE
Kelverion Runbook Studio
Runbook Studio lets you build runbooks offline using the resources in your on-premises environment, however at some point you will want to connect Runbook Studio to Azure to access and manage the assets in your automation accounts and to publish your runbooks.
Before you can connect Runbook Studio to Azure you must first provide it with the Tenant ID and
Client ID values that you recorded when you registered Runbook Studio with Azure Active Directory .
To enter this information, click Azure on the main menu and select Setup.
Once this information is provided you can connect Runbook Studio to Azure by clicking Connect on the toolbar. When you have successfully connected to Azure you can select the Azure tab on the
Library pane to access information about the automation accounts in your Azure subscriptions.
Since Runbook Studio provides you with access to all of your automation accounts, you need to specify the Active Automation Account before you can publish a runbook. Also, when an active automation account is specified, Runbook Studio can provide assistance when configuring activities that use global certificate, credential, connection and variable assets.
When you are connected to Azure, you can specify the Active Automation Account by selecting a
Subscription and Account on the main toolbar. Alternatively, you can right click on an automation account in the Azure
Library and click Set as active account.
Kelverion Runbook Studio 1.2, User Guide 12
GRAPHICAL RUNBOOKS
Kelverion Runbook Studio
The Kelverion Runbook Studio provides runbook authors with the tools to build graphical runbooks using facilities that are available in your on-premises environment and then lets you publish your runbooks to any of your Azure Automation Accounts.
All runbooks have the following properties.
Property Description
Name
Runbook Type
A unique name to identify the runbook. Runbook names can only contain letters, numbers, underscores and dashes. The name must begin with a letter
The type of runbook, either Graphical or Graphical PowerShell Workflow.
The former is based on Native PowerShell whereas the latter is based on
PowerShell Workflow.
Description An optional description of the runbook
Input Parameters An optional set of parameters that can be used to invoke the runbook.
You can access the properties for a runbook by clicking Properties in the toolbar or by clicking on an empty area on the runbook canvas.
RUNBOOK FILES
You can create or open as many runbooks as you require and quicly switch between them by clicking the appropriate tab at the top of the runbook canvas.
When you create a new runbook, you have the option to create a Graphical runbook, which is based on native PowerShell, or a Graphical PowerShell Worflow runbook, which is based on PowerShell
Workflow. Each runbook type has advantages and disadvantages so you should carefully consider what type you require as you will not be allowed to change it afterwards.
For example, if your runbook must support checkpoints and the ability to run activities in parallel, then you should choose Graphical PowerShell Workflow. Alternatively, if your runbook will include Code activities that will make use of PowerShell features not supported by PoweShell
Workflow, then you should choose Graphical.
Create a new runbook
On the File menu click New or
On the Ribbon click New or
Press Ctrl + N
Open an existing runbook file
On the File menu click Open or
On the Ribbon click Open or
Press Ctrl + O
Kelverion Runbook Studio 1.2, User Guide 13
Kelverion Runbook Studio
When building your runbooks, you can save your work at any time as a Kelverion Runbook File
(*.Runbook). To help ensure that you do not lose any unsaved work, Runbook Studio will prompt you to save your work when you try to close a runbook that has been changed.
Save a runbook:
On the File menu click Save or
On the Ribbon click Save or
Press Ctrl + S
Save as another file:
On the File menu click Save As or
Press Ctrl + Shift + S
Important: Whether it is a runbook you created from scratch in Runbook Studio or a runbook that you created online in Azure and then opened in Runbook Studio, you should be aware that you are working on an on-premises copy of the runbook, that is not actively connected to any of your runbooks in Azure.
For example, when you right click on a graphical runbook on the Azure library and click Open,
Runbook Studio downloads the runbook's data and creates a new on-premises copy. This copy is not linked to the online version in any way other than that it initially shares the same name. After you have opened an Azure runbook, you can save the runbook as a file on your computer, so that you can edit it locally, or publish a draft to any of your automation accounts.
Important: As the Name property is used to uniquely identify a runbook in an Azure Automation
Account, care should be taken when publishing a runbook to an automation account that is different from the one that you downloaded it from. If you are not careful, it is possible to overwrite an otherwise unrelated runbook that simply shares the same name as the runbook you are trying to publish.
Runbook Studio will warn you when it detects a runbook with the same name as the runbook you are trying to publish and then ask you whether you would like to continue before publishing the runbook to Azure.
RUNBOOK INPUT PARAMETERS
Your runbooks may require input to control their behavior. For example, if you are designing a runbook that needs to start a virtual machine you may need to provide information, such as the name of the virtual machine.
Each runbook input parameter is defined by the following properties.
Property
Name
Description
Type
Mandatory
Default Value
Description
A unique name to identify the input parameter. Runbook parameter names can only contain letters, numbers, underscores and dashes. The name must begin with a letter
An optional description of the parameter's function.
The data type that is expected.
Specifies whether a value must be provided for the parameter.
An optional value that can be assigned to the parameter when one is not provided.
Kelverion Runbook Studio 1.2, User Guide 14
Kelverion Runbook Studio
You can access the input parameters for a runbook by clicking Properties on the toolbar and then selecting Parameters on the Properties pane.
To add an input parameter to the active runbook, select the
Parameters tab and then click Add Parameter.
To edit an input parameter, click the Edit button . To delete an parameter, click the Delete button .
LOGGING AND TRACING
The Logging and Tracing pane contains options that can be enabled to help you diagnose problems with your runbooks. By default, logging and tracing should be disabled to improve performance.
VERBOSE RECORDS
The Verbose message stream contains general information about the operation of a runbook. Since the Debug stream is for interactive sessions and therefore not available to runbooks, you should use the Verbose Stream to report diagnostic information. You can write verbose messages using the
Write-Verbose cmdlet.
To include verbose messages in the job history you must enable the Log verbose records option.
When this option is enabled, all verbose messages will be displayed when you test your runbook in either Runbook Studio or the Azure portal.
PROGRESS RECORDS
When enabled, progress records are included in the job history before and after each activity in the runbook runs. To include progress records in the job history, you must enable the Log progress
records option. Progress records are not stored when you run a published version of your runbook in Azure and not when you test a draft runbook in Runbook Studio or the Azure portal.
ACTIVITY LEVEL TRACING
For graphical runbooks, additional logging is available in the form of activity-level tracing. There are two levels of tracing: Basic and Detailed. Tracing information is written to the Verbose stream, so you must enable Verbose logging when you enable tracing.
When Basic Tracing is enabled, you can see the start and end times of each activity in the runbook as well as information about retries, such as the number of attempts and the start time of each retry attempt. When Detailed Tracing is enabled, you get Basic tracing plus input and output data for each activity,
Kelverion Runbook Studio 1.2, User Guide 15
Kelverion Runbook Studio
TESTING RUNBOOKS
Runbook Studio lets you test the runbooks in your Azure Automation Accounts and view the output that is being generated in real time.
To test a runbook, connect to Azure and then right click on the desired runbook in the Azure
Resources pane and select Test Draft.
To start a runbook test job, select where you want to run the runbook (either on Azure or an available Hybrid Worker) and click the Start button. If your runbook has one or more input parameters you will be provided with a dialog that you can use to provide values for the test job. You must provide a value for all mandatory parameters.
You can suspend, resume or stop a runbook test job by clicking the Suspend, Resume or Stop button respectively. Only one test job can be running at any given time.
The ability to Suspend and Resume test jobs is only supported by runbooks that are based on Native
PowerShell.
The output generated by your runbook as well as logging and tracing messages, if enabled, will be displayed in the Output tab.
Detailed information about the individual output streams can be viewed by clicking the Streams tab.
Kelverion Runbook Studio 1.2, User Guide 16
ACTIVITIES
Kelverion Runbook Studio
Activities are the building blocks that you will use to construct your runbooks. An activity can be to call a PowerShell cmdlet, run a child runbook or execute PowerShell Workflow code.
All activities have the following properties:
Property
Label
Description
Checkpoint
Description
A unique label that identifies the activity in the runbook. Runbook Studio will provide a default name for each activity, but you can provide your own labels to make their role in the runbook more obvious.
An optional description of the activity. Providing a description is a great way to let everyone understand the function of the activity in the runbook.
Indicates whether or not a checkpoint is set in the runbook workflow after the activity runs. Checkpoints are only available for Graphical PowerShell Workflow runbooks.
If the runbook uses Azure cmdlets you should follow best practices and follow a check-pointed activity with an Add-AzureRMAccount in case the runbook is suspended and restarts from this checkpoint on a different worker.
In addition, some activities will also have additional properties, such as:
Discovery options (unique to Kelverion Smart Integration Modules)
Parameter sets
Mandatory and/or optional parameters
Retry options
Once you have added an activity to your runbook you can drag the activity and place it anywhere on the runbook canvas that makes sense to your runbook. Although the location of the activity on the canvas does not affect its behavior, choosing a good location can help express its role and how it is associated with other activities in the runbook.
When you select an activity in the runbook canvas, its properties will be displayed in the Properties pane.
Kelverion Runbook Studio 1.2, User Guide 17
Kelverion Runbook Studio
RETRY BEHAVIOR
Some activity types can be configured to run multiple times until a particular condition, which you specify, is satisfied. You can use the retry behavior options to configure activities that should run multiple times, that are error prone or may need more than one attempt for success.
When you enable retry for an activity, you can configure the runbook to wait a specified number of minutes or seconds before running the activity again. If no delay is specified the runbook will run the activity again, immediately after it completes.
The retry condition lets you specify a PowerShell expression that the runbook will evaluate after each time the activity runs. If the result of the expression is true the activity does not run again, and the runbook moves on to the next child activity in the runbook.
When defining the retry conditions for your activity you can take advantage of a global variable called $RetryData. Specific information about the last time the activity ran can be accessed using the following properties.
Property
NumberOfAttempts
Output
TotalDuration
StartedAt
Description
Number of times that the activity has ran
Output that was generated by the activity the last time that it ran
Time elapsed since the activity was started
Time in UTC when the activity was first started
The following are some examples of activity retry conditions
# Run the activity exactly 5 times
$RetryData.NumberOfAttempts -eq 5
# Run the activity until it produces some output
$RetryData.Output.Count -ge 1
# Run the activity until at least 2 minutes has elapsed
$RetryData.TotalDuration.TotalMinutes -ge 2
Kelverion Runbook Studio 1.2, User Guide 18
Kelverion Runbook Studio
ADDITIONAL PARAMETERS
Some activities also provide you with the ability to specify additional PowerShell workflow parameters that you can use to control the behavior of the activity.
For example, to output detailed information about the operation performed by an activity you would specify -Verbose:$True
ACTIVITY LINKS
Links are used in a runbook to determine the sequence in which the activities in your runbook are executed, and to facilitate the flow of data from one activity to the next.
You can create a link between two activities by hovering the cursor on the bottom of the source activity until it changes to the link cursor and then dragging and dropping the new link to a destination activity.
When adding a link from a command activity, Runbook Studio will check to see if the activity declares an output type. If an output type is declared, then Runbook Studio will add a Pipeline link. Otherwise it will add a Sequence link.
When you select a link on the runbook, Link Properties will be displayed on the Properties pane. All links have the following properties.
Property
Type
Label
Description
Description
When Pipeline is selected the destination activity is run once for each output object that is generated by the source object.
When Sequence is selected the destination activity runs only once and it receives an array of objects containing all of the output objects that were generated by the source activity.
An optional label that will be displayed next to the link on the runbook canvas.
An optional description to help describe the link. Providing a link with a description is especially helpful when the link is conditional.
A graphical runbook will start all activities that do not have an incoming link, and run them in parallel. An activity can be can be the source activity for more than one destination activity, in which case each outgoing link from the source activity will be processed in parallel.
THE DATABUS
Any data that is output by an activity with an outgoing link is written to the runbook's databus. A destination activity can use the databus to access the output from any previous activity in the runbook.
Kelverion Runbook Studio 1.2, User Guide 19
Kelverion Runbook Studio
How the data is written to the databus depends on the type of the outgoing link. If the link is a
pipeline, the output data is added to the data bus as multiple, individual objects. If the link is a
sequence, the output data is added to the databus as a single array of objects.
When a destination activity is connected to a source activity through a pipeline link, you can use the
Activity output data source to assign output from the activity to a specific parameter. When you select the Activity output data source, Runbook Studio will provide you with a list of source activities whose data can be accessed. You can also specify an optional Path to access a specify property of the output object.
Data from the databus can also be used in PowerShell script code, such as the code use to define a link condition, the code used in a PowerShell expression data source or the code used to configure a
Workflow Script activity. When writing script code, the $ActivityOutput global variable can be used to access the output from a previous activity.
The $ActivityOutput variable is a hashtable and you use the label assigned to an activity to access its data. If the output from the activity is an object you can also access a specific property. For example:
$ActivityOutput['Activity Label']
$ActivityOutput['Activity Label'].PropertyName
CONDITIONS
Link conditions let you specify the scenarios for which the activities in a runbook will run. When you specify a link condition, the destination activity will only run if the conditional expression is true.
To add a condition to a link, select the Condition tab, enable Apply condition and then enter a conditional expression in the Condition box.
A link condition must be a valid PowerShell expression that evaluates to true or false. To help build expressions that evaluate the output from source activities you can use the global $ActivityOutput variable. The $ActivityOutput variable is a hashtable and it contains the output from all of the activities leading to the link. To access the output from a specific activity, use the label of the activity whose output you want to retrieve.
For Pipeline links the conditional expression is evaluated for each output object that is generated by the source activity. For example, with a source activity of Get-AzureVM, the following pipeline condition could be used to select virtual machines that are stopped.
$ActivityOutput['Get-AzureVM'].PowerState -eq 'Stopped'
Kelverion Runbook Studio 1.2, User Guide 20
Kelverion Runbook Studio
For Sequence links, the condition is only evaluated once since the source activity generates an array containing all of the outputs that it generated. Sequence links are a good way to test that all of the objects generated by a source activity satisfy a certain condition. For example, with a source activity of Get-AzureVM, the following sequence condition could be used to test whether all of the returned virtual machines are stopped.
$allStopped = $true foreach ($vm in $ActivityOutput['Get-AzureVM'])
{ if ($vm.PowerState -ne 'Stopped')
{
$allStopped = $false
}
}
$allStopped
CYCLES
A cycle is created when a destination activity links back to its source activity or to another activity that eventually links back to its source. Cycles are not currently supported in Azure Automation and
Runbook Studio will let you know when it detects a cycle in your runbook. For example, all of these scenarios are invalid.
WORKING WITH GLOBAL ASSETS
When authoring runbooks you will often find yourself using the global assets that you have defined in Azure Automation. Runbook Studio makes it easy to use the assets from any of your Azure automation accounts in your runbooks.
One way to accomplish this is to simply drag and drop one of the cmdlets from the Orchestrator.AssetManagement.Cmdlets module onto the runbook canvas and then configure its parameters as required.
If you have connected Runbook Studio to Azure, you can also just drag and drop the desired resource from the Azure Library onto your runbook. If you want to set the value of a global variable, right click the variable on the Azure
Library and click Add set variable to canvas.
Kelverion Runbook Studio 1.2, User Guide 21
Kelverion Runbook Studio
For example, you could add a Get-AutomationConnection to you runbook to retrieve a specific global connection and then assign its output to a parameter in a destination activity using the Activity
output data source.
Instead of adding an activity to your runbook to retrieve a global asset, you can simply use one of the global asset data source options that are provided when configuring a parameter.
For example, instead of using the Get-AutomationConnection cmdlet to retrieve a global connection asset you simply select the Connection asset data source and select or type the name of the connection asset that you want to use.
If you have connected Runbook Studio to Azure and selected an automation account as the Active Automation Account, Runbook studio will provide a list of the assets that are available for the data source that you have selected.
PUBLISHING RUNBOOKS TO AZURE
The runbooks you build in Runbook Studio are stored as files on your computer and are not connected to the runbooks in your Azure Automation Accounts. To make your runbooks available to
Azure you must publish a draft copy to an Azure Automation Account.
You can publish drafts of your runbooks to as many automation accounts as you like, but care should be taken to ensure that the cmdlets and assets used by the runbook are available in the automation account that you are publishing too.
The first step in publishing your runbooks is to set the Active
Automation Account, and there are a couple of ways that you can do this. The first is to select the desired Subscription and
Account in the main toolbar and the second is to right click on an automation account in the Azure
Library and click Set as active account.
Once you have set an active automation account, click the Publish Draft button in the toolbar.
If Runbook Studio detects any problems that may prevent the runbook from running in Azure it will display an error report. You must fix all errors before the runbook can be published.
If the Azure Automation Account that you are publishing to already contains a runbook with the same name as the on-premises runbook that you are publishing, Runbook Studio will ask you to confirm that you want to overwrite the runbook in Azure.
Care should be taken to ensure that you are publishing your runbooks to the correct automation account and that you are not accidentally overwriting a runbook with the same
name in another account.
Kelverion Runbook Studio 1.2, User Guide 22
ACTIVITY TYPES
Kelverion Runbook Studio
Runbook Studio supports several different types of activities, and each one has a specific role in the runbooks that you will build.
The activity types supported by Runbook Studio include:
Activity Type
Command Activity
Invoke Runbook Activity
Junction Activity
Smart Activity
Code Activity
Description
Invoke a specific PowerShell cmdlet using parameters that you specify
Invoke another runbook in your automation account, optionally using parameters that you specify
A control activity that waits until all incoming branches have completed
A special type of cmdlet activity that lets you interactively discover the resources in your enterprise environment. Smart activities are unique to Kelverion Smart Integration Modules and Runbook
Studio.
Accepts Native PowerShell for PowerShell Workflow code in order to provide complex functionality that would otherwise not be available
COMMAND ACTIVITY
Command Activities are used when you want to invoke a PowerShell cmdlet in your runbook. Cmdlet activities appear as a rectangle on the runbook canvas.
Runbook Studio automatically provides you with access to the cmdlets that are available on your computer.
The cmdlets that are available in Runbook Studio will likely differ from the cmdlets that have been imported to a particular Azure Automation Account. Consequently, before publishing a runbook to
Azure, you should verify that the automation account that you are targeting contains the required modules and cmdlets.
PARAMETER SETS
Windows PowerShell uses parameter sets to enable a single cmdlet to perform different actions for different scenarios. Each parameter set exposes different mandatory and optional parameters.
All cmdlets have at least one parameter set, and many cmdlets have multiple.
By default, Runbook Studio will automatically select the default parameter set, if one is specified or the first parameter set if one is not.
Kelverion Runbook Studio 1.2, User Guide 23
Kelverion Runbook Studio
To view the parameter sets for a cmdlet activity, select the activity on the canvas and then select the
Parameter Sets tab on the Properties pane.
If the cmdlet is available on your computer, Runbook Studio will display the syntax of the parameter set to help you select which one you require.
The current parameter set determines which parameters you can access. You can change the current parameter set by selecting it in the list, however any parameters that you have already configured will be lost.
PARAMETERS
When you specify a value for a parameter you must select a data source. Depending on the type of data source that is selected you may be provided with additional options. For example, if you select the Activity Output data source you must also select the activity whose output will be assigned to the parameter and optionally the path to a specific property of the output.
You must configure all mandatory parameters. To view the optional parameters that are associated with an activity, click Optional at the top of the Parameters tab.
Several factors determine the data sources that are available to a parameter and these include the parameter's data type, whether it is linked to another activity and whether the runbook has any input parameters.
Runbook studio supports the following data sources.
Data Source
Activity output
Not configured
Certificate asset
Credential asset
Constant
Description
Specify activity whose output will be assigned to the parameter. You may also provide an optional Path to select a specific property of the output objects that are generated by the activity.
Available when the activity is linked to a source activity.
Clears any value that was previously configured. You must configure all mandatory parameters.
Specify the name of the global certificate asset that will be used to provide a value for the parameter.
If you have connected to Azure and selected a Subscription and
Automation Account on the toolbar, the data source will provide the names of the certificates that are available.
Specify the name of the global credential asset that will be used to provide a value for the parameter.
If you have connected to Azure and selected a Subscription and
Automation Account on the toolbar, the data source will provide the names of the credentials that are available.
Specify a constant value to assign to the parameter.
Available for parameters that have the following data types:
Kelverion Runbook Studio 1.2, User Guide 24
Kelverion Runbook Studio
Connection asset
String
DateTime
Boolean
Char
Byte
SByte
Int16
Int32
Int64
UInt16
UInt32
Uint64
Decimal
Double
Float
SwitchParameter
When assigning a constant DateTime value, Runbook Studio assumes the value is in UTC.
Specify the name of the global connection asset that will be used to provide a value for the parameter.
If you have connected to Azure and selected a Subscription and
Automation Account on the toolbar, the data source will provide the names of the connections that are available.
Empty string
Null
An empty string will be assigned to the parameter. Available when the parameter is type System.String
A null ($null) value will be assigned to the parameter. Available when the parameter type is a reference type.
PowerShell expression Specify a simple PowerShell expression whose output will be assigned to the parameter.
You can use variables in the expression to access the output of an activity or a runbook parameter.
Runbook input Specify the name of the runbook input parameter whose value will be assigned to the parameter.
Available when the runbook has one or more input parameters.
Variable asset Specify the name of the global variable asset that will be used to provide a value for the parameter.
If you have connected to Azure and selected a Subscription and
Automation Account on the toolbar, the data source will provide the names of the variables that are available.
INVOKE RUNBOOK ACTIVITY
The Invoke Runbook activity is used to invoke another child runbook. The Invoke
Runbook activity appears as a rounded rectangle when displayed on the runbook canvas.
If the runbook that you want to invoke has parameters, you can access them by selecting
Parameters on the Properties pane. For information about configuring parameters refer to the
Parameters section of the Cmdlet Activity.
Kelverion Runbook Studio 1.2, User Guide 25
Kelverion Runbook Studio
CODE ACTIVITY
The Code activity is a special type of activity that can be used in a runbook to run
PowerShell Workflow code. The Workflow Script activity can be used to provide functionality that would not otherwise be available. The Workflow Script appears as an octagon on the runbook canvas.
You can view and modify the PowerShell Workflow code that will be executed by the activity by selecting the Workflow Script activity on the canvas and then selecting the Code tab on the
Properties pane.
This code executed by a Workflow Script activity is not a complete workflow, but it must contain valid PowerShell Workflow code. Although your script cannot accept parameters, it can use variables for activity output and runbook input parameters. If a Workflow Script activity is linked to another child activity, its output is added to the databus, otherwise it is added to the output of the runbook.
JUNCTION ACTIVITY
A Junction is a special activity that will wait until all incoming branches are completed. This allows a runbook to run multiple activities in parallel and then ensure that they have all completed before continuing. Junction activities appear as a circle with merging arrows in the center.
Junction activities can have many incoming links, however only one incoming link can be a
pipeline. The number of incoming sequence links is not constrained.
SMART ACTIVITY
Smart Activities are a special type of command activity that enable interactive discovery of the resources in your enterprise environment. Smart activities appear as a five-sided polygon on the runbook canvas.
For example, the Insert-SQLRow activity in the Kelverion Integration Module for Microsoft SQL Server, can connect to a selected database in your environment and automatically provide you with the names of the tables that you can modify. Furthermore, when you select a table, Runbook Studio will dynamically generate parameters based on the columns that are in the table that you selected.
When you publish a runbook to Azure, smart activities are converted to Workflow Script activities that contain PowerShell Workflow code that maps the dynamically generated parameters and filters onto the static parameters of the cmdlet that will be invoked by the activity.
Kelverion Runbook Studio 1.2, User Guide 26
Kelverion Runbook Studio
CONNECTING SMART ACTIVITIES TO YOUR ENVIRONMENT
Smart activities need to know how to connect to the systems in your IT environment. You can manage the connections used by the activities in a smart integration module by clicking Connections on the toolbar.
Important: Smart activity connections are not global connection assets, although they may share similar configuration properties. Smart activity connections are used by Runbook Studio to facilitate discovery. If any of the smart activities in your runbook require a connection to your systems when run in Azure, you must create the appropriate global connection assets in Azure and then configure the activities to use them.
When you save a runbook that contains one or more smart activities, the runbook file that is generated will also contain connection information. This will let you open the runbook file on another instance of Runbook Studio where the connection information has not yet been defined.
However, since the runbook file is not secure, sensitive connection information, such as passwords, will be excluded and will have to be re-entered before you can use the runbook.
Alternatively, you can export smart connection information so that it is available to other instances of
Runbook Studio. Smart connection export files are encrypted with a password that you specify and as a result may contain sensitive connection information, such as passwords. When you import a smart connection export file into Runbook Studio, all connection information will be restored exactly as it was originally entered.
EXPORTING SMART CONNECTIONS
1. In the Toolbar click Connections. The Smart Connections dialog is displayed.
2. Highlight the connections you wish to export.
3. Click Export. The Export Smart Connections dialog is displayed.
4. Click the File Path Browse button (...) and select the file you want to create.
5. In the Password box, type a password to encrypt the file.
6. In the Confirm Password box, enter the password again.
7. Click OK.
IMPORTING SMART CONNECTIONS
1. In the Toolbar click Connections. The Smart Connections dialog is displayed.
2. Click Import. The Import Smart Connections dialog is displayed.
3. Click the File Path Browse button (...) and select the file you want to import.
4. In the Password box, type the password that was used to export the file.
5. Optionally, select Overwrite existing connections to override the connection if it already exists.
6. Click OK. The imported smart connections should be displayed in the list.
Kelverion Runbook Studio 1.2, User Guide 27
Kelverion Runbook Studio
DISCOVERY
When you add a Smart Activity to a runbook, Runbook Studio replaces the standard cmdlet activity
Parameter Sets tab, with a special Discovery tab.
At the top of the Discovery tab is a Connection box that lets you select the connection that will be used to connect to the system whose resources you want to discover. For example, this could be a connection to a Microsoft SQL Server Database, a BMC Remedy ARS server or a ServiceNow instance.
After you select a connection, the smart activity will provide you with additional discovery options.
When you have provided values for all discovery options,
Runbook Studio will dynamically populate the Properties and optional Filters tabs with options that you can use to configure the activity.
PARAMETERS
Smart activities dynamically generate parameters by integrating with external systems using the discovery options that you provided and these parameters can be accessed by selecting the
Parameters tab.
For information on configuring parameters refer to the Parameters section of the Cmdlet Activity.
FILTERS
To help you build runbooks that retrieve complex data from external systems, some smart integration modules will provide activities that let you define filters.
If a smart activity supports filters the Activity Properties will include a Filters tab. To add a filter select the Filters tab and click
Add Filter.
To edit a filter, click the Edit button .
To delete a filter, click the Delete button .
When applying multiple filters to the output generated by an activity, only objects that satisfy every filter condition will be included.
OUTPUT PROPERTIES
Data that is generated by an activity with an outgoing link is written to the databus and any destination activity can assign data from the databus to its parameters using the Activity output data source. In many instances you will want to select a specific property of an output object and this
Kelverion Runbook Studio 1.2, User Guide 28
Kelverion Runbook Studio can be difficult if the object contains many properties and/or is a PSObject with dynamically generated properties.
Smart activities make using the databus easier, because they provide
Runbook Studio with the set of output properties that can be accessed based on the discovery options that you entered.
When you use the Activity output data source to assign an output from a smart activity to a parameter, click the down arrow in the Field path box to see the list of properties that are available.
GENERATING POWERSHELL
Kelverion Runbook Studio is primarily focused on helping users build graphical runbooks for Azure
Automation. Furthermore, the advanced discovery features provided by the activities in Kelverion’s catalog of smart integration modules are designed to work with Runbook Studio and as a result they can be difficult to configure when building runbooks in native PowerShell or PowerShell Workflow.
To help users of Service Management Automation use Kelverion’s integration modules in their runbooks, Runbook Studio provides the ability to generate PowerShell code snippets from any activity in your graphical runbook. This is particularly helpful with Kelverion’s Smart activities, because Runbook Studio will automatically handle translating the dynamically generated parameters and/or filters in your activity into the correct PowerShell code needed to invoke the cmdlet.
To generate PowerShell code for an activity, simply right-click the activity and select View PowerShell
Code. Runbook Studio will generate the code required to invoke the activity and then display it in a dialog for you to review.
To use the PowerShell code in Service Management
Automation or a PowerShell editor such as
PowerShell ISE, just click Copy and paste the text into the body of your script.
Kelverion Runbook Studio 1.2, User Guide 29
SENDING FEEDBACK
Kelverion Runbook Studio
If you encounter a problem while working with Runbook Studio or have an idea for making Runbook
Studio even better, we would like to hear from you.
To send feedback to Kelverion, click Send Feedback description of your idea or issue and then click Send. in the toolbar, provide us with a
Alternatively, you can send us an e-mail at [email protected].
We look forward to hearing from you.
Kelverion Runbook Studio 1.2, User Guide 30
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Related manuals
advertisement