jira

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// AuthorizeURL is where the user approves the OAuth application.
	AuthorizeURL = "https://auth.atlassian.com/authorize"

	// TokenURL exchanges authorization codes and refresh tokens for access tokens.
	TokenURL = "https://auth.atlassian.com/oauth/token"

	// AccessibleResourcesURL lists the Jira Cloud sites the OAuth grant has access to.
	AccessibleResourcesURL = "https://api.atlassian.com/oauth/token/accessible-resources"

	// APIProxyHost is how OAuth apps reach Jira's REST APIs - the site's own domain rejects OAuth bearer tokens.
	APIProxyHost = "https://api.atlassian.com/ex/jira"
)
View Source
const (
	SecretOAuthAccessToken  = "accessToken"
	SecretOAuthRefreshToken = "refreshToken"
)
View Source
const CreateIssuePayloadType = "jira.issue"
View Source
const DeleteIssuePayloadType = "jira.issueDeleted"
View Source
const GetIssuePayloadType = "jira.issue"
View Source
const GetWorkflowPayloadType = "jira.workflow"
View Source
const (

	// IssueCommentEventPayloadType is the event type emitted for every matching comment webhook.
	IssueCommentEventPayloadType = "jira.issueComment"
)
View Source
const (

	// IssueEventPayloadType is the event type emitted for every matching issue webhook.
	IssueEventPayloadType = "jira.issue"
)
View Source
const TransitionIssuePayloadType = "jira.issue"
View Source
const UpdateIssuePayloadType = "jira.issue"

Variables

This section is empty.

Functions

func ADFToText

func ADFToText(value any) string

ADFToText renders a Jira rich text value as readable plain text.

Jira Cloud answers with a rich text field such as an issue description either as an Atlassian Document Format document or, on a site that still sends the legacy representation, as a wiki markup string. Both shapes reach SuperPlane through webhooks and through the REST API, and a caller that interpolates a document into a string writes Go map formatting into user-facing text. A value that carries no readable text becomes an empty string.

func ApplyCompletionStatus

func ApplyCompletionStatus(client *Client, issueKey, column string, opts DoTransitionOptions) error

ApplyCompletionStatus moves an issue to the chosen column, or to a reachable Done-category status when column is empty. Prefer a status named Done.

func HostedOAuthCallbackURL

func HostedOAuthCallbackURL(baseURL string) string

HostedOAuthCallbackURL is the stable Atlassian callback for the hosted app.

func IsJiraAttachmentURL

func IsJiraAttachmentURL(raw string) bool

IsJiraAttachmentURL reports whether raw points at a Jira attachment download.

func IsRetryableAPIError

func IsRetryableAPIError(err error) bool

IsRetryableAPIError reports whether the consumer should nack the message so Tackle redelivers it. Rate limits, request timeouts, server errors, and transport failures retry. Client errors such as 401, 403, and 404 do not.

func IssueAlreadyInColumn

func IssueAlreadyInColumn(issue *Issue, column string) bool

func IssueDescriptionText

func IssueDescriptionText(issue *Issue) string

IssueDescriptionText reads the description of an issue as plain text.

func IssueHasWorkOrder

func IssueHasWorkOrder(tx *gorm.DB, factory *models.Factory, ref IssueRef) (bool, error)

IssueHasWorkOrder reports whether this factory already has a work order for the Jira issue on this site. Matching covers every work-order state.

func IssueKeyFromEventData

func IssueKeyFromEventData(eventData any) (string, bool)

IssueKeyFromEventData reads the Jira issue key from a canvas root event envelope. The envelope looks like:

{ "type": "jira.issue", "data": { "issue": { "key": "ENG-5" } } }

func IssueKeyFromURL

func IssueKeyFromURL(rawURL string) (string, bool)

IssueKeyFromURL reads the Jira issue key from an issue page URL.

func IssueStatusCategory

func IssueStatusCategory(issue *Issue) string

IssueStatusCategory reads the current workflow status category of an issue.

func IssueStatusName

func IssueStatusName(issue *Issue) string

IssueStatusName reads the current workflow status name of an issue.

func IssueURL

func IssueURL(siteURL, issueKey string) string

IssueURL builds the issue page address from the site and the issue key.

func IssueURLFragment

func IssueURLFragment(ref IssueRef) string

IssueURLFragment is the origin-URL substring that identifies a Jira issue on one site. Callers use it for a coarse lookup, then confirm with IssueRefFromURL so `acme.../browse/ENG-5` cannot match `acme.../browse/ENG-50` or the same key on another host.

func LockIssueWorkOrder

func LockIssueWorkOrder(tx *gorm.DB, factory *models.Factory, ref IssueRef) error

LockIssueWorkOrder serializes work-order creation for one Jira issue on one site in this factory. The lock is held until the caller commits tx.

func ParseJiraDateTime

func ParseJiraDateTime(raw string) (time.Time, bool)

ParseJiraDateTime parses timestamps returned by Jira APIs.

func ProjectKeyFromIssueKey

func ProjectKeyFromIssueKey(issueKey string) string

ProjectKeyFromIssueKey reads the project of an issue key such as ENG-42. A key without the "<project>-<number>" shape reports an empty project.

func SiteURLFromMetadata

func SiteURLFromMetadata(raw any) string

func UseHostedInstall

func UseHostedInstall(integrationName string) bool

UseHostedInstall is true when this integration create should skip Client ID and Client Secret and authorize SuperPlane's Atlassian OAuth app.

func UseHostedOAuth

func UseHostedOAuth() bool

UseHostedOAuth reports whether the process holds SuperPlane's Jira OAuth app.

Types

type ADFDoc

type ADFDoc struct {
	Type    string    `json:"type"`
	Version int       `json:"version"`
	Content []ADFNode `json:"content"`
}

func WrapInADF

func WrapInADF(text string) *ADFDoc

type ADFNode

type ADFNode struct {
	Type    string    `json:"type"`
	Content []ADFText `json:"content,omitempty"`
}

type ADFText

type ADFText struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

type APIError

type APIError struct {
	StatusCode int
	Body       string
}

APIError is a non-2xx response from Jira. Consumers use StatusCode to decide whether to retry.

