enable API version 6.0 for Get-VSTeamUserEntitlement

.docs/Get-VSTeamUserEntitlement.md

@@ -14,6 +14,44 @@
 
 ## EXAMPLES
 
+### Example 1: Get user by Id
+
+```powershell
+Get-VSTeamUserEntitlement -Id f1ef22eb-5dd6-4e26-907c-986a0311b106
+```
+
+This command gets the user entitlement of the user identified by id.
+
+### Example 2: Get users by name
+
+```powershell
+Get-VSTeamUserEntitlement -Name username
+```
+
+This command gets a list of users which mail or user name contains 'username'.
+Filtering by Name, License, or UserType is available only when MemberEntitlementManagement service version is 6.0 or upper. See Get-VSTeamAPIVersion and Set-VSTeamAPIVersion commands
+
+
+### Example 3: Filter with some conditions
+
+```powershell
+Get-VSTeamUserEntitlement -Filter "licenseId eq 'Account-Express' and licenseStatus eq 'Disabled'"
+```
+
+This command gets a list of users that match the license status and license type conditions.
+The -Filter parameter is available only when MemberEntitlementManagement service version is 6.0 or upper. See Get-VSTeamAPIVersion and Set-VSTeamAPIVersion commands
+
+
+### Example 4: List paged users
+
+```powershell
+Get-VSTeamUserEntitlement -Skip 100 -Top 100
+```
+
+This command list the from the user in the 101 position, the next 100 users
+Filtering using the -Top -Skip parameters only works when MemberEntitlementManagement service version is below 6.0. See Get-VSTeamAPIVersion and Set-VSTeamAPIVersion commands
+
+
 ## PARAMETERS
 
 ### Skip
@@ -53,11 +91,92 @@ Comma (",") separated list of properties to select in the result entitlements.
 
 ```yaml
 Type: String
-Parameter Sets: List
+Parameter Sets: List,PagedFilter,PagedParams
 Required: True
 Default value: None
 ```
 
+### MaxPages
+
+User entlitement API returs a paged result. This parameter allows to limit the number of pages to be retrieved. Default is 0 = all pages.
+
+```yaml
+Type: int
+Parameter Sets: PagedFilter,PagedParams
+Required: False
+Default value: $null
+```
+
+### Filter
+
+Equality operators relating to searching user entitlements seperated by and clauses. Valid filters include: licenseId, licenseStatus, userType, and name. 
+- licenseId: filters based on license assignment using license names. i.e. licenseId eq 'Account-Stakeholder' or licenseId eq 'Account-Express'.
+- licenseStatus: filters based on license status. currently only supports disabled. i.e. licenseStatus eq 'Disabled'. To get disabled basic licenses, you would pass (licenseId eq 'Account-Express' and licenseStatus eq 'Disabled') 
+- userType: filters off identity type. Suppored types are member or guest i.e. userType eq 'member'. 
+- name: filters on if the user's display name or email contians given input. i.e. get all users with "test" in email or displayname is "name eq 'test'". 
+
+A valid query could be: (licenseId eq 'Account-Stakeholder' or (licenseId eq 'Account-Express' and licenseStatus eq 'Disabled')) and name eq 'test' and userType eq 'guest'.
+
+Currently, filter names and values must match exactly the case. i.e.:
+* LicenseID will throw Invalid filter message. 
+* licenseId eq 'account-stakeholder' will return an empty list
+
+```yaml
+Type: string
+Parameter Sets: PagedFilter
+Required: False
+Default value: None
+```
+
+### License
+
+Filters based on license assignment using license names
+
+The acceptable values for this parameter are:
+- Account-Stakeholder: Stakeholder
+- Account-Express: Basic
+- Account-Advanced: Basic + Test Plans
+
+Other licenses which source (licenseSource) is MSDN cannot be filtered here
+Parameter values are case sensitive
+
+```yaml
+Type: string
+Parameter Sets: PagedParams
+Required: False
+Default value: None
+```
+
+### UserType
+
+Filters based on user type
+
+The acceptable values for this parameter are:
+- member
+- guest
+
+Parameter values are case sensitive
+
+```yaml
+Type: string
+Parameter Sets: PagedParams
+Required: False
+Default value: None
+```
+
+### Name
+
+Filters on if the user's display name or email contains given input
+
+```yaml
+Type: string
+Parameter Sets: PagedParams
+Required: False
+Default value: None
+Alias: Mail
+```
+
+
 ## INPUTS
 
 ## OUTPUTS

.docs/synopsis/Get-VSTeamUserEntitlement.md

@@ -1 +1,6 @@
-Get User Entitlement for a user.
+Get User Entitlement for a user, or a paged list of users matching the specified filter
+
+Please note that Filter, Name, UserType and License parameters only works when MemberEntitlementManagement module version is 6.0 or upper
+In the same way Top and Skip paramerers only works up to version 5.1
+
+You can setup the specific version for the MemberEntitlementManagement calling Set-VSTeamAPIVersion -Service MemberEntitlementManagement -Version VersionNumberYouNeed.

Source/Private/common.ps1

@@ -175,9 +175,19 @@ function _supportsSecurityNamespace {
 }
 
 function _supportsMemberEntitlementManagement {
+   [CmdletBinding()]
+   param(
+      [string]$expression = $null
+   )
    _hasAccount
-   if (-not $(_getApiVersion MemberEntitlementManagement)) {
+   $apiVer = _getApiVersion MemberEntitlementManagement
+   if (-not $apiVer) {
       throw 'This account does not support Member Entitlement.'
+   } elseif ($null -ne $expression) {
+      $isMatch = Invoke-Expression "'$apiVer' $expression"
+      if (-not $isMatch) {
+         throw "EntitlementManagemen version must match $expression for this call, current value $apiVer"
+      }
    }
 }
 

Source/Public/Get-VSTeamUserEntitlement.ps1

@@ -9,22 +9,58 @@ function Get-VSTeamUserEntitlement {
       [int] $Skip = 0,
 
       [Parameter(ParameterSetName = 'List')]
+      [Parameter(ParameterSetName = 'PagedFilter')]
+      [Parameter(ParameterSetName = 'PagedParams')]
       [ValidateSet('Projects', 'Extensions', 'Grouprules')]
       [string[]] $Select,
 
       [Parameter(ParameterSetName = 'ByID')]
       [Alias('UserId')]
-      [string[]] $Id
+      [string[]] $Id,
+
+      [Parameter(ParameterSetName = 'PagedFilter')]
+      [Parameter(ParameterSetName = 'PagedParams')]
+      [int] $MaxPages = 0,
+
+      [Parameter(ParameterSetName = 'PagedFilter')]
+      [string] $Filter,
+
+      [Parameter(ParameterSetName = 'PagedParams')]
+      [ValidateSet('Account-Stakeholder', 'Account-Express', 'Account-Advanced', IgnoreCase = $false)]
+      [Alias('License')]
+      [string] $LicenseId,                                                            #license name is case sensitive
+
+      [Parameter(ParameterSetName = 'PagedParams')]
+      [ValidateSet('guest', 'member', IgnoreCase = $false)]                            #userType is case sensitive: values in lowercase
+      [string] $UserType,
+
+      [Parameter(ParameterSetName = 'PagedParams')]
+      [Alias('UserName')]
+      [Alias('Mail')]
+      [string] $Name
    )
 
+
    process {
-      # This will throw if this account does not support MemberEntitlementManagement
-      _supportsMemberEntitlementManagement
+      # This will throw if this account does not support MemberEntitlementManagement 
+      # or supported version is not correct with the type of API call
+      $paramCounter = _countParameters -BoundParameters $PSBoundParameters
+      $paramset = 'PagedParams', 'PagedFilter'
+      if ($paramCounter -eq 0) {
+         $memberEntitlementManagementRequirement = $null
+      } elseif ($paramset -contains $PSCmdlet.ParameterSetName) {
+         $memberEntitlementManagementRequirement = "-ge '6.0'"
+      } else {
+         $memberEntitlementManagementRequirement = "-le '5.1'"
+      }
+      _supportsMemberEntitlementManagement $memberEntitlementManagementRequirement
+
 
+      $apiVersion = _getApiVersion MemberEntitlementManagement
       $commonArgs = @{
          subDomain = 'vsaex'
          resource  = 'userentitlements'
-         version   = $(_getApiVersion MemberEntitlementManagement)
+         version   = $apiVersion
       }
 
       if ($Id) {
@@ -37,23 +73,91 @@ function Get-VSTeamUserEntitlement {
          }
       }
       else {
-         # Build the url to list the teams
+         # use the appropiate syntax depending on the API version
+         $useContinuationToken = $false
+         if ($paramCounter -eq 0) {
+            if ($apiVersion -gt '6.0') {
+               $useContinuationToken = $true
+            }
+         } else {
+            if ($paramset -contains $PSCmdlet.ParameterSetName) {
+               $useContinuationToken = $true
+            }
+         }
+
          $listurl = _buildRequestURI @commonArgs
+         $objs = @()
+         Write-Verbose "Use continuation token: $useContinuationToken"
+         if ($useContinuationToken) {
+            if ($psCmdLet.ParameterSetName -eq 'PagedParams') {
+               #parameter names must be lowercase, parameter values depends on the parameter
+               if ($name) {
+                  $filter += "name eq '$name' and "
+               }
+               if ($LicenseId) {
 
-         $listurl += _appendQueryString -name "top" -value $top -retainZero
-         $listurl += _appendQueryString -name "skip" -value $skip -retainZero
-         $listurl += _appendQueryString -name "select" -value ($select -join ",")
+                  $filter += "licenseId eq '$LicenseId' and " 
+               }
+               if ($UserType) {
+                  $filter += "userType eq '$UserType' and "
+               }
+               $filter = $filter.SubString(0, $filter.Length - 5)
+            }
+            $listurl += _appendQueryString -name "`$filter" -value $filter
+            $listurl += _appendQueryString -name "select" -value ($select -join ",")
 
-         # Call the REST API
-         $resp = _callAPI -url $listurl
+            # Call the REST API
+            if ($MaxPages -le 0){
+               $MaxPages = [int32]::MaxValue
+            }
+            $i = 0
+            $apiParameters = $listurl
+            Write-Verbose "API params: $listurl"
+            do {
+               $resp = _callAPI -url $apiParameters
+               $continuationToken = $resp.continuationToken
+               $i++
+               Write-Verbose "page $i"
+               foreach ($item in $resp.members) {
+                  $objs += [vsteam_lib.UserEntitlement]::new($item)
+               }
+               if (-not [String]::IsNullOrEmpty($continuationToken)) {
+                  $continuationToken = [uri]::EscapeDataString($continuationToken)
+                  $apiParameters = "${listurl}&continuationToken=$continuationToken"
+               }
+            } while (-not [String]::IsNullOrEmpty($continuationToken) -and $i -lt $MaxPages)
 
-         $objs = @()
+         } else {
+            $listurl += _appendQueryString -name "top" -value $top -retainZero
+            $listurl += _appendQueryString -name "skip" -value $skip -retainZero
+            $listurl += _appendQueryString -name "select" -value ($select -join ",")
 
-         foreach ($item in $resp.members) {
-            $objs += [vsteam_lib.UserEntitlement]::new($item)
-         }
+            # Call the REST API
+            Write-Verbose "API params: $listurl"
+            $resp = _callAPI -url $listurl
 
+            foreach ($item in $resp.members) {
+               $objs += [vsteam_lib.UserEntitlement]::new($item)
+            }
+         }
          Write-Output $objs
+
+      }
+   }
+}
+
+
+function _countParameters() {
+   param(
+      $BoundParameters
+   )
+   $counter = 0
+   $advancedPameters = @('Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable')
+   foreach($p in $BoundParameters.GetEnumerator()) {
+      if ($p.Key -notin $advancedPameters) {
+         $counter++
       }
    }
-}
+   Write-Verbose "Found $counter parameters"
+   $counter
+}