In this article, I would be showing you how to create a Jira issue using the "go-atlassian" library.

Step 1: Set up the project

1. Create a new directory for your project.

2. Open a terminal and navigate to the project directory.

3. Initialize a new Go module using the following command:

go mod init <module-name>

Step 2: Install the "go-atlassian" library

In the terminal, run the following command to install the "go-atlassian" library:

go get -v github.com/ctreminiom/go-atlassian

Step 3: Import the necessary packages

1. Create a new Go file (e.g., main.go) in your project directory.

2. Open the file and import the required packages:

package main

import (
	"fmt"
	"log"
	"os"

	jira "github.com/ctreminiom/go-atlassian/jira/v2"
)

Step 4: Authenticate with Jira

In the main function, create a new Jira client and authenticate using your Jira URL, username, and API token:

func main() {

	jiraHost := "https://<_jira_instance_>.atlassian.net"
	mailAddress := "<your_mail>"
	apiToken := "<your_api_token>"

	client, err := jira.New(nil, jiraHost)
	if err != nil {
		log.Fatal(err)
	}

	client.Auth.SetBasicAuth(mailAddress, apiToken)
}

Step 5: Custom fields definition

OPTIONAL, you can define custom-fields values you want to set on the issue creation. This library supports the following custom-fields types:

var customFields = models.CustomFields{}
err = customFields.Groups("customfield_10052", []string{"jira-administrators", "jira-administrators-system"})
if err != nil {
	log.Fatal(err)
}

err = customFields.Number("customfield_10043", 1000.3232)
if err != nil {
	log.Fatal(err)
}

Step 6: Create an issue

Create a new issue using the Create method and set the custom fields:

payload := &models.IssueSchemeV2{
	Fields: &models.IssueFieldsSchemeV2{
		Summary:   "New summary test",
		Project:   &models.ProjectScheme{ID: "10000"},
		IssueType: &models.IssueTypeScheme{Name: "Story"},
	},
}

newIssue, _, err := client.Issue.Create(context.Background(), payload, &customFields)
if err != nil {
	log.Fatal(err)
}

Step 7: Run the program

1. Save the main.go file.

2. In the terminal, navigate to your project directory.

3. Execute the following command to run the program:

This will create a new issue in Jira with the specified custom field values. Please note that you may need to modify the code according to your specific Jira configuration and custom field types.

go-atlassian is a Go library that provides a simple and convenient way to interact with various Atlassian products' REST APIs. Atlassian is a leading provider of software and tools for software development, project management, and collaboration. Some of the products that go-atlassian supports include Jira, Confluence, Jira Service Management, and more.

The go-atlassian library is designed to simplify the process of building Go applications that interact with Atlassian products. It provides a set of functions and data structures that can be used to easily send HTTP requests to the Atlassian APIs, parse the responses, and work with the data returned.

🚀Features

• Easy-to-use functions and data structures that abstract away much of the complexity of working with the APIs.

• Comprehensive support for various Atlassian products' APIs.

• Support for common operations like creating, updating, and deleting entities in Atlassian products.

• Active development and maintenance by the community, with regular updates and bug fixes.

• Comprehensive documentation and examples to help developers get started with using the library.

📁 Installation

If you do not have Go installed yet, you can find installation instructions here. Please note that the package requires Go version 1.20 or later for module support.

To pull the most recent version of go-atlassian, use go get.

go get github.com/ctreminiom/go-atlassian/v2

📪 Packages

Then import the package into your project as you normally would. You can import the following packages:

🔨 Usage

Before using the go-atlassian package, you need to have an Atlassian API key. If you do not have a key yet, you can sign up here.

Create a client with your instance host and access token to start communicating with the Atlassian API's. In this example, we're going to instance a new Confluence Cloud client.

instance, err := confluence.New(nil, "INSTANCE_HOST")
if err != nil {
    log.Fatal(err)
}
instance.Auth.SetBasicAuth("YOUR_CLIENT_MAIL", "YOUR_APP_ACCESS_TOKEN")

If you need to use a preconfigured HTTP client, simply pass its address to the New function.

transport := http.Transport{
	Proxy: http.ProxyFromEnvironment,
	Dial: (&net.Dialer{
		// Modify the time to wait for a connection to establish
		Timeout:   1 * time.Second,
		KeepAlive: 30 * time.Second,
	}).Dial,
	TLSHandshakeTimeout: 10 * time.Second,
}
client := http.Client{
	Transport: &transport,
	Timeout:   4 * time.Second,
}
instance, err := confluence.New(&client, "INSTANCE_HOST")
if err != nil {
	log.Fatal(err)
}
instance.Auth.SetBasicAuth("YOUR_CLIENT_MAIL", "YOUR_APP_ACCESS_TOKEN")

☕Cookbooks

For detailed examples and usage of the go-atlassian library, please refer to our Cookbook. This section provides step-by-step guides and code samples for common tasks and scenarios.

🌍 Services

The library uses the services interfaces to provide a modular and flexible way to interact with Atlassian products' REST APIs. It defines a set of services interfaces that define the functionality of each API, and then provides implementations of those interfaces that can be used to interact with the APIs.

// BoardConnector represents the Jira boards.
// Use it to search, get, create, delete, and change boards.
type BoardConnector interface {
	Get(ctx context.Context, boardID int) (*model.BoardScheme, *model.ResponseScheme, error)
	Create(ctx context.Context, payload *model.BoardPayloadScheme) (*model.BoardScheme, *model.ResponseScheme, error)
	Filter(ctx context.Context, filterID, startAt, maxResults int) (*model.BoardPageScheme, *model.ResponseScheme, error)
	Backlog(ctx context.Context, boardID int, opts *model.IssueOptionScheme, startAt, maxResults int) (*model.BoardIssuePageScheme, *model.ResponseScheme, error)
	Configuration(ctx context.Context, boardID int) (*model.BoardConfigurationScheme, *model.ResponseScheme, error)
	Epics(ctx context.Context, boardID, startAt, maxResults int, done bool) (*model.BoardEpicPageScheme, *model.ResponseScheme, error)
	IssuesWithoutEpic(ctx context.Context, boardID int, opts *model.IssueOptionScheme, startAt, maxResults int) (
		*model.BoardIssuePageScheme, *model.ResponseScheme, error)
	IssuesByEpic(ctx context.Context, boardID, epicID int, opts *model.IssueOptionScheme, startAt, maxResults int) (
		*model.BoardIssuePageScheme, *model.ResponseScheme, error)
	Issues(ctx context.Context, boardID int, opts *model.IssueOptionScheme, startAt, maxResults int) (*model.BoardIssuePageScheme,
		*model.ResponseScheme, error)
	Move(ctx context.Context, boardID int, payload *model.BoardMovementPayloadScheme) (*model.ResponseScheme, error)
	Projects(ctx context.Context, boardID, startAt, maxResults int) (*model.BoardProjectPageScheme, *model.ResponseScheme, error)
	Sprints(ctx context.Context, boardID, startAt, maxResults int, states []string) (*model.BoardSprintPageScheme,
		*model.ResponseScheme, error)
	IssuesBySprint(ctx context.Context, boardID, sprintID int, opts *model.IssueOptionScheme, startAt, maxResults int) (
		*model.BoardIssuePageScheme, *model.ResponseScheme, error)
	Versions(ctx context.Context, boardID, startAt, maxResults int, released bool) (*model.BoardVersionPageScheme,
		*model.ResponseScheme, error)
	Delete(ctx context.Context, boardID int) (*model.ResponseScheme, error)
	Gets(ctx context.Context, opts *model.GetBoardsOptions, startAt, maxResults int) (*model.BoardPageScheme,
		*model.ResponseScheme, error)
}

