Set up the Zammad integration

The Zammad integration connects octoja to your Zammad instance, so that monitoring alarms turn into tickets your team already works in. Setting it up takes three things: the connection itself, the ticket settings with a ticket group, and an alert rule that routes alarms to Zammad.

What the integration does

Once connected and configured, the integration does two separate jobs:

• Creates a ticket from an alarm — when a monitoring check raises an alarm and an alert rule routes it to the Zammad channel, octoja creates a ticket in the selected Ticket group. If the device's customer is matched to a Zammad organization, the ticket is filed against that organization.
• Handles the recovery — when the check recovers, octoja adds an internal note to the ticket and, in the same step, sets it to the Recovery state.

Everything runs outbound, from octoja to Zammad. octoja only ever touches the tickets it created itself, it never pulls existing Zammad tickets into octoja, and it never deletes anything in Zammad. Apart from tickets, the only things octoja creates or changes in Zammad are the requester user and that user's membership in your matched organizations (see Step 3).

Connecting on its own creates nothing. A connected integration only produces tickets once a Ticket group is saved (Step 4) and an alert rule points at the Zammad channel (Step 5). These are the two steps people most often miss.

Prerequisites

• The Integration Management permission in octoja. Permissions are assigned under Administration → Groups.
• The Customer Management permission as well, if you also want to import customers from Zammad.
• A Zammad instance reachable from your octoja instance, self-hosted or hosted by Zammad. octoja accepts https:// and http:// addresses; use HTTPS, because the API token is sent with every request. For a firewall or IP allowlist in front of your Zammad API, see IP addresses and firewall rules.
• A Zammad API token with the ticket.agent and admin.group permissions. If tickets should also be filed against the matched organizations, the token must additionally be allowed to edit Zammad users (see Step 3).
• An email address for the requester of the alert tickets, ideally a mailbox of your own team.
• At least one active group in Zammad for the alert tickets to land in.
• A monitoring check that already runs, so there is an alarm to turn into a ticket.

Step 1 — Gather your Zammad credentials

Collect three values that you enter in octoja in the next step:

• Zammad URL: the address you open Zammad at in your browser, for example https://tickets.example.com. If you leave out https://, octoja adds it; a trailing slash is removed.
• API token: Create it in Zammad in your profile under Token Access and grant the ticket.agent and admin.group permissions. Create a dedicated token for octoja so you can revoke it on its own if needed. The setup dialog in octoja names the path as well.
• Requester email: Every alert ticket is attributed to this Zammad user, not to your customer's contact. If no Zammad user with this address exists yet, Zammad creates one with the first ticket. Use an address of your own team, for example rmm@example.com, so notifications to the requester do not reach your customers.

Step 2 — Connect octoja to Zammad

1. In octoja, go to Administration → Integrations and find the Zammad card.
2. Click Set up. The Connect Zammad dialog opens.
3. Fill in the three fields:

4. Click Test connection. octoja uses the token to read the group list from Zammad and reports Connection successful. or the reason the attempt failed. If the token lacks admin.group, this test already fails. The test checks only the URL and token, not the email address.
5. Click Connect. octoja checks the connection again, reads your instance's priorities and states to prefill Step 4, and opens the Zammad integration page on its Configuration tab.

Connect rejects invalid credentials with "Could not connect to Zammad" and the reason; nothing is saved in that case.

To change the token, disconnect first. While a connection exists, octoja rejects connecting again with a message that the Zammad integration is already connected. Disconnect as described under Disconnect Zammad, then connect with the new token.

Step 3 — Match customers to Zammad organizations

Matching is optional. It tells octoja which Zammad organization belongs to which octoja customer, so tickets are filed against the right client. If your Zammad instance does not use organizations, skip this step.

1. On the Configuration tab, find the Customer matching section, which counts how many of your customers are matched.
2. Click Match customers. The Match customers to Zammad organizations dialog opens.
3. Pick the Zammad organization for each octoja customer and click Save matches.

The picker lists the active organizations of your Zammad instance. The table's … menu holds two shortcuts: Auto-match by name pairs up every customer whose name lines up with an organization and leaves the ambiguous cases to you, and Show only unmatched hides the rows you have already done. Each octoja customer can be matched to exactly one organization, and the other way round.

An unmatched customer does not stop a ticket. The ticket is still created in the ticket group, only without an organization. The customer name is in the ticket description either way.

What octoja changes in Zammad for this: Zammad keeps a ticket's organization only when the requester belongs to that organization. On the first ticket for a matched organization, octoja therefore adds the requester to that organization as an additional organization, then sets the organization on the ticket. Later tickets for the same organization need nothing more. If the token may not edit users, the ticket stays without an organization; the delivery still counts as successful, and the response of the entry on the History tab contains organization not applied.

Step 4 — Choose the ticket settings