func (*APIError) Error

func (e *APIError) Error() string

type AccessibleResource

type AccessibleResource struct {
	ID     string   `json:"id"`
	Name   string   `json:"name"`
	URL    string   `json:"url"`
	Scopes []string `json:"scopes"`
}

AccessibleResource is one Jira Cloud site the OAuth grant has access to.

type Auth

type Auth struct {
	// contains filtered or unexported fields
}

func NewAuth

func NewAuth(client core.HTTPContext) *Auth

func (*Auth) AccessibleResources

func (a *Auth) AccessibleResources(accessToken string) ([]AccessibleResource, error)

func (*Auth) ExchangeCode

func (a *Auth) ExchangeCode(clientID, clientSecret, code, redirectURI string) (*TokenResponse, error)

func (*Auth) HandleCallback

func (a *Auth) HandleCallback(req *http.Request, clientID, clientSecret, expectedState, redirectURI string) (*TokenResponse, error)

HandleCallback validates the OAuth callback request and exchanges its code for tokens.

func (*Auth) RefreshToken

func (a *Auth) RefreshToken(clientID, clientSecret, refreshToken string) (*TokenResponse, error)

type Client

type Client struct {
	CloudID     string
	AccessToken string
	// contains filtered or unexported fields
}

Client speaks to Jira Cloud through Atlassian's OAuth API proxy (api.atlassian.com/ex/jira/{cloudId}/...).

func NewClient

func NewClient(httpCtx core.HTTPContext, ctx core.IntegrationContext) (*Client, error)

func (*Client) CreateIssue

func (c *Client) CreateIssue(req *CreateIssueRequest) (*CreateIssueResponse, error)

func (*Client) CreateIssueWebhook

func (c *Client) CreateIssueWebhook(callbackURL, jqlFilter string, events []string) (int64, error)

CreateIssueWebhook registers a dynamic webhook for issue events, scoped by an optional JQL filter.

func (*Client) DeleteIssue added in v0.22.0

func (c *Client) DeleteIssue(issueKey string, opts DeleteIssueOptions) error

func (*Client) DeleteIssueWebhooks

func (c *Client) DeleteIssueWebhooks(webhookIDs []int64) error

DeleteIssueWebhooks removes previously-registered dynamic webhooks by id.

func (*Client) DoTransition added in v0.22.0

func (c *Client) DoTransition(issueKey, id string) error

DoTransition advances an issue along the given workflow transition.

func (*Client) DoTransitionWithOptions added in v0.25.0

func (c *Client) DoTransitionWithOptions(issueKey, id string, opts DoTransitionOptions) error

DoTransitionWithOptions advances an issue and optionally applies transition-scoped fields. The caller is responsible for ensuring that any fields it sets are actually on the chosen transition's screen — Jira returns a 400 with "Field 'X' cannot be set. It is not on the appropriate screen, or unknown." otherwise. applyStatusWithOptions handles that pre-check.

func (*Client) GetCurrentUser

func (c *Client) GetCurrentUser() (*User, error)

func (*Client) GetIssue

func (c *Client) GetIssue(issueKey string) (*Issue, error)

func (*Client) GetIssueTransitions added in v0.22.0

func (c *Client) GetIssueTransitions(issueKey string) ([]Transition, error)

GetIssueTransitions returns the transitions available from an issue's current workflow state, expanded with each transition's per-screen fields so callers can decide whether a given field (for example resolution) can be set during the transition.

func (*Client) GetIssueWithOptions added in v0.22.0

func (c *Client) GetIssueWithOptions(issueKey string, opts GetIssueOptions) (*Issue, error)

func (*Client) GetProject added in v0.25.0

func (c *Client) GetProject(projectKey string) (*Project, error)

func (*Client) GetProjectIssueTypes added in v0.22.0

func (c *Client) GetProjectIssueTypes(projectKey string) ([]IssueTypeMeta, error)

GetProjectIssueTypes returns the issue types available for creating issues in the given project. Uses the create-metadata endpoint which scopes the list to types the user is permitted to create.

func (*Client) GetProjectStatuses added in v0.22.0

func (c *Client) GetProjectStatuses(projectKey string) ([]Status, error)

GetProjectStatuses returns the unique set of statuses across all issue types in a project. /rest/api/3/project/{key}/statuses returns an entry per issue type, each with its own status list — we flatten and dedupe by status name.

func (*Client) GetWorkflowScheme added in v0.25.0

func (c *Client) GetWorkflowScheme(schemeID string) (*WorkflowSchemeDetail, error)

GetWorkflowScheme returns details for one workflow scheme.

func (*Client) GetWorkflowSchemeForProject added in v0.25.0

func (c *Client) GetWorkflowSchemeForProject(projectID string) (*WorkflowSchemeDetail, error)

GetWorkflowSchemeForProject returns the workflow scheme assigned to a company-managed project. For team-managed projects Jira may return an empty list (their workflow lives directly on the project), so callers should handle a nil result.

func (*Client) GetWorkflowStatusesByName added in v0.25.0

func (c *Client) GetWorkflowStatusesByName(workflowName string) ([]Status, error)

GetWorkflowStatusesByName returns the statuses of the workflow with the given exact name. Jira's /rest/api/3/workflow/search?workflowName=... does a prefix-style match server-side and can return multiple workflows, so we filter for an exact name match here and refuse to guess if none of the returned workflows match — returning a different workflow's statuses would silently mis-describe the issue's state machine.

func (*Client) IssueFiles

func (c *Client) IssueFiles(ctx context.Context, issueKey, description string) ([]IssueFile, error)

IssueFiles downloads the files attached to an issue, plus Jira attachment URLs already written in description. OAuth credentials stay on the request.

func (*Client) ListAssignableUsers added in v0.22.0

func (c *Client) ListAssignableUsers(projectKey string) ([]User, error)

ListAssignableUsers returns the users assignable to issues in a given project. /rest/api/3/user/assignable/search is paginated; we cap at 50 entries, which matches the picker's practical UX.

func (*Client) ListGlobalStatuses added in v0.25.0

func (c *Client) ListGlobalStatuses() ([]Status, error)

