Communications

Purpose

The Communications group in Clarity Transform holds the four screens that set up outgoing notifications: SMTP Configuration, Teams Notifications, Email Templates and Email Recipient Fields. Each screen has its own section below.

The screens are connected by fields rather than by a fixed order:

• an SMTP profile's Credentials value is selected from the credentials held on Settings → Identity & Access Management → Credentials;
• each email template record holds an Smtp Profile value;
• an email template whose recipient type is RecipientField takes its recipient field from the Qualified Field values allowed on Email Recipient Fields.

Where to find it

• Settings → Communications → SMTP Configuration
• Settings → Communications → Teams Notifications
• Settings → Communications → Email Templates
• Settings → Communications → Email Recipient Fields

Filters

Each of the four screens is a grid with a Search: box and a filter row under each column.

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.

SMTP Configuration

Settings → Communications → SMTP Configuration. The screen has no page header. It lists named SMTP profiles, and more than one profile can exist.

Columns

• Profile
• Smtp
• From
• Credentials
• Display Name
• Port
• Use Ssl

The grid also has the hidden columns Id and Reply To, and the audit fields.

Fields

The create form (Create new entry) and the edit form (Edit entry) have four fields:

• Profile: text.
• Smtp: text.
• From: text.
• Credentials: a list of the credentials held on Settings → Identity & Access Management → Credentials.

Display Name, Port, Use Ssl and Reply To are hidden in the form, so they can't be set there. The form footer has Cancel and Save.

Actions

The screen uses the standard grid toolbar: Create New, Edit, Remove selected, Clear selection, Reload table data, Enable spreadsheet editing, Export CSV and Import CSV. Each row has a View Details row action (the eye icon).

Add an SMTP profile

1. Go to Settings → Communications → SMTP Configuration.
2. Select the add icon in the grid toolbar (Create New). The Create new entry form opens.
3. Enter the Profile, Smtp and From values.
4. Select a stored credential in Credentials.
5. Select Save, or Cancel to close the form without saving.

Teams Notifications

Settings → Communications → Teams Notifications. The screen has no page header.

Columns

• Tenant Id
• Client Id
• Credentials
• Teams App Id
• Activity Type
• Enabled

Fields

The create form (Create new entry) has the same six fields, in this order:

• Tenant Id: text. Help: "Microsoft Entra tenant ID for the Teams notification app registration."
• Client Id: text. Help: "Application (client) ID for the Teams notification app registration."
• Credentials: a list of the credentials held on Settings → Identity & Access Management → Credentials. Help: "Credential target containing the Microsoft Entra client secret."
• Teams App Id: text. Help: "Teams catalog app ID that is installed for recipients and linked to the Entra app registration."
• Activity Type: a free-text field with no option list. Help: "Use systemDefault for free-form activity feed notifications unless a manifest activity type is defined."
• Enabled: a checkbox. Help: "Enable Microsoft Teams delivery alongside email for supported workflow notifications."

There is no webhook URL field and no per-event selection list.

Actions

The screen uses the standard grid toolbar: Create New, Edit, Remove selected, Clear selection, Reload table data, Enable spreadsheet editing, Export CSV and Import CSV. The grid rows have no row actions.

Set up Teams notifications

1. Go to Settings → Communications → Teams Notifications.
2. Select the add icon in the grid toolbar (Create New). The Create new entry form opens.
3. Enter the Tenant Id, Client Id and Teams App Id of the Teams notification app registration.
4. Select the credential that holds the client secret in Credentials.
5. Enter the Activity Type, for example systemDefault, and select Enabled.
6. Select Save, or Cancel to close the form without saving.

Email Templates

Settings → Communications → Email Templates. The screen subtitle reads: "Manage reusable email templates for runbook task notifications. Write your message in plain text using placeholders - the system automatically wraps it in a branded email layout. Assign templates to tasks via the Task Library to send automatic notifications when tasks complete or fail."

Columns

• Name
• Description
• Send From Address
• Email Recipient
• Subject Line
• Send Per Entity
• Is Active