Each service interface includes a set of methods that correspond to the available endpoints in the corresponding API. For example, the IssueService interface includes methods like Create, Update, and Get that correspond to the POST, PUT, and GET endpoints in the Jira Issues API.

🎉 Implementation

Behind the scenes, the Create method on the IssueService interface is implemented by the issueService.Create function in the go-atlassian library. This function sends an HTTP request to the relevant endpoint in the Jira Issues API, using the credentials and configuration provided by the client, and then parses the response into a usable format.

Here's a little example about how to get the issue transitions using the Issue service.

ctx := context.Background()
issueKey := "KP-2"
expand := []string{"transitions"}
issue, response, err := atlassian.Issue.Get(ctx,issueKey, nil, expand)
if err != nil {
	log.Fatal(err)
}
log.Println(issue.Key)
for _, transition := range issue.Transitions {
	log.Println(transition.Name, transition.ID, transition.To.ID, transition.HasScreen)
}

The rest of the service functions work much the same way; they are concise and behave as you would expect. The documentation contains several examples on how to use each service function.

📪Call a RAW API Endpoint

If you need to interact with an Atlassian API endpoint that hasn't been implemented in the go-atlassian library yet, you can make a custom API request using the built-in Client.Call method to execute raw HTTP requests.

Please raise an issue in order to implement the endpoint

package main  
  
import (  
    "context"  
    "fmt" 
    "github.com/ctreminiom/go-atlassian/v2/jira/v3" 
    "log" 
    "net/http" 
    "os"
 )  
  
type IssueTypeMetadata struct {  
    IssueTypes []struct {  
       ID          string `json:"id"`  
  Name        string `json:"name"`  
  Description string `json:"description"`  
  } `json:"issueTypes"`  
}  
  
func main() {  
  
    var (  
       host  = os.Getenv("SITE")  
       mail  = os.Getenv("MAIL")  
       token = os.Getenv("TOKEN")  
    )  
  
    atlassian, err := v3.New(nil, host)  
    if err != nil {  
       log.Fatal(err)  
    }  
  
    atlassian.Auth.SetBasicAuth(mail, token)  
  
    // Define the RAW endpoint  
    apiEndpoint := "rest/api/3/issue/createmeta/KP/issuetypes"  
  
    request, err := atlassian.NewRequest(context.Background(), http.MethodGet, apiEndpoint, "", nil)  
    if err != nil {  
       log.Fatal(err)  
    }  
  
    customResponseStruct := new(IssueTypeMetadata)  
    response, err := atlassian.Call(request, &customResponseStruct)  
    if err != nil {  
       log.Fatal(err)  
    }  
  
    fmt.Println(response.Status)  
}

✍️ Contributions

If you would like to contribute to this project, please adhere to the following guidelines.

• Submit an issue describing the problem.

• Fork the repo and add your contribution.

• Follow the basic Go conventions found here.

• Create a pull request with a description of your changes.

Again, contributions are greatly appreciated!

💡 Inspiration

The project was created with the purpose to provide a unique point to provide an interface for interacting with Atlassian products.

This module is highly inspired by the Go library https://github.com/andygrunwald/go-jira but focused on Cloud solutions.

The library shares many similarities with go-jira, including its use of service interfaces to define the functionality of each API, its modular and flexible approach to working with Atlassian products' API's. However, go-atlassian also adds several new features and improvements that are not present in go-jira.

Despite these differences, go-atlassian remains heavily inspired by go-jira, and many of the core design principles and patterns used in go-jira can be found in go-atlassian as well.

📝 License

Copyright © 2023 Carlos Treminio. This project is MIT licensed.

🤝 Special Thanks

We would like to extend our sincere thanks to the following sponsors for their generous support:

• Atlassian for providing us Atlassian Admin/Jira/Confluence Standard licenses.

• JetBrains for providing us with free licenses of GoLand

• GitBook for providing us non-profit / open-source plan so hence I would like to express my thanks here.

In this article, I would be showing you how to create a Service Management customer request with custom-fields.

Step 1: Set up the project

1. Create a new directory for your project.

2. Open a terminal and navigate to the project directory.

3. Initialize a new Go module using the following command:

go mod init <module-name>

Step 2: Install the "go-atlassian" library

In the terminal, run the following command to install the "go-atlassian" library:

go get -v github.com/ctreminiom/go-atlassian

Step 3: Import the necessary packages

1. Create a new Go file (e.g., main.go) in your project directory.

2. Open the file and import the required packages:

package main

import (
	"fmt"
	"github.com/ctreminiom/go-atlassian/jira/sm"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
)

Step 4: Authenticate with Jira

In the main function, create a new Jira client and authenticate using your Jira URL, username, and API token:

func main() {

	jiraHost := "https://<_jira_instance_>.atlassian.net"
	mailAddress := "<your_mail>"
	apiToken := "<your_api_token>"

	client, err := sm.New(nil, jiraHost)
	if err != nil {
		log.Fatal(err)
	}

	client.Auth.SetBasicAuth(mailAddress, apiToken)
}

Step 5: Create an ITSM customer request with custom fields

Define the fields you want to set:

payload := &models.CreateCustomerRequestPayloadScheme{
	Channel:             "",
	Form:                nil,
	IsAdfRequest:        false,
	RaiseOnBehalfOf:     "",
	RequestFieldValues:  nil,
	RequestParticipants: nil,
	RequestTypeID:       "10",
	ServiceDeskID:       "1",
}

if err := payload.AddCustomField("summary", "Summary Sample"); err != nil {
	log.Fatal(err)
}

if err := payload.DateCustomField("duedate", time.Now()); err != nil {
	log.Fatal(err)
}

if err := payload.Components([]string{"Intranet"}); err != nil {
	log.Fatal(err)
}

if err := payload.AddCustomField("labels", []string{"label-00", "label-01"}); err != nil {
	log.Fatal(err)
}

• Create a new issue using the Create method and set the custom fields:

ticket, response, err := atlassian.Request.Create(context.Background(), payload, form)
if err != nil {
	log.Fatal(err)
}

Step 6: Run the program

1. Save the main.go file.

2. In the terminal, navigate to your project directory.

3. Execute the following command to run the program:

go run main.go

This will create a new ITSM customer request in Jira with the specified custom field values.

In this article, I would be showing you how to extract user last-activity information from the Atlassian Admin API's using go-atlassian

Step 1: Create a new Go project

Create a new directory for your project and navigate to it in your terminal or command prompt. Initialize a new Go module using the following command:

go mod init your-module-name

Step 2: Install the "go-atlassian" library

To use the "go-atlassian" library, you need to install it as a dependency in your project. Run the following command:

go get github.com/ctreminiom/go-atlassian

Step 3: Import the required packages

Create a new Go file, e.g., main.go, and import the necessary packages:

package main

import (
	"fmt"
	"log"

	"github.com/ctreminiom/go-atlassian/admin"
)

Step 4: Set up Cloud Admin client

Initialize the Atlassian Admin client with your API token:

func main() {
	//https://support.atlassian.com/organization-administration/docs/manage-an-organization-with-the-admin-apis/
	var apiKey = os.Getenv("ATLASSIAN_ADMIN_TOKEN")

	cloudAdmin, err := admin.New(nil)
	if err != nil {
		log.Fatal(err)
	}

	cloudAdmin.Auth.SetBearerToken(apiKey)
	cloudAdmin.Auth.SetUserAgent("curl/7.54.0")
}

Step 5: Extract the organization ID

It's required to extract the ID of the organization you're using, the organization ID can be extract on the admin URL, as the image below:

Step 6: Extract the organization users

In this step, we're going to extract the organization users and store them into an array variable, please use the following code block to extract them.

// Extract the organization users
var (
	organizationID = "9a1jj823-jac8-123d-jj01-63315k059cb2"
	cursor         string
	users          []*models.AdminOrganizationUserScheme
)

for {

	page, response, err := cloudAdmin.Organization.Users(context.Background(), organizationID, cursor)
	if err != nil {
		if response != nil {
			log.Println("Response HTTP Response", response.Bytes.String())
		}
		log.Fatal(err)
	}

	users = append(users, page.Data...)

	if len(page.Links.Next) == 0 {
		break
	}

	//extract the next cursor pagination
	nextAsURL, err := url.Parse(page.Links.Next)
	if err != nil {
		log.Fatal(err)
	}

	cursor = nextAsURL.Query().Get("cursor")
}

for _, user := range users {
	log.Println("Name:", user.Name, " -- ID:", user.AccountID)
}

Step 7: Extract the last-login date

With the organization users extracted, we need to iterate each user and extract the last-login information, you can use the following code to do that:

for _, user := range users {

	lastLogin, response, err := cloudAdmin.Organization.Directory.Activity(context.Background(), organizationID, user.AccountID)
	if err != nil {
		if response != nil {
			log.Println("Response HTTP Response", response.Bytes.String())
		}
		log.Fatal(err)
	}

	// The products are iterated because an Atlassian user may contain multiple products
	// If you're looking to a specific product, you can modify the loop logic and extract
	// the last-login for Jira or Confluence
	for _, product := range lastLogin.Data.ProductAccess {

		fmt.Println(lastLogin.Data.AddedToOrg, product)
	}
}

Overview

The go-atlassian jira module provides a set of functions and types for interacting with the Jira REST API. It is designed to make it easy for developers to build powerful integrations and automations that leverage the capabilities of the Jira platform.

The module is available in two versions: v2 and v3. These versions correspond to different versions of the Jira REST API, with v2 supporting Jira versions 6.4 to 7.2, and v3 supporting Jira versions 7.3 and later.

ADF Format

The Atlassian Document Format (ADF) is a JSON-based format used by Atlassian products, including Jira, to represent rich content such as text, tables, and lists. The jira module in go-atlassian provides support for working with ADF content in both the v3package.

commentBody := jira.CommentNodeScheme{}
	commentBody.Version = 1
	commentBody.Type = "doc"
	
	
//Append Header
commentBody.AppendNode(&jira.CommentNodeScheme{
	Type:    "heading",
	Attrs: map[string]interface{}{"level": 1},

	Content: []*jira.CommentNodeScheme{
		{
			Type: "text",
			Text: "Header 1",
		},
	},
})

In v3, the IssueService and related services like CommentService provide functions that allow you to interact with ADF content. For example, the CreateIssue function in v3 includes a parameter for Fields, which is a struct that includes fields for specifying various attributes of the new issue, including the issue summary, description, and any custom fields. The Fields struct includes a field for Description, which can be set to a struct representing ADF content.

To search issues using a JQL query, use the Issue.Search service function.

var (
	jql    = "order by created DESC"
	fields = []string{"status"}
	expand = []string{"changelog", "renderedFields", "names", "schema", "transitions", "operations", "editmeta"}
)

issues, response, err := atlassian.Issue.Search.Post(context.Background(), jql, fields, expand, 0, 50, "")
if err != nil {
	log.Fatal(err)
}

log.Println("HTTP Endpoint Used", response.Endpoint)
log.Println(issues.Total)

In this article, I would be showing you how to extract the boards associated with a Jira project using go-atlassian

Step 1: Create a new Go project

Create a new directory for your project and navigate to it in your terminal or command prompt. Initialize a new Go module using the following command:

go mod init your-module-name

Step 2: Install the "go-atlassian" library

To use the "go-atlassian" library, you need to install it as a dependency in your project. Run the following command:

go get github.com/ctreminiom/go-atlassian

Step 3: Import the required packages

Create a new Go file, e.g., main.go, and import the necessary packages:

package main

import (
	"fmt"
	"log"

	jira "github.com/ctreminiom/go-atlassian/agile"
)

Step 4: Set up Jira Agile API client

Initialize the Jira Agile API client with your Jira base URL and API token:

func main() {
	jiraClient, err := jira.New(nil, "https://your-jira-instance.atlassian.net")
	if err != nil {
		log.Fatal(err)
	}

	// Set API token for authentication
	jiraClient.Auth.SetBasicAuth(mail, token)
}

Step 5: Extract the boards

In this step, you're going to use the Jira Agile API, more specifically, the Board service, Gets() method. This methods supports multiple query parameters, but in this example, we're going to use the ProjectKeyOrID param to filter the board linked to a Jira project.

The following example iterates the Board.Gets() method and appends the boards into a slice.

options := &models.GetBoardsOptions{
		ProjectKeyOrID: "KP",
	}

var boards []*models.BoardScheme
var startAt int

for {

	fmt.Println("Pagination #", startAt)

	page, response, err := instance.Board.Gets(context.Background(), options, startAt, 50)
	if err != nil {

		if response != nil {
			log.Fatal(response.Bytes.String())
		}
		log.Fatal(err)
	}

	boards = append(boards, page.Values...)

	if page.IsLast {
		break
	}

	startAt = +50
}

The Jira audit logs are a set of records that document all the activities and changes made in Jira. These logs provide a detailed record of who did what, when, and where within Jira. Here are a few examples of the type of activities that are logged in the Jira audit logs:

The audit logs are useful for several reasons. For example, they can be used to track changes made to sensitive data, to identify who made specific changes to issues or projects, or to diagnose issues with Jira.

Get audit records

GET /rest/api/{2-3}/auditing/record

This method allows you to retrieve the audit records for specific activities that have occurred within Jira.

Jira application roles are a way of managing user permissions and access in Jira. Jira comes with a set of predefined roles that define common types of users, such as administrators, developers, and project managers.

Each Jira application role has a set of permissions associated with it, which determine what actions a user in that role is allowed to perform. For example, the "Admin" role has permission to manage Jira system settings and users, while the "Developer" role has permission to create and edit issues and view source code.

Get all application roles

GET /rest/api/{2-3}/applicationrole

This endpoint is used to retrieve a list of all application roles that are defined in a Jira instance. This endpoint can be used to get information about the roles that are available in Jira, and to help manage user access and permissions.

Get application role

GET /rest/api/{2-3}/applicationrole/{key}

This method allows you to retrieve information about a specific application role in Jira using the key name as reference.

In this article, I would be showing you how to create Jira workflow and append transitions using go-atlassian

Step 1: Create a new Go project

Create a new directory for your project and navigate to it in your terminal or command prompt. Initialize a new Go module using the following command:

go mod init your-module-name

Step 2: Install the "go-atlassian" library

To use the "go-atlassian" library, you need to install it as a dependency in your project. Run the following command:

go get github.com/ctreminiom/go-atlassian

Step 3: Import the required packages

Create a new Go file, e.g., main.go, and import the necessary packages:

package main

import (
	"fmt"
	"log"

	jira "github.com/ctreminiom/go-atlassian/jira/v2"
)

Step 4: Set up Jira API client

Initialize the Jira API client with your Jira base URL and API token:

func main() {
	jiraClient, err := jira.New(nil, "https://your-jira-instance.atlassian.net")
	if err != nil {
		log.Fatal(err)
	}

	// Set API token for authentication
	jiraClient.Auth.SetBasicAuth(mail, token)
}

Step 5: Create a workflow

To create a new workflow, we need to the create the models.WorkflowPayloadScheme payload struct with the following information.

1. Worfklow Name.

2. Workflow Description.

3. Workflow Statuses.

4. Workflow Transitions.

Let's try to create a workflow with directed transitions and all-to-all transitions, something like this:

Step 5.1: Extract the status ID's

The first step to create a Jira workflow is recognize what's gonna be the statuses you want to use.

In this particular example, we're needed to use the following statuses:

• Open

• In Progress

• QA

• Waiting for approval

• Escalated

• Closed

• Resolved

var statusesNamesAsSlice = []string{
	"Open", "In Progress", "QA",
	"Waiting for approval", "Escalated",
	"Closed", "Resolved",
}

var statusesAsMap = make(map[string]*models.WorkflowStatusDetailScheme)
for _, statusName := range statusesNamesAsSlice {

	options := &models.WorkflowStatusSearchParams{
		SearchString: statusName,
	}

	page, response, err := instance.Workflow.Status.Search(context.Background(), options, 0, 1)
	if err != nil {
		if response != nil {
			log.Println(response.Bytes.String())
			log.Println(response.Code)
		}

		log.Fatal(err)
	}

	var wasFound bool
	for _, status := range page.Values {

		if status.Name == statusName {
			statusesAsMap[status.Name] = status
			wasFound = true
			break
		}
	}

	if !wasFound {

		// If the workflow is not found, it's required to create a new global status
		statusPayload := &models.WorkflowStatusPayloadScheme{
			Statuses: []*models.WorkflowStatusNodeScheme{
				{
					Name:           statusName,
					StatusCategory: "IN_PROGRESS",
				},
			},
			Scope: &models.WorkflowStatusScopeScheme{
				Type: "GLOBAL",
			},
		}

		statuses, response, err := instance.Workflow.Status.Create(context.Background(), statusPayload)
		if err != nil {
			if response != nil {
				log.Println(response.Bytes.String())
				log.Println(response.Code)
			}

			log.Fatal(err)
		}

		for _, status := range statuses {

			if status.Name == statusName {
				statusesAsMap[status.Name] = status
				break
			}
		}
	}
}

for name, data := range statusesAsMap {
	fmt.Println(name, data.ID)
}

The previously code extracts the status ID's from the Jira instance and if one status is not available on the instance, it'll automatically create the statuses and append the information on the statusesAsMap variable.

With the status ID's, we can proceed with the creation of the workflow statuses payload

var workflowStatuses []*models.WorkflowTransitionScreenScheme
for _, status := range statusesAsMap {

	workflowStatuses = append(workflowStatuses, &models.WorkflowTransitionScreenScheme{
		ID:         status.ID,
		Properties: nil,
	})
}

Step 5.2: Create the workflow transitions

With the statuses id's extracted, we can create a workflow transitions. The transitions define the paths that an issue can take from one status to another.

For example: an issue in the "Open" status can transition to the "In Progress" status when work begins on it.

There're the conditional validations needed to create a valid workflow transition:

• include one initial transition.

• not use the same name for a global and directed transition.

• have a unique name for each global transition.

• have a unique 'to' status for each global transition.

• have unique names for each transition from a status.

• not have a 'from' status on initial and global transitions.

• have a 'from' status on directed transitions.

var workflowTransitions []*models.WorkflowTransitionPayloadScheme

// -----
// The initial transition is required, it creates the relationship between the creation trigger with the
// first status
// -----
workflowTransitions = append(workflowTransitions, &models.WorkflowTransitionPayloadScheme{
	Name: "Create",
	To:   "1",
	Type: "initial",
})

// -----
// Create the Escalated and Waiting for approval statuses because the relationship is all-to-all
workflowTransitions = append(workflowTransitions, &models.WorkflowTransitionPayloadScheme{
	Name: "Escalated",
	To:   statusesAsMap["Escalated"].ID,
	Type: "global",
})

workflowTransitions = append(workflowTransitions, &models.WorkflowTransitionPayloadScheme{
	Name: "Waiting for approval",
	To:   statusesAsMap["Waiting for approval"].ID,
	Type: "global",
})
// -----

// ----
// Create the directed transitions, it's required to use the from and to statuses

// Open -----------------------> In Progress
workflowTransitions = append(workflowTransitions, &models.WorkflowTransitionPayloadScheme{
	Name: "In Progress",
	From: []string{statusesAsMap["Open"].ID},
	To:   statusesAsMap["In Progress"].ID,
	Type: "directed",
})

// In Progress -----------------------> QA
workflowTransitions = append(workflowTransitions, &models.WorkflowTransitionPayloadScheme{
	Name: "QA",
	From: []string{statusesAsMap["In Progress"].ID},
	To:   statusesAsMap["QA"].ID,
	Type: "directed",
})

// QA -----------------------> In Progress
workflowTransitions = append(workflowTransitions, &models.WorkflowTransitionPayloadScheme{
	Name: "QA",
	From: []string{statusesAsMap["QA"].ID},
	To:   statusesAsMap["In Progress"].ID,
	Type: "directed",
})

// QA -----------------------> Closed
workflowTransitions = append(workflowTransitions, &models.WorkflowTransitionPayloadScheme{
	Name: "Closed",
	From: []string{statusesAsMap["QA"].ID},
	To:   statusesAsMap["Closed"].ID,
	Type: "directed",
})

// QA -----------------------> Resolved
workflowTransitions = append(workflowTransitions, &models.WorkflowTransitionPayloadScheme{
	Name: "Resolved",
	From: []string{statusesAsMap["QA"].ID},
	To:   statusesAsMap["Resolved"].ID,
	Type: "directed",
})

Step 5.3: Create the workflow

In conclusion, we can combine the statuses and transitions structs and create the workflow using the structs created on the previous steps.

workflowPayload := &models.WorkflowPayloadScheme{
	Name:        "Workflow Name - Sample",
	Description: "Workflow Name - Description",
	Statuses:    workflowStatuses,
	Transitions: workflowTransitions,
}

newWorkflow, response, err := instance.Workflow.Create(context.Background(), workflowPayload)
if err != nil {
	if response != nil {
		log.Println(response.Bytes.String())
		log.Println(response.Code)
	}

	log.Fatal(err)
}

log.Println(newWorkflow.Name)
log.Println(newWorkflow.EntityID)

Git Gist File

System Administrators can configure an announcement banner to display pertinent information on all Jira pages. The banner can be used to relate important information (e.g. scheduled server maintenance, approaching project deadlines, etc.) to all users. Further, the banner visibility level can be configured to display to all users or just logged-in users.

