Document Details

## Schedule a runbook in the Azure portal When your runbook has been published, you can schedule it for operation: 1. In the Azure portal, search for and select **Automation Accounts**. 1. On the **Automation Accounts** page, select your Automation account from the list. 1. Select the runbook from your list of runbooks. 1. Select **Schedules** under **Resources**. 1. Select **Add a schedule**. 1. In the **Schedule Runbook** pane, select **Link a schedule to your runbook**. 1. Choose **Create a new schedule** in the **Schedule** pane. 1. Enter a name, description, and other parameters in the **New schedule** pane. 1. Once the schedule is created, highlight it and click **OK**. It should now be linked to your runbook. 1. Look for an email in your mailbox to notify you of the runbook status. ## Restore deleted runbook You can recover a deleted runbook through PowerShell scripts. To recover a runbook, ensure that the following conditions are met: - The runbooks to be restored were deleted in the past 29 days. - The Automation account for that runbook exists. - The *Automation Contributor* role permission is granted to the System-assigned managed identity of the Automation account. ### PowerShell script - Execute the PowerShell script as a job in your Automation account to restore the deleted runbooks. - Download the PowerShell [script](https://github.com/azureautomation/Restore-Runbook) from GitHub. Alternatively, you can [import](#import-a-runbook-from-the-azure-portal) the PowerShell script named *Restore Automation runbook* from Runbook Gallery. Provide the name of the runbook that is to be restored and run it as a job in Azure Automation to restore the deleted runbooks. - Download the [script](https://github.com/azureautomation/List-Deleted-Runbooks) from GitHub or [import](#import-a-runbook-from-the-azure-portal) the PowerShell script named *List Deleted Automation Runbook* from Runbook Gallery, to identify the names of the runbooks that were deleted in last 29 days. ## Obtain job statuses ### View statuses in the Azure portal Details of job handling in Azure Automation are provided in [Jobs](automation-runbook-execution.md#jobs). When you are ready to see your runbook jobs, use Azure portal and access your Automation account. On the right, you can see a summary of all the runbook jobs in **Job Statistics**.  The summary displays a count and graphical representation of the job status for each job executed. Clicking the tile presents the Jobs page, which includes a summarized list of all jobs executed. This page shows the status, runbook name, start time, and completion time for each job. :::image type="content" source="./media/manage-runbooks/automation-account-jobs-status-blade.png" alt-text="Screenshot of the Jobs page."::: You can filter the list of jobs by selecting **Filter jobs**. Filter on a specific runbook, job status, or a choice from the dropdown list, and provide the time range for the search.  Alternatively, you can view job summary details for a specific runbook by selecting that runbook from the Runbooks page in your Automation account and then selecting **Jobs**. This action presents the Jobs page. From here, you can click a job record to view its details and output. :::image type="content" source="./media/manage-runbooks/automation-runbook-job-summary-blade.png" alt-text="Screenshot of the Jobs page with the Errors button highlighted."::: ### Retrieve job statuses using PowerShell Use the [Get-AzAutomationJob](/powershell/module/Az.Automation/Get-AzAutomationJob) cmdlet to retrieve the jobs created for a runbook and the details of a particular job. If you start a runbook using `Start-AzAutomationRunbook`, it returns the resulting job. Use [Get-AzAutomationJobOutput](/powershell/module/Az.Automation/Get-AzAutomationJobOutput) to retrieve job output. The following example gets the last job for a sample runbook and displays its status, the values provided for the runbook parameters, and the job output.

If you want the runbook to execute with the system-assigned managed identity, leave the code as-is. If you prefer to use a user-assigned managed identity, then: 1. From line 5, remove `$AzureContext = (Connect-AzAccount -Identity).context`, 1. Replace it with `$AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context`, and 1. Enter the Client ID. > [!NOTE] > For PowerShell 7.2 hybrid jobs, make changes in line 28. Replace `$PSPrivateMetadata.JobId.Guid` with `$env:PSPrivateMetaData`. ## Handle transient errors in a time-dependent script Your runbooks must be robust and capable of handling [errors](automation-runbook-execution.md#errors), including transient errors that can cause them to restart or fail. If a runbook fails, Azure Automation retries it. If your runbook normally runs within a time constraint, have the script implement logic to check the execution time. This check ensures the running of operations such as startup, shutdown, or scale-out only during specific times. > [!NOTE] > The local time on the Azure sandbox process is set to UTC. Calculations for date and time in your runbooks must take this fact into consideration. ## Retry logic in runbook to avoid transient failures Runbooks often make calls to remote systems such as Azure via ARM, Azure Resource Graph, SQL services and other web services. When the system that the runbooks are calling is busy, temporary unavailable or implementing throttling under load, the calls are vulnerable to have runtime errors. To build resiliency in the runbooks, you must implement retry logic when making the calls so that the runbooks can handle a transient problem without failing. For more information, refer [Retry pattern](/azure/architecture/patterns/retry) and [General REST and retry guidelines](/azure/architecture/best-practices/retry-service-specific#general-rest-and-retry-guidelines). ### Example 1: If your runbook makes only one or two calls

