# Zammad API Client (Ruby) [![Gem Version](https://badge.fury.io/rb/zammad_api.svg)](https://badge.fury.io/rb/zammad_api) [![CI](https://github.com/zammad/zammad-api-client-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/zammad/zammad-api-client-ruby/actions/workflows/ci.yml) --- > [!IMPORTANT] > ## 📣 2.0 is taking shape — tell us what you think > > **Version 2.0 is a breaking release, and it is not finished yet: this is `2.0.0.alpha1`, > its first prerelease.** This is the moment when your feedback can still change it: names, > defaults, what is missing, what reads wrong, and anything that makes upgrading from 1.x > harder than it should be. > > **[→ Open an issue and tell us](https://github.com/zammad/zammad-api-client-ruby/issues/new)** > > Especially useful to hear: > > - Which 1.x calls in **your** code the [migration table](#migrating-from-1x) does not cover. > - Endpoints you reach with [raw requests](#raw-requests) that should be modelled resources. > - Anything the [test kit](#testing-code-that-uses-this-client) cannot stand in for. > - Naming that made you look twice, and defaults you had to override every time. > > Rough notes are welcome — a half-formed "this felt off" is worth more to us now than a > polished report after the release. --- Ruby client for the Zammad API v1.0. - Requires **Ruby 3.4** or later. - Ships **RBS signatures** in `sig/`, so typed projects get completion and checking out of the box. - Requests carry **timeouts** and **retry with backoff** for transient failures by default. - Collections are **lazily paginated** `Enumerable`s, with a familiar `order` / `page` / `in_batches` / `find_each` surface. - Records support **pattern matching**, and clients are **immutable** and safe to share between threads. - **Your own resources** — `client.resource(Role)` gives a class you declare everything a modelled one has — and **raw requests** reach the rest of the API, without giving up authentication, retries or the error classes. - A **test kit** (`zammad_api/test`) stands in for a Zammad, so your own tests need no HTTP interception. > **Upgrading from 1.x?** See [Migrating from 1.x](#migrating-from-1x), which lists every > call that changed. > > **Staying on 1.x?** See [Staying on 1.x](#staying-on-1x) for where its code lives and how > to install it. ## Installation 2.0 is a prerelease for now, `2.0.0.alpha1`, and a prerelease has to be asked for: ```ruby gem 'zammad_api', '~> 2.0.0.alpha' ``` Or: ```sh gem install zammad_api --pre ``` `'~> 2.0'` does not match an alpha, and `gem install zammad_api` without `--pre` installs 1.x. ### Staying on 1.x 1.x stays available for a project that is not ready for 2.0, or that runs on a Ruby older than 3.4: 1.x needs Ruby 3.0 or later. Its code lives on the [`1-stable`](https://github.com/zammad/zammad-api-client-ruby/tree/1-stable) branch, and the [README there](https://github.com/zammad/zammad-api-client-ruby/blob/1-stable/README.md) documents the 1.x API. To install it, keep the version below 2: ```ruby gem 'zammad_api', '~> 1.4' ``` Or: ```sh gem install zammad_api -v '~> 1.4' ``` 1.x is in maintenance mode, and will stay there for the foreseeable future: it still gets fixes, while new features go into 2.0 only. Report a 1.x problem in the same [issue tracker](https://github.com/zammad/zammad-api-client-ruby/issues), naming the version, and open a pull request for it against `1-stable`. ## Creating a client ### Access token ```ruby client = ZammadAPI::Client.new( url: 'https://zammad.example.com/', http_token: 'your-access-token' ) ``` ### OAuth2 ```ruby client = ZammadAPI::Client.new( url: 'https://zammad.example.com/', oauth2_token: 'your-oauth2-token' ) ``` ### Username and password ```ruby client = ZammadAPI::Client.new( url: 'https://zammad.example.com/', user: 'user@example.com', password: 'some_pass' ) ``` A client authenticates one way. Passing more than one of these — a token beside a user and password, say — raises `ZammadAPI::ConfigurationError` rather than quietly sending one of them. ### From the environment `from_env` reads `ZAMMAD_URL` and `ZAMMAD_TOKEN` (or `ZAMMAD_USER` and `ZAMMAD_PASSWORD`, or `ZAMMAD_OAUTH2_TOKEN`), so a script needs no configuration of its own. Anything passed in wins over the environment, credentials included — passing `user:` and `password:` replaces a token the environment holds rather than sitting beside it. An environment that itself sets more than one way to authenticate is refused, until an argument says which is meant: ```ruby client = ZammadAPI::Client.from_env client = ZammadAPI::Client.from_env(timeout: 300) ``` ### Options | Option | Default | Description | | ---------------- | ------------------ | ------------------------------------------------------------------ | | `url` | *required* | Base URL. A sub-path such as `https://example.com/zammad/` works; credentials in it are refused. | | `http_token` | `nil` | Zammad access token. | | `oauth2_token` | `nil` | OAuth2 bearer token. | | `user` | `nil` | Login for basic authentication. | | `password` | `nil` | Password for basic authentication. | | `timeout` | `60` | Seconds to wait for a response. | | `open_timeout` | `10` | Seconds to wait for the connection. | | `retries` | `2` | Retry attempts for a `GET` that failed transiently. `0` disables retrying. | | `retry_interval` | `0.5` | Seconds before the first retry; doubles on each attempt. No wait is longer than `timeout`. | | `ssl_verify` | `true` | Set to `false` only against a server with a self-signed certificate. | | `proxy` | `nil` | Proxy URL. | | `user_agent` | `zammad_api-ruby/` | Value of the `User-Agent` header. | | `logger` | discards output | Any `Logger`; the client logs requests and responses at `debug`. | | `adapter` | Faraday's default | Name of the Faraday adapter to use. | | `middleware` | `nil` | Callable that receives the Faraday connection while it is built. | Credentials are never written to the log, and `client.config` redacts them however it is printed — `inspect`, `to_s` or `pp`, which is what a console shows — so a configuration object is safe to include in an error report. Credentials belong in the options above, not in the URL. `https://user:secret@host/` raises `ZammadAPI::ConfigurationError`, because the HTTP stack would send those as basic authentication in place of the token configured beside them. ### Checking the connection ```ruby client.me.email # => "agent@example.com", the account the credentials belong to client.version # => "6.4.0", the Zammad instance's version ``` `client.version` is the version of the Zammad instance; `ZammadAPI::VERSION` is the version of this gem. ### Adapter and middleware The HTTP stack is Faraday's, and these two options are the seam into it — for a persistent-connection adapter, instrumentation, or a cache: ```ruby client = ZammadAPI::Client.new( url: 'https://zammad.example.com/', http_token: 'token', adapter: :net_http_persistent, middleware: ->(connection) { connection.use(MyInstrumentation) } ) ``` The callable runs last, after this gem's own middleware and before the adapter, so it sees requests as the client finished building them and responses before anything else does. Faraday stays an implementation detail either way: an unregistered adapter raises `ZammadAPI::ConfigurationError`, not a Faraday error. Faraday's default adapter, `net_http`, opens and closes a connection around every request, so a walk of N pages is N TCP connections and N TLS handshakes. That is the default because it needs no extra gem; for anything that pages, downloads attachments in a loop, or runs a worker pool, add `faraday-net_http_persistent` to your Gemfile and pass `adapter: :net_http_persistent` as above. Nothing else changes — the option is the whole of it. Middleware that decodes the response body — `connection.response :json` — is the one thing the seam will not take, and says so with a `ZammadAPI::ConfigurationError`. This gem parses JSON itself, and hands the undecoded bytes back as the file from `attachment.download`, so a stack that has already consumed the body leaves nothing faithful to return. ## Available resources `groups`, `organizations`, `tickets`, `ticket_articles`, `ticket_priorities`, `ticket_states`, `users` `client.resource_names` returns the current list. The names are plural because what each one hands back stands for every record of its kind: `client.tickets.each` walks them all, and `client.tickets.find(1)` picks one out. The singular names from 1.x — `client.ticket` and the rest — still work as deprecated aliases; see [Migrating from 1.x](#the-client). Anything not in that list is reachable by [declaring a resource](#resources-this-gem-does-not-model) for it, or with [raw requests](#raw-requests). ### Coverage What each major version of this gem models, set against what Zammad's API serves. A check is a class or a method of the gem's own; an empty box is something 2.0 does not model yet. | | 1.x | 2.0 | | ------------------------------------------------ | :-: | :-: | | **Records** | | | | Tickets | ✅ | ✅ | | Ticket articles | ✅ | ✅ | | Article attachments | ✅ | ✅ | | Ticket states | ✅ | ✅ | | Ticket priorities | ✅ | ✅ | | Users | ✅ | ✅ | | Organizations | ✅ | ✅ | | Groups | ✅ | ✅ | | Text modules | | ⬜ | | **Ticket features** | | | | Tags | | ⬜ | | Links | | ⬜ | | Mentions | | ⬜ | | Time accounting | | ⬜ | | Checklists | | ⬜ | | Shared drafts | | ⬜ | | Merge | | ⬜ | | History | | ⬜ | | **Knowledge base** | | | | Knowledge bases | | ⬜ | | Categories | | ⬜ | | Answers, and publishing them | | ⬜ | | Answer attachments | | ⬜ | | Search | | ⬜ | | **Across resources** | | | | Global search | | ⬜ | | CSV imports (users, organizations, text modules) | | ⬜ | An empty box in the 2.0 column is not out of reach: [declare a resource](#resources-this-gem-does-not-model) for an endpoint that serves records, or use [raw requests](#raw-requests) for one that does not. The empty boxes are also where this gem grows next — [open an issue](https://github.com/zammad/zammad-api-client-ruby/issues/new) for the one you need, so we know what to model first. ### Resources this gem does not model A resource is a class with a path. Declare one for an endpoint that serves records the way the modelled ones do — an index, and a member under its id — and `client.resource` hands you the same thing `client.tickets` is: ```ruby class Role < ZammadAPI::Resources::Base path 'api/v1/roles' end roles = client.resource(Role) roles.each { |role| puts role.name } # paginated, like any other roles.find(2).update(note: 'Reviewed') # change tracking and save roles.create(name: 'Auditor') roles.find_by(name: 'Agent') ``` Say what else is true of the endpoint, where it differs from the defaults: | Declaration | Default | Says | | ------------------ | ------- | -------------------------------------------------------------------- | | `path '…'` | *required* | The index endpoint, relative to the instance URL. | | `searchable true` | `false` | Zammad routes `/search`, so `search` works and `find_by` uses it. | | `max_per_page 100` | `1000` | The largest page the index endpoint serves. | | `sortable false` | `true` | The index endpoint is always served in the same order, so `order` refuses it. | | `belongs_to :role, class_name: 'Role'` | — | A foreign key, read as a record through `record.related.role`. | | `has_many :members, class_name: 'User', path: ->(id) { "…/#{id}" }` | — | A list served whole by an endpoint of its own. | `class_name` is a resource of this gem by its own name, `'User'`, or a class of yours by its full name, `'Acme::Role'`. A subclass of a modelled resource works too, and inherits what its parent declares: `class MyTicket < ZammadAPI::Resources::Ticket`. Use raw requests for an endpoint that is not shaped like that — an action, a report, a setting. ## Raw requests `get`, `post`, `put` and `delete` reach any endpoint of the Zammad API, without giving up authentication, timeouts, retries, credential redaction, JSON decoding or the error classes. Use them for the endpoints that are not a list of records, and for a one-off call to one that is. ```ruby client.get('api/v1/roles').body # => [{id: 1, name: "Admin", ...}, ...] client.post('api/v1/tags/add', query: {object: 'Ticket', o_id: 1, item: 'urgent'}) client.put('api/v1/roles/2', body: {note: 'Updated'}) client.delete('api/v1/tags/remove', query: {object: 'Ticket', o_id: 1, item: 'urgent'}) ``` All four take `headers:`, for an endpoint that needs one: ```ruby client.get('api/v1/tickets/1', headers: {'Accept-Language' => 'de-de'}) ``` Names are case-insensitive, and two spellings of one header are refused rather than merged. `Authorization` and `From` are refused outright: the first is what the client's credentials are for, the second is what `on_behalf_of` sets, and replacing either from a single request would leave the client reporting something it no longer does. Each returns a `ZammadAPI::Response`, so the status and headers stay reachable: ```ruby response = client.get('api/v1/tickets') response.status # => 200 response.headers['content-type'] response.body # decoded JSON, or the raw body for anything else response.raw_body # the bytes as they arrived response.json? # => whether the body was decoded ``` Zammad reports the size of a result in the body rather than in a header, and only where you ask for it: `only_total_count=true` or `with_total_count=true` on a `/search` endpoint, and `full=true` on the index endpoints that render through `model_index_render`. `count` on a search collection uses the first of those. Paths are relative to the instance URL, and a leading slash is ignored, so they can be pasted straight from the Zammad documentation. An absolute URL raises `ArgumentError`: the client's credentials only ever go to the instance it was configured for, so a link taken from a response body has to be reduced to its path first. A non-2xx response raises the same error class it would raise for a modelled resource, and only a `GET` is retried. ## Working with records ### Create ```ruby group = client.groups.new(name: 'Support', note: 'Some note') group.save group.id # => 42 group.name # => "Support" ``` Or in one call: ```ruby group = client.groups.create(name: 'Support', note: 'Some note') ``` ### Fetch ```ruby group = client.groups.find(42) group.name # => "Support" group[:name] # same, and nil rather than an error when it is absent group.fetch(:name) # raises KeyError if the attribute is absent group.key?(:name) # => true group.to_h # every attribute, as a Hash you may modify ``` Or by attribute value: ```ruby client.users.find_by(email: 'someone@example.com') # => the record, or nil client.users.find_by!(email: 'nobody@example.com') # raises NotFoundError client.groups.exists?(42) # => true ``` `find_by` answers with the record if there is one this client can read, and `nil` if there is not, on every resource and for any kind of value. Zammad cannot be asked that directly, because its index endpoints cannot filter — see [Narrowing](#narrowing) — so `find_by` fetches candidates and checks them itself. A record it returns genuinely carries the attributes you asked for, compared exactly and against the value as Zammad stores it, so `find_by(email: 'Someone@Example.com')` does not match a login Zammad downcased. There are two ways it fetches the candidates, and they cost differently: ```ruby client.users.find_by(email: 'someone@example.com', active: true) # searches the email, matches both client.users.find_by(firstname: 'Jane', lastname: 'Doe') # searches "Jane", matches both client.ticket_states.find_by(name: 'open') # no search endpoint: walks the list client.users.find_by(organization_id: 5) # no string to search on: walks the index ``` A search is the cheap way, and is used wherever the resource has a search endpoint and one of the values is a string. The term is one string value, because Zammad matches words: a value of another type would go out as the word it prints as, so `active: true` would look for records containing `"true"`. Every other value is matched against the hits. Everywhere else `find_by` walks the index, a page at a time, until a record matches. That is one request for a list of ticket states. Against every user or ticket on an instance it is a request per page until the match, and the whole index for a miss — the same walk `all.detect { ... }` makes, so give `find_by` a string to search on where there is one. The values are never joined into one term. An instance searching without Elasticsearch matches the term literally, through a SQL `LIKE` over each string column, so `"Jane Doe"` would ask for a single column containing the whole of it and match nobody. What the search can surface is Zammad's business: a value the instance has not indexed, or cannot index, is a record `find_by` will not find. `find_by(...) || create(...)` can therefore still create a duplicate — as writing the search out by hand would. `find_by` reads the hits a page at a time until one matches, so a match usually costs one request and a miss costs one per page of hits. It cannot stop at the first page: Zammad's search sorts by `updated_at`, newest first, rather than by relevance, so where a few hundred records contain the term the one that carries it exactly can be on any page. Zammad records can carry administrator-defined custom attributes, so readers are resolved against the attributes the record arrived with rather than declared ahead of time. A reader for an attribute the record does not carry raises `NoMethodError`, naming what it does carry — a typo is not worth a silent `nil` that flows on into whatever you write with it: ```ruby group.titel # NoMethodError: undefined attribute titel for ... group[:titel] # => nil group.fetch(:titel, nil) # => nil group.key?(:titel) # => false ``` That matters beyond typos: Zammad serves a reduced object where the authenticated user may not see the whole record, so an attribute that exists in Zammad can be missing here. The message says so. Use `[]`, `fetch` with a default, or `key?` wherever an attribute may legitimately be absent. `attributes` and `changes` are deeply frozen, because a record that let you write into them would report a change it had never staged and would not send: ```ruby group.attributes[:name] = 'Support 2' # FrozenError group.name = 'Support 2' # the way to stage a change group.to_h # a deep copy, yours to modify ``` ### Pattern matching Records implement `deconstruct_keys`, so they work with `case/in`: ```ruby case client.tickets.find(1) in {state: 'closed'} nil in {state: String => state, priority: '3 high'} escalate(state) in {group: {name: 'Support'}} notify_support end ``` `Config` and `Response` are `Data` objects, so their members match too: ```ruby case client.config in {http_token: String} :token_auth in {user: String, password: String} warn 'prefer an access token over basic auth' end ``` ### Update ```ruby group = client.groups.find(42) group.name = 'Support 2' group.changed? # => true group.changes # => {name: ["Support", "Support 2"]} group.save # sends only the changed attributes ``` A `save` on a persisted record with nothing staged sends no request at all and returns `true`. Zammad applies an empty update, bumping `updated_at` and `updated_by`, so a no-op save would otherwise rewrite the record's audit trail. Writing back the value a record was loaded with is not a change, so it stages nothing. Writing an attribute the record does not carry always is one, even when the value is `nil`: Zammad reduces the object it serializes for a permission-scoped client, so a key being absent says nothing about what is stored, and `group.note = nil` is a request to store `nil` rather than a write to drop. Or in one call: ```ruby group.update(name: 'Support 2', note: 'Renamed') # assigns, then saves group.assign_attributes(name: 'Support 3') # assigns without saving ``` ### Saving and validation failures `save` returns whether the record was stored, and leaves a rejection in `error`: ```ruby group = client.groups.new(name: '') if group.save puts group.id else warn group.error.server_message # => "Name is required" end ``` Only a rejection of the attributes (HTTP 422) is reported that way. An expired token, a missing record or an unreachable instance still raises, because those are not something the calling code can correct by fixing an attribute. `save!` and `update!` raise on every failure, including validation, which is what you want in a script: ```ruby group.save! # raises ZammadAPI::ValidationError group.update!(name: '') # the same, in one call ``` `client.groups.create(...)` uses `save!`, so it raises rather than handing back a record that looks created but is not. Use `new` plus `save` when you need to branch instead. ### Associations Zammad expands an association into a name under the plain attribute, so those reads are already loaded and free: ```ruby ticket = client.tickets.find(1) ticket.customer # => "customer@example.com" ticket.state # => "open" ticket.group # => "Users" ticket.customer_id # => 7 ``` `related` reaches the whole record behind one of those, which costs a request: ```ruby ticket.related.customer.firstname # => "Nicole" ticket.related.group.note ticket.related.articles # => [TicketArticle, ...] ticket.related.created_by.email client.users.find(7).related.organization ``` A `has_many` reader such as `articles` is the one list here that is read in a single request and comes back as an Array rather than a paginating collection, because the association endpoints Zammad routes serve the whole list: `ticket_articles/by_ticket` renders every article of the ticket and takes no paging parameter. A ticket's articles are also reachable without `related`, and `add_article` writes one: ```ruby ticket.articles # the same list ticket.add_article(body: 'Reset link sent.', type: 'note') # => the created TicketArticle ``` The readers live under `related` rather than on the record so that `ticket.customer` keeps returning the name it always did — an attribute read that silently became an HTTP request would be a poor trade. `belongs_to` targets are memoized, and `reload` or a save drops the memo; `has_many` lists are fetched each call, so an article added in between shows up. `Ticket.associations` lists what a resource declares. ### Comparing and serializing A record is the Zammad record it came from, not the object that happens to hold it, so two records of the same kind carrying the same id are equal. That makes `uniq`, `Set`, `include?` and records-as-Hash-keys behave: ```ruby client.tickets.find(1) == client.tickets.find(1) # => true [client.tickets.find(1), client.tickets.find(1)].uniq.size # => 1 Set[client.tickets.find(1), client.tickets.find(1)].size # => 1 seen = { client.tickets.find(1) => :handled } seen[client.tickets.find(1)] # => :handled ``` A record with no id is equal only to itself, because two unsaved records are two records waiting to be created however alike their attributes are. One consequence: a record's first save assigns its id and so changes its hash, and a record used as a Hash key before that save has to be rehashed after it. `to_json` renders the attributes, so a record can be cached, queued or logged as it stands, and nests inside a structure being generated: ```ruby client.groups.find(1).to_json # => "{\"id\":1,\"name\":\"Support\"}" JSON.generate(group: client.groups.find(1)) ``` `as_json` returns the same attributes as a Hash, for ActiveSupport and any encoder that follows its convention. ### Reload and destroy ```ruby group.reload # re-reads from Zammad, discarding unsaved changes group.destroy # => true group.destroyed? # => true group.persisted? # => false, so this is not the inverse of new_record? group.save # raises: the record is gone, and a PUT would only 404 group.update(...) # raises too, and stages nothing, so the record stays unchanged group.name = 'X' # raises as well: a destroyed record reads as it last was in Zammad client.groups.destroy(42) # delete by id, without fetching first ``` ## Collections `all`, `order` and `search` return a lazily paginated `ZammadAPI::Collection`. No request is made until you iterate, and pages are fetched as needed. A resource proxy is itself `Enumerable` over `all`, so `.all` is optional: ```ruby client.tickets.each { |ticket| puts ticket.title } client.tickets.first(5) client.tickets.pluck(:title) client.tickets.find_each(batch_size: 50) { |ticket| archive(ticket) } ``` `find` keeps its own meaning there — `client.tickets.find(1)` is a lookup by id, not `Enumerable#find`. Use `detect` for the block form. ```ruby # Walks every page automatically. client.tickets.all.each do |ticket| puts ticket.title end # Stops after the first page, because Enumerable stops consuming. first_five = client.tickets.all.first(5) # Lazy chains work as expected. client.tickets.all.lazy.select { |t| t.state == 'open' }.first(10) # One array of records per request, e.g. for a bulk import. client.tickets.all.in_batches(of: 50) do |tickets| import(tickets) end # Record by record, with the page size set inline. client.tickets.all.find_each(batch_size: 50) do |ticket| archive(ticket) end ``` ### Sorting `order` sorts on the server: ```ruby client.groups.order(:name) # ascending client.organizations.order(name: :desc) client.groups.order(:active, name: :desc) # by active, then by name descending client.tickets.search('state.name:open').order(created_at: :desc) ``` An attribute on its own sorts ascending and a keyword says which way one runs, as in ActiveRecord. A second `order` sorts within the first, so `order(:active).order(name: :desc)` is the third line above. Not every endpoint sorts. `/api/v1/tickets` and `/api/v1/users` are always served in id order — their controllers hardcode it and drop `sort_by` along with everything else they do not read — so `order` on those raises `ArgumentError` rather than handing back records it would be calling sorted. A search sorts for every resource that can be searched: ```ruby client.tickets.order(:title) # ArgumentError: api/v1/tickets is always served in the same order and ignores sort_by, # so order would hand back the records as they were. A search does sort: ... client.tickets.search('state.name:open').order(:title) ``` ### Narrowing **Zammad's index endpoints do not filter.** `ApplicationController#model_index_render` sorts and pages and drops every other parameter. Filtering by an attribute value exists only on the `/search` endpoints, which is why a collection has no `where`: there is nothing an index endpoint would do with what it was given. Narrow by a value with [`find_by`](#fetch) for one record, or `search` for many: ```ruby client.users.find_by(email: 'someone@example.com') client.tickets.search('state.name:open').first(10) ``` `search` also takes the other things a search endpoint narrows by, as keywords — `condition:`, `ids:`, `role_ids:`, `group_ids:` and `permissions:`: ```ruby client.users.search('smith', role_ids: [2]) client.users.search('smith', group_ids: [1], permissions: ['ticket.agent']) client.tickets.search('printer', condition: {'ticket.state_id' => {operator: 'is', value: [1, 2]}}) ``` Any other keyword raises `ArgumentError`. Zammad drops a parameter it does not know, so `search('smith', active: true)` would come back unnarrowed with nothing to say so; an attribute value goes in the term, a sort in `order`, and paging in `page`, `in_batches` or `find_each`. A `nil` value raises too: there is no query string that means "this field is null". Zammad routes a search endpoint per model, not for every model. `users`, `organizations`, `tickets` and `groups` have one; `ticket_states`, `ticket_priorities` and `ticket_articles` do not, and `search` on those raises `ZammadAPI::Error` rather than reaching a 404 that would read as a missing record. `find_by` works on them all the same, by walking the list: ```ruby client.ticket_states.find_by(name: 'open') client.ticket_priorities.select { it.active } ``` ### Search ```ruby client.organizations.search('zammad').each do |organization| puts organization.name end ``` ### Explicit pages ```ruby tickets = client.tickets.all tickets.page(2) # page 2 at the size the endpoint serves tickets.page(2, per_page: 10) # records 11 to 20 ``` Collections are immutable: `order` and `page` return a new collection and leave the original untouched. ### Page size A request fetches as many records as the endpoint will serve — 100 for `/api/v1/tickets`, 200 for a search, 1000 for the other index endpoints — so a walk spends as few round trips as it can. Three calls take another size, each for its own kind of work: ```ruby client.tickets.all.find_each(batch_size: 50) { |ticket| archive(ticket) } # walking client.tickets.all.in_batches(of: 50) { |tickets| import(tickets) } # batching client.tickets.all.page(2, per_page: 100) # one page ``` `find_each` without a block is an Enumerator, so it is also how you read at a chosen page size: `client.tickets.all.find_each(batch_size: 50).first(7)`. `page` and a batch size are two ways of naming the same thing, so combining them raises: `page(3, per_page: 50)` already says which records the collection holds, and re-sizing it would quietly hand back different ones. Size the page itself, or slice with `each_slice`. That cap is also the ceiling. `find_each` and `in_batches` are reduced to it: a batch size is how much to fetch at a time, so a smaller one costs more requests and still yields every record. `page` raises instead, because a page size also says *which* records you get — `page(3, per_page: 500)` reduced to 100 hands back records 201 to 300 rather than 1001 to 1500. So `in_batches(of: 500)` over tickets yields batches of 100, while `page(3, per_page: 500)` over tickets is refused. A walk learns the size the endpoint actually serves from the first page rather than trusting that cap, so an instance that pages smaller than expected is walked to the end rather than truncated at the first short page. That keeps a walk complete: a page size the server silently shrank would otherwise end the iteration at the first page. `first` and `take` size their own request rather than taking records off the front of one sized for walking, so the cheap-looking call is cheap: ```ruby client.tickets.all.first # one request, for one record client.tickets.all.first(5) # one request, for five client.tickets.all.take(5) # the same, and the same cost ``` They size the request, not the collection, so they still read on where a page comes back shorter than it was asked for — `first(5)` answers with five records if five exist, however the endpoint chooses to page them. A collection `page` already limited keeps its own size, since that size says which records it holds. ### Reading single attributes ```ruby client.users.all.pluck(:email) # => ["a@example.com", ...] client.tickets.all.pluck(:id, :title) # => [[1, "Help"], ...] ``` Zammad cannot be asked for a subset of the fields, so this shapes the result rather than shrinking the request. ### Counting `count` is one request on a search, which Zammad can answer without serving the records. Every other endpoint has to be walked, because an index endpoint offers nothing cheaper: `model_index_render` reads `sort_by`, `order_by` and the paging and drops every other parameter, so it has no answer for `only_total_count` and no total to report. ```ruby client.tickets.search('state.name:open').count # one request client.tickets.all.count # one request per page ``` `size` and `length` are `count`, and cost the same. `empty?` and `first` ask for a single record rather than a page: ```ruby client.tickets.search('state.name:merged').empty? # one request, for one record client.groups.all.size # => 12, having walked ``` A block or an argument is `Enumerable#count` counting matches, and walks either way: ```ruby client.tickets.all.count { it.state == 'open' } # walks every page ``` Nothing is cached, so every traversal of a collection fetches again. ### `find` is a lookup, not a filter `find` on a resource takes an id. On a collection it is `Enumerable#find`, which takes a block — and its argument is an ifnone callable, not an id, so passing one is refused rather than answered with an Enumerator and no request: ```ruby client.tickets.find(1) # the lookup by id client.tickets.all.detect { ... } # the block form client.tickets.all.find { ... } # the same client.tickets.all.find(1) # ArgumentError, naming both of the above ``` ## Deriving clients A client is immutable. `with` returns a new one with some options changed, re-validating them and carrying over any `on_behalf_of` scope: ```ruby bulk = client.with(timeout: 300, retries: 5) bulk.tickets.all.each { |ticket| archive(ticket) } ``` Naming credentials replaces the ones the client has, whichever kind they were, so `client.with(oauth2_token: '…')` on a client built with an access token authenticates with the OAuth2 token alone. Because nothing is mutated after construction, one client — and any client derived from it — is safe to use from several threads at once. ## Acting on behalf of another user As described in the [Zammad API documentation](https://docs.zammad.org/en/latest/api/intro.html#actions-on-behalf-of-other-users), actions can be performed on behalf of another user. `on_behalf_of` returns a **new** client, so the original is unaffected and both are safe to use concurrently. ```ruby support = client.on_behalf_of('agent@example.com') support.tickets.create(title: 'Help', group: 'Users', customer_id: 1) ``` Or scoped to a block: ```ruby client.on_behalf_of('agent@example.com') do |scoped| scoped.tickets.find(1) end ``` The identifier can be a login, an email address or a user id. This sends the standard HTTP `From` header and requires Zammad 5.0 or later. ## Error handling Every error descends from `ZammadAPI::Error`. ```text ZammadAPI::Error ├── ZammadAPI::ConfigurationError invalid client options ├── ZammadAPI::UnknownResourceError no such resource, e.g. client.unicorn ├── ZammadAPI::ParseError unexpected response shape ├── ZammadAPI::PaginationError endpoint ignored the page parameter ├── ZammadAPI::TransportError │ ├── ZammadAPI::ConnectionError unreachable host or TLS failure │ └── ZammadAPI::TimeoutError exceeded timeout or open_timeout └── ZammadAPI::ResponseError carries the HTTP response ├── ZammadAPI::ClientError 4xx │ ├── ZammadAPI::AuthenticationError 401 │ ├── ZammadAPI::AuthorizationError 403 │ ├── ZammadAPI::NotFoundError 404 │ ├── ZammadAPI::ValidationError 422 │ └── ZammadAPI::RateLimitError 429 └── ZammadAPI::ServerError 5xx ``` ```ruby begin client.tickets.find(1) rescue ZammadAPI::NotFoundError nil rescue ZammadAPI::RateLimitError => e # The client already waited and retried, so this limit outlasted that. reschedule(in: e.retry_after || 60) rescue ZammadAPI::ResponseError => e warn "#{e.status}: #{e.server_message}" warn e.body.inspect end ``` `ResponseError` exposes `status`, `body`, `headers`, `server_message`, `operation` and `resource_class`. A proxy that returns an HTML error page instead of JSON produces a `ServerError` describing the status, not a JSON parse failure. ### Timeouts and retries A `GET` is retried on connection failures, timeouts and the transient statuses 429, 500, 502, 503 and 504, with exponential backoff. A `Retry-After` header on one of those responses is honoured: the client waits as long as the server asked before the next attempt, up to `timeout` seconds. A longer one is not waited out. The request fails at once with the error for its status, and `RateLimitError#retry_after` carries the figure, so a job can reschedule itself rather than hold a thread for however long a maintenance page suggests. A write is never retried. `POST` would create a second record, and `PUT` and `DELETE` are not safe to repeat against Zammad either, whatever HTTP says about them: a ticket update carrying an `article` adds that article — and sends its e-mail — once per delivery, and a `DELETE` repeated after a lost answer comes back as a 404 for a record that was just deleted. So a write that fails raises, and the code that knows what the request carried decides whether to send it again: ```ruby begin ticket.update!(state: 'closed') rescue ZammadAPI::TransportError, ZammadAPI::ServerError ticket.reload # did it arrive? retry if ticket.state != 'closed' end ``` ```ruby client = ZammadAPI::Client.new( url: 'https://zammad.example.com/', http_token: 'token', timeout: 10, retries: 5 ) ``` ## Logging ```ruby client = ZammadAPI::Client.new( url: 'https://zammad.example.com/', http_token: 'token', logger: Logger.new($stdout) ) ``` Requests, response statuses and durations are logged at `debug` level. Payload keys that look like credentials (`password`, `token`, `secret`, ...) are redacted. ## Testing code that uses this client `zammad_api/test` ships a stand-in Zammad, so your own tests need no HTTP interception: ```ruby require 'zammad_api/test' RSpec.describe TicketCloser do let(:zammad) { ZammadAPI::Test.new } it 'closes the ticket' do zammad.stub(:get, 'api/v1/tickets/1', body: {id: 1, title: 'Help', state: 'open'}) zammad.stub(:put, 'api/v1/tickets/1', body: {id: 1, state: 'closed'}) described_class.new(zammad.client).close(1) expect(zammad.requests.last.verb).to eq(:put) expect(zammad.requests.last.body).to eq({state: 'closed'}) end end ``` `zammad.client` is a real `ZammadAPI::Client`, so responses come back through the same decoding, error mapping and record building as real ones — a stub with `status: 404` raises `NotFoundError`, and one with `status: 422` makes `save` return `false`. | Method | What it does | | ------ | ------------ | | `stub(verb, path, status:, body:, headers:, query:)` | Declares a response. Stubbing the same endpoint twice with the same scope describes a sequence; the last stub answers every later request. `query:` matches a subset, so it need not repeat `expand`, `page` or `per_page`. | | `client` | A client wired to this stand-in. | | `requests` | Every request made, oldest first, as `verb` / `path` / `query` / `body` / `headers` / `on_behalf_of`. | | `reset` | Forgets the stubs and the recorded requests. | A `Hash` or `Array` body is served as JSON and gets `content-type: application/json` unless `headers:` says otherwise — and it is that header, not the Ruby type, that decides whether the body comes back decoded, exactly as it does on the wire. So a `Hash` stubbed as `text/html` comes back as the raw string and reading a record from it raises `ParseError`, which is what Zammad would do. Header names and values are stringified and names downcased, the way a real `Response` carries them; a value that is not text, or two spellings of one header name, are refused where the stub is written rather than turned into something the wire could not send. `query` and `headers` are recorded through the real transport's own stringification, so they hold what a request would have carried rather than the raw Ruby values — and a header the wire would refuse is refused here too. `headers` names only what the call asked for; the ones the client sets from its configuration are not in it, and an `on_behalf_of` scope has a field of its own. A request that was not stubbed raises `ZammadAPI::Test::UnstubbedRequestError`, listing what is stubbed, rather than answering with something empty. It is deliberately not a `ZammadAPI::Error`: a forgotten stub means the test is wrong, not that Zammad refused something, so a `rescue ZammadAPI::Error` in the code under test lets it through instead of reporting it as an API failure. ### Stubbing a list endpoint One stub is enough for a collection that fits in a page. The records it holds are one page of them, so a request for any later page is answered the way an endpoint out of records would answer it: ```ruby zammad.stub(:get, 'api/v1/groups', body: [{id: 1, name: 'Users'}, {id: 2, name: 'Sales'}]) client.groups.all.map(&:name) # => ["Users", "Sales"] ``` Stub the endpoint again to describe a list that changes between reads. A read is one step of the sequence however many pages it asks for, so each read gets the next stub and the last one answers every read after it: ```ruby zammad.stub(:get, 'api/v1/groups', body: [{id: 1, name: 'Users'}]) zammad.stub(:get, 'api/v1/groups', body: [{id: 1, name: 'Users'}, {id: 2, name: 'Sales'}]) client.groups.all.count # => 1 client.groups.all.count # => 2 ``` Name a `page` to say what each one holds, and the stub is served exactly as written: ```ruby zammad.stub(:get, 'api/v1/groups', body: first_hundred, query: {page: 1}) zammad.stub(:get, 'api/v1/groups', body: [{id: 101}], query: {page: 2}) ``` ### Scopes that overlap A stub naming `query:` answers ahead of one that does not, so a scoped stub and a catch-all are two separate answers rather than a sequence: ```ruby zammad.stub(:get, 'api/v1/tickets/search', body: {total_count: 42}, query: {only_total_count: true}) zammad.stub(:get, 'api/v1/tickets/search', body: [{id: 1}]) client.tickets.search('urgent').count # => 42, however often it is asked ``` Two stubs whose scopes match a request equally well raise `ZammadAPI::Test::AmbiguousStubError` rather than one of them being picked: `count` sends the search term and `only_total_count` together, so a records stub scoped to `{query: 'urgent'}` matches it just as well as the count stub does. Name what tells the requests apart — here, the search term on the count stub too — or leave the more general one unscoped as above. ## Type signatures RBS signatures ship in `sig/` and are checked in CI with [Steep](https://github.com/soutaro/steep). Add the gem to your own RBS collection to type-check calls into this client. Records are typed, not only the client. `client.tickets` is a `ResourceProxy[Resources::Ticket]`, so `find`, `first`, `find_by`, the block of `each` and a search all hand you a `Ticket`, and each resource declares the attributes every supported Zammad serves for it: ```ruby ticket = client.tickets.find(1) ticket.title # String ticket.organization_id # Integer? ticket.related.customer&.email # String? ticket.titel # a type error, where it used to be untyped ``` Three things are deliberately not declared, and each has a way through: - **Attributes an administrator added.** Read one with `ticket[:escalation_reason]`, or declare it in your own signatures by reopening the class: ```rbs class ZammadAPI::Resources::Ticket attr_accessor escalation_reason: String? end ``` - **Columns only newer Zammad versions have**, which an older instance does not serve. `record[:name]` reads those too. - **The name `expand` adds for an association that may be empty**, such as `organization` on a ticket or a user. Zammad leaves the key out rather than sending `null`, so a reader would raise rather than answer `nil`; `ticket[:organization]` is `nil` in that case, and `ticket.organization_id` is always there. A proxy for [a resource of your own](#resources-this-gem-does-not-model) is untyped until you say what it holds, because a signature cannot carry a class into its own return type: ```ruby roles = client.resource(Role) #: ZammadAPI::ResourceProxy[Role] ``` The types describe a record Zammad served. One built with `new` carries only what it was given until it is saved, and reading anything else from it raises `NoMethodError`, whatever the signature says the type would be. ## Examples Runnable scripts covering pagination, pattern matching, acting on behalf of a user, attachments, error handling and threaded use live in [`examples/`](examples/README.md). ## Development ```sh bin/setup # or: bundle install bundle exec rake # unit specs, RuboCop and Steep ``` | Task | What it does | | ------------------------ | ----------------------------------------------------- | | `rake spec:unit` | Unit specs; stubbed, no Zammad needed | | `rake spec:integration` | Integration specs against a live Zammad | | `rake check_connection` | Drives a live Zammad end to end and prints a transcript | | `rake rubocop` | Style checks | | `rake steep` | Type-check `lib/` against `sig/`, and `spec/typed/` the way a caller is checked | Set `COVERAGE=true` to produce a coverage report in `coverage/`. ### Testing against a live Zammad The integration specs and `check_connection` need a reachable Zammad instance and **will create and delete records**, so point them at something disposable: ```sh export TEST_URL=http://localhost:3000/ export TEST_USER=admin@example.com export TEST_PASSWORD=test bundle exec rake check_connection # one linear pass, readable transcript bundle exec rake spec:integration # the full spec suite ``` `check_connection` walks the documented workflows in order — create, find, update, reload, pattern match, paginate, search, ticket with articles, attachment download, acting on behalf of a user, and each error class — printing `ok` or `FAIL` per step and cleaning up after itself. It stops early if a precondition fails, so a broken instance produces one clear line rather than a cascade. CI runs both against a Zammad booted from source: the `integration` job clones Zammad, starts it, waits for it to answer, runs `check_connection` as a fast preflight, then runs the integration specs. Trigger it by hand from the Actions tab (`workflow_dispatch`) to test against a specific Zammad ref. ## Migrating from 1.x Version 2.0 fixes long-standing behaviour that could not change without breaking compatibility. Most calling code needs no edits, and almost everything that does raises at the call site. Start with the handful of changes that do not. If this is not the time to move, [1.x stays available](#staying-on-1x). ### Changes that do not announce themselves - **`record.attributes = {...}`** was a writer in 1.x. It is now an ordinary attribute assignment, so it stages a change named `attributes` and `save` sends it to Zammad: ```ruby group.attributes = {name: 'Support'} group.changes # => {attributes: [nil, {name: "Support"}]} ``` Use `assign_attributes(name: 'Support')`, or `update` to assign and save. - **`rescue Faraday::ConnectionFailed`** (and any other Faraday exception) no longer matches. Transport failures are wrapped, so rescue `ZammadAPI::ConnectionError`, `ZammadAPI::TimeoutError`, or `ZammadAPI::TransportError` for both. ### The client | 1.x | 2.0 | Why | | -------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------- | | `Client.new(config_hash)` | `Client.new(**config_hash)` | Options are keyword arguments now, so a Hash has to be splatted | | an unknown option was ignored | raises `ArgumentError: unknown keyword` | A typo'd option used to be dropped without a word | | `logger: true` | `logger: Logger.new($stderr)` | The flag became an object, so you choose the device and level. Anything that answers `debug` is accepted; `true` raises `ConfigurationError` | | `client.ticket`, `client.user`, … | `client.tickets`, `client.users`, … | A resource is `Enumerable` over every record now, so `client.ticket.each` read as if it acted on one ticket. The singular names still work and warn in Ruby's `deprecated` category; run with `RUBYOPT=-W:deprecated` to find them. They go in 3.0 | | `client.on_behalf_of = 'login'` | `client.on_behalf_of('login')` → new client | The setter mutated the client and leaked across threads | | `client.perform_on_behalf_of('x') { }` | `client.on_behalf_of('x') { \|scoped\| ... }` | The old block form left the header set if the block raised | | `ZammadAPI::Resources::Role < Base` reached by `client.role` | `client.resource(Role)`, for a `Role < ZammadAPI::Resources::Base` of your own | The named readers are a fixed list, and a class is handed over rather than looked up by name. [Raw requests](#raw-requests) reach whatever is not a resource | ### Collections | 1.x | 2.0 | Why | | ---------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- | | `collection.each` stopped after one page | `each` walks every page | Iterating truncated silently at the page size: 100 for `all`, 10 for `search` | | `collection.page(1, 3) { \|r\| ... }` | `collection.page(1, per_page: 3).each { ... }` | `page` now returns a collection instead of mutating and yielding | | `collection.page_next` / `page_prev` | `collection.page(n)` or `in_batches` | Removed; they mutated shared state | | `collection.each_page { ... }` | `collection.in_batches { ... }` | Ruby already has a name for this | | `collection[3]` | `collection.page(4, per_page: 1).first` | An index that costs a request, and that ignored `page`, was a trap | | `collection.find(1)` | `client.x.find(1)`, or `collection.detect { ... }` | On a collection `find` is `Enumerable#find`, whose argument is an ifnone callable — so an id answered with an Enumerator and made no request. It raises now | | `client.x.all(per_page: 50)` | `client.x.all.page(1, per_page: 50)`, `find_each(batch_size: 50)` | `all` accepted the argument and discarded it; page size belongs to the call that reads | | `client.x.all(active: true)` | `client.x.search(...)`, or `client.x.all.detect { ... }` | The filter never reached the request in 1.x, and could not have: Zammad's index endpoints do not filter, so 2.0 has no call that pretends to. `find_by(active: true)` answers with the first such record, by walking the index where it has no string to search on | | `client.x.search(query: 'zammad')` | `client.x.search('zammad')` | The search term is the argument, not a keyword | | `client.x.search(query: 'z', page: 2, per_page: 50)` | `client.x.search('z').page(2, per_page: 50)` | Search did honour those two; paging is the collection's job now | ### Records | 1.x | 2.0 | Why | | ----------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | | `record.save` raised on a rejection | `save` → `false` with `record.error`; `save!` raises | Branching on a rejected attribute needed a begin/rescue | | `record.attributes[:x] = 1` | `record.x = 1`, or `record.to_h` for a copy | Writing through the reader staged no change, so `save` never sent it | | `record.attributes = {...}` | `record.assign_attributes(...)` / `record.update(...)` | The writer is gone, and the name now stages an attribute of its own | | `record.id = 5` | `client.x.find(5)` | The id addresses the record, so a staged one deleted or updated a different record than it reported | | `record.new_instance` | `record.new_record?` / `record.persisted?` | Internal flag is no longer public; the old name raises `NoMethodError`, naming the attributes the record does carry | | `resource.url` (instance) | `Resource.resource_path` (class) | Clashed with an attribute named `url` | | `record.unknown_attribute` → `nil` | raises `NoMethodError`; use `record[:x]`, `fetch(:x, nil)` or `key?(:x)` | A typo read as `nil` and flowed on into whatever was written with it. Zammad also serves a reduced object where the user may not see the whole record, and that is worth being told about | | `client.x.new(id: 5)` | `client.x.find(5)` | The constructor was the one door that did not refuse a staged id — and the only one whose value reached Zammad, since a new record is sent in full | | `client.users.find(ticket.customer_id)` | `ticket.related.customer` | Following a foreign key needed the client threaded through | | `ticket.article(body: '…')` | `ticket.add_article(body: '…')` | A noun that sends a `POST`, one letter away from `ticket.articles`, which only reads. `article` still works and warns in Ruby's `deprecated` category; it goes in 3.0 | ### Errors | 1.x | 2.0 | Why | | ------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- | | `ZammadAPI::Error < RuntimeError` | `ZammadAPI::Error < StandardError` | `RuntimeError` is for `raise "string"` | | `ZammadAPI::ResourceNotFoundError` | `ZammadAPI::UnknownResourceError` | Renamed so it is not confused with a 404, now `NotFoundError` | | `ClientError` for every 4xx | `AuthenticationError`, `NotFoundError`, `ValidationError`, … | All still `ClientError`, so existing rescues keep working | | a Faraday exception for a dead host | `ZammadAPI::ConnectionError` / `TimeoutError` | Every failure this gem can raise descends from `ZammadAPI::Error` | | `error.response` was a Faraday object | `ZammadAPI::Response` with `status`/`body`/`headers` | Faraday is no longer part of the public surface | | `error.body` was a raw JSON string | decoded Hash, or the raw body for non-JSON | Saves every caller from parsing it again | ### Removed constants, and the Ruby version | 1.x | 2.0 | Why | | ------------------------------------------------ | -------------------------- | ------------------------------------------------------------ | | `ZammadAPI::ListBase` / `ListAll` / `ListSearch` | `ZammadAPI::Collection` | One class instead of three | | `ZammadAPI::Dispatcher` | `ZammadAPI::ResourceProxy` | Renamed; `client.` hands you one | | `ZammadAPI::Log`, `ZammadAPI::JsonHelper` | removed | Pass any `Logger` as `logger:`; decoding moved into the transport | | Ruby >= 3.0 | Ruby >= 3.4 | 3.0 through 3.3 are end-of-life or nearly so | ### Defaults 1.x did not have A collection fetches as many records per request as the endpoint serves — 1000 on the index endpoints, 100 on tickets, 200 on a search — rather than a fixed 100, so a walk spends roughly a tenth of the round trips. `page(n)` without `per_page:` is a page of that size, so pin it with `page(n, per_page: 100)` if a persisted page number has to keep meaning what it did. A request now times out after 60 seconds (10 to connect) where 1.x waited as long as the server took, so a call that used to hang raises `ZammadAPI::TimeoutError`. A `GET` is retried twice with exponential backoff on connection failures, timeouts and the transient statuses, which means a genuinely broken endpoint takes a little longer to report itself; a `POST`, `PUT` or `DELETE` is never retried. Both are options — see [Timeouts and retries](#timeouts-and-retries). The `User-Agent` is now `zammad_api-ruby/` rather than `Zammad API Ruby`. ### What did not change `find`, `all`, `create` and `new` on a resource, `record.destroy`, attribute readers and writers, `ticket.articles` and `attachment.download`. The resources themselves are reached by their plural names now — `client.tickets` — and adding an article is `ticket.add_article`; the old names still answer, with a deprecation warning. `record.save`, `record.changes` and `record.attributes` still exist and still mean what they meant; the tables above only change how they behave at the edges. ## License Dual licensed under the [AGPL-3.0-only](LICENSE.AGPL.txt) or [MIT](LICENSE.MIT.txt) licenses. See [LICENSE.md](LICENSE.md).