Initial version of the Snippet

Tools4everBV · Oct 3, 2023 · 5f4e52c · 5f4e52c
1 parent a38edf0
commit 5f4e52c
Show file tree

Hide file tree

Showing 3 changed files with 116 additions and 0 deletions.
diff --git a/action.ps1 b/action.ps1
@@ -0,0 +1,77 @@
+# HelloID-Task-SA-Target-ExchangeOnPremises-DistributionGroupGrantMembership
+############################################################################
+# Form mapping
+$formObject = @{
+    GroupIdentity = $form.GroupIdentity
+    UsersToAdd    = [array]$form.Users
+}
+
+[bool]$IsConnected = $false
+try {
+    $adminSecurePassword = ConvertTo-SecureString -String $ExchangeAdminPassword -AsPlainText -Force
+    $adminCredential = [System.Management.Automation.PSCredential]::new($ExchangeAdminUsername, $adminSecurePassword)
+    $sessionOption = New-PSSessionOption -SkipCACheck -SkipCNCheck
+    $exchangeSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri $ExchangeConnectionUri -Credential $adminCredential -SessionOption $sessionOption -Authentication Kerberos  -ErrorAction Stop
+    $null = Import-PSSession $exchangeSession -DisableNameChecking -AllowClobber -CommandName 'Add-DistributionGroupMember'
+    $IsConnected = $true
+
+    foreach ($user in $formObject.UsersToAdd) {
+        try {
+            Write-Information "Executing ExchangeOnPremises action: [DistributionGroupGrantMembership] for: [$($formObject.GroupIdentity)]"
+            $null = Add-DistributionGroupMember -Identity $formObject.GroupIdentity -Member $user.UserPrincipalName -Confirm:$false -ErrorAction Stop
+
+            $auditLog = @{
+                Action            = 'GrantMembership'
+                System            = 'ExchangeOnPremises'
+                TargetIdentifier  = $formObject.GroupIdentity
+                TargetDisplayName = $formObject.GroupIdentity
+                Message           = "ExchangeOnPremises action: [DistributionGroupGrantMembership] user [$($user.UserPrincipalName)] to: [$($formObject.GroupIdentity)] executed successfully"
+                IsError           = $false
+            }
+            Write-Information -Tags 'Audit' -MessageData $auditLog
+            Write-Information "ExchangeOnPremises action: [DistributionGroupGrantMembership] user [$($user.UserPrincipalName)] to: [$($formObject.GroupIdentity)] executed successfully"
+        } catch {
+            $ex = $_
+            if ($ex.CategoryInfo.Reason -eq 'MemberAlreadyExistsException') {
+                $auditLog = @{
+                    Action            = 'GrantMembership'
+                    System            = 'ExchangeOnPremises'
+                    TargetIdentifier  = $formObject.GroupIdentity
+                    TargetDisplayName = $formObject.GroupIdentity
+                    Message           = "ExchangeOnPremises action: [DistributionGroupGrantMembership] user [$($user.UserPrincipalName)] to: [$($formObject.GroupIdentity)] executed successfully"
+                    IsError           = $false
+                }
+                Write-Information -Tags 'Audit' -MessageData $auditLog
+                Write-Information "ExchangeOnPremises action: [DistributionGroupGrantMembership] user [$($user.UserPrincipalName)] to: [$($formObject.GroupIdentity)] executed successfully"
+            } else {
+                $auditLog = @{
+                    Action            = 'GrantMembership'
+                    System            = 'ExchangeOnPremises'
+                    TargetIdentifier  = $formObject.GroupIdentity
+                    TargetDisplayName = $formObject.GroupIdentity
+                    Message           = "Could not execute ExchangeOnPremises action: [DistributionGroupGrantMembership] user [$($user.UserPrincipalName)] to: [$($formObject.GroupIdentity)], error: $($ex.Exception.Message)"
+                    IsError           = $true
+                }
+                Write-Information -Tags 'Audit' -MessageData $auditLog
+                Write-Error "Could not execute ExchangeOnPremises action: [DistributionGroupGrantMembership] user [$($user.UserPrincipalName)] to: [$($formObject.GroupIdentity)], error: $($ex.Exception.Message)"
+            }
+        }
+    }
+} catch {
+    $ex = $_
+    $auditLog = @{
+        Action            = 'GrantMembership'
+        System            = 'ExchangeOnPremises'
+        TargetIdentifier  = $formObject.GroupIdentity
+        TargetDisplayName = $formObject.GroupIdentity
+        Message           = "Could not execute ExchangeOnPremises action: [DistributionGroupGrantMembership] to: [$($formObject.GroupIdentity)], error: $($ex.Exception.Message)"
+        IsError           = $true
+    }
+    Write-Information -Tags 'Audit' -MessageData $auditLog
+    Write-Error "Could not execute ExchangeOnPremises action: [DistributionGroupGrantMembership] to: [$($formObject.GroupIdentity)], error: $($ex.Exception.Message)"
+} finally {
+    if ($IsConnected) {
+        Remove-PSSession -Session $exchangeSession -Confirm:$false  -ErrorAction Stop
+    }
+}
+############################################################################
diff --git a/icon.png b/icon.png
diff --git a/readme.md b/readme.md
@@ -0,0 +1,39 @@
+
+# HelloID-Task-SA-Target-ExchangeOnPremises-DistributionGroupGrantMembership
+
+## Prerequisites
+Before using this snippet, verify you've met with the following requirements:
+- [ ] User defined variables: `$ExchangeAdminUsername`, `$ExchangeAdminPassword` and `$ExchangeConnectionUri` created in your HelloID portal. [See also Custom Variables](https://docs.helloid.com/en/variables/custom-variables.html)
+
+## Description
+
+This code snippet executes the following tasks:
+
+1. Define a hash table `$formObject`. The keys of the hash table represent the properties of the `Add-DistributionGroupMember` cmdlet, while the values represent the values entered in the form.
+
+> To view an example of the form output, please refer to the JSON code pasted below.
+
+```json
+{
+    "GroupIdentity": "TestDistributionGroup",
+    "Users": [
+        {
+            "UserPrincipalName": "jan@connectors.com"
+        },
+        {
+            "UserPrincipalName": "koppelaar@connectors.com"
+        }
+    ]
+}
+```
+
+> :exclamation: It is important to note that the names of your form fields might differ. Ensure that the `$formObject` hashtable is appropriately adjusted to match your form fields.
+> The **GroupIdentity** can hold different values [See the Microsoft Docs page](https://learn.microsoft.com/en-us/powershell/module/exchange/add-distributiongroupmember?view=exchange-ps)
+
+2. Constructs a PowerShell credential object from the supplied administrative username and password
+
+3. Connects with the credentials to the Exchange on premises environment by means of the `New-PSSession` cmdlet
+
+4. Calls the `Add-DistributionGroupMember` cmdlet to add the users to the DistributionGroup
+
+5. Disconnects from the Exchange session by means of the `Remove-PsSession` cmdlet