From d315a6181aacb43c196b1814bae235da33858501 Mon Sep 17 00:00:00 2001 From: Phillip Guzman Date: Sun, 8 Jul 2018 07:40:06 -0500 Subject: [PATCH] updated documentation --- docs/en-US/commands/Get-JiraIssue.md | 578 ++++++++++++++++----------- 1 file changed, 354 insertions(+), 224 deletions(-) diff --git a/docs/en-US/commands/Get-JiraIssue.md b/docs/en-US/commands/Get-JiraIssue.md index 7697bf16..51687d34 100644 --- a/docs/en-US/commands/Get-JiraIssue.md +++ b/docs/en-US/commands/Get-JiraIssue.md @@ -1,224 +1,354 @@ -function Get-JiraIssue { - # .ExternalHelp ..\JiraPS-help.xml - [CmdletBinding( SupportsPaging, DefaultParameterSetName = 'ByIssueKey' )] - param( - [Parameter( Position = 0, Mandatory, ParameterSetName = 'ByIssueKey' )] - [ValidateNotNullOrEmpty()] - [Alias('Issue')] - [String[]] - $Key, - - [Parameter( Position = 0, Mandatory, ParameterSetName = 'ByInputObject' )] - [ValidateNotNullOrEmpty()] - [ValidateScript( - { - if (("JiraPS.Issue" -notin $_.PSObject.TypeNames) -and (($_ -isnot [String]))) { - $exception = ([System.ArgumentException]"Invalid Type for Parameter") #fix code highlighting] - $errorId = 'ParameterType.NotJiraIssue' - $errorCategory = 'InvalidArgument' - $errorTarget = $_ - $errorItem = New-Object -TypeName System.Management.Automation.ErrorRecord $exception, $errorId, $errorCategory, $errorTarget - $errorItem.ErrorDetails = "Wrong object type provided for Issue. Expected [JiraPS.Issue] or [String], but was $($_.GetType().Name)" - $PSCmdlet.ThrowTerminatingError($errorItem) - } - else { - return $true - } - } - )] - [Object[]] - $InputObject, - <# - #ToDo:Deprecate - This is not necessary if $Key uses ValueFromPipelineByPropertyName - #ToDo:CustomClass - Once we have custom classes, this check can be done with Type declaration - #> - - [Parameter( Mandatory, ParameterSetName = 'ByJQL' )] - [Alias('JQL')] - [String] - $Query, - - [Parameter( Mandatory, ParameterSetName = 'ByFilter' )] - [ValidateNotNullOrEmpty()] - [ValidateScript( - { - if (("JiraPS.Filter" -notin $_.PSObject.TypeNames) -and (($_ -isnot [String]))) { - $exception = ([System.ArgumentException]"Invalid Type for Parameter") #fix code highlighting] - $errorId = 'ParameterType.NotJiraFilter' - $errorCategory = 'InvalidArgument' - $errorTarget = $_ - $errorItem = New-Object -TypeName System.Management.Automation.ErrorRecord $exception, $errorId, $errorCategory, $errorTarget - $errorItem.ErrorDetails = "Wrong object type provided for Filter. Expected [JiraPS.Filter] 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] - $Filter, - - [Parameter()] - [ValidateNotNullOrEmpty()] - [String[]] - $Fields, - - [Parameter( ParameterSetName = 'ByJQL' )] - [Parameter( ParameterSetName = 'ByFilter' )] - [UInt32] - $StartIndex = 0, - - [Parameter( ParameterSetName = 'ByJQL' )] - [Parameter( ParameterSetName = 'ByFilter' )] - [UInt32] - $MaxResults = 0, - - [Parameter( ParameterSetName = 'ByJQL' )] - [Parameter( ParameterSetName = 'ByFilter' )] - [UInt32] - $PageSize = $script:DefaultPageSize, - - [Parameter()] - [System.Management.Automation.PSCredential] - [System.Management.Automation.Credential()] - $Credential = [System.Management.Automation.PSCredential]::Empty - ) - - begin { - Write-Verbose "[$($MyInvocation.MyCommand.Name)] Function started" - - $server = Get-JiraConfigServer -ErrorAction Stop - - $searchURi = "$server/rest/api/latest/search" - $resourceURi = "$server/rest/api/latest/issue/{0}" - - $Fields = $Fields -join "," - } - - process { - Write-DebugMessage "[$($MyInvocation.MyCommand.Namune)] ParameterSetName: $($PsCmdlet.ParameterSetName)" - Write-DebugMessage "[$($MyInvocation.MyCommand.Name)] PSBoundParameters: $($PSBoundParameters | Out-String)" - - switch ($PSCmdlet.ParameterSetName) { - 'ByIssueKey' { - foreach ($_key in $Key) { - Write-Verbose "[$($MyInvocation.MyCommand.Name)] Processing [$_key]" - Write-Debug "[$($MyInvocation.MyCommand.Name)] Processing `$_key [$_key]" - - $getParameter = @{ expand = "transitions" } - if ($Fields) { - $getParameter["fields"] = $Fields - } - - $parameter = @{ - URI = $resourceURi -f $_key - Method = "GET" - GetParameter = $getParameter - Credential = $Credential - } - - Write-Debug "[$($MyInvocation.MyCommand.Name)] Invoking JiraMethod with `$parameter" - $result = Invoke-JiraMethod @parameter - - Write-Output (ConvertTo-JiraIssue -InputObject $result) - } - } - 'ByInputObject' { - # Write-Warning "[$($MyInvocation.MyCommand.Name)] The parameter '-InputObject' has been marked as deprecated." - foreach ($_issue in $InputObject) { - Write-Verbose "[$($MyInvocation.MyCommand.Name)] Processing [$_issue]" - Write-Debug "[$($MyInvocation.MyCommand.Name)] Processing `$_issue [$_issue]" - - Write-Output (Get-JiraIssue -Key $_issue.Key -Credential $Credential) - } - } - 'ByJQL' { - $parameter = @{ - URI = $searchURi - Method = "GET" - GetParameter = @{ - jql = (ConvertTo-URLEncoded $Query) - validateQuery = $true - expand = "transitions" - maxResults = $PageSize - - } - OutputType = "JiraIssue" - Paging = $true - Credential = $Credential - } - if ($Fields) { - $parameter["GetParameter"]["fields"] = $Fields - } - # Paging - ($PSCmdlet.PagingParameters | Get-Member -MemberType Property).Name | ForEach-Object { - $parameter[$_] = $PSCmdlet.PagingParameters.$_ - } - # Make `SupportsPaging` be backwards compatible - if ($StartIndex) { - Write-Warning "[$($MyInvocation.MyCommand.Name)] The parameter '-StartIndex' has been marked as deprecated. For more information, plase read the help." - $parameter["Skip"] = $StartIndex - } - if ($MaxResults) { - Write-Warning "[$($MyInvocation.MyCommand.Name)] The parameter '-MaxResults' has been marked as deprecated. For more information, plase read the help." - $parameter["First"] = $MaxResults - } - - - Write-Debug "[$($MyInvocation.MyCommand.Name)] Invoking JiraMethod with `$parameter" - Invoke-JiraMethod @parameter - } - 'ByFilter' { - $filterObj = (Get-JiraFilter -InputObject $Filter -Credential $Credential -ErrorAction Stop).searchurl - <# - #ToDo:CustomClass - Once we have custom classes, this will no longer be necessary - #> - - $parameter = @{ - URI = $filterObj - Method = "GET" - GetParameter = @{ - validateQuery = $true - expand = "transitions" - maxResults = $PageSize - } - OutputType = "JiraIssue" - Paging = $true - Credential = $Credential - - } - if ($Fields) { - $parameter["GetParameter"]["fields"] = $Fields - } - # Paging - ($PSCmdlet.PagingParameters | Get-Member -MemberType Property).Name | ForEach-Object { - $parameter[$_] = $PSCmdlet.PagingParameters.$_ - } - # Make `SupportsPaging` be backwards compatible - if ($StartIndex) { - Write-Warning "[$($MyInvocation.MyCommand.Name)] The parameter '-StartIndex' has been marked as deprecated. For more information, plase read the help." - $parameter["Skip"] = $StartIndex - } - if ($MaxResults) { - Write-Warning "[$($MyInvocation.MyCommand.Name)] The parameter '-MaxResults' has been marked as deprecated. For more information, plase read the help." - $parameter["First"] = $MaxResults - } - - Write-Debug "[$($MyInvocation.MyCommand.Name)] Invoking JiraMethod with `$parameter" - Invoke-JiraMethod @parameter - } - } - } - - end { - Write-Verbose "[$($MyInvocation.MyCommand.Name)] Complete" - } -} +--- +external help file: JiraPS-help.xml +Module Name: JiraPS +online version: https://atlassianps.org/docs/JiraPS/commands/Get-JiraIssue/ +locale: en-US +schema: 2.0.0 +layout: documentation +permalink: /docs/JiraPS/commands/Get-JiraIssue/ +--- +# Get-JiraIssue + +## SYNOPSIS + +Returns information about an issue in JIRA. + +## SYNTAX + +### ByIssueKey (Default) + +```powershell +Get-JiraIssue [-Key] [-Fields ][-IncludeTotalCount] [-Skip ] [-First ] + [-Credential ] [] +``` + +### ByInputObject + +```powershell +Get-JiraIssue [-InputObject] [-IncludeTotalCount] [-Skip ] [-First ] + [-Credential ] [] +``` + +### ByJQL + +```powershell +Get-JiraIssue -Query [-Fields ] [-StartIndex ] [-MaxResults ] [[PageSize] ] + [-IncludeTotalCount] [-Skip ] [-First ] [-Credential ] [] +``` + +### ByFilter + +```powershell +Get-JiraIssue -Filter [-Fields ][-StartIndex ] [-MaxResults ] [[PageSize] ] + [-IncludeTotalCount] [-Skip ] [-First ] [-Credential ] [] +``` + +## DESCRIPTION + +This function retrieves the data of a issue 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 article from Atlassian: [https://confluence.atlassian.com/display/JIRA/Advanced+Searching](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`. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Get-JiraIssue -Key TEST-001 +``` + +This example fetches the issue "TEST-001". + +The default `Format-Table` view of a Jira issue only shows the value of "Key", "Summary", "Status" and "Created". +> This can be manipulated with `Format-Table`, `Format-List` and `Select-Object` + +### EXAMPLE 2 + +```powershell +Get-JiraIssue "TEST-002" | Add-JiraIssueComment "Test comment from PowerShell" +``` + +This example illustrates pipeline use from `Get-JiraIssue` to `Add-JiraIssueComment`. + +### EXAMPLE 3 + +```powershell +Get-JiraIssue -Query 'project = "TEST" AND created >= -5d' +``` + +This example illustrates using the `-Query` parameter and JQL syntax to query Jira for matching issues. + +### EXAMPLE 4 + +```powershell +Get-JiraIssue -InputObject $oldIssue +``` + +This example illustrates how to get an update of an issue from an old result of `Get-JiraIssue` stored in $oldIssue. + +### EXAMPLE 5 + +```powershell +Get-JiraFilter -Id 12345 | Get-JiraIssue +``` + +This example retrieves all issues that match the criteria in the saved filter with id 12345. + +### EXAMPLE 6 + +```powershell +Get-JiraFilter 12345 | Select-Object * +``` + +This prints all fields of the issue to the console. + +## PARAMETERS + +### -Key + +Key of the issue to search for. + +```yaml +Type: String[] +Parameter Sets: ByIssueKey +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Object of an issue to search for. + +```yaml +Type: Object[] +Parameter Sets: ByInputObject +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Query + +JQL query for which to search for. + +```yaml +Type: String +Parameter Sets: ByJQL +Aliases: JQL + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Filter + +Object of an existing JIRA filter from which the results will be returned. + +```yaml +Type: Object +Parameter Sets: ByFilter +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Fields + +Field you would like to select from your issue + +```yaml +Type: String[] +Parameter Sets: ByFilter +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -StartIndex + +> NOTE: This parameter has been marked as deprecated and will be removed with the next major release. +> Use `-Skip` instead. + +Index of the first issue to return. + +This can be used to "page" through issues in a large collection or a slow connection. + +```yaml +Type: UInt32 +Parameter Sets: ByJQL, ByFilter +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MaxResults + +> NOTE: This parameter has been marked as deprecated and will be removed with the next major release. +> Use `-First` instead. + +Maximum number of results to return. + +By default, all issues will be returned. + +```yaml +Type: UInt32 +Parameter Sets: ByJQL, ByFilter +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PageSize + +How many issues should be returned per call to JIRA. + +This parameter only has effect if `-MaxResults` is not provided or set to 0. + +Normally, you should not need to adjust this parameter, +but if the REST calls take a long time, +try playing with different values here. + +```yaml +Type: UInt32 +Parameter Sets: ByJQL, ByFilter +Aliases: + +Required: False +Position: Named +Default value: 25 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeTotalCount + +Causes an extra output of the total count at the beginning. + +Note this is actually a uInt64, but with a custom string representation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Skip + +Controls how many things will be skipped before starting output. + +Defaults to 0. + +```yaml +Type: UInt64 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -First + +Indicates how many items to return. + +```yaml +Type: UInt64 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 18446744073709551615 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Credentials to use to connect to JIRA. +If not specified, this function will use anonymous access. + +```yaml +Type: PSCredential +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [JiraPS.Issue] / [String] + +- If a JiraPS.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 + +### [JiraPS.Issue] + +## 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. + +## RELATED LINKS + +[about_JiraPS_CreatingIssues](../../about/creating-issues.html) + +[about_JiraPS_CustomFields](../../about/custom-fields.html) + +[New-JiraIssue](../New-JiraIssue/)