Merge pull request #22 from teamviewer/Import-TeamViewerUser_FormatAndScriptAnalyzer

Import-TeamViewerUser: format & ScriptAnalyzer

Author: ChristianJ-TV

Import-TeamViewerUser/Import-TeamViewerUser.Tests.ps1

@@ -1,12 +1,10 @@
-# Copyright (c) 2019-2021 TeamViewer GmbH
-# See file LICENSE.txt
+# Copyright (c) 2019-2023 TeamViewer Germany GmbH
+# See file LICENSE
 
 BeforeAll {
     $testApiToken = [securestring]@{}
-    . "$PSScriptRoot\Import-TeamViewerUser.ps1" `
-        -ApiToken $testApiToken `
-        -Path "testPath" `
-        -InformationAction 'SilentlyContinue'
+
+    . "$PSScriptRoot\Import-TeamViewerUser.ps1" -ApiToken $testApiToken -Path 'testPath' -InformationAction 'SilentlyContinue'
 
     Mock Invoke-TeamViewerPing { $true }
     Mock Get-TeamViewerUser {}
@@ -20,16 +18,19 @@ BeforeAll {
 Describe 'Import-TeamViewerUser' {
     It 'Should check the connection to the TeamViewer API' {
         { Import-TeamViewerUser } | Should -Not -Throw
+
         Assert-MockCalled Invoke-TeamViewerPing -Times 1 -Scope It
     }
 
     It 'Should abort if TeamViewer API is not reachable' {
         Mock Invoke-TeamViewerPing { $false }
+
         { Import-TeamViewerUser -ErrorAction Stop } | Should -Throw
     }
 
     It 'Should check for existence of a user' {
         $testUser | Import-TeamViewerUser
+
         Assert-MockCalled Get-TeamViewerUser -Times 1 -Scope It -ParameterFilter {
             $Email -And $Email -eq $testUser.email
         }
@@ -39,7 +40,7 @@ Describe 'Import-TeamViewerUser' {
         BeforeAll {
             Mock Get-TeamViewerUser {
                 @{
-                    Id    = 'u1234';
+                    Id    = 'u1234'
                     Email = $testUser.email
                     Name  = 'Old Name'
                 }
@@ -51,6 +52,7 @@ Describe 'Import-TeamViewerUser' {
             $result | Should -Not -BeNullOrEmpty
             $result.Updated | Should -Be 1
             $result.Created | Should -Be 0
+
             Assert-MockCalled Set-TeamViewerUser -Times 1 -Scope It -ParameterFilter {
                 $User -And $User.Id -eq 'u1234' -And
                 $Property -And $Property -eq $testUser
@@ -59,6 +61,7 @@ Describe 'Import-TeamViewerUser' {
 
         It 'Should acknowledge errors and continue' {
             Mock Set-TeamViewerUser { Write-Error 'test failure' }
+
             $result = ($testUser | Import-TeamViewerUser)
             $result | Should -Not -BeNullOrEmpty
             $result.Updated | Should -Be 0
@@ -73,6 +76,7 @@ Describe 'Import-TeamViewerUser' {
             $result | Should -Not -BeNullOrEmpty
             $result.Created | Should -Be 1
             $result.Updated | Should -Be 0
+
             Assert-MockCalled New-TeamViewerUser -Times 1 -Scope It -ParameterFilter {
                 $Email -And $Email -eq $testUser.email -And
                 $Name -And $Name -eq $testUser.name -And
@@ -88,10 +92,12 @@ Describe 'Import-TeamViewerUser' {
                 password        = 'test123'
                 sso_customer_id = 'foobar'
             }
+
             $result = ($testUser2 | Import-TeamViewerUser)
             $result | Should -Not -BeNullOrEmpty
             $result.Created | Should -Be 1
             $result.Updated | Should -Be 0
+
             Assert-MockCalled New-TeamViewerUser -Times 1 -Scope It -ParameterFilter {
                 $Email -eq $testUser2.email -And
                 $Name -eq $testUser2.name -And
@@ -103,6 +109,7 @@ Describe 'Import-TeamViewerUser' {
 
         It 'Should acknowledge errors and continue' {
             Mock New-TeamViewerUser { Write-Error 'test failure' }
+
             $result = ($testUser | Import-TeamViewerUser)
             $result | Should -Not -BeNullOrEmpty
             $result.Updated | Should -Be 0

Import-TeamViewerUser/Import-TeamViewerUser.ps1

@@ -3,19 +3,15 @@
     Imports a set of users to a TeamViewer company.
 
  .DESCRIPTION
-    The script imports and updates a set of users to the TeamViewer company that
-    corresponds to a given API token. By default, the users will be loaded from
-    a given CSV-formatted file. There is also an option to pipeline userdata to
-    this script.
-    In contrast to the definition of the "Import-" verb for Powershell, this
-    script does *NOT* import the users from TeamViewer to Powershell but
-    performs the reverse operation, by creating/updating TeamViewer users.
+    The script imports and updates a set of users to the TeamViewer company that corresponds to a given API token.
+    By default, the users will be loaded from a given CSV-formatted file. There is also an option to pipeline userdata to this script.
+    In contrast to the definition of the "Import-" verb for Powershell, this script does *NOT* import the users from TeamViewer to Powershell, `
+    but performs the reverse operation, by creating / updating TeamViewer users.
 
  .PARAMETER ApiToken
     The TeamViewer API token to use.
     Must be a user access token.
-    The token requires the following access permissions:
-        - `User management: Create users, view users, edit users`
+    The token requires the following access permissions: `User management: Create users, view users, edit users`
 
  .PARAMETER Path
     Path to the CSV-formatted file to load the user data from.
@@ -26,28 +22,23 @@
     Cannot be used in combination with the `Path` CSV option.
 
  .PARAMETER Delimiter
-    The optional delimiter that is used when loading CSV data from the given
-    file path. Only works in combination with the `Path` option.
+    The optional delimiter that is used when loading CSV data from the given file path.
+    Only works in combination with the `Path` option.
 
  .PARAMETER DefaultUserLanguage
-    The fallback language code used for creating new users. This will be used
-    for the welcome email. This value is only considered if not given in the CSV
-    or pipeline user data.
+    The fallback language code used for creating new users. This will be used for the welcome email.
+    This value is only considered if not given in the CSV or pipeline user data.
 
  .PARAMETER DefaultUserPassword
-    The fallback user password used for creating new users. This value is only
-    considered if not given in the CSV or pipeline user data.
+    The fallback user password used for creating new users. This value is only considered if not given in the CSV or pipeline user data.
 
  .PARAMETER DefaultUserPermissions
-    The fallback user permissions used for creating new users. This value is
-    only considered if not given in the CSV or pipeline user data.
-    Must be a comma-separated list of user permissions.
-    See the "TeamViewer API Documentation" for valid inputs.
+    The fallback user permissions used for creating new users. This value is only considered if not given in the CSV or pipeline user data.
+    Must be a comma-separated list of user permissions, see the "TeamViewer API Documentation" for valid inputs.
 
  .PARAMETER DefaultSsoCustomerId
-    The fallback SSO customer ID, used for creating new users that are already
-    enabled and activated for SSO logins. This value is only considered if not
-    given in the CSV or pipeline user data.
+    The fallback SSO customer ID, used for creating new users that are already enabled and activated for SSO logins.
+    This value is only considered if not given in the CSV or pipeline user data.
 
  .EXAMPLE
     .\Import-TeamViewerUser 'example.csv'
@@ -79,9 +70,9 @@
     Install-Module TeamViewerPS
     ```
 
-    Copyright (c) 2019-2021 TeamViewer GmbH
-    See file LICENSE.txt
-    Version 2.0
+    Copyright (c) 2019-2023 TeamViewer Germany GmbH
+    See file LICENSE
+    Version 2.1
 #>
 
 [CmdletBinding(DefaultParameterSetName = 'File', SupportsShouldProcess = $true)]
@@ -111,25 +102,43 @@ param(
     [securestring] $DefaultSsoCustomerId
 )
 
-if (-Not $MyInvocation.BoundParameters.ContainsKey('ErrorAction')) { $script:ErrorActionPreference = 'Stop' }
-if (-Not $MyInvocation.BoundParameters.ContainsKey('InformationAction')) { $script:InformationPreference = 'Continue' }
+if (-Not $MyInvocation.BoundParameters.ContainsKey('ErrorAction')) {
+    $script:ErrorActionPreference = 'Stop'
+}
+
+if (-Not $MyInvocation.BoundParameters.ContainsKey('InformationAction')) {
+    $script:InformationPreference = 'Continue'
+}
 
-function Install-TeamViewerModule { if (!(Get-Module TeamViewerPS)) { Install-Module TeamViewerPS } }
+function Install-TeamViewerModule {
+    Write-Information 'Checking for TeamViewerPS.'
+
+    if (!(Get-Module TeamViewerPS)) {
+        Write-Information 'Installing TeamViewerPS.'
+
+        Install-Module TeamViewerPS
+    }
+}
 
 function Import-TeamViewerUser {
     Begin {
-        Write-Information "Checking connection to TeamViewer API."
+        Write-Information 'Checking connection to TeamViewer web API.'
+
         if (!(Invoke-TeamViewerPing $ApiToken)) {
-            Write-Error "Failed to contact TeamViewer API. Token or connection problem."
+            Write-Error 'Failed to contact TeamViewer web API. Token or connection problem.'
         }
+
         $statistics = @{ Created = 0; Updated = 0; Failed = 0; }
         $stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
     }
     Process {
-        if (!$_) { return }
+        if (!$_) {
+            return
+        }
 
         # Convert the input object to a hashtable
         $user = $_
+
         if (!($_ -is [System.Collections.Hashtable]) -and $_ -is [psobject]) {
             $user = @{ }
             $_.psobject.Properties | ForEach-Object { $user."$($_.Name)" = $_.Value } | Out-Null
@@ -138,15 +147,19 @@ function Import-TeamViewerUser {
         try {
             # Check if the user already exists on the TeamViewer-side
             $existingUser = (Get-TeamViewerUser -ApiToken $ApiToken -Email $user.email)
+
             if ($existingUser) {
                 # Update the existing user.
                 Write-Information "User with email '$($user.email)' found. Updating user."
+
                 Set-TeamViewerUser -ApiToken $ApiToken -User $existingUser -Property $user | Out-Null
+
                 $statistics.Updated++
             }
             else {
                 # Create a new user
                 Write-Information "No user with email '$($user.email)' found. Creating user."
+
                 $additionalParameters = @{}
 
                 if ($user.password) {
@@ -180,29 +193,35 @@ function Import-TeamViewerUser {
                     $additionalParameters['SsoCustomerIdentifier'] = $DefaultSsoCustomerId
                 }
 
-                New-TeamViewerUser `
-                    -ApiToken $ApiToken `
-                    -Name $user.name `
-                    -Email $user.email `
-                    @additionalParameters | Out-Null
+                New-TeamViewerUser -ApiToken $ApiToken -Name $user.name -Email $user.email @additionalParameters | Out-Null
+
                 $statistics.Created++
             }
         }
         catch {
             Write-Information "Failed to process user with email '$($user.email)': $_"
+
             $statistics.Failed++
         }
     }
     End {
         # Output some statistics
         $stopwatch.Stop()
         $statistics.Duration = $stopwatch.Elapsed
+
         Write-Output $statistics
     }
 }
 
 if ($MyInvocation.InvocationName -ne '.') {
     Install-TeamViewerModule
-    $Users = if ($Path) { Get-Content $Path | ConvertFrom-Csv -Delimiter $Delimiter } else { $Users }
+
+    $Users = if ($Path) {
+        Get-Content $Path | ConvertFrom-Csv -Delimiter $Delimiter
+    }
+    else {
+        $Users
+    }
+
     $Users | Import-TeamViewerUser
 }

Import-TeamViewerUser/README.md

@@ -2,12 +2,10 @@
 
 Imports a set of users to a TeamViewer company.
 
-The script imports and updates a set of users to the TeamViewer company
-that corresponds to a given API token. By default, the users will be loaded from
-a given CSV-formatted file. There is also an option to pipeline userdata to this
-script. In contrast to the definition of the "Import-" verb for Powershell, this
-script does *NOT* import the users from TeamViewer to Powershell but performs
-the reverse operation, by creating/updating TeamViewer users.
+The script imports and updates a set of users to the TeamViewer company that corresponds to a given API token.
+By default, the users will be loaded from a given CSV-formatted file. There is also an option to pipeline userdata to this script.
+In contrast to the definition of the "Import-" verb for Powershell, this script does *NOT* import the users from TeamViewer to Powershell,
+but performs the reverse operation, by creating/updating TeamViewer users.
 
 ## Prerequisites
 
@@ -39,7 +37,7 @@ $pwd = ConvertTo-SecureString 'MyPassword123' -AsPlainText -Force
 .\Import-TeamViewerUser 'example.csv' -DefaultUserPassword $pwd
 ```
 
-### Import users from Powershell data. Use the given default password as fallback.
+### Import users from Powershell data. Use the given default password as fallback
 
 ```powershell
 $users = @(
@@ -51,7 +49,7 @@ $pwd = ConvertTo-SecureString 'MyPassword123' -AsPlainText -Force
 $users | .\Import-TeamViewerUser -DefaultUserPassword $pwd
 ```
 
-### Run the import script in "Test Mode" to see the changes that would be made.
+### Run the import script in "Test Mode" to see the changes that would be made
 
 ```powershell
 .\Import-TeamViewerUser 'example.csv' -WhatIf

PSScriptAnalyzerSettings.psd1

@@ -0,0 +1,5 @@
+@{
+    Severity     = @('Error', 'Warning')
+    # ToDo: Remove excludes after Import-TeamViewerUser was adapted
+    ExcludeRules = @('PSUseProcessBlockForPipelineCommand', 'PSAvoidUsingConvertToSecureStringWithPlainText')
+}