Skip to content

Runbooks

Purpose

In Clarity Transform, runbooks are on Execute → Migration Operations → Runbooks. They are cut-over runbooks, separate from T-Minus runbooks: for T-Minus templates, see T-Minus Runbook Templates. The on-screen subtitle reads: "Runbooks are automated migration plans built from Move Groups. Each runbook defines the sequence of tasks to be executed for a batch of assets during migration, helping you standardize, schedule, and track migration activities for consistency and control."

A Runbook is a sequenced list of tasks that must be executed during a migration cut-over window. Each task has Assigned To, Planned Start, Planned End, Status and Notes fields, and the task record also holds its actual start, end and duration. The Event Command Center counts an event's runbooks and runbook tasks on its RUNBOOKS and RUNBOOK TASKS cards.

The Task Library holds reusable tasks, grouped into Task Library Groups on Execute → Pre-Migration Setup → Task Groups. Create Runbook from Task Library creates two linked runbooks for each move group selected in Move Group Names: a primary runbook from the Primary Task Library Group and a rollback runbook from the Rollback Task Library Group.

Where to find it

Execute → Migration Operations → Runbooks

Selecting a runbook's Name opens the runbook detail page, which lists the runbook's tasks. The detail page is not in the sidebar.

What you see

Columns

The Runbooks grid has these columns:

  • Name: opens the runbook detail page.
  • Reconciliation Status
  • Event Name
  • Status
  • Move Groups

The grid also has the hidden columns Mode, Runbook Type, Linked Runbook Name, Task Library Group Name, Tested By, Test Started At, Test Completed At, Promoted To Live By, Promoted To Live At, Id and the audit fields. Each row has a View Details row action (the eye icon).

The Reconciliation Status badge reads "Reconciliation passed - click for details", "Reconciliation failed - click for details" or "Not yet reconciled - click to run". Selecting any badge reconciles that runbook and opens the Runbook Reconciliation dialog with its report.

Runbook Reconciliation dialog

The dialog title shows the number of runbooks in the report, for example Runbook Reconciliation (1). Its text reads: "Comparing N selected runbook(s) against the current device membership of their linked move group(s)." The dialog has a Close button.

Values

The values below are those seen in the lab data.

  • Status: Completed, In Progress, Cancelled, Failed, Not Started, Ready
  • Reconciliation Status: Passed, Failed
  • Mode: Live, Test
  • Runbook Type: Primary, Rollback

Test and live

A new runbook starts in Test mode. In Test mode, running the tasks is a simulation: the task states are simulated rather than the real migration actions being carried out. When the test is done, the runbook is promoted to live.

The runbook detail page shows a mode panel for the selected runbook above the task table, with a Promote to Live button. For a rollback runbook, the panel also names its primary runbook and has Declare Rollback; VMs become eligible for rollback once their primary cutover task completes. Promote to Live opens the Promote to Live dialog, which reads: "Simulated task state will be reset and the runbook will switch to real execution mode." and "This action cannot be undone." Its buttons are Cancel and Confirm Promotion.

The data records who tested the runbook and when (Tested By, Test Started At, Test Completed At) and who promoted it and when (Promoted To Live By, Promoted To Live At). A promotion is recorded in Logging → Activity Log as the event type RunbookPromotedToLive.

Actions

The grid toolbar has:

  • the add icon (it has no Create New tooltip on this screen)
  • Create Runbook from Task Library: opens the Create Runbook from Tasks dialog. If a runbook creation reported problems, the button shows an issue count; select it to open the Runbook Creation Issues panel.
  • Edit
  • Remove selected
  • Clear selection
  • Reload table data
  • Enable spreadsheet editing
  • Export CSV
  • Import CSV
  • Show completed
  • Reconcile selected runbooks: its tooltip reads "Select one or more runbooks first" until a runbook is selected, then Compare selected runbooks. It reconciles the selected runbooks and shows "Reconciliation complete for N runbook(s). Check the status column."; the result is in Reconciliation Status.

Fields

The edit form (Edit entry) opens for the selected row and has these fields:

  • Name
  • Event Name: a list of the migration events.
  • Status: a text field.
  • Move Groups: a text field.

The hidden columns are not shown in the form.

Create Runbook from Tasks dialog

  • Move Group Names: a select list; you can choose more than one. Help text: "Search and select one or more move groups."
  • Primary Task Library Group: a select list.
  • Rollback Task Library Group: a select list.

The dialog's buttons are Cancel and Apply.

Filters

Each column has a filter row, and the grid has a Search: box and an entries per page selector (10, 25, 50 or All).

The grid remembers its Search: text, column filters, sort order and page size between visits. If the grid shows fewer rows than you expect, clear the Search: box and the filter row.

Runbook detail page

Task fields are on the runbook detail, opened by selecting a runbook name.

Above the task table, a mode panel shows the selected runbook's mode. See Test and live.

On a rollback runbook, the task table shows only the tasks for VMs that are eligible for rollback. Tasks that are not tied to a VM, such as the start and end tasks and application-level tasks, always show.

Controls

  • Table... and Graph...: switch between the task table and a graph view.
  • Select a Runbook...: chooses the runbook to show.
  • The standard add, edit, delete and clear icons.
  • Show my tasks
  • Override Run Validation
  • Auto-refresh: 30s
  • Assign to Me: assigns a task to you.

Task columns

  • Actions: the task's row controls (see below).
  • Name
  • Cis To Action
  • Planned Start
  • Planned End: a task cannot start after its planned end time.
  • Status
  • Action
  • Script
  • Sequence: the task's position in the runbook.
  • Applications To Action
  • Task Recipient
  • Notes
  • Assigned To

