Business Engagement and Approvals¶

This workflow follows the approval route in Clarity Transform: asking the owners of the applications, devices and databases in a migration event to approve their migration, following their responses, and confirming the plan. Each stage names the screen, the actions that matter, and the page that documents the screen in full.

The route in short:

Set up the outgoing email (and, if you want it, Teams), the email templates and the extra recipients.
Make sure each item has an owner with a valid email address.
Build the event's move groups.
Send the approval requests from Plan → Move Groups.
Follow the read receipts and responses on Plan → Business Engagement.
Chase owners, record decisions given outside Clarity, and arrange planning meetings.
Lock the event, and send the migration confirmation if you want it.

Stage 1: Set up email and Teams¶

Approval requests go out by email, and also by Microsoft Teams when Teams notifications are set up. Calendar invites for planning meetings need email.

What you want to send	What it needs
Approval requests (Send Approval)	An SMTP profile or Teams notifications
Planning meeting invites (Schedule Meeting)	An SMTP profile. Teams cannot send calendar invites.

Add an SMTP profile on Settings → Communications → SMTP Configuration. See Add an SMTP profile.
To send Teams notifications as well, set up Settings → Communications → Teams Notifications. See Set up Teams notifications.

Without either, Send Approval is greyed out, with the message "No communication channel configured. Set up SMTP or Microsoft Teams under Settings → Notifications to enable this." The setup screens are under Settings → Communications, although the message says Settings → Notifications.

Stage 2: Check the email templates¶

Go to Settings → Communications → Email Templates. These templates belong to the approval route:

Template	When it is sent, from its description
Migration Approval Request	"Sent to application/device owners requesting approval for migration. Groups all entities per owner into a single email". Sent by Send Approval.
Migration Planning Meeting	"Sent when a migration planning meeting is scheduled with an owner". Sent by Schedule Meeting.
Migration Approval Confirmed	"Sent to migration contacts when an approval batch (or whole event) is fully approved, confirming the migration date."
Approved Migration Plan	"Sent automatically to each owner once every one of their items in a migration event has been decided (approved or rejected)".

Select a template's row and select Preview to see the email with sample values. Each template's Email Recipient names the record fields its recipients are read from. To use another owner or contact field, allow it on Settings → Communications → Email Recipient Fields first. Keep each template's Is Active ticked.

See Email Templates and Email Recipient Fields.

Stage 3: Add project contacts as extra recipients¶

Go to Governance → Project Directory. To copy a project contact, such as the migration lead, into an approval email, edit the contact and tick:

Include In Migration Approval Request: "Also notify this contact when a Migration Approval Request is sent."
Include In Migration Approval Confirmed: "Also notify this contact when a Migration Approval is confirmed."
Include In Approved Migration Plan: "Also notify this contact when an Approved Migration Plan is sent."

Tick Teams Notifications Enabled as well for the contact to get Teams notifications for the ticked steps. See Add a contact as a recipient for a workflow notification.

Stage 4: Check the owner field the emails use¶

Approval requests go to the owners of the items in the move groups. Business Engagement shows one row per item in each approval request. In the approval data checked for this build, a move group that held applications and servers produced rows for its devices only.

Which owner field an email is sent to is set by its template's Email Recipient on Settings → Communications → Email Templates. Open the templates and read it first:

Email	Template	Example Email Recipient	The field to fill in
Approval request	Migration Approval Request	`device.device_owner`	Device Owner on Device records
Planning meeting invite	Migration Planning Meeting	`application.app_owner`	App Owner on Application records

The field each template names must hold a valid email address for every item.

If the client records owners only on applications, either copy each application's App Owner into Device Owner on its devices (filter the Device grid by Application and use Enable spreadsheet editing), or change the approval template's Email Recipient. Test either way with one move group and a mailbox you control before the real send.

Each owner must be a valid email address. If it is not, the owner gets no request, and the item shows as Skipped - invalid email on Business Engagement.

The confirmation emails go to other contact fields on the device record: Migration Contact, Migration Testing By and App Shutdown Contact. Fill them in before you lock the event.

Stage 5: Build the move groups¶

Go to Plan → Events and Plan → Move Groups. Approval requests are sent per move group, so the event and its move groups must exist and hold the items first.

Create the event on Plan → Events, then create the move groups and link them to it with Event Name.
Add the assets with the move group's Populate Move Group dialog. See Add assets to a move group.
Don't lock the event yet: a locked event's move groups can't be populated.

See the Migration Planning workflow for these screens in full.

Stage 6: Send the approval requests¶

Go to Plan → Move Groups.

Select the rows of the move groups to send. You can select more than one.
Open the Actions menu and, under Workflow, select Send Approval.
The Send Approval Request dialog reads "Notify application and device owners for the selected move groups." and "This will send approval requests by email and, when configured, Microsoft Teams." It lists the selected move groups. Select Send Approval Request.

Clarity confirms the send, for example "Approval requests sent successfully using 3 emails and 2 Teams notifications." Owner fields that are not valid email addresses are listed in an error message. The Activity Log records ApprovalRequestSent.

See Send an approval request.

Stage 7: Follow the responses and read receipts¶

Go to Plan → Business Engagement and choose the Event.

The cards count the items approved, the items Overdue (2+ days) and the planning meetings booked.
Email Opened is the read receipt: the date and time the owner opened the email, or Not opened.
Approval Status shows Pending, Overdue (no response after 2 working days), Approved, Rejected or Skipped - invalid email. Rejection Reason shows the reason for a rejection.
Meeting shows Requested by owner, Requested, Invite Sent or Booked.
Select Refresh to load the latest responses.

