Public/Get-JiraGroupMember.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
function Get-JiraGroupMember {
    <#
    .SYNOPSIS
       Returns members of a given group in JIRA
    .DESCRIPTION
       This function returns members of a provided group in JIRA.
    .EXAMPLE
       Get-JiraGroupmember testGroup
       This example returns all members of the JIRA group testGroup.
    .EXAMPLE
       Get-JiraGroup 'Developers' | Get-JiraGroupMember
       This example illustrates the use of the pipeline to return members of
       the Developers group in JIRA.
    .INPUTS
       [JiraPS.Group] The group to query for members
    .OUTPUTS
       [JiraPS.User[]] Members of the provided group
    .NOTES
       By default, this will return all active users who are members of the
       given group. For large groups, this can take quite some time.
 
       To limit the number of group members returned, use
       the MaxResults parameter. You can also combine this with the
       StartIndex parameter to "page" through results.
 
       This function does not return inactive users. This appears to be a
       limitation of JIRA's REST API.
    #>

    [CmdletBinding()]
    param(
        # Group object of which to display the members.
        [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )]
        [ValidateNotNullOrEmpty()]
        [ValidateScript(
            {
                if (("JiraPS.Group" -notin $_.PSObject.TypeNames) -and (($_ -isnot [String]))) {
                    $errorItem = [System.Management.Automation.ErrorRecord]::new(
                        ([System.ArgumentException]"Invalid Type for Parameter"),
                        'ParameterType.NotJiraGroup',
                        [System.Management.Automation.ErrorCategory]::InvalidArgument,
                        $_
                    )
                    $errorItem.ErrorDetails = "Wrong object type provided for Group. Expected [JiraPS.Group] or [String], but was $($_.GetType().Name)"
                    $PSCmdlet.ThrowTerminatingError($errorItem)
                    <#
                      #ToDo:CustomClass
                      Once we have custom classes, this check can be done with Type declaration
                    #>

                }
                else {
                    return $true
                }
            }
        )]
        [Object[]]
        $Group,

        # Index of the first user to return. This can be used to "page" through
        # users in a large group or a slow connection.
        [ValidateRange(0, [Int]::MaxValue)]
        [Int]
        $StartIndex = 0,

        # Maximum number of results to return. By default, all users will be
        # returned.
        [ValidateRange(0, [Int]::MaxValue)]
        [Int]
        $MaxResults = 0,

        # Credentials to use to connect to JIRA.
        # If not specified, this function will use anonymous access.
        [PSCredential]
        $Credential
    )

    begin {
        Write-Verbose "[$($MyInvocation.MyCommand.Name)] Function started"

        # This is a parameter in Get-JiraIssue, but in testing, JIRA doesn't
        # reliably return more than 50 results at a time.
        $pageSize = 50

        if ($MaxResults -eq 0) {
            Write-DebugMessage "[$($MyInvocation.MyCommand.Name)] MaxResults was not specified. Using loop mode to obtain all members."
            $loopMode = $true
        }
        else {
            $loopMode = $false
            if ($MaxResults -gt 50) {
                Write-Warning "JIRA's API may not properly support MaxResults values higher than 50 for this method. If you receive inconsistent results, do not pass the MaxResults parameter to this function to return all results."
            }
        }
    }

    process {
        Write-DebugMessage "[$($MyInvocation.MyCommand.Name)] ParameterSetName: $($PsCmdlet.ParameterSetName)"
        Write-DebugMessage "[$($MyInvocation.MyCommand.Name)] PSBoundParameters: $($PSBoundParameters | Out-String)"

        $groupObj = Get-JiraGroup -GroupName $Group -Credential $Credential -ErrorAction Stop

        foreach ($_group in $groupObj) {
            Write-Verbose "[$($MyInvocation.MyCommand.Name)] Processing [$_group]"
            Write-Debug "[$($MyInvocation.MyCommand.Name)] Processing `$_group [$_group]"

            if ($loopMode) {
                # Using the Size property of the group object, iterate
                # through all users in a given group.

                $totalResults = $_group.Size
                $allUsers = New-Object -TypeName System.Collections.ArrayList

                for ($i = 0; $i -lt $totalResults; $i = $i + $PageSize) {
                    if ($PageSize -gt ($i + $totalResults)) {
                        $thisPageSize = $totalResults - $i
                    }
                    else {
                        $thisPageSize = $PageSize
                    }
                    $percentComplete = ($i / $totalResults) * 100
                    Write-Progress -Activity "$($MyInvocation.MyCommand.Name)" -Status "Obtaining members ($i - $($i + $thisPageSize) of $totalResults)..." -PercentComplete $percentComplete

                    Write-DebugMessage "[$($MyInvocation.MyCommand.Name)] Obtaining members $i - $($i + $thisPageSize)..."
                    $thisSection = Get-JiraGroupMember -Group $_group -StartIndex $i -MaxResults $thisPageSize -Credential $Credential

                    foreach ($_user in $thisSection) {
                        [void] $allUsers.Add($_user)
                    }
                }

                Write-Progress -Activity "$($MyInvocation.MyCommand.Name)" -Completed
                Write-Output ($allUsers.ToArray())
            }
            else {
                # Since user is an expandable property of the returned
                # group from JIRA, JIRA doesn't use the MaxResults argument
                # found in other REST endpoints. Instead, we need to pass
                # expand=users[0:15] for users 0-15 (inclusive).
                $parameter = @{
                    URI        = '{0}&expand=users[{1}:{2}]' -f $_group.RestUrl, $StartIndex, ($StartIndex + $MaxResults)
                    Method     = "GET"
                    Credential = $Credential
                }
                Write-Debug "[$($MyInvocation.MyCommand.Name)] Invoking JiraMethod with `$parameter"
                $result = Invoke-JiraMethod @parameter

                Write-Output (ConvertTo-JiraGroup -InputObject $result).Member
            }
        }
    }

    end {
        Write-Verbose "[$($MyInvocation.MyCommand.Name)] Complete"
    }
}