The grid also has the hidden columns Recipient Type, Recipient Custom, Message Body, Id, Delivery Policy, Teams Preview Text, Teams Topic and Smtp Profile, and the audit fields. Delivery Policy holds EmailOnly or EmailAndTeams.

Fields

The create form (Create new entry) has these fields, in this order. The edit form (Edit entry) has the same fields, filled in.

• Name: text.
• Description: multi-line text.
• Send From Address: text, with the placeholder "Optional - defaults to the SMTP From address". Help: "Optional. Leave blank to use the default SMTP From address."
• Email Recipient: a list with Custom Recipient(s) and the fields allowed on Email Recipient Fields, shown as table.field. Help: "Choose a field from Email Recipient Fields, or select Custom Recipient(s)." A template can hold more than one recipient field. The grid shows them separated by commas.
• Subject Line: multi-line text, with the placeholder "e.g. Migration task {TaskName} - {Status}".
• Message Body: multi-line text, with the placeholder "Type your message here. Use {Placeholders} from the reference panel above."
• Send Per Entity: a checkbox.
• Is Active: a checkbox.

When Email Recipient is Custom Recipient(s), a Custom Recipient(s) field appears, with the placeholder "name@example.com, another@example.com". Help: "Enter one or more email addresses separated by commas."

Recipient Type, Delivery Policy, Teams Preview Text, Teams Topic and Smtp Profile are hidden in the form, so they can't be set there. The form footer has Cancel and Save.

Values

• Recipient type: RecipientField or Custom. Saving a template sets this for you: Custom when Email Recipient is Custom Recipient(s), otherwise RecipientField. Older templates can still hold ApplicationOwner or DeviceOwner. The grid shows these as application.app_owner and device.device_owner, and they become RecipientField the next time the template is saved.
• Templates present in the instance observed for this build (23): Application Smoke Test, Migration Task Complete, Migration Approval Request, Device Smoke Test, Interview Request, Interview Meeting Request, Migration Approval Confirmed, Migrated Device Notification, Sequence Smoke Test, Approved Migration Plan, App Services Shutdown, Migration Planning Meeting, T-Minus Task Ready, T-Minus Task Overdue, Event Update, Event Closure, Interview Outcome, Go Decision, No-Go Decision, Command Centre Update, Event Lifecycle - Started, Event Lifecycle - Closed and Event Lifecycle - Owner Summary.

Available Placeholders

The expandable Available Placeholders panel above the grid lists the tokens, in five groups. Tokens use single braces, and {ExpiryDate} appears in two groups. Its note reads: "Use placeholders in Subject Template and Body Template. When Send Per Entity is enabled, emails are sent individually per resolved device/application recipient with entity-specific placeholders resolved."

• Task Context: {RecipientName} {TaskName} {TaskId} {Status} {RunbookName} {AssignedTo} {PlannedStart} {PlannedEnd} {Timestamp} {ErrorDetails}
• Device Context: {VMName} {ProviderId} {DeviceOwner} {DeviceCount} {DeviceTable}
• Application Context: {ApplicationName} {ScopeType} {ScopeName} {AppOwner} {TechnicalContact} {TestingBy} {Environment} {Criticality}
• Smoke Test Links: {SmokeScopeTable} {SmokeTestResponseUrl} {ExpiryDate}
• Approval / Migration Context: {MigrationDate} {EventName} {MoveGroupName} {EntityCount} {OwnerEmail} {ExpiryDate} {MigrationSchedule} {EntityTable} {ReviewButton}

Actions

• The standard grid toolbar: Create New, Edit, Remove selected, Clear selection, Reload table data, Enable spreadsheet editing, Export CSV and Import CSV.
• Preview: select a template row first, then select Preview. The Email Preview dialog shows the email with sample values in place of the placeholders, inside the branded email layout. Close it with Close. If no row is selected, Clarity shows "Select a template row to preview."
• View Details: a row action (the eye icon) on each row.

Add an email template

1. Go to Settings → Communications → Email Templates.
2. Select the add icon in the grid toolbar (Create New). The Create new entry form opens.
3. Enter a Name and Description.
4. Choose the Email Recipient: a recipient field, or Custom Recipient(s). If you choose Custom Recipient(s), enter the addresses, separated by commas, in the Custom Recipient(s) field that appears.
5. Enter the Subject Line and the Message Body, using tokens from Available Placeholders.
6. Select Send Per Entity and Is Active as needed.
7. Select Save, or Cancel to close the form without saving.

Preview a template

1. Go to Settings → Communications → Email Templates.
2. Select the template's row in the grid.
3. Select Preview. The Email Preview dialog shows the email with sample values in the branded layout.
4. Select Close.

Where templates are used

• Task Library tasks: a task sends the template chosen in its Email Template Name. See Attach a template to a task.
• Go/No-Go decisions: recording Go or No-Go sends the Go Decision or No-Go Decision template to the Event Update group. Clarity finds these templates by name, so do not rename them. See Go/No-Go.
• Command Centre updates: Send Update on the Event Command Center emails the selected event's key figures and your note to the Event Update group, using the Command Centre Update template.
• T-Minus Send Email tasks: when the status of a T-Minus Send Email task changes, Clarity says whether its email is being sent and to how many recipients, or why it was not sent.

To check whether a notification email went out, see Check whether a notification email was sent.

These templates belong to the approval route (see the Business Engagement and Approvals workflow). Their descriptions on this screen say when each is sent:

• Migration Approval Request: "Sent to application/device owners requesting approval for migration. Groups all entities per owner into a single email". It is sent by Send Approval on Move Groups. Its Delivery Policy is EmailAndTeams, and it uses the Approval / Migration Context placeholders, including {ReviewButton} and {ExpiryDate}.
• Migration Planning Meeting: "Sent when a migration planning meeting is scheduled with an owner", with Schedule Meeting on Business Engagement.
• 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)".

The Project Directory checkboxes Include In Migration Approval Request, Include In Migration Approval Confirmed and Include In Approved Migration Plan add project contacts to these emails.

Attach a template to a task

1. Go to Execute → Pre-Migration Setup → Task Library.
2. Select the task's row and select Edit.
3. Either set Action to Send Email, or tick Send Email On Complete or Send Email On Failed. Any of these shows the Email Template Name field.
4. Choose the template in Email Template Name.
5. Select Save.

System tasks (the built-in tasks shipped with Clarity) cannot have their email settings changed: Send Email On Complete, Send Email On Failed and Email Template Name are locked for them.

Email Recipient Fields

Settings → Communications → Email Recipient Fields. The header is Email Recipient Fields, and the subtitle reads: "Configure the allowed application and device fields that email templates can use to resolve recipients. Choose the entity first, then pick a valid source column from that CI table."

Each row allows one field. An entity can have several rows.

Columns

• Entity Type: device or application.
• Field Name: the options depend on the Entity Type chosen.
• Qualified Field: for example, Field Name device_owner has Qualified Field device.device_owner.

Fields

The create form (Create new entry) and the edit form (Edit entry) have two fields:

• Entity Type: a list with device and application.
• Field Name: a list of the chosen entity's columns.

Qualified Field is hidden in the form, so it can't be set there. The form footer has Cancel and Save.

Actions

The screen uses the standard grid toolbar: Create New, Edit, Remove selected, Clear selection, Reload table data, Enable spreadsheet editing, Export CSV and Import CSV. Each row has a View Details row action (the eye icon).

Allow a field as a recipient source

1. Go to Settings → Communications → Email Recipient Fields.
2. Select the add icon in the grid toolbar (Create New). The Create new entry form opens.
3. Choose the Entity Type first.
4. Pick a Field Name from the options for that entity.
5. Select Save, or Cancel to close the form without saving.

Related pages

• Credentials: the stored credentials offered in the Credentials select on SMTP Configuration and Teams Notifications.
• Pre-Migration Setup: the Task Library, where templates are assigned to runbook tasks.
• Go/No-Go: the decisions that send the Go Decision and No-Go Decision templates.
• Activity Log: a record of each notification email queued, sent, not sent or failed.
• Project Directory: the Include In checkboxes that pre-select additional recipients for specific notifications, and Teams Notifications Enabled.