jira

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Nov 20, 2022 License: GPL-3.0 Imports: 26 Imported by: 0

Documentation

Overview

Package jira contains the Jira bridge implementation

Index

Constants

View Source 
const TimeFormat = "2006-01-02T15:04:05.999999999Z0700"

Variables

View Source 
var (
	ErrMissingCredentials = errors.New("missing credentials")
)

Functions

func ParseTime 

func ParseTime(timeStr string) (time.Time, error)

ParseTime parse an RFC3339 string with nanoseconds

func UpdateIssueStatus 

func UpdateIssueStatus(client *Client, issueKeyOrID string, desiredStateNameOrID string) (time.Time, error)

UpdateIssueStatus attempts to change the "status" field by finding a transition which achieves the desired state and then performing that transition

Types

type ChangeLogEntry 

type ChangeLogEntry struct {
	ID      string          `json:"id"`
	Author  User            `json:"author"`
	Created Time            `json:"created"`
	Items   []ChangeLogItem `json:"items"`
}

ChangeLogEntry One entry in a changelog https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

type ChangeLogItem 

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

ChangeLogItem "field-change" data within a changelog entry. A single changelog entry might effect multiple fields. For example, closing an issue generally requires a change in "status" and "resolution" https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

type ChangeLogIterator 

type ChangeLogIterator struct {
	Err error
	// contains filtered or unexported fields
}

ChangeLogIterator cursor within paginated results from the /search endpoint

func (*ChangeLogIterator) HasError 

func (cli *ChangeLogIterator) HasError() bool

HasError returns true if the iterator is holding an error

func (*ChangeLogIterator) HasNext 

func (cli *ChangeLogIterator) HasNext() bool

HasNext returns true if there is another item available in the result set

func (*ChangeLogIterator) Next 

func (cli *ChangeLogIterator) Next() *ChangeLogEntry

Next Return the next item in the result set and advance the iterator. Advancing the iterator may require fetching a new page.

type ChangeLogPage 

type ChangeLogPage struct {
	StartAt    int              `json:"startAt"`
	MaxResults int              `json:"maxResults"`
	Total      int              `json:"total"`
	IsLast     bool             `json:"isLast"` // Cloud-only
	Entries    []ChangeLogEntry `json:"histories"`
	Values     []ChangeLogEntry `json:"values"`
}

ChangeLogPage A collection of changes to issue metadata https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

func (*ChangeLogPage) IsLastPage 

func (clp *ChangeLogPage) IsLastPage() bool

IsLastPage return true if there are no more items beyond this page

func (*ChangeLogPage) NextStartAt 

func (clp *ChangeLogPage) NextStartAt() int

NextStartAt return the index of the first item on the next page

type Client 

type Client struct {
	*http.Client
	// contains filtered or unexported fields
}

Client Thin wrapper around the http.Client providing jira-specific methods for API endpoints

func NewClient 

func NewClient(ctx context.Context, serverURL string) *Client

NewClient Construct a new client connected to the provided server and utilizing the given context for asynchronous events

func (*Client) AddComment 

func (client *Client) AddComment(issueKeyOrID, body string) (*Comment, error)

AddComment adds a new comment to an issue (and returns it).

func (*Client) CreateIssue 

func (client *Client) CreateIssue(projectIDOrKey, title, body string,
	extra map[string]interface{}) (*IssueCreateResult, error)

CreateIssue creates a new JIRA issue and returns it

func (*Client) DoTransition 

func (client *Client) DoTransition(issueKeyOrID string, transitionID string) (time.Time, error)

DoTransition changes the "status" of an issue

func (*Client) GetChangeLog 

func (client *Client) GetChangeLog(idOrKey string, maxResults int, startAt int) (*ChangeLogPage, error)

GetChangeLog fetch one page of the changelog for an issue via the /issue/{IssueIdOrKey}/changelog endpoint (for JIRA cloud) or /issue/{IssueIdOrKey} with (fields=*none&expand=changelog) (for JIRA server) https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue

func (*Client) GetComments 

func (client *Client) GetComments(idOrKey string, maxResults int, startAt int) (*CommentPage, error)

GetComments returns a page of comments via the issue/{IssueIdOrKey}/comment endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getComment

func (*Client) GetIssue 

func (client *Client) GetIssue(idOrKey string, fields []string, expand []string,
	properties []string) (*Issue, error)

GetIssue fetches an issue object via the /issue/{IssueIdOrKey} endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue

func (*Client) GetProject 

func (client *Client) GetProject(projectIDOrKey string) (*Project, error)

GetProject returns the project JSON object given its id or key

func (*Client) GetServerInfo 

func (client *Client) GetServerInfo() (*ServerInfo, error)

GetServerInfo Fetch server information from the /serverinfo endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue

func (*Client) GetServerTime 

func (client *Client) GetServerTime() (Time, error)

GetServerTime returns the current time on the server

func (*Client) GetTransitions 

func (client *Client) GetTransitions(issueKeyOrID string) (*TransitionList, error)

GetTransitions returns a list of available transitions for an issue

func (*Client) IterChangeLog 

func (client *Client) IterChangeLog(idOrKey string, pageSize int) *ChangeLogIterator

IterChangeLog returns an iterator over entries in the changelog for an issue

func (*Client) IterComments 

func (client *Client) IterComments(idOrKey string, pageSize int) *CommentIterator

IterComments returns an iterator over paginated comments within an issue

func (*Client) IterSearch 

func (client *Client) IterSearch(jql string, pageSize int) *SearchIterator

IterSearch return an iterator over paginated results for a JQL search

func (*Client) Login 

func (client *Client) Login(credType, login, password string) error

Login POST credentials to the /session endpoint and get a session cookie

func (*Client) RefreshSessionToken 

func (client *Client) RefreshSessionToken(username, password string) error

RefreshSessionToken formulate the JSON request object from the user credentials and POST it to the /session endpoint and get a session cookie

func (*Client) RefreshSessionTokenRaw 

func (client *Client) RefreshSessionTokenRaw(credentialsJSON []byte) error

RefreshSessionTokenRaw POST credentials to the /session endpoint and get a session cookie

func (*Client) Search 

func (client *Client) Search(jql string, maxResults int, startAt int) (*SearchResult, error)

Search Perform an issue a JQL search on the /search endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/search

func (*Client) SetTokenCredentials 

func (client *Client) SetTokenCredentials(username, password string) error

SetTokenCredentials POST credentials to the /session endpoint and get a session cookie

func (*Client) UpdateComment 

func (client *Client) UpdateComment(issueKeyOrID, commentID, body string) (
	*Comment, error)

UpdateComment changes the text of a comment

func (*Client) UpdateIssueBody 

func (client *Client) UpdateIssueBody(issueKeyOrID, body string) (time.Time, error)

UpdateIssueBody changes the "description" field of a JIRA issue

func (*Client) UpdateIssueTitle 

func (client *Client) UpdateIssueTitle(issueKeyOrID, title string) (time.Time, error)

UpdateIssueTitle changes the "summary" field of a JIRA issue

func (*Client) UpdateLabels 

func (client *Client) UpdateLabels(issueKeyOrID string, added, removed []bug.Label) (time.Time, error)

UpdateLabels changes labels for an issue

type ClientTransport 

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

ClientTransport wraps http.RoundTripper by adding a "Content-Type=application/json" header

func (*ClientTransport) RoundTrip 