Get announcement banner configuration

GET /rest/api/{2/3}/announcementBanner

Get returns the current announcement banner configuration.

Update announcement banner configuration

PUT /rest/api/{2-3}/announcementBanner

Update updates the announcement banner configuration.

Introduction

In Jira Cloud, custom fields are managed in a way that allows for flexibility and dynamic creation. Each new custom field that you create within a Jira Cloud instance is assigned a unique ID. This ID is used to identify and manage the custom field's configuration and data within the Jira system.

In this particular case, the library contains multiples helpers method will help you to extract the customfield information by type using the response buffer.

Extract from a single issue

The following methods can be used to extract the customfield information from one issue.

ParseMultiSelectCustomField

This method parses a multi-select custom field from the given buffer data associated with the specified custom field ID and returns a slice of pointers to CustomFieldContextOptionSchema structs.

ParseSelectCustomField

ParseSelectCustomField parses a select custom field from the given buffer data associated with the specified custom field ID and returns a CustomFieldContextOptionScheme struct

ParseCascadingSelectCustomField

This method parses a cascading custom field from the given buffer data associated with the specified custom field ID and returns a CascadingSelectScheme struct pointer.

ParseDatePickerCustomField

ParseDatePickerCustomField parses the datepicker customfield from the given buffer data associated with the specified custom field ID and returns a struct time.Time value

ParseDateTimeCustomField

ParseDateTimeCustomField parses the datetime customfield from the given buffer data associated with the specified custom field ID and returns a struct time.Time value.

ParseMultiUserPickerCustomField

This method parses a group-picker custom field from the given buffer data associated with the specified custom field ID and returns a slice of pointers to UserDetailScheme structs.

ParseMultiGroupPickerCustomField

This method parses a group-picker custom field from the given buffer data associated with the specified custom field ID and returns a slice of pointers to GroupDetailScheme structs.

ParseFloatCustomField

ParseFloatCustomField parses a float custom field from the given buffer data associated with the specified custom field ID and returns string.

ParseSprintCustomField

ParseSprintCustomField parses a sprints custom field from the given buffer data associated with the specified custom field ID and returns a slice of the SprintDetailScheme struct.

ParseLabelCustomField

ParseLabelCustomField parses a textfield slice custom field from the given buffer data associated with the specified custom field ID and returns string slice.

ParseMultiVersionCustomField

ParseMultiVersionCustomField parses a version-picker custom field from the given buffer data associated with the specified custom field ID and returns a slice of pointers to VersionDetailScheme structs.

ParseUserPickerCustomField

ParseUserPickerCustomField parses a user custom field from the given buffer data associated with the specified custom field ID and returns a struct of UserDetailScheme.

ParseAssetCustomField

ParseAssetCustomField parses the Jira assets elements from the given buffer data associated with the specified custom field ID and returns a struct CustomFieldAssetScheme slice.

ParseStringCustomField

ParseStringCustomField parses a textfield custom field from the given buffer data associated with the specified custom field ID and returns string.

Extract from multiple issues

If you want to extract the customfield values from a buffer of issues, you can use the following methods, it returns a map where the key is the issue key and the value is the customfield values parsed

ParseMultiSelectCustomFields

ParseMultiSelectCustomFields extracts and parses multi-select custom field data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a slice of CustomFieldContextOptionScheme structs, representing the parsed multi-select custom field values.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseSelectCustomFields

ParseSelectCustomFields extracts and parses select custom field data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a CustomFieldContextOptionScheme struct, representing the parsed select custom field value.

ParseCascadingCustomFields

ParseCascadingCustomFields extracts and parses a cascading custom field data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a CascadingSelectScheme struct pointer, representing the parsed cascading custom field value.

ParseMultiUserPickerCustomFields

ParseMultiUserPickerCustomFields extracts and parses a user picker custom field data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a slice of UserDetailScheme structs, representing the parsed multi-select custom field values.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseDatePickerCustomFields

ParseDatePickerCustomFields extracts and parses the datepicker customfield data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a time.Time value, representing the parsed datepicker values with the Jira issues.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseDateTimeCustomFields

ParseDateTimeCustomFields extracts and parses the datetime customfield data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a time.Time value, representing the parsed datetime values with the Jira issues.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseMultiGroupPickerCustomFields

ParseMultiGroupPickerCustomFields extracts and parses a group picker custom field data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a slice of GroupDetailScheme structs, representing the parsed multi-group custom field values.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseFloatCustomFields

ParseFloatCustomFields extracts and parses the float customfield information from multiple issues using a bytes.Buffer.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a string representing the parsed float64 customfield value.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseStringCustomFields

ParseStringCustomFields extracts and parses the textfield customfield information from multiple issues using a bytes.Buffer.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a string representing the parsed textfield customfield value.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseUserPickerCustomFields

ParseUserPickerCustomFields extracts and parses a user custom field data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a UserDetailScheme struct pointer ,representing the parsed user custom field value.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseSprintCustomFields

ParseSprintCustomFields extracts and parses sprint custom field data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a slice of SprintDetailScheme structs, representing the parsed sprint custom field values.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseLabelCustomFields

ParseLabelCustomFields extracts and parses the label customfield information from multiple issues using a bytes.Buffer.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a string slice representing the parsed label customfield value.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseMultiVersionCustomFields

ParseMultiVersionCustomFields extracts and parses a version picker custom field data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a slice of VersionDetailScheme structs, representing the parsed multi-version custom field values.

• The JSON data within the buffer is expected to have a specific structure where the custom field values are organized by issue keys and options are represented within a context.

• The function parses this structure to extract and organize the custom field values.

• If the custom field data cannot be parsed successfully, an error is returned.

ParseAssetCustomFields

ParseAssetCustomFields extracts and parses jira assets customfield data from a given bytes.Buffer from multiple issues.

This function takes the name of the custom field to parse and a bytes.Buffer containing JSON data representing the custom field values associated with different issues. It returns a map where the key is the issue key and the value is a slice of CustomFieldAssetScheme structs, representing the parsed assets associated with a Jira issues.

In Jira, a group is a collection of users who have similar roles, responsibilities, or permissions. Groups can be used to simplify user management by allowing you to grant permissions and roles to entire groups of users rather than individual users.

Here are some ways you can use groups in Jira:

1. Assigning permissions: You can assign permissions to a group of users instead of individual users. For example, you might create a group called "Developers" and grant them permissions to create and modify issues.

2. Sharing filters and dashboards: You can share filters and dashboards with groups of users. For example, you might create a filter that shows all issues assigned to the "Developers" group and share it with all members of that group.

3. Managing notifications: You can use groups to manage notifications in Jira. For example, you might create a group called "Product Owners" and add all product owners to that group. You can then set up notifications so that all members of the "Product Owners" group are notified when certain events occur in Jira.

4. Restricting access: You can use groups to restrict access to certain parts of Jira. For example, you might create a group called "Administrators" and grant them access to sensitive parts of Jira such as user management and system settings.

Create Group

POST /rest/api/{2-3}/group

Creates a group

Remove group

DELETE /rest/api/{2-3}/group

Deletes a group

Bulk Groups

GET /rest/api/{2-3}/group/bulk

Get users from groups

GET /rest/api/{2-3}/group/member

Add user to group

POST /rest/api/{2-3}/group/user