ListGlobalStatuses returns every workflow status visible to the caller via /rest/api/3/statuses/search. Used by the issueStatus resource picker when no project context is available (e.g. when defining a global workflow) and to look up status categories at workflow-create time.

func (*Client) ListIssueAttachments

func (c *Client) ListIssueAttachments(issueKey string) ([]IssueAttachment, error)

ListIssueAttachments returns files linked to one issue.

func (*Client) ListIssueWebhooks

func (c *Client) ListIssueWebhooks() ([]IssueWebhook, error)

ListIssueWebhooks returns every dynamic webhook registered by this OAuth app.

func (*Client) ListPriorities added in v0.22.0

func (c *Client) ListPriorities() ([]Priority, error)

ListPriorities returns all priorities configured on the Jira site. Priorities are instance-level, not project-scoped.

func (*Client) ListProjects

func (c *Client) ListProjects() ([]Project, error)

func (*Client) ListResolutions added in v0.25.0

func (c *Client) ListResolutions() ([]Resolution, error)

ListResolutions returns all resolutions configured on the Jira site. Resolutions are instance-level, not project-scoped.

func (*Client) Refresh

func (c *Client) Refresh() error

Refresh exchanges the stored refresh token for a new access/refresh token pair and persists them, along with when the new access token expires so Sync can proactively refresh ahead of that point.

func (*Client) RefreshIssueWebhooks

func (c *Client) RefreshIssueWebhooks(webhookIDs []int64) error

RefreshIssueWebhooks extends the life of previously-registered dynamic webhooks by another 30 days from now - Atlassian expires them 30 days after creation or after their last refresh.

func (*Client) SearchIssues added in v0.22.0

func (c *Client) SearchIssues(jql string, maxResults int) ([]IssueSearchHit, error)

SearchIssues runs a JQL search and returns the first page of issues (maxResults is capped at 100).

func (*Client) SearchIssuesUpTo added in v0.22.0

func (c *Client) SearchIssuesUpTo(jql string, maxIssues int) ([]IssueSearchHit, error)

SearchIssuesUpTo pages through POST /rest/api/3/search/jql until maxIssues are collected or Jira reports no further results. Jira caps each request at 100 issues.

func (*Client) UpdateIssue added in v0.22.0

func (c *Client) UpdateIssue(issueKey string, req *UpdateIssueRequest, opts UpdateIssueOptions) error

type Comment

type Comment struct {
	ID           string `json:"id"`
	Body         any    `json:"body"`
	Author       *User  `json:"author,omitempty"`
	UpdateAuthor *User  `json:"updateAuthor,omitempty"`
}

Comment is a Jira issue comment, as sent in comment webhook payloads.

type CommentWebhookPayload

type CommentWebhookPayload struct {
	WebhookEvent string   `json:"webhookEvent"`
	Comment      *Comment `json:"comment"`
	Issue        *Issue   `json:"issue"`
}

CommentWebhookPayload is the shape Jira Cloud sends for comment event webhooks.

type CreateIssue

type CreateIssue struct{}

func (*CreateIssue) Cancel

func (c *CreateIssue) Cancel(ctx core.ExecutionContext) error

func (*CreateIssue) Cleanup

func (c *CreateIssue) Cleanup(ctx core.SetupContext) error

func (*CreateIssue) Color

func (c *CreateIssue) Color() string

func (*CreateIssue) Configuration

func (c *CreateIssue) Configuration() []configuration.Field

func (*CreateIssue) Description

func (c *CreateIssue) Description() string

func (*CreateIssue) Documentation

func (c *CreateIssue) Documentation() string

func (*CreateIssue) ExampleOutput

func (c *CreateIssue) ExampleOutput() map[string]any

func (*CreateIssue) Execute

func (c *CreateIssue) Execute(ctx core.ExecutionContext) error

func (*CreateIssue) HandleHook added in v0.18.0

func (c *CreateIssue) HandleHook(ctx core.ActionHookContext) error

func (*CreateIssue) HandleWebhook

func (*CreateIssue) Hooks added in v0.18.0

func (c *CreateIssue) Hooks() []core.Hook

func (*CreateIssue) Icon

func (c *CreateIssue) Icon() string

func (*CreateIssue) Label

func (c *CreateIssue) Label() string

func (*CreateIssue) Name

func (c *CreateIssue) Name() string

func (*CreateIssue) OutputChannels

func (c *CreateIssue) OutputChannels(configuration any) []core.OutputChannel

func (*CreateIssue) Setup

func (c *CreateIssue) Setup(ctx core.SetupContext) error

type CreateIssueFields

type CreateIssueFields struct {
	Project     ProjectRef `json:"project"`
	IssueType   IssueType  `json:"issuetype"`
	Summary     string     `json:"summary"`
	Description *ADFDoc    `json:"description,omitempty"`
	Assignee    *UserRef   `json:"assignee,omitempty"`
}

type CreateIssueRequest

type CreateIssueRequest struct {
	Fields CreateIssueFields `json:"fields"`
}

type CreateIssueResponse

type CreateIssueResponse struct {
	ID   string `json:"id"`
	Key  string `json:"key"`
	Self string `json:"self"`
}

type CreateIssueSpec

type CreateIssueSpec struct {
	Project     string `json:"project" mapstructure:"project"`
	IssueType   string `json:"issueType" mapstructure:"issueType"`
	Summary     string `json:"summary" mapstructure:"summary"`
	Description string `json:"description" mapstructure:"description"`
	Assignee    string `json:"assignee" mapstructure:"assignee"`
	Status      string `json:"status" mapstructure:"status"`
}

type DeleteIssue added in v0.22.0

type DeleteIssue struct{}

func (*DeleteIssue) Cancel added in v0.22.0

func (c *DeleteIssue) Cancel(ctx core.ExecutionContext) error

func (*DeleteIssue) Cleanup added in v0.22.0

func (c *DeleteIssue) Cleanup(ctx core.SetupContext) error

func (*DeleteIssue) Color added in v0.22.0

func (c *DeleteIssue) Color() string

func (*DeleteIssue) Configuration added in v0.22.0