## Import a runbook You can import a PowerShell or PowerShell Workflow (**.ps1**) script, a graphical runbook (**.graphrunbook**), or a Python 2 or Python 3 script (**.py**) to make your own runbook. You specify the [type of runbook](automation-runbook-types.md) that is created during import, taking into account the following considerations. * You can import a **.ps1** file that doesn't contain a workflow into either a [PowerShell runbook](automation-runbook-types.md#powershell-runbooks) or a [PowerShell Workflow runbook](automation-runbook-types.md#powershell-workflow-runbooks). If you import it into a PowerShell Workflow runbook, it is converted to a workflow. In this case, comments are included in the runbook to describe the changes made. * You can import only a **.ps1** file containing a PowerShell Workflow into a [PowerShell Workflow runbook](automation-runbook-types.md#powershell-workflow-runbooks). If the file contains multiple PowerShell workflows, the import fails. You have to save each workflow to its own file and import each separately. * Do not import a **.ps1** file containing a PowerShell Workflow into a [PowerShell runbook](automation-runbook-types.md#powershell-runbooks), as the PowerShell script engine can't recognize it. * Only import a **.graphrunbook** file into a new [graphical runbook](automation-runbook-types.md#graphical-runbooks). ### Import a runbook from the Azure portal You can use the following procedure to import a script file into Azure Automation. > [!NOTE] > You can only import a **.ps1** file into a PowerShell Workflow runbook using the portal. 1. In the Azure portal, search for and select **Automation Accounts**. 1. On the **Automation Accounts** page, select your Automation account from the list. 1. From the Automation account, select **Runbooks** under **Process Automation** to open the list of runbooks. 1. Click **Import a runbook**. You can select either of the following options: 1. **Browse for file** - selects a file from your local machine. 1. **Browse from Gallery** - You can browse and select an existing runbook from gallery. 1. Select the file. 1. If the **Name** field is enabled, you have the option of changing the runbook name. The name must start with a letter and can contain letters, numbers, underscores, and dashes. 1. The [**Runbook type**](automation-runbook-types.md) is automatically populated, but you can change the type after taking the applicable restrictions into account. 1. The **Runtime version** is either auto-populated or pick the version from the drop-down list. 1. Click **Import**. The new runbook appears in the list of runbooks for the Automation account. 1. You have to [publish the runbook](#publish-a-runbook) before you can run it. > [!NOTE] > After you import a graphical runbook, you can convert it to another type. However, you can't convert a graphical runbook to a textual runbook. ### Import a runbook with PowerShell Use the [Import-AzAutomationRunbook](/powershell/module/az.automation/import-azautomationrunbook) cmdlet to import a script file as a draft runbook. If the runbook already exists, the import fails unless you use the `Force` parameter with the cmdlet. The following example shows how to import a script file into a runbook.