Adds a user to a group

Remove user from group

DELETE /rest/api/{2-3}/group/user

Removes a user from a group

Get fields

GET /rest/api/{2-3}/field

Returns system and custom issue fields according to the following rules:

• Fields that cannot be added to the issue navigator are always returned.

• Fields that cannot be placed on an issue screen are always returned.

• Fields that depend on global Jira settings are only returned if the setting is enabled. That is, timetracking fields, subtasks, votes, and watches.

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	fields, response, err := atlassian.Issue.Field.Gets(context.Background())
	if err != nil {
		log.Fatal(err)
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	for _, field := range fields {
		log.Println(field)
	}
}

Create custom field

POST /rest/api/{2-3}/field

Creates a custom field, the method returns the following information:

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	fieldNewCreate := models.CustomFieldScheme{
		Name:        "Alliance 2",
		Description: "this is the alliance description field",
		FieldType:   "cascadingselect",
		SearcherKey: "cascadingselectsearcher",
	}

	field, response, err := atlassian.Issue.Field.Create(context.Background(), &fieldNewCreate)
	if err != nil {
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
	log.Println("field", field)
}

Get fields paginated

GET /rest/api/{2-3}/field/search

Returns a paginated list of fields for Classic Jira projects. The list can include:

• all fields.

• specific fields, by defining id.

• fields that contain a string in the field name or description, by defining query.

• specific fields that contain a string in the field name or description, by defining id and query.

Only custom fields can be queried, type must be set to custom. the method returns the following information:

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	options := models.FieldSearchOptionsScheme{
		Types:   []string{"custom"},
		OrderBy: "lastUsed",
		Expand:  []string{"screensCount", "lastUsed"},
	}

	fields, response, err := atlassian.Issue.Field.Search(context.Background(), &options, 0, 50)
	if err != nil {
		log.Fatal(err)
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
	log.Println(fields.IsLast, fields.Total, fields.MaxResults, fields.StartAt)

	for _, field := range fields.Values {
		log.Println(field.ID, field.Description)
	}
}

Delete Field

DELETE /rest/api/{2-3}/field/{id}

Deletes a custom field. The custom field is deleted whether it is in the trash or not.

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	task, response, err := atlassian.Issue.Field.Delete(context.Background(), "customfield_103034")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
	log.Println(task.Status, task.ID, task.Finished)
}

Get Jira attachment settings

GET /rest/api/{2-3}/attachment/meta

Returns the attachment settings, that is, whether attachments are enabled and the maximum attachment size allowed, the method returns the following information:

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	settings, response, err := atlassian.Issue.Attachment.Settings(context.Background())
	if err != nil {
		log.Fatal(err)
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
	log.Println("settings", settings.Enabled, settings.UploadLimit)
}

Get attachment metadata

GET /rest/api/{2-3}/attachment/{id}

Returns the metadata for an attachment. Note that the attachment itself is not returned, the method returns the following information:

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/davecgh/go-spew/spew"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	metadata, response, err := atlassian.Issue.Attachment.Metadata(context.Background(), "10016")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("Response HTTP Code", response.Code)
	log.Println("HTTP Endpoint Used", response.Endpoint)

	spew.Dump(metadata)
}

Get all metadata for an expanded attachment

GET /rest/api/{2-3}/attachment/{id}/expand/human

Returns the metadata for the contents of an attachment, if it is an archive, and metadata for the attachment itself.

For example, if the attachment is a ZIP archive, then information about the files in the archive is returned and metadata for the ZIP archive. Currently, only the ZIP archive format is supported, the method returns the following information:

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/davecgh/go-spew/spew"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	humanMetadata, response, err := atlassian.Issue.Attachment.Human(context.Background(), "10016")
	if err != nil {
		log.Fatal(err)
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
	spew.Dump(humanMetadata)
}

Delete attachment

DELETE /rest/api/{2-3}/attachment/{id}

Deletes an attachment from an issue, the method returns the following information:

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	response, err := atlassian.Issue.Attachment.Delete(context.Background(), "attachmentID")
	if err != nil {
		log.Fatal(err)
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
}

Add attachment

POST /rest/api/{2-3}/issue/{issueIdOrKey}/attachments

Adds one or more attachments to an issue. Attachments are posted as multipart/form-data (RFC 1867).

• The request must have a X-Atlassian-Token: no-check header, if not it is blocked. See Special headers for more information.

• The name of the multipart/form-data parameter that contains the attachments must be file.

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"log"
	"os"
	"path/filepath"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)


	absolutePath, err := filepath.Abs("jira/mocks/image.png")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("Using the path", absolutePath)

	reader, err := os.Open(absolutePath)
	if err != nil {
		log.Fatal(err)
	}

	defer reader.Close()

	var (
		issueKeyOrID = "KP-2"
		fileName = "image-mock-00.png"
	)

	attachments, response, err := atlassian.Issue.Attachment.Add(context.Background(), issueKeyOrID, fileName, reader)
	if err != nil {
		log.Fatal(err)
		return
	}

	log.Println("Response HTTP Code", response.Code)
	log.Println("HTTP Endpoint Used", response.Endpoint)
	log.Printf("We've found %v attachments", len(attachments))

	for _, attachment := range attachments {
		log.Println(attachment.ID, attachment.Filename)
	}
}

Download Attachment

GET /rest/api/{2-3}/attachment/content/{id}

This endpoint returns the contents of an attachment. A Range header can be set to define a range of bytes within the attachment to download.

If successful, Jira will return a response with the attachment file. You can save the file to your local filesystem or process it in your application as needed.

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	attachmentMetadata, response, err := atlassian.Issue.Attachment.Metadata(context.Background(), "10016")
	if err != nil {
		log.Fatal(err)
	}

	response, err = atlassian.Issue.Attachment.Download(context.Background(), "10016", false)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("Response HTTP Code", response.Code)
	log.Println("HTTP Endpoint Used", response.Endpoint)

	if err := os.WriteFile(attachmentMetadata.Filename, response.Bytes.Bytes(), 0666); err != nil {
		log.Fatal(err)
	}
}

Get Field Configuration Items

GET /rest/api/{2-3}/fieldconfiguration/{id}/fields

Returns a paginated list of all fields for a configuration.

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"log"
	"os"
)

func main()  {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	fieldConfigurationID, startAt, maxResults := 10000, 0, 50
	items, response, err := atlassian.Issue.Field.Configuration.Item.Gets(context.Background(), fieldConfigurationID, startAt, maxResults)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	for _, item := range items.Values {

		log.Println("----------------------")
		log.Println(item.ID)
		log.Println(item.Description)
		log.Println(item.IsRequired)
		log.Println(item.IsRequired)
		log.Println(item.Renderer)
		log.Println("----------------------")
	}
}

Update Field Configuration Items

PUT /rest/api/{2-3}/fieldconfiguration/{id}/fields

Updates fields in a field configuration. The properties of the field configuration fields provided override the existing values.

• The operation can set the renderer for text fields to the default text renderer (text-renderer) or wiki style renderer (wiki-renderer). However, the renderer cannot be updated for fields using the autocomplete renderer (autocomplete-renderer).

package main

import (
	"context"
	v2 "github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
	"log"
	"os"
)