func (c *DeleteIssue) Configuration() []configuration.Field

func (*DeleteIssue) Description added in v0.22.0

func (c *DeleteIssue) Description() string

func (*DeleteIssue) Documentation added in v0.22.0

func (c *DeleteIssue) Documentation() string

func (*DeleteIssue) ExampleOutput added in v0.22.0

func (c *DeleteIssue) ExampleOutput() map[string]any

func (*DeleteIssue) Execute added in v0.22.0

func (c *DeleteIssue) Execute(ctx core.ExecutionContext) error

func (*DeleteIssue) HandleHook added in v0.22.0

func (c *DeleteIssue) HandleHook(ctx core.ActionHookContext) error

func (*DeleteIssue) HandleWebhook added in v0.22.0

func (*DeleteIssue) Hooks added in v0.22.0

func (c *DeleteIssue) Hooks() []core.Hook

func (*DeleteIssue) Icon added in v0.22.0

func (c *DeleteIssue) Icon() string

func (*DeleteIssue) Label added in v0.22.0

func (c *DeleteIssue) Label() string

func (*DeleteIssue) Name added in v0.22.0

func (c *DeleteIssue) Name() string

func (*DeleteIssue) OutputChannels added in v0.22.0

func (c *DeleteIssue) OutputChannels(configuration any) []core.OutputChannel

func (*DeleteIssue) Setup added in v0.22.0

func (c *DeleteIssue) Setup(ctx core.SetupContext) error

type DeleteIssueOptions added in v0.22.0

type DeleteIssueOptions struct {
	DeleteSubtasks bool
}

type DeleteIssueOutput added in v0.22.0

type DeleteIssueOutput struct {
	ID      string `json:"id"`
	Key     string `json:"key"`
	Deleted bool   `json:"deleted"`
}

type DeleteIssueSpec added in v0.22.0

type DeleteIssueSpec struct {
	Project        string `json:"project" mapstructure:"project"`
	IssueKey       string `json:"issueKey" mapstructure:"issueKey"`
	DeleteSubtasks bool   `json:"deleteSubtasks" mapstructure:"deleteSubtasks"`
}

type DoTransitionOptions added in v0.25.0

type DoTransitionOptions struct {
	Comment    string
	Resolution string
}

type FlexibleString added in v0.25.0

type FlexibleString string

func (FlexibleString) String added in v0.25.0

func (s FlexibleString) String() string

func (*FlexibleString) UnmarshalJSON added in v0.25.0

func (s *FlexibleString) UnmarshalJSON(b []byte) error

type GetIssue added in v0.22.0

type GetIssue struct{}

func (*GetIssue) Cancel added in v0.22.0

func (c *GetIssue) Cancel(ctx core.ExecutionContext) error

func (*GetIssue) Cleanup added in v0.22.0

func (c *GetIssue) Cleanup(ctx core.SetupContext) error

func (*GetIssue) Color added in v0.22.0

func (c *GetIssue) Color() string

func (*GetIssue) Configuration added in v0.22.0

func (c *GetIssue) Configuration() []configuration.Field

func (*GetIssue) Description added in v0.22.0

func (c *GetIssue) Description() string

func (*GetIssue) Documentation added in v0.22.0

func (c *GetIssue) Documentation() string

func (*GetIssue) ExampleOutput added in v0.22.0

func (c *GetIssue) ExampleOutput() map[string]any

func (*GetIssue) Execute added in v0.22.0

func (c *GetIssue) Execute(ctx core.ExecutionContext) error

func (*GetIssue) HandleHook added in v0.22.0

func (c *GetIssue) HandleHook(ctx core.ActionHookContext) error

func (*GetIssue) HandleWebhook added in v0.22.0

func (*GetIssue) Hooks added in v0.22.0

func (c *GetIssue) Hooks() []core.Hook

func (*GetIssue) Icon added in v0.22.0

func (c *GetIssue) Icon() string

func (*GetIssue) Label added in v0.22.0

func (c *GetIssue) Label() string

func (*GetIssue) Name added in v0.22.0

func (c *GetIssue) Name() string

func (*GetIssue) OutputChannels added in v0.22.0

func (c *GetIssue) OutputChannels(configuration any) []core.OutputChannel

func (*GetIssue) Setup added in v0.22.0

func (c *GetIssue) Setup(ctx core.SetupContext) error

type GetIssueOptions added in v0.22.0

type GetIssueOptions struct {
	Fields string
	Expand string
}

type GetIssueSpec added in v0.22.0

type GetIssueSpec struct {
	Project  string `json:"project" mapstructure:"project"`
	IssueKey string `json:"issueKey" mapstructure:"issueKey"`
	Expand   string `json:"expand" mapstructure:"expand"`
}

type GetWorkflow added in v0.25.0

type GetWorkflow struct{}

func (*GetWorkflow) Cancel added in v0.25.0

func (c *GetWorkflow) Cancel(ctx core.ExecutionContext) error

func (*GetWorkflow) Cleanup added in v0.25.0

func (c *GetWorkflow) Cleanup(ctx core.SetupContext) error

func (*GetWorkflow) Color added in v0.25.0

func (c *GetWorkflow) Color() string

func (*GetWorkflow) Configuration added in v0.25.0

func (c *GetWorkflow) Configuration() []configuration.Field

func (*GetWorkflow) Description added in v0.25.0

func (c *GetWorkflow) Description() string

func (*GetWorkflow) Documentation added in v0.25.0

func (c *GetWorkflow) Documentation() string

func (*GetWorkflow) ExampleOutput added in v0.25.0

func (c *GetWorkflow) ExampleOutput() map[string]any

func (*GetWorkflow) Execute added in v0.25.0

func (c *GetWorkflow) Execute(ctx core.ExecutionContext) error

func (*GetWorkflow) HandleHook added in v0.25.0

func (c *GetWorkflow) HandleHook(ctx core.ActionHookContext) error

func (*GetWorkflow) HandleWebhook added in v0.25.0

func (*GetWorkflow) Hooks added in v0.25.0

func (c *GetWorkflow) Hooks() []core.Hook

func (*GetWorkflow) Icon added in v0.25.0

func (c *GetWorkflow) Icon() string