## Import a runbook You can import a PowerShell or PowerShell Workflow (**.ps1**) script, a graphical runbook (**.graphrunbook**), or a Python 2 or Python 3 script (**.py**) to make your own runbook. You specify the [type of runbook](automation-runbook-types.md) that is created during import, taking into account the following considerations. * You can import a **.ps1** file that doesn't contain a workflow into either a [PowerShell runbook](automation-runbook-types.md#powershell-runbooks) or a [PowerShell Workflow runbook](automation-runbook-types.md#powershell-workflow-runbooks). If you import it into a PowerShell Workflow runbook, it is converted to a workflow. In this case, comments are included in the runbook to describe the changes made. * You can import only a **.ps1** file containing a PowerShell Workflow into a [PowerShell Workflow runbook](automation-runbook-types.md#powershell-workflow-runbooks). If the file contains multiple PowerShell workflows, the import fails. You have to save each workflow to its own file and import each separately. * Do not import a **.ps1** file containing a PowerShell Workflow into a [PowerShell runbook](automation-runbook-types.md#powershell-runbooks), as the PowerShell script engine can't recognize it. * Only import a **.graphrunbook** file into a new [graphical runbook](automation-runbook-types.md#graphical-runbooks). ### Import a runbook from the Azure portal You can use the following procedure to import a script file into Azure Automation. > [!NOTE] > You can only import a **.ps1** file into a PowerShell Workflow runbook using the portal. 1. In the Azure portal, search for and select **Automation Accounts**. 1. On the **Automation Accounts** page, select your Automation account from the list. 1. From the Automation account, select **Runbooks** under **Process Automation** to open the list of runbooks. 1. Click **Import a runbook**. You can select either of the following options: 1. **Browse for file** - selects a file from your local machine. 1. **Browse from Gallery** - You can browse and select an existing runbook from gallery. 1. Select the file. 1. If the **Name** field is enabled, you have the option of changing the runbook name. The name must start with a letter and can contain letters, numbers, underscores, and dashes. 1. The [**Runbook type**](automation-runbook-types.md) is automatically populated, but you can change the type after taking the applicable restrictions into account. 1. The **Runtime version** is either auto-populated or pick the version from the drop-down list. 1. Click **Import**. The new runbook appears in the list of runbooks for the Automation account. 1. You have to [publish the runbook](#publish-a-runbook) before you can run it. > [!NOTE] > After you import a graphical runbook, you can convert it to another type. However, you can't convert a graphical runbook to a textual runbook. ### Import a runbook with PowerShell Use the [Import-AzAutomationRunbook](/powershell/module/az.automation/import-azautomationrunbook) cmdlet to import a script file as a draft runbook. If the runbook already exists, the import fails unless you use the `Force` parameter with the cmdlet. The following example shows how to import a script file into a runbook.

If you want the runbook to execute with the system-assigned managed identity, leave the code as-is. If you prefer to use a user-assigned managed identity, then: 1. From line 5, remove `$AzureContext = (Connect-AzAccount -Identity).context`, 1. Replace it with `$AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context`, and 1. Enter the Client ID. ## Work with a custom script > [!NOTE] > You can't normally run custom scripts and runbooks on the host with a Log Analytics agent installed. To use a custom script: 1. Create an Automation account. 2. Deploy the [Hybrid Runbook Worker](automation-hybrid-runbook-worker.md) role. ## Test a runbook When you test a runbook, the [Draft version](#publish-a-runbook) is executed and any actions that it performs are completed. No job history is created, but the [output](automation-runbook-output-and-messages.md#use-the-output-stream) and [warning and error](automation-runbook-output-and-messages.md#working-with-message-streams) streams are displayed in the **Test output** pane. Messages to the [verbose stream](automation-runbook-output-and-messages.md#write-output-to-verbose-stream) are displayed in the Output pane only if the [VerbosePreference](automation-runbook-output-and-messages.md#work-with-preference-variables) variable is set to `Continue`. Even though the Draft version is being run, the runbook still executes normally and performs any actions against resources in the environment. For this reason, you should only test runbooks on non-production resources. > [!NOTE] > All runbook execution actions are logged in the **Activity Log** of the automation account with the operation name **Create an Azure Automation job**. However, runbook execution in a test pane where the draft version of the runbook is executed would be logged in the activity logs with the operation name **Write an Azure Automation runbook draft**. Select **Operation** and **JSON** tab to see the scope ending with *../runbooks/(runbook name)/draft/testjob*. The procedure to test each [type of runbook](automation-runbook-types.md) is the same. There's no difference in testing between the textual editor and the graphical editor in the Azure portal. 1. Open the Draft version of the runbook in either the [textual editor](automation-edit-textual-runbook.md) or the [graphical editor](automation-graphical-authoring-intro.md). 1. Click **Test** to open the **Test** page. 1. If the runbook has parameters, they're listed in the left pane, where you can provide values to be used for the test. 1. If you want to run the test on a [Hybrid Runbook Worker](automation-hybrid-runbook-worker.md), change **Run Settings** to **Hybrid Worker** and select the name of the target group. Otherwise, keep the default **Azure** to run the test in the cloud. 1. Click **Start** to begin the test. 1. You can use the buttons under the **Output** pane to stop or suspend a [PowerShell Workflow](automation-runbook-types.md#powershell-workflow-runbooks) or [graphical](automation-runbook-types.md#graphical-runbooks) runbook while it's being tested. When you suspend the runbook, it completes the current activity before being suspended. Once the runbook is suspended, you can stop it or restart it. 1. Inspect the output from the runbook in the **Output** pane. ## Publish a runbook When you create or import a new runbook, you have to publish it before you can run it. Each runbook in Azure Automation has a Draft version and a Published version. Only the Published version is available to be run, and only the Draft version can be edited. The Published version is unaffected by any changes to the Draft version. When the Draft version should be made available, you publish it, overwriting the current Published version with the Draft version. ### Publish a runbook in the Azure portal 1. In the Azure portal, search for and select **Automation Accounts**. 1. On the **Automation Accounts** page, select your Automation account from the list. 1. Open the runbook in your Automation account. 1. Click **Edit**. 1. Click **Publish** and then select **Yes** in response to the verification message. ### Publish a runbook using PowerShell Use the [Publish-AzAutomationRunbook](/powershell/module/Az.Automation/Publish-AzAutomationRunbook) cmdlet to publish your runbook.