func main()  {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	payload := &models.UpdateFieldConfigurationItemPayloadScheme{
		FieldConfigurationItems: []*models.FieldConfigurationItemScheme{
			{
				ID:          "components",
				IsRequired:  true,
			},
		},
	}


	response, err := atlassian.Issue.Field.Configuration.Item.Update(context.Background(), 10000, payload)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
}

This resource represents options for sharing filters. Use it to get share scopes as well as add and remove share scopes from filters.

Get default share scope

GET /rest/api/3/filter/defaultShareScope

Returns the default sharing settings for new filters and dashboards for a user, the method returns the following information:

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	scope, response, err := atlassian.Filter.Share.Scope(context.Background())
	if err != nil {
		if response != nil {
			log.Println("Response HTTP Response", response.Bytes.String())
		}
		return
	}

	log.Println("Response HTTP Code", response.Code)
	log.Println("HTTP Endpoint Used", response.Endpoint)
	log.Println("Scope", scope)
}

Get share permissions

PUT /rest/api/3/filter/defaultShareScope

Returns the share permissions for a filter. A filter can be shared with groups, projects, all logged-in users, or the public. Sharing with all logged-in users or the public is known as global share permission, the method returns the following information:

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	permissions, response, err := atlassian.Filter.Share.Gets(context.Background(), 1)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	for index, permission := range permissions {
		log.Println(index, permission.Type, permission.Type)
	}
}

Add share permission

POST /rest/api/3/filter/{id}/permission

Add a share permissions to a filter. If you add global share permission (one for all logged-in users or the public) it will overwrite all share permissions for the filter, the method returns the following information:

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/jira/v3"
	"github.com/ctreminiom/go-atlassian/jira/v2"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	/*
		We can add different share permissions, for example:

		---- Project ID only
		payload := jira.PermissionFilterBodyScheme{
				Type:      "project",
				ProjectID: "10000",
			}

		---- Project ID and role ID
		payload := jira.PermissionFilterBodyScheme{
				Type:          "project",
				ProjectID:     "10000",
				ProjectRoleID: "222222",
			}

		==== Group Name
		payload := jira.PermissionFilterBodyScheme{
				Type:          "group",
				GroupName: "jira-users",
			}
	*/

	payload := models.PermissionFilterPayloadScheme{
		Type:      "project",
		ProjectID: "10000",
	}

	permissions, response, err := atlassian.Filter.Share.Add(context.Background(), 1001, &payload)
	if err != nil {
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	for index, permission := range permissions {
		log.Println(index, permission.ID, permission.Type)
	}
}

Get share permission

GET /rest/api/3/filter/{id}/permission

Returns share permission for a filter. A filter can be shared with groups, projects, all logged-in users, or the public.

Sharing with all logged-in users or the public is known as global share permission, the method returns the following information:

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/jira/v3"
	"github.com/ctreminiom/go-atlassian/jira/v2"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	permission, response, err := atlassian.Filter.Share.Get(context.Background(), 10001, 100012)
	if err != nil {
		log.Fatal(err)
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
	log.Println(permission)
}

Delete share permission

DELETE /rest/api/3/filter/{id}/permission/{permissionId}

Deletes share permission from a filter.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/jira/v3"
	"github.com/ctreminiom/go-atlassian/jira/v2"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	response, err := atlassian.Filter.Share.Delete(context.Background(), 11111, 11111)
	if err != nil {
		log.Fatal(err)
		return
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
}

Set default share scope

PUT /rest/api/3/filter/defaultShareScope

Sets the default sharing for new filters and dashboards for a user.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/jira/v3"
	"github.com/ctreminiom/go-atlassian/jira/v2"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	response, err := atlassian.Filter.Share.SetScope(context.Background(), "GLOBAL")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)
}

In this article, I would be showing you how to add custom-fields on a Jira project screens using go-atlassian. Before we get started, let's first understand the Jira entities involved in this process: screens, screen tabs, and screen tab fields.

1. Screens:

   • Screens in Jira define the layout and configuration of different views, such as issue creation, editing, and viewing.

   • Each screen consists of one or more screen tabs.

2. Screen Tabs:

   • Screen tabs are sections within a screen that group related fields together.

   • A screen can have multiple screen tabs, and each tab can contain multiple fields.

3. Screen Tab Fields:

   • Screen tab fields are the individual fields (e.g., standard or custom fields) displayed within a screen tab.

Step 1: Create a new Go project

Create a new directory for your project and navigate to it in your terminal or command prompt. Initialize a new Go module using the following command:

go mod init your-module-name

Step 2: Install the "go-atlassian" library

To use the "go-atlassian" library, you need to install it as a dependency in your project. Run the following command:

go get github.com/ctreminiom/go-atlassian

Step 3: Import the required packages

Create a new Go file, e.g., main.go, and import the necessary packages:

package main

import (
	"fmt"
	"log"

	jira "github.com/ctreminiom/go-atlassian/jira/v2"
)

Step 4: Set up Jira API client

Initialize the Jira API client with your Jira base URL and API token:

func main() {
	client, err := jira.New(nil, "https://your-jira-instance.atlassian.net")
	if err != nil {
		log.Fatal(err)
	}

	// Set API token for authentication
	client.Auth.SetBasicAuth(mail, token)
}

Step 5: Extract the issue type screen scheme

Before to add the customfields on the project screens, we need to search the issue type screen scheme associated with a Jira project, then iterates the mapping to extract the screen schemes linked. In this particular example, we're going to add the following customfields on the KP project:

• Start Date customfield_10068

• Sprint customfield_10020

• DueDate duedate

• timeTracking timetracking

• Environment customfield_10069

• Category customfield_10070

• Testing By customfield_10071

Use the following code to extract the issue type screen scheme linked to the KP project.

var projectKey = "KP"

// --------------------------------------------------
// Extract the project ID using the Project.Get() method
// --------------------------------------------------
project, response, err := client.Project.Get(context.Background(), projectKey, nil)
if err != nil {
	if response != nil {
		log.Println("Response HTTP Response", response.Bytes.String())
		log.Println("Status HTTP Response", response.Status)
	}
	log.Fatal(err)
}

// --------------------------------------------------
// Transform the project id string to integer
// --------------------------------------------------
projectIDAsInt, err := strconv.Atoi(project.ID)
if err != nil {
	log.Fatal(err)
}

// --------------------------------------------------
// Extract the issue type screen scheme linked to the project selected
// --------------------------------------------------
projectMapping, response, err := client.Issue.Type.ScreenScheme.Projects(context.Background(), []int{projectIDAsInt}, 0, 50)
if err != nil {
	if response != nil {
		log.Println("Response HTTP Response", response.Bytes.String())
		log.Println("Status HTTP Response", response.Status)
	}
	log.Fatal(err)
}

// --------------------------------------------------
// Iterates the struts and extract the issue type screen scheme id
// --------------------------------------------------
var issueTypeScreenSchemeID string
for _, scheme := range projectMapping.Values {

	for _, projectID := range scheme.ProjectIds {

		if project.ID == projectID {
			issueTypeScreenSchemeID = projectID
		}
	}
}

Step 6: Extract the screen schemes

With the Issue Type Screen Scheme ID extracted from the previous step, we can proceed with the screen scheme extraction, use the following code to extract the screen schemes

// --------------------------------------------------
// Transform the project id string to integer
// --------------------------------------------------
issueTypeScreenSchemeIDAsInt, err := strconv.Atoi(issueTypeScreenSchemeID)
if err != nil {
	log.Fatal(err)
}