func (*GetWorkflow) Label added in v0.25.0

func (c *GetWorkflow) Label() string

func (*GetWorkflow) Name added in v0.25.0

func (c *GetWorkflow) Name() string

func (*GetWorkflow) OutputChannels added in v0.25.0

func (c *GetWorkflow) OutputChannels(configuration any) []core.OutputChannel

func (*GetWorkflow) Setup added in v0.25.0

func (c *GetWorkflow) Setup(ctx core.SetupContext) error

type GetWorkflowOutput added in v0.25.0

type GetWorkflowOutput struct {
	IssueKey             string                        `json:"issueKey"`
	IssueType            string                        `json:"issueType,omitempty"`
	ProjectKey           string                        `json:"projectKey,omitempty"`
	WorkflowName         string                        `json:"workflowName,omitempty"`
	WorkflowSchemeID     string                        `json:"workflowSchemeId,omitempty"`
	WorkflowSchemeName   string                        `json:"workflowSchemeName,omitempty"`
	CurrentStatus        string                        `json:"currentStatus,omitempty"`
	CurrentStatusID      string                        `json:"currentStatusId,omitempty"`
	Statuses             []WorkflowStatus              `json:"statuses,omitempty"`
	AvailableTransitions []WorkflowAvailableTransition `json:"availableTransitions,omitempty"`
}

GetWorkflowOutput summarizes the workflow currently bound to an issue: where the issue is now, every status the workflow defines, and every transition it can take from the current state.

type GetWorkflowSpec added in v0.25.0

type GetWorkflowSpec struct {
	Project  string `json:"project" mapstructure:"project"`
	IssueKey string `json:"issueKey" mapstructure:"issueKey"`
}

type Issue

type Issue struct {
	ID     string         `json:"id"`
	Key    string         `json:"key"`
	Self   string         `json:"self"`
	Fields map[string]any `json:"fields"`
}

type IssueAttachment

type IssueAttachment struct {
	ID           string
	Filename     string
	MIMEType     string
	ContentURL   string
	ThumbnailURL string
}

IssueAttachment is a file linked to a Jira issue. Webhook payloads may include these records under issue.fields.attachment, but a fresh API read is still used so late uploads are not missed.

type IssueChangelog

type IssueChangelog struct {
	ID    string               `json:"id,omitempty"`
	Items []IssueChangelogItem `json:"items,omitempty"`
}

type IssueChangelogItem

type IssueChangelogItem struct {
	Field      string `json:"field"`
	FieldType  string `json:"fieldtype,omitempty"`
	From       string `json:"from,omitempty"`
	FromString string `json:"fromString,omitempty"`
	To         string `json:"to,omitempty"`
	ToString   string `json:"toString,omitempty"`
}

type IssueCommentEvent

type IssueCommentEvent struct {
	Action  string   `json:"action"`
	Comment *Comment `json:"comment"`
	Issue   *Issue   `json:"issue"`
}

IssueCommentEvent is the event SuperPlane emits for each matching comment webhook.

type IssueEvent

type IssueEvent struct {
	Action string `json:"action"`
	// URL is the issue page (`<site>/browse/<key>`). Origin sniffing prefers
	// this key over nested `self` addresses, which point at the API proxy.
	// The field is omitted when the site address is unknown.
	URL   string `json:"url,omitempty"`
	Issue *Issue `json:"issue"`
	// Description is the issue description as plain text. Jira Cloud holds a
	// description in Atlassian Document Format, which reads as a Go map when a
	// template interpolates it, so the event carries a readable copy next to
	// the raw field. The key is always present: an absent key would resolve to
	// "null" in a template.
	Description string          `json:"description"`
	User        *User           `json:"user,omitempty"`
	Changelog   *IssueChangelog `json:"changelog,omitempty"`
}

IssueEvent is the event SuperPlane emits for each matching issue webhook.

func NewIssueEvent

func NewIssueEvent(action string, issue *Issue, user *User, changelog *IssueChangelog, siteURL string) IssueEvent

NewIssueEvent builds the event for one issue, so every emitter - the issue and incident webhooks, and the intake seed - reports the same shape.

type IssueFile

type IssueFile struct {
	Name        string
	ContentType string
	Body        []byte
	ReplaceURLs []string
}

IssueFile is a downloaded Jira file ready to store on a work order. ReplaceURLs are the exact description strings that should become the stored file reference. An empty list means the file is appended.

type IssueRef

type IssueRef struct {
	Key  string
	Host string
}

IssueRef identifies one Jira issue on one site.

func IssueRefFromEventData

func IssueRefFromEventData(eventData any) (IssueRef, bool)

IssueRefFromEventData reads the Jira issue key and site host from a canvas root event envelope. The envelope looks like:

{ "type": "jira.issue", "data": { "url": "https://acme.atlassian.net/browse/ENG-5", "issue": { "key": "ENG-5" } } }

func IssueRefFromSite

func IssueRefFromSite(siteURL, issueKey string) (IssueRef, bool)

IssueRefFromSite builds an issue identity from a site address and issue key.

func IssueRefFromURL

func IssueRefFromURL(rawURL string) (IssueRef, bool)

IssueRefFromURL reads the Jira issue key and site host from an issue page URL. It accepts `/browse/<key>` with or without a trailing slash or query string. Other paths are ignored.

type IssueSearchHit added in v0.22.0

type IssueSearchHit struct {
	ID     string         `json:"id"`
	Key    string         `json:"key"`
	Fields map[string]any `json:"fields"`
}

IssueSearchHit is one element from POST /rest/api/3/search/jql.

type IssueType

type IssueType struct {
	Name string `json:"name"`
}

type IssueTypeMeta added in v0.22.0

type IssueTypeMeta struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Subtask bool   `json:"subtask"`
}

type IssueWebhook

type IssueWebhook struct {
	ID             int64    `json:"id"`
	URL            string   `json:"url"`
	JQLFilter      string   `json:"jqlFilter"`
	Events         []string `json:"events"`
	ExpirationDate string   `json:"expirationDate"`
}

IssueWebhook is one dynamic webhook registered by this OAuth app.

type IssueWebhookPayload