The Ticket settings section decides where a ticket lands and what it looks like. The dropdowns are read live from Zammad every time the page opens.

If octoja finds no suitable priority or closed state while connecting, that dropdown stays empty. Tickets then get Zammad's default priority, and a recovery only adds the note without changing the state.

Without a ticket group, no ticket is created. octoja skips the alarm and records a Create ticket entry on the History tab with the response no default Zammad group configured. Such an entry does not count as a failure and is not retried.

Settings are not saved automatically. Every change stays local until you click Save in the page header or press Ctrl+S. The button only exists on the Configuration tab.

Step 5 — Route alerts to the Zammad channel

This is the step that makes tickets appear. No alarm reaches Zammad until an alert rule sends it there.

1. Open the config package that contains the check you want tickets for, go to its Checks tab and open the check. If the check sits on a single device rather than in a package, open that device and use its own Checks tab.
2. Switch to the check's Alert tab and pick or create an alert configuration.
3. In that configuration, add the channel Zammad ticket.
4. Set the rule for the channel — the share of recent results and the minimum severity that has to be reached — and save the check.

Zammad is a single, tenant-wide channel: once you pick Zammad ticket there is nothing else to select. The channel only appears in the picker once Zammad is connected — if Zammad ticket is missing from the list, finish Step 2 first. A paused integration keeps the channel selectable, but a rule saved against it creates no tickets. When tickets fail to appear, check the integration status as well.

For the full walkthrough of alert configurations, rules and schedules, see Set up alerts for a check.

A ticket octoja opens is titled [octoja] <check> <status> – <device>. Its description names the check, the device, the reported status, how many of the last runs failed and the customer name, followed by the check's output and a link to the device's check page in octoja. The title and description are always written in English.

What happens when a check recovers

Unlike some other ticketing systems, octoja does not check whether someone in Zammad is already working on the ticket: when a Recovery state is set, the ticket moves to that state on every recovery. The note is internal and always written in English.

Only tickets octoja created for that alarm are touched. If the original ticket never came into existence — because no ticket group was set, for instance — there is nothing to comment on, and the recovery passes without a trace in Zammad.

Import customers from Zammad

If your customers do not exist in octoja yet, you can seed them from your Zammad organizations. This lives on the Customers page, not on the integration page.

1. Open Customers and choose Import from ticketing system. The Import customers from Zammad dialog lists the active organizations.
2. Select the organizations you want and click the import button, for example Import 3 organizations.

Each selected organization becomes an octoja customer, and the customer match from Step 3 is created for you. Organizations that are already matched are marked Imported and skipped. Importing needs the Customer Management permission in addition to Integration Management.

The menu item opens the first connected ticketing system in a fixed order: DocBee, HaloPSA, Inserve, Autotask, Codemeta OS, Odoo, Jira, TOPdesk, TANSS, c-entron Service-Board, Freshservice, Zammad. Zammad sits last, so if any other ticketing system is connected as well, that system's import dialog opens instead.

When tickets stop arriving

The History tab lists recent Create ticket and Recovery attempts with their outcome, request and response. It is the place to look whenever a ticket you expected is missing. There is no replay button.

• A delivery failed. octoja retries a failed ticket create or recovery after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours. Errors Zammad reports as a client mistake — a rejected token or missing permissions, for instance — are not retried, because repeating them would not change the answer.
• The card shows the status Paused. After 20 consecutive delivery failures octoja stops creating new tickets. To resume, disconnect and connect again. Matches, the ticket group and the requester are kept; the two priorities and the Recovery state, however, are prefilled from Zammad again when you reconnect. Check them afterwards and save.
• The history shows no default Zammad group configured. No Ticket group is saved — pick one in Step 4 and save.
• Tickets arrive without an organization. The device's customer is not matched to an organization (Step 3), or the response in the history contains organization not applied because the token may not edit users.
• The dropdowns are empty. The stored token is no longer valid or lacks the required permissions. Disconnect and connect again with a working token.
• No tickets at all. Confirm that a Ticket group is saved, that an alert configuration on the check really includes the Zammad ticket channel, and that the integration is connected and not paused.

Disconnect Zammad

To remove the connection, open the Zammad integration page, scroll to the Danger Zone and click Disconnect. Confirm in the Disconnect Zammad? dialog with Disconnect.

Only the API token is removed. Customer matches, ticket settings and the delivery history stay as they were, and every ticket already created remains in Zammad. To reconnect, enter the Zammad URL, API token and requester email again.

Tips

• Click Save after every change — a dropdown you changed but did not save has no effect on the next alarm.
• Use an internal mailbox of your team as the requester, not a customer's address.
• Use Test connection before Connect. A failed test shows Zammad's response, so you can fix the token before saving anything.
• After every reconnect, check the priorities and the Recovery state, because octoja prefills them again.