en-US/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. The secret-free context is also mirrored to $global:JiraContext for older scripts. New-*, Update-*, Set-JSMRequestTransition and Set-JiraContext support -WhatIf and -Confirm. COMMANDS Connection Set-JiraContext Sets the Jira Cloud site and credentials used by the other tcs.jira functions. Generic requests Invoke-JiraRequest Sends a request to the Jira Cloud or Jira Service Management REST API, with JQL search, paging and retries for HTTP 429 and 503. Jira issues 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. Jira Service Management requests Get-JSMRequest Gets a Jira Service Management customer request. New-JSMRequest Creates a Jira Service Management customer 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 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 Find issues with JQL: Invoke-JiraRequest -Method Get -JQL 'project = PROJ AND 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 Invoke-JiraRequest Get-ModuleConfig Set-ModuleConfig https://github.com/ntatschner/TheCodeSaiyan-PowerShell-tcs.jira KEYWORDS tcs TheCodeSaiyan Jira JSM Atlassian |