Send email on adding members to groups

You can configure Adaxes to automatically send an email notification when a certain operation takes place in your directory. This is done using business rules. In this tutorial, you will learn how to create a business rule to send an email message when a new member is added to a group.

Business rules trigger only for operations performed via Adaxes. To handle changes made outside of Adaxes, e.g. using Active Directory Users and Computers or Microsoft Entra admin center, you can use scheduled tasks.

  1. Launch Adaxes Administration console.

     How {id=collapse1}
    • On the computer where Adaxes Administration console is installed, open Windows Start menu.

    • Click Adaxes Administration Console.

  2. Right-click your Adaxes service, point to New and click Business Rule.

  3. Enter a name for the new business rule and click Next.

  4. To trigger the business rule after adding a member to a group:

    • Select Group.

    • Select After adding a member to a group.

  5. Click Next.

  6. Click Add an action.

  7. Select the Send e-mail notification action.

  8. In the Action Parameters section, customize the email notification template.

    To insert information about the group, new member and operation initiator, use value references. To insert a value reference, click the button.

    Examples

    • %mail% – email address of the group.
    • %adm-MemberEmail% – email address of the new member.
    • %adm-MemberFullName% – full name of the new group member.
    • %adm-InitiatorFullName% – full name of the operation initiator.
    • %adm-InitiatorUserName% – user principal name of the operation initiator.
    • %name% – name of the group.
    • %member% – distinguished name (DN) of the new member.
    • %adm-OperationDescription% – the operation description.

    Example

    Group: %name%
    New member: %adm-MemberFullName%
    Initiator: %adm-InitiatorFullName% (%adm-InitiatorUserName%)
    Operation: %adm-OperationDescription%
    

    After replacing value references, the notification text will be as follows:

    Group: Admins
    New member: John Doe
    Initiator: Aaron Dorben (aaron.dorben@example.com)
    Operation: Add 'John Doe (example.com\Users)' to 'Admins (example.com\Groups)'
    

    To send notifications in the HTML format, select HTML in the drop-down list next to the Message field.

    Using scripts

    It is also possible to send email notifications using a PowerShell script. This is helpful if you need to build the list of recipients based on specific conditions, or if you need to alter the email body depending on the group / new member.

     How {id=use_script_to_request_approval}
    • In the Add Action dialog, select the Run a program or PowerShell script action.

    • Click the Edit button.

      Click the button to provide a custom description for the action.

    • To send an email message from a script, call the SendMail method of the predefined PowerShell variable $Context.

      Example 1 – Send email to the primary group owner.

      if ([string]::IsNullOrEmpty("%adm-ManagedByEmail%"))
      {
          # Primary owner has no email.
          return
      }
      
      $to = "%adm-ManagedByEmail%"
      $subject = "New member added to %name%"
      $bodyText =
      @"
      New member: %member%
      Initiator: %adm-InitiatorFullName% (%adm-InitiatorUserName%)
      Group name: %name%
      Group DN: %distinguishedName%
      Operation: %adm-OperationDescription%
      "@
      $bodyHtml = $null
      $Context.SendMail($to, $subject, $bodyText, $bodyHtml)
      

      Value reference %adm-ManagedByEmail% will be replaced with the value of the Email property of the primary group owner. Primary owner is available only in Active Directory.

      Example 2 – Send email to all group owners.

      # Get all owners.
      $ownerDNs = $Context.TargetObject.GetPropertyValues("adm-Owners")
      if (-not $ownerDNs)
      {
          # Group has no owners.
          return
      }
      
      # Get email addresses of all owners.
      $allOwnerEmails = @()
      foreach ($dn in $ownerDNs)
      {
          $owner = $Context.BindToObjectByDN($dn)
          $ownerEmail = $owner.GetPropertyValue("mail")
          if ($ownerEmail)
          {
              $allOwnerEmails += $ownerEmail
          }
      }
      
      # Send email.
      if ($allOwnerEmails.Count > 0)
      {
          $to = $allOwnerEmails -join ","
          $subject = "New member added to %name%"
          $bodyText = 
      @"
          New member: %member%
          Initiator: %adm-InitiatorFullName% (%adm-InitiatorUserName%)
          Group name: %name%
          Group DN: %distinguishedName%
          Operation: %adm-OperationDescription%
      "@
          $bodyHtml = $null
          $Context.SendMail($to, $subject, $bodyText, $bodyHtml)
      }
      

      For more details about object ownership in Adaxes, see Object owners.

      Example 3 – Send email to the manager of the new member.

      $member = $Context.BindToObjectByDN("%member%")
      try
      {
          $memberManagerDN = $member.Get("manager")
          $manager = $Context.BindToObjectByDN($memberManagerDN)
          $to = $manager.Get("mail")
      }
      catch
      {
          # New member has no manager or the manager has no email.
          return
      }
      $subject = "New member added to %name%"
      $bodyText =
      @"
      New member: %adm-MemberFullName%
      Initiator: %adm-InitiatorFullName% (%adm-InitiatorUserName%)
      Group name: %name%
      Group DN: %distinguishedName%
      Operation: %adm-OperationDescription%
      "@
      $bodyHtml = $null
      $Context.SendMail($to, $subject, $bodyText, $bodyHtml)
      

      For information on how to create scripts for business rules, custom commands, and scheduled tasks, see Server-side scripting.

  9. Conditions

    To send email notifications only if certain conditions are met, right-click the action and then click Add Condition.

    Example 1 – If the new member is from the IT department.

     Step by step
    • Select the If <property of the member> <relation> <value> condition.

    • In the Condition Parameters section, specify If department equals IT.

    • Click OK.

    Example 2 – If the new member is also a member of another group.

     Step by step
    • Select the If the member is a member of <group> condition.

    • In the Condition Parameters section, select is in the drop-down list and specify the group.

    • Click OK.

    Example 3 – If the initiator is not a member of a specific group.

     Step by step
    • Select the If the initiator is a member of <group> condition.

    • In the Condition Parameters section, select is not in the drop-down list and specify the group.

    • Click OK.

    Example 4 – If the initiator is not a member of the same group.

     Step by step
    • Select the If the initiator is a member of <group> condition.

    • In the Condition Parameters section, select is not in the drop-down list, and click the button.

    • Activate the Template tab.

    • In the Template field, enter %distinguishedName%.

      Value reference %distinguishedName% will be replaced with the DN of the group where the new member is added.

    • Click OK.

    Example 5 – If the initiator and the group are not in the same organizational unit.

     Step by step
    • Select the If located under <location> condition.

    • In the Condition Parameters section, select is not in the drop-down list, and click the button.

    • Activate the Template tab.

    • In the Template field, enter %adm-InitiatorParentDN%.

      Value reference %adm-InitiatorParentDN% will be replaced with the DN of the organizational unit where the account of the initiator is located.

    • Click OK.

    When done, click Next.

  10. On the Activity Scope step, click Add.

    Select the following items:

    • All Objects – select to send notifications when a member is added to any group in any domain managed by Adaxes.

    • Domain – select to send notifications when a member is added to any group located in a specific domain.

    • OU or Container – select to send notifications when a member is added to a group located in an organizational unit or container.

    • Group – select to send notifications when a member is added to a specific group, or a group that is a member of the selected group.

    • Business unit – select to send notifications when a member is added to a group that belongs to a business unit. To select a business unit, open the Look in drop-down list and select Business Units.

    You can exclude groups, organizational units and business units from the activity scope of the business rule. For example, if you've assigned the rule over all groups in a domain, but don't want the rule to trigger for groups in a specific OU, you can exclude that OU from the activity scope. To exclude an object, select the Exclude the selection option in the Assignment Options dialog box.

     Step by step {id=exclude_scope}
    • Click the object you want to exclude.

    • In the Assignment Options dialog, select the Exclude the selection option.

    • Click OK.

    When done, click OK.

  11. Click Finish.