zammad

package module
v0.0.0-...-e9e7d13 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2024 License: BSD-3-Clause Imports: 8 Imported by: 0

README

Go client for Zammad REST API

This is an Go implementation to lets you use the Zammad's REST API, see https://zammad.com/en/product/features/rest-api for an introduction. The documentation in the code has further links to details of the Zammad API.

Example

package main

import (
    "log"

    "github.com/AlessandroSechi/zammad-go"
)

func main() {
	client := zammad.New("https://my-zammad-instance.com")
	client.Token = "my-accces-token"
	// or basic auth see godoc

	users, err := client.UserList() // Get all users
	if err != nil {
		log.Fatal(err)
	}

	user, err := client.UserShow(1) // Get User with ID 1
	if err != nil {
		log.Fatal(err)
	}

	// to iterate over pages
	ticketRes := client.TicketListResult(zammad.WithPerPage(50))
	for ticketRes.Next() {
		tickets, err := ticketRes.Fetch()
		if err != nil {
			log.Fatalf("failed: %s", err)
		}

		log.Printf("number of tickets: %d\n", len(tickets))
	}
}

Development

If you want to test the code against a live zammad instance, you'll need to create an access token and set the following environment variables before testing:

  • ZAMMAD_INSTANCE: this is the URL of you zammad instance
  • ZAMMAD_TOKEN: this the access token you can use

Documentation

Overview

Package zammad is a full fledged Go package to interact with the Zammad (REST) API. The API types from Zammad are kept small enough to work against the Zammad API.

See https://zammad.com/en/product/features/rest-api for an introduction.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	Client   Doer
	Username string
	Password string
	Token    string
	OAuth    string
	Url      string
	// FromFunc is used to set the From HTTP header, if you want to act on behalf of another user.
	// See https://docs.zammad.org/en/latest/api/intro.html#actions-on-behalf-of-other-users. If not nil
	// *and* returning a non empty string, this value will be used in the request.
	FromFunc func() string
}

Client is used to query Zammad. It is safe to use concurrently. If you (inadvertly) added multiple authencation options that will be applied in the order, basic auth, token based, and then oauth. Where the last one set, wins.

func New 

func New(URL string) *Client

New returns a new Zammad client initialized with an http client. Authentication need to be set seperately. The http client uses a timeout of 5 seconds.

func (*Client) GroupCreate 

func (c *Client) GroupCreate(g Group) (Group, error)

func (*Client) GroupDelete 

func (c *Client) GroupDelete(groupID int) error

func (*Client) GroupList 

func (c *Client) GroupList() ([]Group, error)

func (*Client) GroupListListResult 

func (c *Client) GroupListListResult(opts ...Option) *Result[Group]

func (*Client) GroupListWithOptions 

func (c *Client) GroupListWithOptions(ro RequestOptions) ([]Group, error)

func (*Client) GroupShow 

func (c *Client) GroupShow(groupID int) (Group, error)

func (*Client) GroupUpdate 

func (c *Client) GroupUpdate(groupID int, g Group) (Group, error)

func (*Client) NewRequest 

func (c *Client) NewRequest(method, url string, payload interface{}) (*http.Request, error)

NewRequest constructs a request and converts the payload to JSON.

func (*Client) ObjectCreate 

func (c *Client) ObjectCreate(o Object) (Object, error)

func (*Client) ObjectExecuteDatabaseMigration 

func (c *Client) ObjectExecuteDatabaseMigration() error

func (*Client) ObjectList 

func (c *Client) ObjectList() ([]Object, error)

func (*Client) ObjectListResult 

func (c *Client) ObjectListResult(opts ...Option) *Result[Object]

func (*Client) ObjectListWithOptions 

func (c *Client) ObjectListWithOptions(ro RequestOptions) ([]Object, error)

func (*Client) ObjectShow 

func (c *Client) ObjectShow(objectID int) (Object, error)

func (*Client) ObjectUpdate 

func (c *Client) ObjectUpdate(objectID int, o Object) (Object, error)

func (*Client) OnlineNotificationDelete 

func (c *Client) OnlineNotificationDelete(notificationID int) error

func (*Client) OnlineNotificationList 

func (c *Client) OnlineNotificationList() ([]OnlineNotification, error)

func (*Client) OnlineNotificationListResult 

func (c *Client) OnlineNotificationListResult(opts ...Option) *Result[OnlineNotification]

func (*Client) OnlineNotificationListWithOptions 

func (c *Client) OnlineNotificationListWithOptions(ro RequestOptions) ([]OnlineNotification, error)

func (*Client) OnlineNotificationMarkAllAsRead 

func (c *Client) OnlineNotificationMarkAllAsRead() error

func (*Client) OnlineNotificationShow 

func (c *Client) OnlineNotificationShow(notificationID int) (OnlineNotification, error)

func (*Client) OnlineNotificationUpdate 

func (c *Client) OnlineNotificationUpdate(notificationID int, n OnlineNotification) (OnlineNotification, error)

func (*Client) OrganizationCreate 

func (c *Client) OrganizationCreate(o Organization) (Organization, error)

func (*Client) OrganizationDelete 

func (c *Client) OrganizationDelete(organizationID int) error

func (*Client) OrganizationList 

func (c *Client) OrganizationList() ([]Organization, error)

func (*Client) OrganizationListResult 

func (c *Client) OrganizationListResult(opts ...Option) *Result[Organization]

func (*Client) OrganizationListWithOptions 

func (c *Client) OrganizationListWithOptions(ro RequestOptions) ([]Organization, error)

func (*Client) OrganizationSearch 

func (c *Client) OrganizationSearch(query string, limit int) ([]Organization, error)

func (*Client) OrganizationShow 

func (c *Client) OrganizationShow(organizationID int) (Organization, error)

func (*Client) OrganizationUpdate 

func (c *Client) OrganizationUpdate(organizationID int, o Organization) (Organization, error)

func (*Client) TagAdd 

func (c *Client) TagAdd(t Tag) error

func (*Client) TagAdminCreate 

func (c *Client) TagAdminCreate(t Tag) error

func (*Client) TagAdminDelete 

func (c *Client) TagAdminDelete(tagID int) error

func (*Client) TagAdminList 

func (c *Client) TagAdminList() ([]Tag, error)

func (*Client) TagAdminRename 

func (c *Client) TagAdminRename(tagID int, t Tag) error

func (*Client) TagRemove 

func (c *Client) TagRemove(t Tag) error

func (*Client) TagSearch 

func (c *Client) TagSearch(term string) ([]Tag, error)

func (*Client) TicketArticleByTicket 

func (c *Client) TicketArticleByTicket(ticketID int) ([]TicketArticle, error)

func (*Client) TicketArticleCreate 

func (c *Client) TicketArticleCreate(t TicketArticle) (TicketArticle, error)

func (*Client) TicketArticleShow 

func (c *Client) TicketArticleShow(ticketArticleID int) (TicketArticle, error)

func (*Client) TicketCreate 

func (c *Client) TicketCreate(t Ticket) (Ticket, error)

TicketCreate is used to create a ticket. For this you need to assemble a bare-bones Ticket: 

ticket := Ticket{
	Title:      "your subject",
	Group:      "your group",
	CustomerID: 10, // your customer ID
	Article: TicketArticle{
		Subject: "subject of comment",
		Body: "body of comment",
	},
}

func (*Client) TicketDelete 

func (c *Client) TicketDelete(ticketID int) error

func (*Client) TicketList 

func (c *Client) TicketList() ([]Ticket, error)

func (*Client) TicketListResult 

func (c *Client) TicketListResult(opts ...Option) *Result[Ticket]

func (*Client) TicketListWithOptions 

func (c *Client) TicketListWithOptions(ro RequestOptions) ([]Ticket, error)

func (*Client) TicketPriorityCreate 

func (c *Client) TicketPriorityCreate(t TicketPriority) (TicketPriority, error)

func (*Client) TicketPriorityDelete 

func (c *Client) TicketPriorityDelete(ticketPriorityID int) error

func (*Client) TicketPriorityList 

func (c *Client) TicketPriorityList() ([]TicketPriority, error)

func (*Client) TicketPriorityListResult 

func (c *Client) TicketPriorityListResult(opts ...Option) *Result[TicketPriority]

func (*Client) TicketPriorityListWithOptions 

func (c *Client) TicketPriorityListWithOptions(ro RequestOptions) ([]TicketPriority, error)

func (*Client) TicketPriorityShow 

func (c *Client) TicketPriorityShow(ticketPriorityID int) (TicketPriority, error)

func (*Client) TicketPriorityUpdate 

func (c *Client) TicketPriorityUpdate(ticketPriorityID int, t TicketPriority) (TicketPriority, error)

func (*Client) TicketSearch 

func (c *Client) TicketSearch(query string, limit int) ([]Ticket, error)

TicketSearch searches for tickets. See https://docs.zammad.org/en/latest/api/ticket/index.html#search.

func (*Client) TicketShow 

func (c *Client) TicketShow(ticketID int) (Ticket, error)

func (*Client) TicketStateCreate 

func (c *Client) TicketStateCreate(t TicketState) (TicketState, error)

func (*Client) TicketStateDelete 

func (c *Client) TicketStateDelete(ticketStateID int) error

func (*Client) TicketStateList 

func (c *Client) TicketStateList() ([]TicketState, error)

func (*Client) TicketStateListResult 

func (c *Client) TicketStateListResult(opts ...Option) *Result[TicketState]

func (*Client) TicketStateListWithOptions 

func (c *Client) TicketStateListWithOptions(ro RequestOptions) ([]TicketState, error)

func (*Client) TicketStateShow 

func (c *Client) TicketStateShow(ticketStateID int) (TicketState, error)

func (*Client) TicketStateUpdate 

func (c *Client) TicketStateUpdate(ticketStateID int, t TicketState) (TicketState, error)

func (*Client) TicketTagByTicket 

func (c *Client) TicketTagByTicket(ticketID int) ([]Tag, error)

func (*Client) TicketUpdate 

func (c *Client) TicketUpdate(ticketID int, t Ticket) (Ticket, error)

func (*Client) UserAccessTokenCreate 

func (c *Client) UserAccessTokenCreate(t UserAccessToken) (UserAccessToken, error)

func (*Client) UserAccessTokenDelete 

func (c *Client) UserAccessTokenDelete(tokenID int) error

func (*Client) UserAccessTokenList 

func (c *Client) UserAccessTokenList() ([]UserAccessToken, error)

func (*Client) UserCreate 

func (c *Client) UserCreate(u User) (User, error)

func (*Client) UserDelete 

func (c *Client) UserDelete(userID int) error

func (*Client) UserList 

func (c *Client) UserList() ([]User, error)

func (*Client) UserListResult 

func (c *Client) UserListResult(opts ...Option) *Result[User]

func (*Client) UserListWithOptions 

func (c *Client) UserListWithOptions(ro RequestOptions) ([]User, error)

func (*Client) UserMe 

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

UserMe returns the current authenticated user.

func (*Client) UserSearch 

func (c *Client) UserSearch(query string, limit int) ([]User, error)

func (*Client) UserShow 

func (c *Client) UserShow(userID int) (User, error)

func (*Client) UserUpdate 

func (c *Client) UserUpdate(userID int, u User) (User, error)

type Date 

type Date struct {
	time.Time
}

Date is a timestamp that is only specified as YYYY-MM-DD, without time zone or a clock time.

func (*Date) UnmarshalJSON 

func (d *Date) UnmarshalJSON(data []byte) error

type Doer 

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer is an interface that allows mimicking a *http.Client.

type ErrorResponse 

type ErrorResponse struct {
	Description      string `json:"error"`
	DescriptionHuman string `json:"error_human"`
}

ErrorResponse is the response returned by Zammad when an error occured.

func (*ErrorResponse) Error 

func (r *ErrorResponse) Error() string

type Group 

type Group struct {
	ID                 int       `json:"id,omitempty"`
	Name               string    `json:"name"`
	NameLast           string    `json:"name_last"`
	FollowUpPossible   string    `json:"follow_up_possible"`
	FollowUpAssignment bool      `json:"follow_up_assignment"`
	Active             bool      `json:"active"`
	UpdatedByID        int       `json:"updated_by_id"`
	CreatedByID        int       `json:"created_by_id"`
	CreatedAt          time.Time `json:"created_at"`
	UpdatedAt          time.Time `json:"updated_at"`
	UserIds            []int     `json:"user_ids"`
}

Group is a Zammad group.

type Object 

type Object *map[string]interface{}

Object represent a Zammad object. See https://docs.zammad.org/en/latest/api/object.html. Also note the warning there: 

Adjusting objects via API can cause serious issues with your instance. Proceed with absolute caution and ensure
to adjust any of Zammads default fields.

type OnlineNotification 

type OnlineNotification struct {
	ID             int       `json:"id"`
	OID            int       `json:"o_id"`
	ObjectLookupID int       `json:"object_lookup_id"`
	TypeLookupID   int       `json:"type_lookup_id"`
	UserID         int       `json:"user_id"`
	Seen           bool      `json:"seen"`
	UpdatedByID    int       `json:"updated_by_id"`
	CreatedByID    int       `json:"created_by_id"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

OnlineNotification represent a Zammad online notification. See https://docs.zammad.org/en/latest/api/notification.html.

type Option 

type Option func(ro *RequestOptions)

Option is a function that modifies a RequestOptions instance.

func WithOrderBy 

func WithOrderBy(orderBy string) Option

WithOrderBy sets the order of sorting in RequestOptions.

func WithPage 

func WithPage(page int) Option

WithPage sets the page number in RequestOptions.

func WithPerPage 

func WithPerPage(perPage int) Option

WithPerPage sets the number of items per page in RequestOptions.

func WithSortBy 

func WithSortBy(sortBy string) Option

WithSortBy sets the field to sort by in RequestOptions.

type Organization 

type Organization struct {
	ID                 int       `json:"id,omitempty"`
	Name               string    `json:"name"`
	Shared             bool      `json:"shared"`
	Domain             string    `json:"domain"`
	DomainAssignment   bool      `json:"domain_assignment"`
	Active             bool      `json:"active"`
	Note               string    `json:"note"`
	Vip                bool      `json:"vip"`
	UpdatedByID        int       `json:"updated_by_id,omitempty"`
	CreatedByID        int       `json:"created_by_id,omitempty"`
	CreatedAt          time.Time `json:"created_at,omitempty"`
	UpdatedAt          time.Time `json:"updated_at,omitempty"`
	MemberIds          []int     `json:"member_ids,omitempty"`
	SecondaryMemberIds []int     `json:"secondary_member_ids,omitempty"`
}

Organization represent a Zammad organisation. See https://docs.zammad.org/en/latest/api/organization.html.

type Permission 

type Permission struct {
	ID          int    `json:"id"`
	Name        string `json:"name"`
	Note        string `json:"note"`
	Preferences struct {
		Translations []string `json:"translations"`
		Disabled     bool     `json:"disabled"`
	} `json:"preferences,omitempty"`
	Active      bool      `json:"active"`
	AllowSignup bool      `json:"allow_signup"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

Permission is a Zammad permission.

type RequestOptions 

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

RequestOptions holds the parameters for making a request.

func NewRequestOptions 

func NewRequestOptions(opts ...Option) RequestOptions

NewRequestOptions creates a new RequestOptions instance with the provided options. It applies each Option function to the RequestOptions instance.

func (RequestOptions) URLParams 

func (ro RequestOptions) URLParams() string

URLParams returns the URL-encoded parameters for the request.

type Result 

type Result[T any] struct {
	// contains filtered or unexported fields
}

Result is a generic type that holds a slice of results and provides methods to paginate through them.

func (*Result[T]) Fetch 

func (tr *Result[T]) Fetch() ([]T, error)

Fetch returns the current slice of results and the last error encountered.

func (*Result[T]) FetchAll 

func (tr *Result[T]) FetchAll() ([]T, error)

FetchAll fetches all pages of results and returns them as a single slice. If an error occurs during fetching, it returns the results fetched so far along with the error.

func (*Result[T]) Next 

func (tr *Result[T]) Next() bool

Next fetches the next page of results. It returns false if there are no more results to fetch. If an error occurs during fetching, it sets the lastErr field and returns true.

type Tag 

type Tag struct {
	ID   int    `json:"id,omitempty"`
	Name string `json:"name"`
}

Tag is a Zammad tag. See https://docs.zammad.org/en/latest/api/ticket/tags.html.

type Ticket 

type Ticket struct {
	Title                 string        `json:"title"`
	Group                 string        `json:"group"`
	OwnerID               int           `json:"owner_id,omitempty"`
	ID                    int           `json:"id,omitempty"`
	Article               TicketArticle `json:"article,omitempty"`
	GroupID               int           `json:"group_id,omitempty"`
	PriorityID            int           `json:"priority_id,omitempty"`
	StateID               int           `json:"state_id,omitempty"`
	State                 string        `json:"state,omitempty"`
	OrganizationID        int           `json:"organization_id"`
	Number                string        `json:"number,omitempty"`
	Customer              string        `json:"customer,omitempty"`
	CustomerID            int           `json:"customer_id,omitempty"`
	LastContactAt         time.Time     `json:"last_contact_at,omitempty"`
	LastContactAgentAt    time.Time     `json:"last_contact_agent_at,omitempty"`
	LastContactCustomerAt time.Time     `json:"last_contact_customer_at,omitempty"`
	CreateArticleTypeID   int           `json:"create_article_type_id,omitempty"`
	CreateArticleSenderID int           `json:"create_article_sender_id,omitempty"`
	ArticleCount          int           `json:"article_count,omitempty"`
	UpdatedByID           int           `json:"updated_by_id,omitempty"`
	CreatedByID           int           `json:"created_by_id,omitempty"`
	CreatedAt             time.Time     `json:"created_at,omitempty"`
	UpdatedAt             time.Time     `json:"updated_at,omitempty"`
}

Ticket is a zammad ticket.

type TicketArticle 

type TicketArticle struct {
	ID       int    `json:"id,omitempty"`
	TicketID int    `json:"ticket_id,omitempty"`
	TypeID   int    `json:"type_id,omitempty"`
	SenderID int    `json:"sender_id,omitempty"`
	From     string `json:"from,omitempty"`
	To       string `json:"to,omitempty"`
	// Don't know if I want to keep the 'any' types here?
	Subject     string    `json:"subject"`
	Body        string    `json:"body"`
	Cc          any       `json:"cc"`
	ReplyTo     any       `json:"reply_to"`
	ContentType string    `json:"content_type"`
	Internal    bool      `json:"internal"`
	UpdatedByID int       `json:"updated_by_id,omitempty"`
	CreatedByID int       `json:"created_by_id,omitempty"`
	OriginByID  any       `json:"origin_by_id,omitempty"`
	CreatedAt   time.Time `json:"created_at,omitempty"`
	UpdatedAt   time.Time `json:"updated_at,omitempty"`
	Type        string    `json:"type,omitempty"`
	Sender      string    `json:"sender,omitempty"`
	CreatedBy   string    `json:"created_by,omitempty"`
	UpdatedBy   string    `json:"updated_by,omitempty"`
}

TicketArticle represents a Zammad ticket article.

type TicketPriority 

type TicketPriority struct {
	ID            int       `json:"id"`
	Name          string    `json:"name"`
	DefaultCreate bool      `json:"default_create"`
	UIIcon        string    `json:"ui_icon"`
	UIColor       string    `json:"ui_color"`
	Note          any       `json:"note"`
	Active        bool      `json:"active"`
	UpdatedByID   int       `json:"updated_by_id"`
	CreatedByID   int       `json:"created_by_id"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

TicketPriority represent a Zammad ticket priority. See https://docs.zammad.org/en/latest/api/ticket/priorities.html.

type TicketState 

type TicketState struct {
	ID               int       `json:"id"`
	StateTypeID      int       `json:"state_type_id"`
	Name             string    `json:"name"`
	IgnoreEscalation bool      `json:"ignore_escalation"`
	DefaultCreate    bool      `json:"default_create"`
	DefaultFollowUp  bool      `json:"default_follow_up"`
	Active           bool      `json:"active"`
	UpdatedByID      int       `json:"updated_by_id"`
	CreatedByID      int       `json:"created_by_id"`
	CreatedAt        time.Time `json:"created_at"`
}

TicketState is a Zammad ticket state

type User 

type User struct {
	ID             int       `json:"id"`
	OrganizationID int       `json:"organization_id"`
	Login          string    `json:"login"`
	Firstname      string    `json:"firstname"`
	Lastname       string    `json:"lastname"`
	Email          string    `json:"email"`
	Web            string    `json:"web"`
	LastLogin      time.Time `json:"last_login"`
}

User is a Zammad user. See https://docs.zammad.org/en/latest/api/user.html.

type UserAccessToken 

type UserAccessToken struct {
	ID          int      `json:"id"`
	Token       string   `json:"token,omitempty"` // Token is only set in the returned UserAccessToken in UserAccessTokenCreate.
	Name        string   `json:"name,omitempty"`  // Name is must be set and is only used in UserAccessTokenCreate.
	UserID      int      `json:"user_id"`
	Action      string   `json:"action"`
	Label       string   `json:"label"`
	Permission  []string `json:"permission,omitempty"` // Permission must be set and is only used in UserAccessTokenCreate.
	Preferences struct {
		Permission []string `json:"permission"`
	} `json:"preferences"`
	LastUsedAt time.Time `json:"last_used_at"`
	ExpiresAt  Date      `json:"expires_at,omitempty"` // ExpiresAt must be set when using in UserAccessTokenCreate.
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`

	// Permissions holds all available Zammad User access token permissions. It's only used UserAccessTokenList.
	// When returns UserAccessTokens from UserAccessTokenList only the first access token will have a filled out
	// permissions struct. For the remaining token this will be empty.
	Permissions []Permission `json:"permissions,omitempty"`
}

UserAccessToken is a Zammad User access token. See https://docs.zammad.org/en/latest/api/user-access-token.html.

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.