type IssueWebhookPayload struct {
	Timestamp    int64           `json:"timestamp,omitempty"`
	WebhookEvent string          `json:"webhookEvent"`
	Issue        *Issue          `json:"issue"`
	User         *User           `json:"user,omitempty"`
	Changelog    *IssueChangelog `json:"changelog,omitempty"`
}

IssueWebhookPayload is the shape Jira Cloud sends for issue event webhooks.

type IssueWebhookRegistration

type IssueWebhookRegistration struct {
	JQLFilter string   `json:"jqlFilter"`
	Events    []string `json:"events"`
}

IssueWebhookRegistration is one entry of the "webhooks" array in a dynamic webhook registration request. JQLFilter has no omitempty: Atlassian's schema requires the key to be present even when its value is an empty string (which matches every issue in every project), so dropping the key entirely for an unfiltered registration makes the whole request fail.

type Jira

type Jira struct{}

func (*Jira) Actions

func (j *Jira) Actions() []core.Action

func (*Jira) Cleanup

func (j *Jira) Cleanup(ctx core.IntegrationCleanupContext) error

func (*Jira) Configuration

func (j *Jira) Configuration() []configuration.Field

func (*Jira) Description

func (j *Jira) Description() string

func (*Jira) HandleHook added in v0.18.0

func (j *Jira) HandleHook(ctx core.IntegrationHookContext) error

func (*Jira) HandleRequest

func (j *Jira) HandleRequest(ctx core.HTTPRequestContext)

func (*Jira) Hooks added in v0.18.0

func (j *Jira) Hooks() []core.Hook

func (*Jira) Icon

func (j *Jira) Icon() string

func (*Jira) Instructions

func (j *Jira) Instructions() string

func (*Jira) Label

func (j *Jira) Label() string

func (*Jira) ListResources

func (j *Jira) ListResources(resourceType string, ctx core.ListResourcesContext) ([]core.IntegrationResource, error)

func (*Jira) Name

func (j *Jira) Name() string

func (*Jira) Sync

func (j *Jira) Sync(ctx core.SyncContext) error

func (*Jira) Triggers

func (j *Jira) Triggers() []core.Trigger

type JiraWebhookHandler

type JiraWebhookHandler struct{}

func (*JiraWebhookHandler) Cleanup

func (*JiraWebhookHandler) CompareConfig

func (h *JiraWebhookHandler) CompareConfig(a, b any) (bool, error)

func (*JiraWebhookHandler) Merge

func (h *JiraWebhookHandler) Merge(current, requested any) (any, bool, error)

func (*JiraWebhookHandler) Setup

type Metadata

type Metadata struct {
	State                *string   `json:"state,omitempty" mapstructure:"state,omitempty"`
	User                 *User     `json:"user,omitempty" mapstructure:"user,omitempty"`
	Projects             []Project `json:"projects" mapstructure:"projects"`
	CloudID              string    `json:"cloudId,omitempty" mapstructure:"cloudId,omitempty"`
	SiteURL              string    `json:"siteUrl,omitempty" mapstructure:"siteUrl,omitempty"`
	SiteName             string    `json:"siteName,omitempty" mapstructure:"siteName,omitempty"`
	AccessTokenExpiresAt string    `json:"accessTokenExpiresAt,omitempty" mapstructure:"accessTokenExpiresAt,omitempty"`

	// WebhookID is the shared dynamic webhook registered by JiraWebhookHandler, mirrored here
	// (in addition to the webhook record's own metadata) so the refreshWebhook hook - which only
	// has access to the integration, not any particular webhook record - can find it.
	WebhookID *int64 `json:"webhookId,omitempty" mapstructure:"webhookId,omitempty"`

	// IssueWebhookScopesRequested records whether the currently stored OAuth token was granted
	// with read:issue-details:jira. Atlassian will not deliver jira:issue_* webhooks without
	// that scope, even when manage:jira-webhook lets SuperPlane register the callback. Existing
	// connections that predate this flag stay Ready and get a reconnect prompt until a
	// successful callback sets it.
	IssueWebhookScopesRequested bool `json:"issueWebhookScopesRequested,omitempty" mapstructure:"issueWebhookScopesRequested,omitempty"`

	// HostedOAuth is true when this connection uses SuperPlane's Atlassian OAuth app.
	HostedOAuth bool `json:"hostedOAuth,omitempty" mapstructure:"hostedOAuth,omitempty"`

	// SetupReturnPath is the in-app path to open after Atlassian authorization.
	SetupReturnPath string `json:"setupReturnPath,omitempty" mapstructure:"setupReturnPath,omitempty"`
}

type NodeMetadata

type NodeMetadata struct {
	Project   *Project `json:"project,omitempty"`
	IssueType string   `json:"issueType,omitempty"`
	Status    string   `json:"status,omitempty"`
}

NodeMetadata stores metadata on action component nodes.

type OnIssue

type OnIssue struct{}

func (*OnIssue) Cleanup

func (t *OnIssue) Cleanup(ctx core.TriggerContext) error

Cleanup does nothing: the shared Jira webhook registered via RequestWebhook is torn down by the platform's webhook cleanup worker (through JiraWebhookHandler.Cleanup) once the last jira.onIssue trigger referencing it is removed.

func (*OnIssue) Color

func (t *OnIssue) Color() string

func (*OnIssue) Configuration

func (t *OnIssue) Configuration() []configuration.Field

func (*OnIssue) Description

func (t *OnIssue) Description() string

func (*OnIssue) Documentation

func (t *OnIssue) Documentation() string

func (*OnIssue) ExampleData

func (t *OnIssue) ExampleData() map[string]any

func (*OnIssue) HandleHook

func (t *OnIssue) HandleHook(ctx core.TriggerHookContext) (map[string]any, error)

func (*OnIssue) HandleWebhook

func (t *OnIssue) HandleWebhook(ctx core.WebhookRequestContext) (int, *core.WebhookResponseBody, error)

func (*OnIssue) Hooks

func (t *OnIssue) Hooks() []core.Hook

func (*OnIssue) Icon

func (t *OnIssue) Icon() string

func (*OnIssue) Label

