en-GB/about_tcs.jira.help.txt
|
TOPIC about_tcs.jira SHORT DESCRIPTION Jira Cloud and Jira Service Management REST API client for PowerShell. LONG DESCRIPTION tcs.jira is part of the TheCodeSaiyan PowerShell suite and requires tcs.core 0.3.0 or later. It connects to one Jira Cloud site per session, sends requests to the Jira platform API (/rest/api/3) and the Jira Service Management API (/rest/servicedeskapi), and gets, creates and updates issues and service requests. Run Set-JiraContext first. It keeps the site URL and the account e-mail address with its API token for the current session only; nothing is written to disk. The token is held as a SecureString in a PSCredential in module scope and the HTTP Basic Authorization header is built for each request, so the token does not appear in the context object, in verbose output or in error messages. Test-JiraContext checks the connection, Get-JiraContext shows it and Clear-JiraContext removes it. The secret-free context is also mirrored to $global:JiraContext for older scripts; this is deprecated and will be removed, use Get-JiraContext. New-*, Update-*, Set-JSMRequestTransition, Set-JiraContext, Clear-JiraContext and Invoke-JiraIssueTransition support -WhatIf and -Confirm. Get-JiraTicket, Update-JiraTicket, Update-JSMRequest and the transition commands take issue keys from the pipeline (an IssueKey or Key property), so the output of Find-JiraIssue can be piped to them. Issue keys must look like PROJ-123 (or be a numeric id) and are URL-encoded in request paths. Transitions are chosen by their target status first and then by their exact name; when nothing matches, the error lists the available transitions. COMMANDS Connection Set-JiraContext Sets the Jira Cloud site and credentials used by the other tcs.jira functions. Get-JiraContext Gets the connection context, without secrets. Test-JiraContext Checks the connection by getting the signed-in user. Clear-JiraContext Removes the connection context and credential. Generic requests Invoke-JiraRequest Sends a request to the Jira Cloud or Jira Service Management REST API, with JQL search, paging, retries (HTTP 429 for every method, 5xx for Get, Put and Delete) and -Raw. Jira issues Find-JiraIssue Finds Jira Cloud issues with a JQL query. Get-JiraTicket Gets a Jira Cloud issue with its comments. New-JiraTicket Creates a Jira Cloud issue. Update-JiraTicket Updates a Jira Cloud issue: transitions it (Done or Resolved), changes fields and/or adds a comment. Get-JiraIssueTransition Gets the transitions of a Jira Cloud issue. Invoke-JiraIssueTransition Moves a Jira Cloud issue to a status, optionally with a comment. Jira Service Management requests Get-JSMServiceDesk Gets Jira Service Management service desks. Get-JSMRequestType Gets the request types of a service desk. Get-JSMRequest Gets a Jira Service Management customer request. New-JSMRequest Creates a Jira Service Management customer request. Get-JSMRequestTransition Gets the customer transitions of a request. Set-JSMRequestTransition Transitions a Jira Service Management request to a new status. Update-JSMRequest Updates a Jira Service Management request: marks it done, changes fields and/or adds a public or internal comment. CONFIGURATION tcs.jira uses the tcs.core settings file for the module: <ApplicationData>/PowerShell/Config/tcs.jira/Module.Config.json View it with Get-ModuleConfig and change it with Set-ModuleConfig: UpdateWarning Warn when a newer version is available (default $true). UpdateCheckIntervalHours Hours between PowerShell Gallery update checks (default 24). Telemetry Send anonymous usage telemetry (default $true). TelemetryUri HTTPS telemetry endpoint (default empty). TelemetryApiKey API key for the telemetry endpoint (default empty). The Jira connection itself is not stored in this file; run Set-JiraContext in each session. ENVIRONMENT VARIABLES TCS_CONFIG_ROOT Moves the settings folder. TCS_SKIP_UPDATE_CHECK=1 Turns the gallery update check off. TCS_TELEMETRY_OPTOUT=1 Turns telemetry off for all tcs modules. TELEMETRY Each exported command reports one anonymous usage event through tcs.core Invoke-TelemetryCollection (command name, duration, success, exception type, PowerShell and OS version and a random installation ID). No user, machine, path or error text is sent, and no Jira data or credentials. Nothing is sent until a TelemetryUri is configured. To opt out, set $env:TCS_TELEMETRY_OPTOUT = '1' (all tcs modules) or run: Set-ModuleConfig -ModuleName tcs.jira -Telemetry $false EXAMPLES Connect with an API token held in an environment variable: Set-JiraContext -JiraUrl 'https://contoso.atlassian.net' -Username 'me@contoso.com' -PersonalAccessToken $env:JIRA_API_TOKEN Get an issue and list its comments: (Get-JiraTicket -IssueKey 'PROJ-123').Comments | Select-Object Author, Created, Body Check the connection: Test-JiraContext | Select-Object displayName, emailAddress Find issues with JQL and comment on each of them: Find-JiraIssue -JQL 'project = PROJ AND status = "In Progress"' | Update-JiraTicket -Comment 'Reviewed' Move an issue to a status: Invoke-JiraIssueTransition -IssueKey 'PROJ-123' -Status 'In Progress' Transition an issue to Done and add a comment: Update-JiraTicket -IssueKey 'PROJ-123' -Comment 'Deployed to production' -MarkDone Turn off update warnings for tcs.jira: Set-ModuleConfig -ModuleName tcs.jira -UpdateWarning $false SEE ALSO about_tcs.core Set-JiraContext Test-JiraContext Find-JiraIssue Invoke-JiraRequest Get-ModuleConfig Set-ModuleConfig https://github.com/ntatschner/TheCodeSaiyan-PowerShell-tcs.jira KEYWORDS tcs TheCodeSaiyan Jira JSM Atlassian |