https://github.com/zammad/zammad-api-client-ruby

Zammad API Client (Ruby)
https://github.com/zammad/zammad-api-client-ruby
Last synced: 6 months ago
JSON representation
Zammad API Client (Ruby)
Host: GitHub
URL: https://github.com/zammad/zammad-api-client-ruby
Owner: zammad
License: other
Created: 2016-06-06T21:07:13.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2024-11-22T12:53:24.000Z (about 1 year ago)
Last Synced: 2025-07-17T17:11:40.043Z (6 months ago)
Language: Ruby
Homepage: https://zammad.com
Size: 99.6 KB
Stars: 22
Watchers: 12
Forks: 11
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.AGPL.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project

README

          # Zammad API Client (Ruby) [![Gem Version](https://badge.fury.io/rb/zammad_api.svg)](https://badge.fury.io/rb/zammad_api)

## API version support

This client supports Zammad API version 1.0.

## Installation

Add this line to your application's Gemfile:

```ruby

gem 'zammad_api'

```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install zammad_api

## Available objects

* user

* organization

* group

* ticket

* ticket_article

* ticket_state

* ticket_priority

## Usage

### Create instance

#### Username/email and password

```ruby

client = ZammadAPI::Client.new(

  url:      'http://localhost:3000/',

  user:     'user',

  password: 'some_pass'

)

```

#### Access token

```ruby

client = ZammadAPI::Client.new(

  url:        'http://localhost:3000/',

  http_token: '12345678901234567890',

)

```

#### OAuth2

```ruby

client = ZammadAPI::Client.new(

  url:          'http://localhost:3000/',

  oauth2_token: '12345678901234567890',

)

```

## Resource management

Individual resources can be created, modified, saved, and destroyed.

### Create object

With new and save:

```ruby

group = client.group.new(

  name: 'Support',

  note: 'Some note',

);

group.save

group.id # id of record

group.name # 'Support'

```

With create:

```ruby

group = client.group.create(

  name: 'Support',

  note: 'Some note',

);

group.id # id of record

group.name # 'Support'

```

### Fetch object

```ruby

group = client.group.find(123)

puts group.inspect

```

### Update object

```ruby

group = client.group.find(123)

group.name = 'Support 2'

group.save

```

### Destroy object

```ruby

group = client.group.find(123)

group.destroy

```

## Collection management

A list of individual resources.

### All

```ruby

groups = client.group.all

group1 = groups[0]

group1.note = 'Some note'

group1.save

groups.each {|group|

  p "group: #{group.name}"

}

```

### Search

```ruby

groups = client.group.search(query: 'some name')

group1 = groups[0]

group1.note = 'Some note'

group1.save

groups.each {|group|

  p "group: #{group.name}"

}

```

### All with pagination (beta)

```ruby

groups = client.group.all

groups.page(1,3) {|group|

  p "group: #{group.name}"

  group.note = 'Some new note, inclued in page 1 with 3 per page'

  group.save

}

groups.page(2,3) {|group|

  p "group: #{group.name}"

  group.note = 'Some new note, inclued in page 2 with 3 per page'

  group.save

}

```

### Search with pagination (beta)

```ruby

groups = client.group.search(query: 'some name')

groups.page(1,3) {|group|

  p "group: #{group.name}"

  group.note = 'Some new note, inclued in page 1 with 3 per page'

  group.save

}

groups.page(2,3) {|group|

  p "group: #{group.name}"

  group.note = 'Some new note, inclued in page 2 with 3 per page'

  group.save

}

```

## Perform actions on behalf of another user