The task record also holds the task's dependencies on parent tasks, its planned duration, and its actual start, end and duration.

Task row controls

Each task row has these controls: View Details, Reset to Not Started, Cancel Task, a start icon (Start Task), a complete icon (Mark as Complete) and View error details.

The start icon is disabled, and its tooltip gives the reason, when:

  • the task has no Planned Start: "Planning incomplete - Planned Start Date required"
  • the planned start time has not been reached: "Task cannot start before planned start time"
  • the planned end time has passed: "Task cannot start after planned end time"
  • its parent tasks are not completed: "Parent tasks must be completed first"
  • the task is already in progress, completed or cancelled
  • the task is Waiting on Customer: "Waiting on the customer's sign-off; complete, fail or reset it instead"

The complete icon is disabled for the same planning, timing and parent-task reasons, and also when "Child tasks are in progress or have incomplete dependencies". It stays available for a task that is Waiting on Customer.

Override Run Validation turns these checks off. The tooltips then read Start Task (Validation Overridden) and Mark as Complete (Validation Overridden).

Task values

  • Status: the values seen are In Progress, Not Started, Completed and Failed. The values allowed in Settings → Field Management → Dropdown Lists are Not Started, In Progress, Paused, Cancelled, Completed, Failed. A sign-off task can also be in the status Waiting on Customer; see Smoke-test notifications and sign-off.

Smoke-test notifications and sign-off

The Task Library has system tasks in pairs: a communications task and a sign-off task, for example Application Smoke Test Comms Sent followed by Application Signed Off.

There is no separate send button for smoke-test emails. The email is sent when an operator starts the "... Smoke Test Comms Sent" task on the runbook detail page. If the start is refused or the email fails, a message shows and the task does not start. The matching "... Signed Off" task then waits in the status Waiting on Customer until the recipient responds. An operator can complete, fail or reset a waiting sign-off task instead. Contacts with Include In Application Smoke Test, Include In Device Smoke Test or Include In Sequence Smoke Test ticked in Project Directory are also notified.

The secure sign-off page shows the runbook name, the testing contact, the impacted device and database scope, and a pass/fail choice. If the recipient selects Failed, they must enter failure notes. Those notes are written back to the linked sign-off task.

A successful response completes the waiting sign-off task and allows the runbook to continue. A failed response marks the sign-off task as Failed, records the notes on the task, and updates the affected application or device migration status.

The Logging → Activity Log event types SmokeTestSignoffOpened, SmokeTestSignoffPassed and SmokeTestSignoffFailed relate to the sign-off page.

How to

Create a runbook from the Task Library

  1. Go to Execute → Migration Operations → Runbooks.
  2. Select Create Runbook from Task Library. The Create Runbook from Tasks dialog opens.
  3. In Move Group Names, choose one or more move groups.
  4. Choose a Primary Task Library Group and a Rollback Task Library Group.
  5. Select Apply. Apply creates two linked runbooks for each move group: a primary runbook named <move group>-<primary group>-Runbook and a rollback runbook named <move group>-<rollback group>-Rollback-Runbook, both in Test mode. They show Creating until Clarity reconciles them, then Not Started. Reconciliation of the new runbooks runs automatically after creation.
  6. If the message after Apply is a warning, select the issue count on Create Runbook from Task Library to open the Runbook Creation Issues panel and read the problems.

Library tasks that have Clarity Tags are created only for the devices whose tags match them, under the task's Tag Match Mode. See Pre-Migration Setup.

Edit a runbook

  1. Go to Execute → Migration Operations → Runbooks.
  2. Select the runbook's row, then select Edit. The Edit entry form opens.
  3. Change the Name, Event Name, Status or Move Groups.
  4. Select Save.

Work through a runbook's tasks

  1. Go to Execute → Migration Operations → Runbooks.
  2. Select the runbook's Name. The runbook detail page opens with the task table.
  3. To assign a task to yourself, select its row, then Assign to Me (disabled until a task is selected). The Activity Log records RunbookTaskAssigned.
  4. Use the start icon in the task's Actions column to start it, and the complete icon when it is done.
  5. If a control can't be used, read its tooltip. A task can start only when its Planned Start is set and reached, its Planned End has not passed, and its parent tasks are completed. See Task row controls.

Send smoke-test comms and record sign-off

  1. Go to Execute → Migration Operations → Runbooks and select the runbook's Name.
  2. Start the "... Smoke Test Comms Sent" task with its start icon. Starting the task sends the smoke-test email.
  3. The matching "... Signed Off" task waits as Waiting on Customer until the recipient responds on the sign-off page.
  4. To close the sign-off without a response, complete, fail or reset the "... Signed Off" task yourself.

Promote a runbook to live

  1. Go to Execute → Migration Operations → Runbooks and select the Name of a runbook in Test mode.
  2. In the mode panel above the task table, select Promote to Live. The Promote to Live dialog opens.
  3. Select Confirm Promotion. The simulated task state is reset and the runbook switches to real execution. This cannot be undone.

Reconcile runbooks

  1. Go to Execute → Migration Operations → Runbooks.
  2. Select one or more runbook rows.
  3. Select Reconcile selected runbooks. The runbooks are reconciled without opening a dialog, and the result shows in Reconciliation Status.

To see the report for one runbook, select its Reconciliation Status badge. The Runbook Reconciliation dialog opens.