jira

package
v1.47.0 Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2025 License: BSD-3-Clause Imports: 18 Imported by: 0

Documentation

Overview

Copyright 2025 SGNL.ai, Inc.

Copyright 2025 SGNL.ai, Inc.

Copyright 2025 SGNL.ai, Inc.

Copyright 2025 SGNL.ai, Inc.

Copyright 2025 SGNL.ai, Inc.

Index

Constants

View Source 
const (
	User        string = "User"
	Issue       string = "Issue"
	Group       string = "Group"
	GroupMember string = "GroupMember"
	Workspace   string = "Workspace"
	Object      string = "Object"
)
View Source 
const (
	// MaxPageSize is the maximum page size allowed in a GetPage request.
	// Each operation can have a different page size limit, and they may change without notice.
	// https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#pagination. See the "maxResults" query parameter.
	// Use 1000 as an estimate.
	MaxPageSize = 1000
)

Variables

View Source 
var DefaultAssetBaseURL = "https://api.atlassian.com/jsm/assets"
View Source 
var EntityIDToParentCollectionID = map[string]string{
	GroupMember: Group,
	Object:      Workspace,
}
View Source 
var (
	// ValidEntityExternalIDs is a map of valid external IDs of entities that can be queried.
	// The map value is the Entity struct, which contains the unique ID attribute, the endpoint to query that entity,
	// and a function to parse the response.
	// Users doc:
	//   https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-users-search-get.
	// Issues doc:
	//   https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-get.
	// Groups doc:
	//   https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups/#api-rest-api-3-group-bulk-get.
	// GroupMembers doc:
	//   https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups/#api-rest-api-3-group-member-get.
	// Workspaces doc:
	// nolint:lll
	//   https://developer.atlassian.com/cloud/jira/service-desk/rest/api-group-assets/#api-rest-servicedeskapi-assets-workspace-get.
	// Objects doc:
	// 	 https://developer.atlassian.com/cloud/assets/rest/api-group-object/#api-object-aql-post.
	ValidEntityExternalIDs = map[string]Entity{
		User: {
			// contains filtered or unexported fields
		},
		Issue: {
			// contains filtered or unexported fields
		},
		Group: {
			// contains filtered or unexported fields
		},
		GroupMember: {
			// contains filtered or unexported fields
		},
		Workspace: {
			// contains filtered or unexported fields
		},
		Object: {
			// contains filtered or unexported fields
		},
	}
)

Functions

func ConstructURL 

func ConstructURL(request *Request, entity Entity, cursor *pagination.CompositeCursor[int64]) (string, error)

ConstructURL constructs the Jira URL for the given request and entity. This URL is used to make a request to the Jira API. For URLs which require a resource ID, the resource ID must be non nil (i.e. a non nil cursor.CollectionID) otherwise an error is returned.

func NewAdapter 

func NewAdapter(client Client) framework.Adapter[Config]

NewAdapter instantiates a new Adapter.

func ParseGroupMembersResponse 

func ParseGroupMembersResponse(
	body []byte, pageSize, cursor int64,
) (objects []map[string]any, nextCursor *int64, err *framework.Error)

func ParseGroupsResponse 

func ParseGroupsResponse(
	body []byte, pageSize int64, cursor int64,
) (objects []map[string]any, nextCursor *int64, err *framework.Error)

func ParseIssuesResponse 

func ParseIssuesResponse(
	body []byte, pageSize int64, cursor int64,
) (objects []map[string]any, nextCursor *int64, err *framework.Error)

func ParseObjectsResponse 

func ParseObjectsResponse(
	body []byte, pageSize int64, cursor int64,
) (objects []map[string]any, nextCursor *int64, err *framework.Error)

func ParseUsersResponse 

func ParseUsersResponse(
	body []byte, pageSize int64, cursor int64,
) (objects []map[string]any, nextCursor *int64, err *framework.Error)

func ParseWorkspacesResponse 

func ParseWorkspacesResponse(
	body []byte, pageSize int64, cursor int64,
) (objects []map[string]any, nextCursor *int64, err *framework.Error)

Types

type Adapter 

type Adapter struct {
	JiraClient Client
}

Adapter implements the framework.Adapter interface to query pages of objects from datasources.

func (*Adapter) GetPage 

func (a *Adapter) GetPage(ctx context.Context, request *framework.Request[Config]) framework.Response

GetPage is called by SGNL's ingestion service to query a page of objects from a datasource.

func (*Adapter) RequestPageFromDatasource 

func (a *Adapter) RequestPageFromDatasource(
	ctx context.Context,
	request *framework.Request[Config],
) framework.Response

RequestPageFromDatasource requests a page of objects from a datasource. It calls the Jira datasource client internally to make the datasource request, parses the response, and handles any errors. It also handles parsing the current cursor and generating the next cursor.

func (*Adapter) ValidateGetPageRequest 