As described in the [Zammad API documentation](https://docs.zammad.org/en/latest/api-intro.html#example-curl-request-on-behalf-of-a-different-user) it is possible to perfom actions on behalf other users. To use this feature you can set the attribute of the client accordingly:

```ruby

client.on_behalf_of = 'some_login'

```

All following actions with the client will be performed on behalf of the user with the `login` "some_login".

To reset this back to regular requests just set `nil`:

```ruby

client.on_behalf_of = nil

```

It's possible to perform only a block of actions on behalf of another user via:

```ruby

client.perform_on_behalf_of('some_login') do

  # ticket is created on behalf of the user with

  # the login "some_login"

  client.ticket.create(

    ...

  )

end

# further actions are performed regularly.

```

## Examples

Create a ticket:

```ruby

ticket = client.ticket.create(

  title: 'a new ticket #1',

  state: 'new',

  group: 'Users',

  priority: '2 normal',

  customer: 'some_customer@example.com',

  article: {

    content_type: 'text/plain', # or text/html, if not given test/plain is used

    body: 'some body',

    # attachments can be optional, data needs to be base64 encoded

    attachments: [

      'filename' => 'some_file.txt',

      'data' => 'dGVzdCAxMjM=',

      'mime-type' => 'text/plain',

    ],

  },

)

ticket.id # id of record

ticket.number # uniq number of ticket

ticket.title # 'a new ticket #1'

ticket.group # 'Support'

ticket.created_at # '2022-01-01T12:42:01Z'

# ...

```

List all new or open tickets:

```ruby

tickets = client.ticket.search(query: 'state:new OR state:open')

ticket[0].id # id of record

ticket[0].number # uniq number of ticket

ticket[0].title # 'title of ticket'

ticket[0].group # 'Support'

ticket[0].created_at # '2022-01-01T12:42:01Z'

tickets.each {|ticket|

  p "ticket: #{ticket.number} - #{ticket.title}"

}

```

Get all articles of a ticket:

```ruby

ticket = client.ticket.find(123)

articles = ticket.articles

articles[0].id # id of record

articles[0].from # creator of article

articles[0].to # recipients of article

articles[0].subject # article subject

articles[0].body # text of message

articles[0].content_type # text/plain or text/html of .body

articles[0].type # 'note'

articles[0].sender # 'Customer'

articles[0].created_at # '2022-01-01T12:42:01Z'

p "ticket: #{ticket.number} - #{ticket.title}"

articles.each {|article|

  p "article: #{article.from} - #{article.subject}"

}

```

Create an article for a ticket:

```ruby

ticket = client.ticket.find(123)

article = ticket.article(

  type: 'note',

  subject: 'some subject 2',

  body: 'some body 2',

  # attachments can be optional, data needs to be base64 encoded

  attachments: [

    'filename' => 'some_file.txt',

    'data' => 'dGVzdCAxMjM=',

    'mime-type' => 'text/plain',

  ],

)

article.id # id of record

article.from # creator of article

article.to # recipients of article

article.subject # article subject

article.body # text of message

article.content_type # text/plain or text/html of .body

article.type # 'note'

article.sender # 'Customer'

article.created_at # '2022-01-01T12:42:01Z'

article.attachments.each { |attachment|

  attachment.filename # 'some_file.txt'

  attachment.size # 1234

  attachment.preferences # { :"Mime-Type"=>"image/jpeg" }

  attachment.download # content of attachment / extra REST call will be executed

}

p "article: #{article.from} - #{article.subject}"

```

Create an article with html and inline images for a ticket:

```ruby

ticket = client.ticket.find(123)

article = ticket.article(

  type: 'note',

  subject: 'some subject 2',

  body: 'some body with an image ',

  content_type: 'text/html', # optional, default is text/plain

)

article.id # id of record

article.from # creator of article

article.to # recipients of article

article.subject # article subject

article.body # text of message

article.content_type # text/plain or text/html of .body

article.type # 'note'

article.sender # 'Customer'

article.created_at # '2022-01-01T12:42:01Z'

article.attachments.each { |attachment|

  attachment.filename # '122.146472496@www.znuny.com'

  attachment.size # 1167

  attachment.preferences # { :'Mime-Type'=>'image/jpeg', :'Content-ID'=>'122.146472496@www.znuny.com', :'Content-Disposition'=>'inline'} }

  attachment.download # content of attachment / extra REST call will be executed

}

p "article: #{article.from} - #{article.subject}"

```

## Testing

### Setup an (empty Zammad) test env

```

git clone git@github.com:zammad/zammad.git

cd zammad

export RAILS_ENV="test"

export APP_RESTART_CMD="bundle exec rake zammad:ci:app:restart"

script/bootstrap.sh && echo '' > log/test.log

cp contrib/auto_wizard_test.json auto_wizard.json

bundle exec rake zammad:ci:test:start

```

### Execute client tests

Run tests via `rake spec`. (Remember to export the vars above if you are running this in another shell.)

## Publishing

1. Update version in [version.rb](lib/zammad_api/version.rb).

2. Add release to [CHANGELOG.md](CHANGELOG.md)

3. Commit.

4. Test build.

```

> rake build

zammad_api 1.0.7 built to pkg/zammad_api-1.0.7.gem.

```

5. Release

```

> rake release

zammad_api 1.0.7 built to pkg/zammad_api-1.0.7.gem.

Tag v1.0.7 has already been created.

Pushing gem to https://rubygems.org...

You have enabled multi-factor authentication. Please enter OTP code.

Code:   ......

Successfully registered gem: zammad_api (1.0.7)

Pushed zammad_api 1.0.7 to https://rubygems.org

```

## Contributing

Bug reports and pull requests are welcome on [GitHub](https://github.com/zammad/zammad-api-client-ruby). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/zammad/zammad-api-client-ruby

Awesome Lists containing this project

README