func (t *OnIssue) Label() string

func (*OnIssue) Name

func (t *OnIssue) Name() string

func (*OnIssue) Setup

func (t *OnIssue) Setup(ctx core.TriggerContext) error

type OnIssueComment

type OnIssueComment struct{}

func (*OnIssueComment) Cleanup

func (t *OnIssueComment) Cleanup(ctx core.TriggerContext) error

func (*OnIssueComment) Color

func (t *OnIssueComment) Color() string

func (*OnIssueComment) Configuration

func (t *OnIssueComment) Configuration() []configuration.Field

func (*OnIssueComment) Description

func (t *OnIssueComment) Description() string

func (*OnIssueComment) Documentation

func (t *OnIssueComment) Documentation() string

func (*OnIssueComment) ExampleData

func (t *OnIssueComment) ExampleData() map[string]any

func (*OnIssueComment) HandleHook

func (t *OnIssueComment) HandleHook(ctx core.TriggerHookContext) (map[string]any, error)

func (*OnIssueComment) HandleWebhook

func (*OnIssueComment) Hooks

func (t *OnIssueComment) Hooks() []core.Hook

func (*OnIssueComment) Icon

func (t *OnIssueComment) Icon() string

func (*OnIssueComment) Label

func (t *OnIssueComment) Label() string

func (*OnIssueComment) Name

func (t *OnIssueComment) Name() string

func (*OnIssueComment) Setup

func (t *OnIssueComment) Setup(ctx core.TriggerContext) error

type OnIssueCommentConfiguration

type OnIssueCommentConfiguration struct {
	Project       string   `json:"project" mapstructure:"project"`
	Events        []string `json:"events" mapstructure:"events"`
	ContentFilter string   `json:"contentFilter" mapstructure:"contentFilter"`
}

type OnIssueCommentMetadata

type OnIssueCommentMetadata struct {
	Project *Project `json:"project,omitempty" mapstructure:"project,omitempty"`
}

type OnIssueConfiguration

type OnIssueConfiguration struct {
	Project string   `json:"project" mapstructure:"project"`
	Events  []string `json:"events" mapstructure:"events"`
}

type OnIssueMetadata

type OnIssueMetadata struct {
	Project *Project `json:"project,omitempty" mapstructure:"project,omitempty"`
}

type Priority added in v0.22.0

type Priority struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type Project

type Project struct {
	ID         string `json:"id"`
	Key        string `json:"key"`
	Name       string `json:"name"`
	Style      string `json:"style,omitempty"`
	Simplified bool   `json:"simplified,omitempty"`
}

type ProjectRef

type ProjectRef struct {
	Key string `json:"key"`
}

type Resolution added in v0.25.0

type Resolution struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type Status added in v0.22.0

type Status struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Category string `json:"-"`
}

Status represents a Jira workflow status. Category is the normalized statusCategory value used by Jira's workflow APIs: "TODO", "IN_PROGRESS", "DONE", or "UNDEFINED". It is populated from either the flat string returned by /rest/api/3/statuses/search or the nested statusCategory.key returned by /rest/api/3/project/{key}/statuses.

func (*Status) UnmarshalJSON

func (s *Status) UnmarshalJSON(data []byte) error

UnmarshalJSON reads both the flat statusCategory string from /rest/api/3/statuses/search and the nested statusCategory.key object returned by issue and transition payloads.

type TokenResponse

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	ExpiresIn    int    `json:"expires_in"`
}

TokenResponse is Atlassian's OAuth token endpoint response. Refresh tokens rotate on every use, so both fields are replaced together on refresh.

func (*TokenResponse) ExpiresAt

func (t *TokenResponse) ExpiresAt() time.Time

ExpiresAt returns when the access token stops working, or the zero time when Atlassian did not report a lifetime.

func (*TokenResponse) GetExpiration

func (t *TokenResponse) GetExpiration() time.Duration

GetExpiration returns how long to wait before resyncing to refresh the token: half its lifetime, so one failed resync still leaves time to retry.

type Transition added in v0.22.0

type Transition struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	To   Status `json:"to"`
	// Fields lists the fields that are present on this transition's screen,
	// keyed by Jira field id (for example "resolution", "customfield_10010").
	// Populated by GetIssueTransitions because we always pass
	// expand=transitions.fields — needed to know whether a transition supports
	// setting fields like resolution. Empty when no screen is configured.
	Fields map[string]any `json:"fields,omitempty"`
}

func (Transition) HasField added in v0.25.0

func (t Transition) HasField(fieldID string) bool

HasField reports whether this transition's screen includes the named Jira field id. Used to avoid the "Field 'X' cannot be set. It is not on the appropriate screen" error from Jira when the user supplies a field that the chosen transition doesn't actually accept.

type TransitionIssue added in v0.25.0

type TransitionIssue struct{}

func (*TransitionIssue) Cancel added in v0.25.0

func (c *TransitionIssue) Cancel(ctx core.ExecutionContext) error

func (*TransitionIssue) Cleanup added in v0.25.0

func (c *TransitionIssue) Cleanup(ctx core.SetupContext) error

func (*TransitionIssue) Color added in v0.25.0

func (c *TransitionIssue) Color() string

func (*TransitionIssue) Configuration added in v0.25.0

func (c *TransitionIssue) Configuration() []configuration.Field

func (*TransitionIssue) Description added in v0.25.0

func (c *TransitionIssue) Description() string

func (*TransitionIssue) Documentation added in v0.25.0

func (c *TransitionIssue) Documentation() string

func (*TransitionIssue) ExampleOutput added in v0.25.0

func (c *TransitionIssue) ExampleOutput() map[string]any

func (*TransitionIssue) Execute added in v0.25.0

func (c *TransitionIssue) Execute(ctx core.ExecutionContext) error

func (*TransitionIssue) HandleHook added in v0.25.0

func (c *TransitionIssue) HandleHook(ctx core.ActionHookContext) error

func (*TransitionIssue) HandleWebhook added in v0.25.0

func (*TransitionIssue) Hooks added in v0.25.0

func (c *TransitionIssue) Hooks() []core.Hook

func (*TransitionIssue) Icon added in v0.25.0