func (ct *ClientTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip overrides the default by adding the content-type header

func (*ClientTransport) SetCredentials 

func (ct *ClientTransport) SetCredentials(username string, token string)

type Comment 

type Comment struct {
	ID           string `json:"id"`
	Body         string `json:"body"`
	Author       User   `json:"author"`
	UpdateAuthor User   `json:"updateAuthor"`
	Created      Time   `json:"created"`
	Updated      Time   `json:"updated"`
}

Comment the JSON object for a single comment item returned in a list of comments https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getComments

type CommentCreate 

type CommentCreate struct {
	Body string `json:"body"`
}

CommentCreate the JSOn object that is POSTed to the /comment endpoint to create a new comment

type CommentIterator 

type CommentIterator struct {
	Err error
	// contains filtered or unexported fields
}

CommentIterator cursor within paginated results from the /comment endpoint

func (*CommentIterator) HasError 

func (ci *CommentIterator) HasError() bool

HasError returns true if the iterator is holding an error

func (*CommentIterator) HasNext 

func (ci *CommentIterator) HasNext() bool

HasNext returns true if there is another item available in the result set

func (*CommentIterator) Next 

func (ci *CommentIterator) Next() *Comment

Next Return the next item in the result set and advance the iterator. Advancing the iterator may require fetching a new page.

type CommentPage 

type CommentPage struct {
	StartAt    int       `json:"startAt"`
	MaxResults int       `json:"maxResults"`
	Total      int       `json:"total"`
	Comments   []Comment `json:"comments"`
}

CommentPage the JSON object holding a single page of comments returned either by direct query or within an issue query https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getComments

func (*CommentPage) IsLastPage 

func (cp *CommentPage) IsLastPage() bool

IsLastPage return true if there are no more items beyond this page

func (*CommentPage) NextStartAt 

func (cp *CommentPage) NextStartAt() int

NextStartAt return the index of the first item on the next page

type Issue 

type Issue struct {
	ID        string        `json:"id"`
	Key       string        `json:"key"`
	Fields    IssueFields   `json:"fields"`
	ChangeLog ChangeLogPage `json:"changelog"`
}

Issue Top-level object for an issue https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

type IssueCreate 

type IssueCreate struct {
	Fields IssueCreateFields `json:"fields"`
}

IssueCreate the JSON object that is POSTed to the /issue endpoint to create a new issue

type IssueCreateFields 

type IssueCreateFields struct {
	Project     Project   `json:"project"`
	Summary     string    `json:"summary"`
	Description string    `json:"description"`
	IssueType   IssueType `json:"issuetype"`
}

IssueCreateFields fields that are included in an IssueCreate request

type IssueCreateResult 

type IssueCreateResult struct {
	ID  string `json:"id"`
	Key string `json:"key"`
}

IssueCreateResult the JSON object returned after issue creation.

type IssueFields 

type IssueFields struct {
	Creator     User        `json:"creator"`
	Created     Time        `json:"created"`
	Description string      `json:"description"`
	Summary     string      `json:"summary"`
	Comments    CommentPage `json:"comment"`
	Labels      []string    `json:"labels"`
}

IssueFields the JSON object returned as the "fields" member of an issue. There are a very large number of fields and many of them are custom. We only grab a few that we need. https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

type IssueType 

type IssueType struct {
	ID string `json:"id"`
}

IssueType the JSON object representing an issue type (i.e. "bug", "task") Note that we don't use all the fields so we have only implemented a couple.

type Jira 

type Jira struct{}

Jira Main object for the bridge

func (*Jira) Configure 

func (j *Jira) Configure(repo *cache.RepoCache, params core.BridgeParams, interactive bool) (core.Configuration, error)

Configure sets up the bridge configuration

func (*Jira) LoginMetaKey 

func (*Jira) LoginMetaKey() string

func (*Jira) NewExporter 

func (*Jira) NewExporter() core.Exporter

NewExporter returns the jira exporter

func (*Jira) NewImporter 

func (*Jira) NewImporter() core.Importer

NewImporter returns the jira importer

func (*Jira) Target 

func (*Jira) Target() string

Target returns "jira"

func (*Jira) ValidParams 

func (*Jira) ValidParams() map[string]interface{}

func (*Jira) ValidateConfig 

func (*Jira) ValidateConfig(conf core.Configuration) error

ValidateConfig returns true if all required keys are present

type Project 

type Project struct {
	ID  string `json:"id,omitempty"`
	Key string `json:"key,omitempty"`
}

Project the JSON object representing a project. Note that we don't use all the fields so we have only implemented a couple.

type SearchIterator 

type SearchIterator struct {
	Err error
	// contains filtered or unexported fields
}

SearchIterator cursor within paginated results from the /search endpoint

func (*SearchIterator) HasError 

func (si *SearchIterator) HasError() bool

HasError returns true if the iterator is holding an error

func (*SearchIterator) HasNext 

func (si *SearchIterator) HasNext() bool

HasNext returns true if there is another item available in the result set

func (*SearchIterator) Next 

func (si *SearchIterator) Next() *Issue

Next Return the next item in the result set and advance the iterator. Advancing the iterator may require fetching a new page.

type SearchRequest 

type SearchRequest struct {
	JQL        string   `json:"jql"`
	StartAt    int      `json:"startAt"`
	MaxResults int      `json:"maxResults"`
	Fields     []string `json:"fields"`
}

SearchRequest the JSON object POSTed to the /search endpoint

type SearchResult 

type SearchResult struct {
	StartAt    int     `json:"startAt"`
	MaxResults int     `json:"maxResults"`
	Total      int     `json:"total"`
	Issues     []Issue `json:"issues"`
}

SearchResult The result type from querying the search endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/search

func (*SearchResult) IsLastPage 

func (sr *SearchResult) IsLastPage() bool

IsLastPage return true if there are no more items beyond this page

func (*SearchResult) NextStartAt 

func (sr *SearchResult) NextStartAt() int

NextStartAt return the index of the first item on the next page

type ServerInfo 

type ServerInfo struct {
	BaseURL          string `json:"baseUrl"`
	Version          string `json:"version"`
	VersionNumbers   []int  `json:"versionNumbers"`
	BuildNumber      int    `json:"buildNumber"`
	BuildDate        Time   `json:"buildDate"`
	ServerTime       Time   `json:"serverTime"`
	ScmInfo          string `json:"scmInfo"`
	BuildPartnerName string `json:"buildPartnerName"`
	ServerTitle      string `json:"serverTitle"`
}

ServerInfo general server information returned by the /serverInfo endpoint. Notably `ServerTime` will tell you the time on the server.

type Session 

type Session struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

Session credential cookie name/value pair received after logging in and required to be sent on all subsequent requests

type SessionQuery 

type SessionQuery struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

SessionQuery the JSON object that is POSTed to the /session endpoint in order to login and get a session cookie

type SessionResponse 

type SessionResponse struct {
	Session Session `json:"session"`
}

SessionResponse the JSON object returned from a /session query (login)

type Status 

type Status struct {
	ID             string         `json:"id"`
	Name           string         `json:"name"`
	Self           string         `json:"self"`
	Description    string         `json:"description"`
	StatusCategory StatusCategory `json:"statusCategory"`
}

Status the JSON object representing a status (i.e. "Open", "Closed")

type StatusCategory 

type StatusCategory struct {
	ID        int    `json:"id"`
	Key       string `json:"key"`
	Self      string `json:"self"`
	ColorName string `json:"colorName"`
	Name      string `json:"name"`
}

StatusCategory the JSON object representing a status category

type Time 

type Time struct {
	time.Time
}

Time is just a time.Time with a JSON serialization

func (*Time) UnmarshalJSON 

func (t *Time) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON parses an RFC3339 date string into a time object borrowed from: https://stackoverflow.com/a/39180230/141023

type Transition 

type Transition struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	To   Status `json:"to"`
}

Transition the JSON object represenging a transition from one Status to another Status in a JIRA workflow

type TransitionList 

type TransitionList struct {
	Transitions []Transition `json:"transitions"`
}

TransitionList the JSON object returned from the /transitions endpoint

type User 

type User struct {
	DisplayName  string `json:"displayName"`
	EmailAddress string `json:"emailAddress"`
	Key          string `json:"key"`
	Name         string `json:"name"`
}

User the JSON object representing a JIRA user https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/user

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.