enable API version 6.0 for Get-VSTeamUserEntitlement

.docs/Get-VSTeamUserEntitlement.md

@@ -6,6 +6,11 @@
 
 <!-- #include "./synopsis/Get-VSTeamUserEntitlement.md" -->
 
+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.
+
 ## SYNTAX
 
 ## DESCRIPTION
@@ -14,6 +19,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 +96,91 @@ 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
+```
+
+
 ## INPUTS
 
 ## OUTPUTS

.docs/synopsis/Get-VSTeamUserEntitlement.md

@@ -1 +1 @@
-Get User Entitlement for a user.
+Get User Entitlement for a user, or a paged list of users matching the specified filter

CHANGELOG.md

@@ -4,6 +4,13 @@
 Merged [Pull Request](https://github.com/MethodsAndPractices/vsteam/pull/468) from [Michael19842](https://github.com/Michael19842) the following:
 - Added parameter `Templateparameter` for queue new build with custom template parameters
 
+Merged [Pull Request](https://github.com/MethodsAndPractices/vsteam/pull/459) from [Miguel Nieto](https://github.com/mnieto) the following:
+
+- Enable API version 6.0 calls in Get-VSTeamUserEntitlement. This add new parameters only available starting from version 6.0.
+  - Top and Skip parameters are still valid on versions up to 5.1. But will throw if called from version 6.0. This preservers backwards compability, but can be a breaking change if you do not pay attention to the API version in your scripts
+  - New parameters will throw if called from version 5.1
+  - Function behaviour can be changed from Set-VSTeamAPIVersion -Service MemberEntitlementManagement -Version $yourVersion
+
 ## 7.8.0
 Merged [Pull Request](https://github.com/MethodsAndPractices/vsteam/pull/475) from [rbleattler](https://github.com/rbleattler) the following:
 - Added Update-VSTeamGitRepositoryDefaultBranch to allow for changing the default branch of a repository

Source/Private/common.ps1

@@ -121,6 +121,64 @@ function _callAPI {
    }
 }
 
+
+# General function to manage API Calls that involve a paged response,
+# either with a ContinuationToken property in the body payload or
+# with a X-MS-ContinuationToken header
+# TODO: Add functionality to manage paged responses based on X-MS-ContinuationToken header
+# TODO: This would need to be integrated probably into the _callAPI function?
+function _callAPIContinuationToken {
+   [CmdletBinding()]
+   param(
+      [string]$Url,
+      # If present, or $true, the function will manage the pages using the header
+      # specified in $ContinuationTokenName.
+      # If not present, or $false, the function will manage the pages using the
+      # continuationToken property specified in $ContinuationTokenName.
+      [switch]$UseHeader,
+      # Allows to specify a header or continuation token property different of the default values.
+      # If this parameter is not specified, the default value is X-MS-ContinuationToken or continuationToken
+      # depending if $UseHeader is present or not, respectively
+      [string]$ContinuationTokenName,
+      # Property in the response body payload that contains the collecion of objects to return to the calling function
+      [string]$PropertyName,
+      # Number of pages to be retrieved. If 0, or not specified, it will return all the available pages
+      [int]$MaxPages
+   )
+
+   if ($MaxPages -le 0){
+      $MaxPages = [int32]::MaxValue
+   }
+   if ([string]::IsNullOrEmpty($ContinuationTokenName)) {
+      if ($UseHeader.IsPresent) {
+         $ContinuationTokenName = "X-MS-ContinuationToken"
+      } else {
+         $ContinuationTokenName = "continuationToken"
+      }
+   }
+   $i = 0
+   $obj = @()
+   $apiParameters = $url
+   do {
+      if ($UseHeader.IsPresent) {
+         throw "Continuation token from response headers not supported in this version"
+      } else {
+         $resp = _callAPI -url $apiParameters
+         $continuationToken = $resp."$ContinuationTokenName"
+         $i++
+         Write-Verbose "page $i"
+         $obj += $resp."$PropertyName"
+         if (-not [String]::IsNullOrEmpty($continuationToken)) {
+            $continuationToken = [uri]::EscapeDataString($continuationToken)
+            $apiParameters = "${url}&continuationToken=$continuationToken"
+         }
+      }
+   } while (-not [String]::IsNullOrEmpty($continuationToken) -and $i -lt $MaxPages)
+
+   return $obj
+}
+
+
 # Not all versions support the name features.
 
 function _supportsGraph {
@@ -175,9 +233,22 @@ function _supportsSecurityNamespace {
 }
 
 function _supportsMemberEntitlementManagement {
+   [CmdletBinding(DefaultParameterSetName="upto")]
+   param(
+      [parameter(ParameterSetName="upto")]
+      [string]$UpTo = $null,
+      [parameter(ParameterSetName="onwards")]
+      [string]$Onwards = $null
+
+   )
    _hasAccount
-   if (-not $(_getApiVersion MemberEntitlementManagement)) {
+   $apiVer = _getApiVersion MemberEntitlementManagement
+   if (-not $apiVer) {
       throw 'This account does not support Member Entitlement.'
+   } elseif (-not [string]::IsNullOrEmpty($UpTo) -and $apiVer -gt $UpTo) {
+      throw "EntitlementManagemen version must be equal or lower than $UpTo for this call, current value $apiVer"
+   } elseif (-not [string]::IsNullOrEmpty($Onwards) -and $apiVer -lt $Onwards) {
+      throw "EntitlementManagemen version must be equal or greater than $Onwards for this call, current value $apiVer"
    }
 }
 
@@ -1180,4 +1251,19 @@ function _checkForModuleUpdates {
       }
    }
 
+}
+
+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
 }