func (c *TransitionIssue) Icon() string

func (*TransitionIssue) Label added in v0.25.0

func (c *TransitionIssue) Label() string

func (*TransitionIssue) Name added in v0.25.0

func (c *TransitionIssue) Name() string

func (*TransitionIssue) OutputChannels added in v0.25.0

func (c *TransitionIssue) OutputChannels(configuration any) []core.OutputChannel

func (*TransitionIssue) Setup added in v0.25.0

func (c *TransitionIssue) Setup(ctx core.SetupContext) error

type TransitionIssueSpec added in v0.25.0

type TransitionIssueSpec struct {
	Project      string `json:"project" mapstructure:"project"`
	IssueKey     string `json:"issueKey" mapstructure:"issueKey"`
	TargetStatus string `json:"targetStatus" mapstructure:"targetStatus"`
	Comment      string `json:"comment" mapstructure:"comment"`
	Resolution   string `json:"resolution" mapstructure:"resolution"`
}

type UpdateIssue added in v0.22.0

type UpdateIssue struct{}

func (*UpdateIssue) Cancel added in v0.22.0

func (c *UpdateIssue) Cancel(ctx core.ExecutionContext) error

func (*UpdateIssue) Cleanup added in v0.22.0

func (c *UpdateIssue) Cleanup(ctx core.SetupContext) error

func (*UpdateIssue) Color added in v0.22.0

func (c *UpdateIssue) Color() string

func (*UpdateIssue) Configuration added in v0.22.0

func (c *UpdateIssue) Configuration() []configuration.Field

func (*UpdateIssue) Description added in v0.22.0

func (c *UpdateIssue) Description() string

func (*UpdateIssue) Documentation added in v0.22.0

func (c *UpdateIssue) Documentation() string

func (*UpdateIssue) ExampleOutput added in v0.22.0

func (c *UpdateIssue) ExampleOutput() map[string]any

func (*UpdateIssue) Execute added in v0.22.0

func (c *UpdateIssue) Execute(ctx core.ExecutionContext) error

func (*UpdateIssue) HandleHook added in v0.22.0

func (c *UpdateIssue) HandleHook(ctx core.ActionHookContext) error

func (*UpdateIssue) HandleWebhook added in v0.22.0

func (*UpdateIssue) Hooks added in v0.22.0

func (c *UpdateIssue) Hooks() []core.Hook

func (*UpdateIssue) Icon added in v0.22.0

func (c *UpdateIssue) Icon() string

func (*UpdateIssue) Label added in v0.22.0

func (c *UpdateIssue) Label() string

func (*UpdateIssue) Name added in v0.22.0

func (c *UpdateIssue) Name() string

func (*UpdateIssue) OutputChannels added in v0.22.0

func (c *UpdateIssue) OutputChannels(configuration any) []core.OutputChannel

func (*UpdateIssue) Setup added in v0.22.0

func (c *UpdateIssue) Setup(ctx core.SetupContext) error

type UpdateIssueOptions added in v0.22.0

type UpdateIssueOptions struct {
	NotifyUsers *bool
}

type UpdateIssueRequest added in v0.22.0

type UpdateIssueRequest struct {
	Fields map[string]any `json:"fields,omitempty"`
}

type UpdateIssueSpec added in v0.22.0

type UpdateIssueSpec struct {
	Project     string    `json:"project" mapstructure:"project"`
	IssueKey    string    `json:"issueKey" mapstructure:"issueKey"`
	Summary     *string   `json:"summary,omitempty" mapstructure:"summary"`
	Description *string   `json:"description,omitempty" mapstructure:"description"`
	IssueType   *string   `json:"issueType,omitempty" mapstructure:"issueType"`
	Assignee    *string   `json:"assignee,omitempty" mapstructure:"assignee"`
	Priority    *string   `json:"priority,omitempty" mapstructure:"priority"`
	Labels      *[]string `json:"labels,omitempty" mapstructure:"labels"`
	NotifyUsers *bool     `json:"notifyUsers,omitempty" mapstructure:"notifyUsers"`
}

type User

type User struct {
	AccountID   string `json:"accountId"`
	DisplayName string `json:"displayName"`
	EmailAddr   string `json:"emailAddress,omitempty"`
}

type UserRef added in v0.22.0

type UserRef struct {
	AccountID string `json:"accountId"`
}

type WebhookConfiguration

type WebhookConfiguration struct {
	Kind     string   `json:"kind,omitempty" mapstructure:"kind,omitempty"`
	Events   []string `json:"events,omitempty" mapstructure:"events,omitempty"`
	Projects []string `json:"projects,omitempty" mapstructure:"projects,omitempty"`
}

Kind distinguishes stored legacy alert webhooks from the shared issue/comment webhook.

type WebhookMetadata

type WebhookMetadata struct {
	WebhookID *int64 `json:"webhookId,omitempty" mapstructure:"webhookId,omitempty"`
}

type WorkflowAvailableTransition added in v0.25.0

type WorkflowAvailableTransition struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	ToStatusID string `json:"toStatusId,omitempty"`
	ToStatus   string `json:"toStatus"`
}

WorkflowAvailableTransition is one transition the issue can take right now from its current status.

type WorkflowSchemeDetail added in v0.25.0

type WorkflowSchemeDetail struct {
	ID                FlexibleString    `json:"id"`
	Name              string            `json:"name"`
	DefaultWorkflow   string            `json:"defaultWorkflow"`
	IssueTypeMappings map[string]string `json:"issueTypeMappings"`
}

WorkflowSchemeDetail is returned by GET /rest/api/3/workflowscheme/{id}. It describes which workflow is used per issue type. Used to resolve the workflow bound to an issue (issue type ID -> workflow name).

type WorkflowStatus added in v0.25.0

type WorkflowStatus struct {
	ID        string `json:"id,omitempty"`
	Name      string `json:"name"`
	Category  string `json:"category,omitempty"`
	IsCurrent bool   `json:"isCurrent,omitempty"`
}

WorkflowStatus is a status inside a workflow definition. Includes whether it's the issue's current status so the canvas can render the workflow as a state machine with the current location highlighted.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL