Skip to content

Commit

Permalink
Merge pull request #101 from ctreminiom/feature/confluence-services
Browse files Browse the repository at this point in the history 
Feature/confluence services
  • Loading branch information
@ctreminiom
ctreminiom authored Jan 23, 2022
2 parents c9288b4 + c8161d0 commit 46c5d7c
Show file tree
Hide file tree
Showing 14 changed files with 2,341 additions and 94 deletions.
199 changes: 126 additions & 73 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,107 +13,160 @@
<a href="https://bestpractices.coreinfrastructure.org/projects/4861"><img src="https://bestpractices.coreinfrastructure.org/projects/4861/badge"></a>
</p>

go-atlassian is a Go module that enables the interaction with the Atlassian Cloud Services. It provides the Go implementation for operating the Atlassian Cloud platform.

## ✨ Features
- Supports Jira Software V2/V3 endpoints.
- Support the Jira Agile endpoints
- Interacts with the Jira Service Management entities.
- Manages the Atlassian Admin Cloud organizations.
- Manages the Atlassian Admin SCIM workflow.
- Checks Confluence Cloud content permissions.
- CRUD Confluence Cloud content (page, blogpost, comment, question).
- Add attachment into Confluence Cloud contents.
- Search contents and spaces.
- Support the Atlassian Document Format (ADF).
- Every method has their corresponding example documented.

## 🔰 Installation
Make sure you have Go installed (download). Version `1.13` or higher is required.
```sh
$ go get -u -v github.com/ctreminiom/go-atlassian
Communicate with the [Atlassian API's](https://developer.atlassian.com/cloud/) quickly and easily
with the **go-atlassian** module. With the **go-atlassian** client, you can retrieve and manipulate
the extensive Atlassian Cloud API's like Jira, Confluence, Jira Agile, Jira Service Management, Atlassian Admin and much more!.

If you find an endpoint not supported, please submit a pull request or raise a feature issue - it's always greatly appreciated.

## Installation

If you do not have [Go](https://golang.org/) installed yet, you can find installation instructions
[here](https://golang.org/doc/install). Please note that the package requires Go version
1.13 or later for module support.

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

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

## 📓 Documentation
Documentation is hosted live at https://docs.go-atlassian.io/
Then import the package into your project as you normally would. You can import the following packages

## 📝 Using the library
````go
package main
|Package|import path |
|--|--|
|Jira v2|`github.com/ctreminiom/go-atlassian/jira/v2`|
|Jira v3|`github.com/ctreminiom/go-atlassian/jira/v3`|
|Jira Agile|`github.com/ctreminiom/go-atlassian/jira/agile`|
|Jira ITSM|`github.com/ctreminiom/go-atlassian/jira/sm`|
|Confluence|`github.com/ctreminiom/go-atlassian/confluence`|
|Cloud Admin|`github.com/ctreminiom/go-atlassian/admin`|

import (
"context"
"github.com/ctreminiom/go-atlassian/jira/v2"
"log"
"os"
)
Now you're ready to Go.

### 🧳 Creating A Client

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](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).

Create a client with your instance host and access token to start communicating with the Atlassian API's.

```go
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.

```go
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,
}

func main() {
instance, err := confluence.New(&client, "INSTANCE_HOST")
if err != nil {
log.Fatal(err)
}

var (
host = os.Getenv("HOST")
mail = os.Getenv("MAIL")
token = os.Getenv("TOKEN")
)
instance.Auth.SetBasicAuth("YOUR_CLIENT_MAIL", "YOUR_APP_ACCESS_TOKEN")
```

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

atlassian.Auth.SetBasicAuth(mail, token)
The client contains a distinct service for working with each of the Atlassian API's
endpoints. Each service has a set of service functions that make specific API
calls to their respective endpoint.

issue, response, err := atlassian.Issue.Get(context.Background(), "KP-2", nil, []string{"transitions"})
if err != nil {
log.Fatal(err)
}
To start communicating with the **go-atlassian**, choose a service and call its service
function. Take the Jira service for example.

log.Println("HTTP Endpoint Used", response.Endpoint)
To get the issue with the transitions, use the **Issue** service function.
```go
ctx := context.Background()
issueKey := "KP-2"
expand := []string{"transitions"}

log.Println(issue.Key)
log.Println(issue.Fields.Reporter.AccountID)
issue, response, err := atlassian.Issue.Get(ctx,issueKey, nil, expand)
if err != nil {
log.Fatal(err)
}

for _, transition := range issue.Transitions {
log.Println(transition.Name, transition.ID, transition.To.ID, transition.HasScreen)
}
log.Println(issue.Key)

// Check if the issue contains sub-tasks
if issue.Fields.Subtasks != nil {
for _, subTask := range issue.Fields.Subtasks {
log.Println("Sub-Task: ", subTask.Key, subTask.Fields.Summary)
}
}
for _, transition := range issue.Transitions {
log.Println(transition.Name, transition.ID, transition.To.ID, transition.HasScreen)
}
````
```

## ⭐️ Project assistance
If you want to say **thank you** or/and support active development of `go-atlassian`:
To search issues using a JQL query, use the **Issue.Search** service function.
```go
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)
```

The rest of the service functions work much the same way; they are concise and
behave as you would expect. The [documentation](https://docs.go-atlassian.io/)
contains several examples on how to use each service function.

## ✍️ 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.
* Add appropriate tests.
* Run go fmt, go vet, and golint.
* Prefer idiomatic Go over non-idiomatic code.
* Follow the basic Go conventions found [here](https://github.com/golang/go/wiki/CodeReviewComments).
* If in doubt, try to match your code to the current codebase.
* Create a pull request with a description of your changes.

Again, contributions are greatly appreciated!

- Add a [GitHub Star](https://github.com/ctreminiom/go-atlassian) to the project.
- Write interesting articles about project on [Dev.to](https://dev.to/), [Medium](https://medium.com/) or personal blog.
- Contributions, issues and feature requests are welcome!
- Feel free to check [issues page](https://github.com/ctreminiom/go-atlassian/issues).

## 💡 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.

## 🧪 Run Test Cases
```sh
go test -v ./...
```

## 📝 License
Copyright © 2021 [Carlos Treminio](https://github.com/ctreminiom).
This project is [MIT](https://opensource.org/licenses/MIT) licensed.

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fctreminiom%2Fgo-atlassian.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fctreminiom%2Fgo-atlassian?ref=badge_large)

## 🌐 Credits
In addition to all the contributors we would like to thank to these companies:
## 🤝 Special Thanks
In addition to all the contributors we would like to thanks to these companies:
- [Atlassian](https://www.atlassian.com/) for providing us Atlassian Admin/Jira/Confluence Standard licenses.
- [JetBrains](https://www.jetbrains.com/) for providing us with free licenses of [GoLand](https://www.jetbrains.com/pycharm/)
- [GitBook](https://www.gitbook.com/) for providing us non-profit / open-source plan so hence I would like to express my thanks here.

<img src="./static/jetbrains-logo.svg">
<img src="./static/gitbook-logo.svg">
<img align="right" src="./static/jetbrains-logo.svg">
<img align="left" src="./static/gitbook-logo.svg">
3 changes: 3 additions & 0 deletions confluence/confluence.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ type Client struct {
Auth *AuthenticationService
Content *ContentService
Space *SpaceService
Label *LabelService
}

func New(httpClient *http.Client, site string) (client *Client, err error) {
Expand Down Expand Up @@ -58,9 +59,11 @@ func New(httpClient *http.Client, site string) (client *Client, err error) {
Group: &ContentRestrictionOperationGroupService{client: client},
User: &ContentRestrictionOperationUserService{client: client},
}},
Version: &ContentVersionService{client: client},
}

client.Space = &SpaceService{client: client}
client.Label = &LabelService{client: client}
return
}

Expand Down
1 change: 1 addition & 0 deletions confluence/content.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ type ContentService struct {
Label *ContentLabelService
Property *ContentPropertyService
Restriction *ContentRestrictionService
Version *ContentVersionService
}

// Gets returns all content in a Confluence instance.
Expand Down
Loading

0 comments on commit 46c5d7c

Please sign in to comment.