Customizing an automation rule or web action output email

Content: 

Overview

In Cayosoft Administrator every automation rule and web action can be configured to send email as an output: you can define if the rule or web action should send a report when it finished its work and select the report type in the Output section. Some automation rules have additional email notification capabilities. Sending emails is added to the Action section of these rules, for example, to notify the manager about user creation or to send users password expiration notifications.

In some cases, you may need to customize the default email and include additional user attribute values in the email body, subject, and To field in automation rules and web actions. For example, to add some specific user attributes to the message subject or body or send the result of a rule or a web action to a user manager. There are links to example scenarios below in this article on how to perform such customization.

Customizing email subject and message

You can add to the email subject and message any user property value in the following format: $($FoundObject.<AD User Property>), where <AD User Property> is the LDAP name of the user property.  

For example, to add to the email subject or message additional user or manager information use the following variables: 

Examples

How to customize Notify Manager email in bulk provisioning rules

There are several automation rules in Cayosoft Administrator to provision users in bulk, for example, Text file | Create AD Users, Import SQL Data | Create AD Users, or Import Oracle Data | Create AD Users. You can customize these rules to notify managers of created users via email, and include employee login information. So that the manager can print this email and give it to a new employee on his first day of work. There are slightly different scenarios: notify the manager about each created user in a separate email, or notify the manager about all created users in a single email.

Notify the manager about each created user in an individual email

1. In Cayosoft Administrator Console open a provisioning rule, for example, Text file | Create AD Users"
2. Expand Notify Manager section
3. Set Notify Manager setting to Yes
4. Replace the default text in the Subject field with this one:
   {"New Account Created for $($FoundObject.givenName) $($FoundObject.sn)"}
5. Replace the default text in the Message field with this one:
   

   {
   $managerName = "Manager"
   if($FoundObject.manager -ne $Null){

        $mgr = Get-ADUser -Identity $FoundObject.manager -Properties * -ErrorAction Ignore

        if($mgr -ne $Null){

             $managerName = $mgr.DisplayName

       }

   }

   $message =

   "

     Dear $managerName<br/><br/>
     New account has been created for $($FoundObject.givenName) $($FoundObject.sn).<br/><br/>  
     Login Name: $($FoundObject.sAMAccountName)<br/>
     Password: " +[System.Security.SecurityElement]::Escape($($FoundObject.Password))+ "<br/><br/>
     Email: $($FoundObject.mail)<br/><br/>

   "

   $message

   }

6. Click Save Changes.

As a result, each created user, his manager will receive one email about each created user.

Notify the manager about all created users

1. In Cayosoft Administrator Console open a provisioning rule, for example, Text file | Create AD Users
2. Expand Notify Manager section
3. Set Notify Manager setting to Yes (Send one email for created users)
4. Replace the default text in the Subject field with this one:
   {"New user accounts created"}
5. Replace the default text in the Message field with this one:
   {
   $managerName = "Manager"
   $managerDN=($FoundObject.manager | select -Unique)
   if($Null -ne $managerDN){
      $mgr = Get-ADUser -Identity $managerDN -Properties * -ErrorAction Ignore
      if($Null -ne $mgr){
          $managerName = $mgr.DisplayName
      }
   }
   $message = "Dear $managerName<br/><br/>New user accounts have been created.<br/><br/>" $FoundObject | %{
        $message += "Login Name: $($_.sAMAccountName)<br/><br/>"
        $message += "Password:" + [System.Security.SecurityElement]::Escape($_.Password)+ "<br/><br/>"
   $message += "Email: $($_.mail)<br/><br/>"
   $message += "<hr/><br/>"
   }
   $message
   }

As a result, when every new user is created, their manager will receive a separate email.

How to notify a suspended users manager with a text saying that the account is suspended

You can configure the Output section of Suspend User web action so that when a user account is suspended user manager will get a notification message. The message text can be different for immediate suspension and scheduled suspension.

Send notification on immediate suspend

To notify a suspended users manager when a user account is suspended, you should do the following:

1. Navigate to Home > Configuration > Web Portal > Web Actions.
2. Click Active Directory > Suspend User web action.
3. Click Change Output Type and select Send as E-mail with attached report.
4. Click OK.
5. Add this code into To field: $(GetMailPropertyByDn -ObjectDN  $FoundObject.manager)
   Note: If the manager attribute is empty you can send a notification to the initiator of the user suspension:
   { if($Null -ne $FoundObject){$emailToSend=$Null; if(-not [string]::IsNullOrWhiteSpace($FoundObject.manager)){$emailToSend = (GetMailPropertyByDn -ObjectDN ($FoundObject.manager))}; if([string]::IsNullOrWhiteSpace($emailToSend)){ $initiatorTag = GetInitiatorInfoTag; $initiatorTag.mail; }else{ $emailToSend; } } }.InvokeReturnAsIs()
   
6. Add this code into the Message field: 

   {
   $managerName = "Manager"
   if($FoundObject.manager -ne $Null){
   $mgr = Get-ADUser -Identity $FoundObject.manager -Properties * -ErrorAction Ignore
   if($mgr -ne $Null){
   $managerName = $mgr.DisplayName
   }
   }

   $message = 
   "
   Dear $managerName<br/><br/>
   This account was suspended: $($FoundObject.givenName) $($FoundObject.sn).<br/><br/>
   Date of suspend $($FixedSuspendDate.ToShortDateString())

   User home directory: $($FoundObject.homeDirectory)<br/>
   "

   $message
   }.InvokeReturnAsIs()

7.  Save changes.

Send different notifications on immediate and scheduled suspend

To send different text for different suspend modes you can use this script in the Message setting in the Output section:

{ $message1="User suspend was scheduled." + " Suspend Date:" + $($FixedSuspendDate.tostring(“MM-dd-yyyy”)); 
$message2="User was suspended." + " Suspend Date:" + $($FixedSuspendDate.tostring(“MM-dd-yyyy”)); 
 if($SuspendMode -eq 'true'){ $message1 }
 else{ $message2 } 
}.InvokeReturnAsIs()

How to add to the output email the name of the user that clicked on the Suspend web action

You can configure the Output section of Suspend User web action so that when a user account is suspended user manager will get a notification message with detailed information. For example, the name of the user that clicked on the Suspend web action. 

When a user is suspended, to get the output email with the name of the user that clicked on the Suspend action, you should do the following:

1. In Administrator Console navigate to Home > Configuration > Web Portal > Web Actions.
2. Click Active Directory > Suspend User web action.
3. Click Change Output Type and select Send as E-mail with attached report.
4. Click OK.
5. Add this code into the Message field: 
   Note: This approach to getting the name of the user that clicked Suspend action is valid only if you have one managed domain in your environment.

    1. To use initiator Display Name:

   {
   $message = 
   "
   This account was suspended by: $((Get-ADUser -Identity $SelfServiceUserIdSid -Properties DisplayName).DisplayName).<br/><br/>

   "

   $message
   }.InvokeReturnAsIs()

   2. To use initiator cn:  $((Get-ADUser -Identity $SelfServiceUserIdSid).Name)
   3. To use initiator samAccountName: $CayoInitiator
6.  Save changes.

How to include the service machine name into an automation rule output email

In some cases, it may be useful to know the service machine name where the automation rule was run. 

To include the service machine name, where the automation rule was run, into an automation rule output email, you should perform the following steps:

1. In Administrator Console navigate to the automation rule in which you want to add the information about where it was run.
2. In the rule Output section change the Rule Output Type. For example, select Send as E-mail with attached report.
3. Add this script into Subject field:  $RuleName Run on $($env:COMPUTERNAME)
   Note: For Fully Qualified Domain Name use this script: $($env:COMPUTERNAME + "." + $env:USERDNSDOMAIN.ToLower())
4. Click Save Changes.

How to customize an output email when provisioning new users with New User web action

Every Cayosoft Administrator rule and web action can send execution results in email, so you can get rule output in a convenient friendly view. Cayosoft Administrator provides two types of email: Report and Alert. The difference between them is that Report always contains a table with rule results, and the Alert has only a text specified in a Message setting and does not contain such a table. 

When provisioning new user accounts in Web Interface by New User action, such output emails can be very useful. You can customize these emails and include some welcome messages for new users.

In this example we will configure the New User action so it will send an alert message to a new user's manager, and include new user login information into the email body: 

1. In Administrator Console navigate to Home > Configuration > Web Portal.
2. Click Web Actions > Active Directory > New User.
3. In the Output section, click on the Change Output Type link and select Send E-mail Alert option.
4. Click OK.
5. Set CC: field to: (GetMailPropertyByDn $ManagerObjectID)

1. Replace the default alert message with this one:
   

   {
   $header = "New user created<br/><br/>"

   $body = "Full name: $Fullname<br/>
   Logon name: $SamAccountNameDomain$samGenerated<br/>
   Email: $mailtoset<br/>
   Password: $pwdToSet<br/>"

   $message = $header + $body

   $message
   }.InvokeReturnAsIs()

2. Click Save Changes.

Tokens that can be used in New User email output message

You can use these tokens in rules that are defined in 'Rules to run after this rule' section of a web action as well.

How to send email to users that are in the rule scope

One of the typical scenarios is when you need to send an email to some users in your organization. For example, send an email with some information to users whose accounts have been created in the last 30 days.

Configuration:

1. Create AD Users report. For details, please see the Working with rules article.

2. Change rule Output type to Send Email Alert.

3. Add mail attribute to Properties to display and System properties in AD Users report.

4. To get users that were created for the last 30 days, add this code to Initialization Script: section: {$global:DatePeriod = (Get-Date).AddDays(-30)}

5. Add filter to Query Criteria: {whenCreated -ge $DatePeriod}

6. Add this script to To field: { $emails=@(); ($LastResult | %{ if($Null -ne $_ -and $_.mail -ne ''){$emails += $_.mail; }}); $emails; }.InvokeReturnAsIs()

7. Specify the Subject and Message.

8. Save changes.

How to notify the initiator when his operation is completed

There are situations when you need to send an email to the initiator when his operation is completed.

In this example, we will configure the New Team web action so it will send a notification email to a user who created this team, and include the team name and creation date, and time in the email body: 

1. In Administrator Console navigate to Home > Configuration > Web Portal > Web Actions > Microsoft 365 > New Team web action.
2. Click Change Output Type and select Send E-mail alert.
3. Click OK.
4. Add this code into the To field: $(GetInitiatorProperty "mail") 
5. Add this code into the Message field:
   {
   $message =
   "
   Team name: $DisplayName <br/>
   Date: $(Get-Date)
   "
   $message
   }.InvokeReturnAsIs()
6. Save changes.

How to add to the auto-reply message in Suspend | Office 365 User and Guest rule the names of the user and his manager

To add the names of the user and his manager to auto-reply email you need to set the script below into the Autoreply Message field in Home > RULES > WebAdmin Rules (Pre-configured) > Suspend | Office 365 User and Guest:

{
 try {
  $userCgraphRes = Get-CGraphResource user -Identifier $FoundObject.UserPrincipalName -Expand Manager -Beta
 } catch{ }

 if($Null -ne $userCgraphRes -and $Null -ne $userCgraphRes.Manager){
  $manager = $userCgraphRes.Manager
  $managerDisplayName = $manager.DisplayName
  $managerUPN = $manager.UserPrincipalName
  $managerMail = $manager.Mail

  $text = "User " +  $userCgraphRes.DisplayName + " is suspended. Please contact " + $managerDisplayName + " at " + $managerMail 
  $text
 }
}.InvokeReturnAsIs()