## Retrieve details from Activity log You can retrieve runbook details, such as the person or account that started a runbook, from the [Activity log](automation-runbook-execution.md#activity-logging) for the Automation account. The following PowerShell example provides the last user to run the specified runbook.

## Schedule a runbook in the Azure portal When your runbook has been published, you can schedule it for operation: 1. In the Azure portal, search for and select **Automation Accounts**. 1. On the **Automation Accounts** page, select your Automation account from the list. 1. Select the runbook from your list of runbooks. 1. Select **Schedules** under **Resources**. 1. Select **Add a schedule**. 1. In the **Schedule Runbook** pane, select **Link a schedule to your runbook**. 1. Choose **Create a new schedule** in the **Schedule** pane. 1. Enter a name, description, and other parameters in the **New schedule** pane. 1. Once the schedule is created, highlight it and click **OK**. It should now be linked to your runbook. 1. Look for an email in your mailbox to notify you of the runbook status. ## Restore deleted runbook You can recover a deleted runbook through PowerShell scripts. To recover a runbook, ensure that the following conditions are met: - The runbooks to be restored were deleted in the past 29 days. - The Automation account for that runbook exists. - The *Automation Contributor* role permission is granted to the System-assigned managed identity of the Automation account. ### PowerShell script - Execute the PowerShell script as a job in your Automation account to restore the deleted runbooks. - Download the PowerShell [script](https://github.com/azureautomation/Restore-Runbook) from GitHub. Alternatively, you can [import](#import-a-runbook-from-the-azure-portal) the PowerShell script named *Restore Automation runbook* from Runbook Gallery. Provide the name of the runbook that is to be restored and run it as a job in Azure Automation to restore the deleted runbooks. - Download the [script](https://github.com/azureautomation/List-Deleted-Runbooks) from GitHub or [import](#import-a-runbook-from-the-azure-portal) the PowerShell script named *List Deleted Automation Runbook* from Runbook Gallery, to identify the names of the runbooks that were deleted in last 29 days. ## Obtain job statuses ### View statuses in the Azure portal Details of job handling in Azure Automation are provided in [Jobs](automation-runbook-execution.md#jobs). When you are ready to see your runbook jobs, use Azure portal and access your Automation account. On the right, you can see a summary of all the runbook jobs in **Job Statistics**.  The summary displays a count and graphical representation of the job status for each job executed. Clicking the tile presents the Jobs page, which includes a summarized list of all jobs executed. This page shows the status, runbook name, start time, and completion time for each job. :::image type="content" source="./media/manage-runbooks/automation-account-jobs-status-blade.png" alt-text="Screenshot of the Jobs page."::: You can filter the list of jobs by selecting **Filter jobs**. Filter on a specific runbook, job status, or a choice from the dropdown list, and provide the time range for the search.  Alternatively, you can view job summary details for a specific runbook by selecting that runbook from the Runbooks page in your Automation account and then selecting **Jobs**. This action presents the Jobs page. From here, you can click a job record to view its details and output. :::image type="content" source="./media/manage-runbooks/automation-runbook-job-summary-blade.png" alt-text="Screenshot of the Jobs page with the Errors button highlighted."::: ### Retrieve job statuses using PowerShell Use the [Get-AzAutomationJob](/powershell/module/Az.Automation/Get-AzAutomationJob) cmdlet to retrieve the jobs created for a runbook and the details of a particular job. If you start a runbook using `Start-AzAutomationRunbook`, it returns the resulting job. Use [Get-AzAutomationJobOutput](/powershell/module/Az.Automation/Get-AzAutomationJobOutput) to retrieve job output. The following example gets the last job for a sample runbook and displays its status, the values provided for the runbook parameters, and the job output.