Functions/Get-JiraIssue.ps1

function Get-JiraIssue
{
    <#
    .Synopsis
       Returns information about an issue in JIRA.
    .DESCRIPTION
       This function obtains references to issues in JIRA.

       This function can be used to directly query JIRA for a specific issue key or internal issue ID. It can also be used to query JIRA for issues matching a specific criteria using JQL (Jira Query Language).

       For more details on JQL syntax, see this articla from Atlassian: https://confluence.atlassian.com/display/JIRA/Advanced+Searching

       Output from this function can be piped to various other functions in this module, including Set-JiraIssue, Add-JiraIssueComment, and Invoke-JiraIssueTransition.
    .EXAMPLE
       Get-JiraIssue -Key TEST-001
       This example returns a reference to JIRA issue TEST-001.
    .EXAMPLE
       Get-JiraIssue "TEST-002" | Add-JiraIssueComment "Test comment from PowerShell"
       This example illustrates pipeline use from Get-JiraIssue to Add-JiraIssueComment.
    .EXAMPLE
       Get-JiraIssue -Query 'project = "TEST" AND created >= -5d'
       This example illustrates using the Query parameter and JQL syntax to query Jira for matching issues.
    .INPUTS
       This function can accept PSJira.Issue objects, Strings, or Objects via the pipeline.

       * If a PSJira.Issue object is passed, this function returns a new reference to the same issue.
       * If a String is passed, this function searches for an issue with that issue key or internal ID.
       * If an Object is passed, this function invokes its ToString() method and treats it as a String.
    .OUTPUTS
       This function outputs the PSJira.Issue object retrieved.
    .NOTES
       This function requires either the -Credential parameter to be passed or a persistent JIRA session. See New-JiraSession for more details. If neither are supplied, this function will run with anonymous access to JIRA.
    #>

    [CmdletBinding(DefaultParameterSetName = 'ByIssueKey')]
    param(
        [Parameter(ParameterSetName = 'ByIssueKey',
                   Mandatory = $true,
                   Position = 0)]
        [ValidateNotNullOrEmpty()]
        [String[]] $Key,

        [Parameter(ParameterSetName = 'ByInputObject',
                   Mandatory = $true,
                   Position = 0)]
        [Object[]] $InputObject,

        [Parameter(ParameterSetName = 'ByJQL',
                   Mandatory = $true)]
        [Alias('JQL')]
        [String] $Query,

        [Parameter(ParameterSetName = 'ByJQL')]
        [Int] $MaxResults = 50,

        # Credentials to use to connect to Jira
        [Parameter(Mandatory = $false)]
        [System.Management.Automation.PSCredential] $Credential
    )

    begin
    {
        Write-Debug "[Get-JiraIssue] Reading server from config file"
        $server = Get-JiraConfigServer -ConfigFile $ConfigFile -ErrorAction Stop

        Write-Debug "[Get-JiraIssue] ParameterSetName=$($PSCmdlet.ParameterSetName)"
    }

    process
    {
        if ($PSCmdlet.ParameterSetName -eq 'ByIssueKey')
        {
            foreach ($k in $Key)
            {
                Write-Debug "[Get-JiraIssue] Processing issue key [$k]"
                $issueURL = "$($server)/rest/api/latest/issue/${k}?expand=transitions"

                Write-Debug "[Get-JiraIssue] Preparing for blastoff!"
                $result = Invoke-JiraMethod -Method Get -URI $issueURL -Credential $Credential

                if ($result)
                {
                    Write-Debug "[Get-JiraIssue] Converting REST result to Jira object"
                    $obj = ConvertTo-JiraIssue -InputObject $result

                    Write-Debug "[Get-JiraIssue] Outputting result"
                    Write-Output $obj
                } else {
                    Write-Debug "[Get-JiraIssue] Invoke-JiraMethod returned no results to output."
                }
            }
        } elseif ($PSCmdlet.ParameterSetName -eq 'ByInputObject') {
            foreach ($i in $InputObject)
            {
                Write-Debug "[Get-JiraIssue] Processing InputObject [$i]"
                if ((Get-Member -InputObject $i).TypeName -eq 'PSJira.Issue')
                {
                    Write-Debug "[Get-JiraIssue] Issue parameter is a PSJira.Issue object"
                    $issueKey = $i.Key
                } else {
                    $issueKey = $i.ToString()
                    Write-Debug "[Get-JiraIssue] Issue key is assumed to be [$issueKey] via ToString()"
                }

                Write-Debug "[Get-JiraIssue] Invoking myself with the Key parameter set to search for issue [$issueKey]"
                $issueObj = Get-JiraIssue -Key $issueKey -Credential $Credential
                Write-Debug "[Get-JiraIssue] Returned from invoking myself; outputting results"
                Write-Output $issueObj
            }
        } elseif ($PSCmdlet.ParameterSetName -eq 'ByJQL') {

            Write-Debug "[Get-JiraMethod] Escaping query and building URL"
            $escapedQuery = [System.Web.HttpUtility]::UrlPathEncode($Query)
            $issueURL = "$($server)/rest/api/latest/search?jql=$escapedQuery&validateQuery=true&expand=transitions&maxResults=$MaxResults"

            Write-Debug "[Get-JiraMethod] Preparing for blastoff!"
            $result = Invoke-JiraMethod -Method Get -URI $issueURL -Credential $Credential

            if ($result)
            {
                # {"startAt":0,"maxResults":50,"total":0,"issues":[]}

                if ($result.total -gt 0)
                {
                    Write-Debug "[Get-JiraMethod] Converting REST result to Jira issue"
                    $obj = ConvertTo-JiraIssue -InputObject $result.issues

                    Write-Debug "[Get-JiraMethod] Outputting result"
                    Write-Output $obj
                } else {
                    Write-Debug "[Get-JiraMethod] No results were found for the specified query"
                    Write-Verbose "No results were found for the query [$Query]"
                }
            } else {
                Write-Debug "[Get-JiraMethod] Invoke-JiraMethod returned no results"
            }
        }
    }

    end
    {
        Write-Debug "[Get-JiraIssue] Complete"
    }
}