func (a *Adapter) ValidateGetPageRequest(ctx context.Context, request *framework.Request[Config]) *framework.Error

ValidateGetPageRequest validates the fields of the GetPage Request.

type Client 

type Client interface {
	GetPage(ctx context.Context, request *Request) (*Response, *framework.Error)
}

Client is a client that allows querying the Jira datasource which contains JSON objects.

func NewClient 

func NewClient(client *http.Client) Client

NewClient instantiates and returns a new Jira Client used to query the Jira datasource.

type Config 

type Config struct {
	// Common configuration
	*config.CommonConfig

	// IssuesJQLFilter is the JQL filter to use when querying for issues.
	// e.g. "project=SGNL OR project=MVP".
	// https://support.atlassian.com/jira-software-cloud/docs/what-is-advanced-search-in-jira-cloud/.
	// If the JQL is invalid, Jira will return a 400.
	// An invalid JQL does not necessarily mean a syntax error, but also for example
	// if a project does not exist, e.g. project=INVALID.
	// Therefore, it's up to the client to ensure the JQL is valid.
	IssuesJQLFilter *string `json:"issuesJqlFilter,omitempty"`

	// ObjectsQLQuery is the AQL query to use when querying for custom Objects.
	// e.g. "qlQuery="objectType = Customer".
	// https://developer.atlassian.com/cloud/assets/rest/api-group-object/#api-object-aql-post.
	// It is up to the client to ensure the ObjectsQLQuery is valid.
	// This field is only used for the Object entity.
	ObjectsQLQuery *string `json:"objectsQlQuery,omitempty"`

	// AssetBaseURL is the base URL to use when querying for Objects.
	// e.g. "https://api.atlassian.com/jsm/assets".
	// If not, specified it defaults to "https://api.atlassian.com/jsm/assets".
	// This field is only used for the Object entity.
	AssetBaseURL *string `json:"assetBaseUrl,omitempty"`
}

Config is the optional configuration passed in each GetPage calls to the adapter. Adapter configuration example: nolint: godot 

{
    "requestTimeoutSeconds": 10,
    "localTimeZoneOffset": 43200,
    "issuesJqlFilter": "project=SGNL OR project=MVP",
    "objectsQlQuery": "objectType = Customer",
    "assetBaseUrl": "https://api.atlassian.com/jsm/assets"
}

func (*Config) Validate 

func (c *Config) Validate(_ context.Context) error

ValidateConfig validates that a Config received in a GetPage call is valid.

type Datasource 

type Datasource struct {
	Client *http.Client
}

Datasource implements the Jira Client interface to allow querying the Jira datasource.

func (*Datasource) GetPage 

func (d *Datasource) GetPage(ctx context.Context, request *Request) (*Response, *framework.Error)

GetPage makes a request to the Jira datasource to get a page of JSON objects. If a response is received, regardless of status code, a Response object is returned with the response body and the status code. If the request fails, an appropriate framework.Error is returned.

type Entity 

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

Entity contains entity specific information, such as the entity's unique ID attribute and the endpoint to query that entity.

type Request 

type Request struct {
	// BaseURL is the base URL of the Jira instance. For example, "https://{domain}.atlassian.net".
	BaseURL string

	// Username is the user name used to authenticate with Jira using basic auth.
	Username string

	// Password is user's Jira API token used to authenticate with Jira using basic auth.
	Password string

	// PageSize is the maximum number of objects to return per page from the API call.
	// This is used as the "maxResults" parameter in the Jira API.
	PageSize int64

	// EntityExternalID is the external ID of the entity. If it's not a valid external ID, then
	// no request will be made.
	EntityExternalID string

	// Cursor identifies the first object of the page to return, as returned by
	// the last request for the entity.
	// nil in the request for the first page.
	Cursor *pagination.CompositeCursor[int64]

	// IssuesJQLFilter is a JQL filter to apply to the request.
	// This is only used when EntityExternalID = "Issue".
	IssuesJQLFilter *string

	// ObjectsQLQuery is a AQL query to apply to the request.
	// This is only used when EntityExternalID = "Object".
	ObjectsQLQuery *string

	// AssetBaseURL is the base URL to retrieve Asset Objects.
	// This is only used when EntityExternalID = "Object".
	AssetBaseURL *string

	// RequestTimeoutSeconds is the timeout duration for requests made to datasources.
	// This should be set to the number of seconds to wait before timing out.
	RequestTimeoutSeconds int
}

Request is a request to Jira.

type Response 

type Response struct {
	// StatusCode is an HTTP status code.
	StatusCode int

	// RetryAfterHeader is the Retry-After response HTTP header, if set.
	RetryAfterHeader string

	// Objects is the list of parsed entity objects returned from Jira.
	// May be empty.
	Objects []map[string]any

	// NextCursor is the cursor that identifies the first object of the next page.
	// nil if this is the last page in this full sync.
	NextCursor *pagination.CompositeCursor[int64]
}

Response is a parsed response returned from Jira.

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.