Customizing an automation rule or web action output email

Overview

In Cayosoft Administrator, every automation rule and web action can be configured to send an email as an output. You can set up a rule or web action to send a report when it finishes and select the report type in the Rule Output section. In some cases, you may need to customize the default email and include additional user attribute values in the email body, subject, and the To field in automation rules and web actions. The article lists customization scenarios to implement in your environment.

Customizing email subject and message

NOTE: When you customize the automation rule, the AD user property used must be added to the Properties to display list to display the setting.

You can add any user property value to the email subject and message in the following format:

$($FoundObject.<AD User Property>)

Replace the <AD User Property> placeholder with the LDAP name of the user property.

NOTE: If you use some text in quotas inside an email message, these quotas must be quoted - add one more double quote before double quotas. For example, if you add an URL to your message, it should look like this: <a href=""https://domain.com"">

Refer to the following examples to add to the email subject or message an additional user:

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 rule, Import SQL Data | Create AD Users rule, or Import Oracle Data | Create AD Users rule. 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.

To 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 the Notify Manager section.

3. Set the 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 the Cayosoft Administrator Console, open a provisioning rule, for example, Text file | Create AD Users.

2. Expand the Notify Manager section.

3. Set the 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:

   Copy

   {
   $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 Rule Output section of the Suspend web action (Active Directory users) 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, do the following:

1. In the Cayosoft Administrator Console, navigate to Home > Configuration > Web Portal > Web Actions.

2. Click Active Directory > .

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:

   Copy

   { 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:

   Copy

   {
   $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 Rule Output section of the Suspend web action (Active Directory users) 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 the Cayosoft Administrator Console, navigate to Home > Configuration > Web Portal > Web Actions.

2. Click Active Directory > Suspend web action (Active Directory users).

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:

      Copy

      {
      $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 the Cayosoft Administrator Console, navigate to the automation rule in which you want to add the information about where it was run.

2. In the rule 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:

   Copy

   $RuleName Run on $($env:COMPUTERNAME)

   NOTE: For Fully Qualified Domain Name use this script:

   Copy

   $($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 the Cayosoft Administrator Console, navigate to Home > Configuration > Web Portal.

2. Click Web Actions > Active Directory > New User.

3. In the Output section, click the Change Output Type link and select Send E- mail Alert option.

4. Click OK.

5. Set CC: field to: (GetMailPropertyByDn $ManagerObjectID)

   NOTE: Use the "CC:" field instead of replacing the default "To:" value because if you don't set Manager on the New User form when creating an account, the message won't be sent and the New User command execution result will show an error message on the Web UI Results screen.

6. 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()

7. 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

NOTE: 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

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

2. Change rule Rule Output section 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 the 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 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 the Cayosoft 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:

   Copy

   {
   $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

For Legacy Suspend (versions 10.2 and low)

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 .

For that, navigate to Home > RULES > WebAdmin Rules (Pre- configured) > Suspend | Office 365 User and Guest rule:

Copy

{
 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()

To add the names of the user and his manager to the auto-reply email, you need to set the script below into the Autoreply Message field in the Modern Suspend Configuration:

{
 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;
 }

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

How to send an email to the user's manager with the user's OneDrive link on suspend

Use the following script in the Message setting in the Email Notifications section in the Modern Suspend Configuration:

Hello $($Manager.DisplayName),<br/><br/>
Account $($SuspendObject.DisplayName) was suspended by $Initiator on $($SuspendDate).<br/><br/>
You now have access to their OneDrive<br/>
<a href="$(GetOneDriveSite $global:SuspendObject.UserPrincipalName)">OneDrive Link</a>

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. In the Cayosoft Administrator Console, navigate to the Delete web action for the corresponding object.

2. In the Output section paste the following script to the Message setting:

   Copy

   {
   $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 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 the AD Users | Send Email Notification rule 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.

How to send an email to a manager with the list of subordinates whose accounts are expiring

The AD Users | Notify Manager Subordinate Account Expiring rule e-mails the person listed as the manager of an account that is about to expire. In the example below, the manager of such accounts will get an email that also includes details of the accounts about to expire.

1. Create the AD Users | Notify Manager Subordinate Account Expiring rule.

2. Specify the rule scope: define Limit scope and Expires in less than (days) settings.

3. Сopy/paste this script below into the Message setting in the Action section.

   Copy

   Hello $($FoundObject.givenName),<br/><br/>
   You are listed as the manager for an account that is about to expire. <br/>
   
   $(
   $outStr='<table><tr><th>AccountExpires</th><th>Display Name</th><th>Description</th><th>UserPrincipalName</th><th>Manager (mail)</th></tr>';
   $managerMail=$FoundObject.mail;
   $correctParam = (PMEXTAD_GetADSettingsByDN -ObjectDN $FoundObject.DistinguishedName)
   $managers[$FoundObject.DistinguishedName] | %{
   $cuser=$_; if($Null -eq $cuser){ return };
   $user = Get-ADUser -Filter {UserPrincipalName -eq $cuser} @correctParam -Properties AccountExpires,UserPrincipalName,Description,DisplayName;
   if($Null -eq $user){ return };
   $retAE='';
   if( $user.AccountExpires -ne $null -and $user.AccountExpires[0] -ne 0 -and $user.AccountExpires[0] -ne 9223372036854775807){ $AccountExpirationDate = [datetime]::FromFileTime($user.AccountExpires[0]);$retAE = $AccountExpirationDate.addDays(-1).ToString();};
   $outStr +='<tr>';
   $outStr +='<td>' + $retAE + '</td>';
   $outStr +='<td>' + $user.DisplayName + '</td>';
   $outStr +='<td>' + $user.Description + '</td>';
   $outStr +='<td>' + $user.UserPrincipalName + '</td>';
   $outStr +='<td>' + $managerMail + '</td>';
   $outStr +='</tr>';
   }
   $outStr += '</table>';
   $outStr;
   )
   
   Thank you,<br/>
   Cayosoft Administrator

4. Save changes.

How to schedule email reminders for managers of suspended users

Managers of suspended users may benefit from reminders to review the recently suspended users. You can customize the user Suspend configuration to send email reminders to managers a certain number of days after the suspension. The guide applies to both AD user Suspend and Microsoft 365 user Suspend configurations. Depending on the target platform, use the specified script. Both scripts contain the following customizable variables:

• The $defaultEmail variable is a fall-back email in case the manager user has no email attribute defined.

• The $mailSubject variable is a subject line.

• The $mailBody variable is the email body.

Refer to the following steps:

1. In the left pane of the Cayosoft Administrator console, navigate to Rules > Suspend Configurations, and select the required user Suspend configuration. Alternatively, create a copy of the required user Suspend configuration to use it separately. Refer to the following article to learn more about creating custom Suspend configurations: Modern Suspend Configuration.

2. In the configuration, locate the Schedule delayed operations dropdown. Expand it and click Add.

   

3. In the Operation dropdown, select Custom script. Copy a script based on the platform and paste it in the Suspend script field. Click OK to save changes.

   • Use the following script for the Active Directory user Suspend configuration:

     Copy

     {
         $defaultEmail="XXX@defaultNotify.email";
         $mailBody="TEST MESSAGE ABOUT USER $($suspendContext.SuspendedObject.DisplayName)";
         $mailSubject ="This is subject of email.";
         ####
         $managerEmail = $Null;
         try{ $managerEmail = (GetMailPropertyByDn ($suspendContext.SuspendOperationInfo.BeforeSuspendState | ConvertFrom-Json).Manager) }catch{ }
         ClearErrorStream
         if("$managerEmail" -eq ""){ $managerEmail = $defaultEmail;}; 
         [void](Cayo-SendMailMessage -InputObject $Null -From $SMTP_From -To $managerEmail -Subject $mailSubject -Body $mailBody -BodyAsHtml $True);
     }

   • Use the following script for the Microsoft 365 user Suspend configuration:

     Copy

     {
         $defaultEmail="XXX@defaultNotify.email";
         $mailBody="TEST MESSAGE ABOUT USER $($suspendContext.SuspendedObject.DisplayName)";
         $mailSubject ="This is subject of email.";
         ####
         $managerEmail = $Null;
         try{ $managerEmail = ($suspendContext.SuspendOperationInfo.BeforeSuspendState | ConvertFrom-Json).ManagerObject.UserPrincipalName }catch{ }
         ClearErrorStream
         if("$managerEmail" -eq ""){ $managerEmail = $defaultEmail;}; 
         [void](Cayo-SendMailMessage -InputObject $Null -From $SMTP_From -To $managerEmail -Subject $mailSubject -Body $mailBody -BodyAsHtml $True);
     }

4. In the new Custom Script operation, expand the Behavior dropdown and select the Delayed execution after suspend option.

   

5. Specify the desired time window between the suspension and the email in the Delay (days) field. Click Save Changes to complete the setup.

   NOTE: If you would like to send the reminder multiple times, create the corresponding number of Custom script operations.

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 rule

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 rule

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 rule

11. AD Users | Self-Service Enrollment Welcome Notification rule

12. AD Users | Send Password Expiration Notification rule

13. Office 365 Licenses | Low License Count Notification

14. Execution History | Notify Administrator About Errors

15. Suspend | Office 365 User and Guest rule

16. AD Users | Send Email Notification rule

17. AD Groups | Send Email Notification rule

18. Office 365 Users | Send Notification rule

    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.

    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. Learn more in: How to customize Notify Manager email in bulk provisioning rules