This script sets an auto-reply message to this: "User <User Name> is suspended. Please contact <Manager Name> at <Manager email>".

How to add the names of Active Directory objects deleted in Web Portal to an email alert

Use the following script in the Message setting of the Output section for the Delete web action:

1. Open Cayosoft Administrator Console.
2. Navigate to Delete web action for the corresponding object.
3. In the Output section paste the following script to the Message setting:
   

   {
   $header = "<H3>These objects are deleted:</H3>"
   $body = "
   <table>
     <tr>
       <td><b>Deleted by:</b></td><td>$((Get-ADUser -Identity $SelfServiceUserIdSid -Properties DisplayName).DisplayName)</td>
     </tr>  
     <tr>
       <td><b>Client:</b></td><td>" 
   $CayoSelectedObjectsIds | %{ 
   $body += " $(ExtractNameFromDN $_.ObjectDN)"
   }
   $body += "  </td></tr>  
   </table>
   "        
       
   $message = $header + $body
   $message
   }.InvokeReturnAsIs()

4. Click Save Changes to apply new settings.
   
   

How to send emails to different recipients based on a user attribute

The AD Users | Send Email Notification rule can be configured to send emails to different recipients based on the attribute values of the users in the rule scope. In the example below, the user email location will be defined based on the physicalDeliveryOfficeName user attribute. 

1. Create AD Users | Send Email Notification rule.
2. Specify the rule scope: define Limit scope and Query criteria settings.
3. Specify user emails in the To setting.
4. Copy\paste this script into the Message setting:
   

   {
   $AccountName = $FoundObject.sAMAccountName
   $Fullname = $FoundObject.displayName
   $location = $FoundObject.physicalDeliveryOfficeName
   
   Function getLocationEmail($location){
   switch($location){
   "Boston" {$emailLocation = "user_boston"}
   "Hong Kong" {$emailLocation = "user_hongkong"}
   default {$emailLocation = "user_boston"}
   }
   $emailLocation
   }
   
   $emailLocation = (getLocationEmail -location $location)
   
   "Login:          $AccountName
   <br/>
   Name:           $Fullname
   <br/>
   Email Location: $emailLocation
   <br/>
   This template is to notify User Support/Desktop Support for an upcoming firm departure. 
   "
   }

5. Add the following attributes to the System Properties:
   1. SamAccountName
   2. physicalDeliveryOfficeName
6. Save changes.

Rules with additional email delivery settings in the Action section

Cayosoft Administrator provides a set of automation rules that have additional delivery settings in the Action section:

1. Text file | Create AD Users
2. Import SQL Data | Create AD Users
3. Import Oracle Data | Create AD Users
4. Text file | Create AD Users with Remote Linked Mailbox
5. Import SQL Data | Create AD Users with Remote Linked Mailbox
6. Import Oracle Data | Create AD Users with Remote Linked Mailbox
7. AD Users | Send Password Expiration Notification
8. AD Group Manager | Group Management Self-Service Notification 
9. AD Users | Notify Manager Subordinate Account Expiring
10. AD Users | Self-Service Enrollment Reminder Notification
11. AD Users | Self-Service Enrollment Welcome Notification
12. AD Users | Send Password Expiration Notification
13. Office 365 Licenses | Low License Count Notification
14. Execution History | Notify Administrator About Errors
15. Suspend | Office 365 User
16. AD Users | Send Email Notification
17. AD Groups | Send Email Notification
18. Office 365 Users | Send Notification

In these rules, in the Action section where the email message is configured, you can also use the variables from the table above to add additional user information.

Click here to get an example of how to customize additional delivery settings in the Action section to notify the manager about created users and include employee login information. So that the manager can print this email and give it to a new employee on his first day of work.  

Related Articles 

How to customize font in Cayosoft Output E-mail