See Track the approvals for an event.

Stage 8: Chase, record decisions and arrange meetings¶

Still on Plan → Business Engagement:

Chase: filter for Overdue or Not opened, and select the owner's address to write to them. See Chase an overdue owner.
Fix skipped items: correct the owner field, then send again from Move Groups. See Fix a skipped request.
Record a decision given outside Clarity, for example in a meeting: select the rows still awaiting a decision, then Record Approval or Record Rejection. A Note is always required, and a rejection also needs a Rejection Reason (Decomm, Unknown VM, Unknown Owner or Yes - Future Event). The dialog says "No email is sent; the decision is logged and rolls up to the move group status." See Record an approval by hand and Record a rejection by hand.
Arrange a planning meeting: select Schedule Meeting in the row to send one calendar invite covering the owner's outstanding approvals for that application in the event. It needs an SMTP profile. Select Mark Booked when the meeting was arranged another way. See Schedule a planning meeting and Mark a meeting as booked.

Stage 9: Check the roll-up¶

The decisions show up on the planning screens:

Plan → Move Groups: the columns Number Approved and Number Rejected. Select Refresh Stats on the Actions menu to bring the figures up to date.
Plan → Events: the columns Number Approved, Number Rejected, Number No Response and Number Decommissioned.

These counts are not a count of owner decisions. In the data checked for this build, a move group showed every server approved while every one of its rows on Business Engagement was still Pending. Use Business Engagement as the record of who has approved. - Plan → Planning Dashboard: the NO APPROVAL card.

When the move groups are ready, select them on Plan → Move Groups and use Mark Ready to Migrate (under Status on the Actions menu). It validates the move groups first, but it does not check for pending approvals: in the data checked for this build, a move group was Ready to Migrate while every one of its approval rows was Pending. Check that every item is decided on Business Engagement before you use it. A device whose Approval Status is Rejected breaks the default guard-rail rule approval_status Equals Rejected. See Mark move groups ready to migrate.

Stage 10: Confirm and lock the event¶

Go to Plan → Events, select the event's row and select Lock Event.

In the Lock Event dialog, tick Send the migration confirmation email to migration contacts to send the final migration confirmation. Its help reads: "When ticked, this sends the final migration confirmation (date & time) for the approved VMs in all move groups of the event(s) to the Migration Contact, Testing By and App Shutdown Contact. Rejected VMs are excluded."
Locking stops new devices being assigned to the event's move groups.
The Activity Log records EventLocked.

See Lock an event.

What happens next¶

Generate the event's T-Minus runbook from View T-minus Runbook on Plan → Events. See Generate a T-Minus runbook for an event.
Build the cut-over runbooks for the move groups. See Runbooks.
Check the approval trail on Logging → Activity Log, with the event types ApprovalRequestSent, ApprovalItemsDecided, ApprovalItemsDecidedByOperator and EventMigrationConfirmationSent. See Activity Log.

Troubleshooting¶

What you see	Why	What to do
Send Approval is greyed out, with the tooltip "No communication channel configured. Set up SMTP or Microsoft Teams under Settings → Notifications to enable this."	Neither an SMTP profile nor Teams notifications is set up.	Do Stage 1.
Send Approval is greyed out with no tooltip	No move group row is selected.	Select one or more move group rows.
Selecting Send Approval shows "No communication channel configured..."	As the first row.	As the first row.
After sending, an error message lists invalid email addresses	Those owner fields are not valid email addresses. Their items show as Skipped - invalid email on Business Engagement.	Correct the owner fields (Stage 4) and send again.
Business Engagement shows "No approval requests found. Send approvals from the Move Groups page first."	No request has been sent for the selected event's move groups.	Do Stage 6, or choose another event.
Schedule Meeting is greyed out, with the tooltip "Calendar invites require SMTP..."	Only Teams is set up. Calendar invites need SMTP.	Add an SMTP profile.
The move group's add button reads "This move group belongs to a locked event and cannot be populated."	The event is locked.	Unlock the event on Plan → Events with Unlock Event, add the assets, then lock it again.
Mark Ready to Migrate opens Migration Readiness Issues	The move groups failed validation, and their status is unchanged.	Fix the issues listed, then try again.
Lock Event is greyed out	No event row is selected.	Select the event's row.

Questions people ask¶

Who is asked to approve? The owners of the items in the selected move groups, read from the field named in the Migration Approval Request template's Email Recipient. Business Engagement has one row per item, with its Owner.

Does recording a decision by hand on Business Engagement send an email? No. The dialog says "No email is sent; the decision is logged and rolls up to the move group status."

Do I need both SMTP and Teams? No. Send Approval is available when either an SMTP profile or Teams notifications is set up. Planning meeting invites need SMTP.

Does locking the event send the confirmation email? Only if you tick Send the migration confirmation email to migration contacts in the Lock Event dialog. It is unticked each time the dialog opens. The email covers the approved VMs only: "Rejected VMs are excluded."

Who gets the confirmation email? The Migration Contact, Testing By and App Shutdown Contact of the approved VMs, as the Lock Event dialog says.

Can I add devices to the event after locking it? No. "Locking prevents new devices being assigned to the event's move groups." Unlock it first.

Where is the audit trail? On Logging → Activity Log, under the event types ApprovalRequestSent, ApprovalItemsDecided, ApprovalItemsDecidedByOperator, EventLocked and EventMigrationConfirmationSent.