// --------------------------------------------------
// Extract the screen schemes linked to the issue type screen schemes
// --------------------------------------------------
schemeMapping, response, err := client.Issue.Type.ScreenScheme.Mapping(
	context.Background(),
	[]int{issueTypeScreenSchemeIDAsInt},
	0,
	50)

if err != nil {
	if response != nil {
		log.Println("Response HTTP Response", response.Bytes.String())
		log.Println("Status HTTP Response", response.Status)
	}
	log.Fatal(err)
}

// --------------------------------------------------
// Iterates the struts and extract the screen schemes ID as integers
// --------------------------------------------------
var screenSchemesIDs []int
for _, scheme := range schemeMapping.Values {

	screenSchemeIDAsInt, err := strconv.Atoi(scheme.ScreenSchemeID)
	if err != nil {
		log.Fatal(err)
	}

	screenSchemesIDs = append(screenSchemesIDs, screenSchemeIDAsInt)
}

Step 7: Extract the screen IDs

The next step is extract the screen ID's from the screen schemes, you can use this code to extract the screen IDs.

// --------------------------------------------------
// Extract the screens from the screen schemes IDs
// --------------------------------------------------
options := &models.ScreenSchemeParamsScheme{IDs: screenSchemesIDs}
screenSchemes, response, err := client.Screen.Scheme.Gets(context.Background(), options, 0, 50)
if err != nil {
	if response != nil {
		log.Println("Response HTTP Response", response.Bytes.String())
		log.Println("Status HTTP Response", response.Status)
	}
	log.Fatal(err)
}

// --------------------------------------------------
// Iterates the struts and screen IDs
// --------------------------------------------------
var screenIDs []int
for _, screenScheme := range screenSchemes.Values {

	if screenScheme.Screens != nil {
		screenIDs = append(screenIDs, screenScheme.Screens.Default)
		screenIDs = append(screenIDs, screenScheme.Screens.Create)
		screenIDs = append(screenIDs, screenScheme.Screens.Edit)
		screenIDs = append(screenIDs, screenScheme.Screens.View)
	}
}

// --------------------------------------------------
// Remove the duplicated values from the screenIDs slice
// I used the function "removeDuplicateInt" from the Stackoverflow question
// https://stackoverflow.com/questions/66643946/how-to-remove-duplicates-strings-or-int-from-slice-in-go
// --------------------------------------------------
screenIDsWithOutDuplicated := removeDuplicateInt(screenIDs)

Step 8: Add the fields on the project screens

The final step is add the custom-fields on the screen default tabs, it's required to validate if the customfield is already added on the screen tab, if not, add the custom-field on the screen and log the result.

We can use the following code below:

var customFieldsIDs = []string{
	"customfield_10068",
	"customfield_10020",
	"duedate",
	"timetracking",
	"customfield_10069",
	"customfield_10070",
	"customfield_10071",
}

// --------------------------------------------------
// Process each screen and do the following validations/logic
// 1. Extract the screen default tab
// 2. Using the default screen tab, extract the customfields stored on it
// 3. Check if the customfield is already added on the screen tab
// 4. If so, skip it
// 5. If not, append the customfield on the screen tab
// --------------------------------------------------

for _, screenID := range screenIDsWithOutDuplicated {

	// --------------------------------------------------
	// If you want to process the default screen, you can comment this if statement
	// --------------------------------------------------
	if screenID == 0 {
		continue
	}

	tabs, response, err := client.Screen.Tab.Gets(context.Background(), screenID, projectKey)
	if err != nil {
		if response != nil {
			log.Println("Response HTTP Response", response.Bytes.String())
			log.Println("Status HTTP Response", response.Status)
		}
		log.Fatal(err)
	}

	defaultTab := tabs[0].ID

	fields, response, err := client.Screen.Tab.Field.Gets(context.Background(), screenID, defaultTab)
	if err != nil {
		if response != nil {
			log.Println("Response HTTP Response", response.Bytes.String())
			log.Println("Status HTTP Response", response.Status)
		}
		log.Fatal(err)
	}

	// --------------------------------------------------
	// Iterate the fields slice and stores the fields already added on the screen tab
	// --------------------------------------------------
	var fieldsAlreadyAdded []string
	for _, field := range fields {
		fieldsAlreadyAdded = append(fieldsAlreadyAdded, field.ID)
	}

	// --------------------------------------------------
	// Check if the customfield requested is already added on the screen tab
	// --------------------------------------------------
	var fieldsAvailableToAdd []string
	for _, customFieldID := range customFieldsIDs {

		var isTaken bool
		for _, fieldsAdded := range fieldsAlreadyAdded {

			if customFieldID == fieldsAdded {
				isTaken = true
				break
			}
		}

		if !isTaken {
			fieldsAvailableToAdd = append(fieldsAvailableToAdd, customFieldID)
		}
	}

	// --------------------------------------------------
	// For each customfield filtered, add the field on the screen tab
	// --------------------------------------------------
	for _, fieldID := range fieldsAvailableToAdd {

		_, response, err = client.Screen.Tab.Field.Add(context.Background(), screenID, defaultTab, fieldID)
		if err != nil {
			if response != nil {
				log.Println("Response HTTP Response", response.Bytes.String())
				log.Println("Status HTTP Response", response.Status)
			}
			log.Fatal(err)
		}

		log.Println("The field", fieldID, "has been added on the screen ", screenID)
	}

The Jira Issue Field Configurations define the behavior of fields within Jira issues. A field configuration is a set of rules that determines which fields are available for a particular issue type or project, and whether those fields are required, read-only, or hidden. Field configurations can be customized to meet the specific needs of your organization.

Get all Field Configurations

GET /rest/api/{2-3}/fieldconfiguration

Returns a paginated list of field configurations. The list can be for all field configurations or a subset determined by any combination of these criteria:

• a list of field configuration item IDs.

• whether the field configuration is a default.

• whether the field configuration name or description contains a query string.

This method uses the following parameters:

package main

import (
	"context"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	fieldConfigurations, response, err := atlassian.Issue.Field.Configuration.Gets(
		context.Background(),
		nil,
		false,
		0,
		50,
	)

	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	for _, configuration := range fieldConfigurations.Values {
		log.Println(configuration)
	}

}

Create Field Configuration

POST /rest/api/{2-3}/fieldconfiguration

Creates a field configuration. The field configuration is created with the same field properties as the default configuration, with all the fields being optional.

This method uses the following parameters:

package main

import (
	"context"
	"fmt"
	"github.com/ctreminiom/go-atlassian/v2/jira/v2"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"log"
	"os"
)

func main()  {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	atlassian, err := v2.New(nil, host)
	if err != nil {
		return
	}

	atlassian.Auth.SetBasicAuth(mail, token)

	newFieldConfiguration, response, err := atlassian.Issue.Field.Configuration.Create(
		context.Background(),
		"Story DUMMY Field Configuration",
		"description sample")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	fmt.Println(newFieldConfiguration.ID)
	fmt.Println(newFieldConfiguration.Name)
	fmt.Println(newFieldConfiguration.Description)
	fmt.Println(newFieldConfiguration.IsDefault)
}

Update Field Configuration

PUT /rest/api/{2-3}/fieldconfiguration/{id}

Updates a field configuration. The name and the description provided in the request override the existing values.