Depending on your organization’s IT capabilities,
users can be managed individually or in bulk,
or even synchronized with third-party directory services.
The simplest way to manage users is directly in the Admin Panel.¶
Use the 🔎 Search for users bar and the Roles buttons to filter the list.
You may search by name, email, or any other user attribute.¶
Bemerkung
🐞 Known bug
The search list displays up to 50 users, from newest to oldest.
That means that if there are more than 50 results,
the user you’re searching for might not be shown.
Use the ⋮ Actions menu to unlock accounts after too many
failed logins. Locked accounts are indicated with a 🔒 lock icon
on the left side.¶
🏴☠️ Taking over a user’s session
Use the ⋮ Actions menu to 👁️ View from user’s perspective.¶
The View from user’s perspective button
allows you to “hijack” another user’s session
and confirm firsthand what they can and can’t do (or see)
when they’re logged in.
This is especially useful when you need to verify
that you’ve set up custom permissions correctly for non-admin users.
Gefahr
⚠ With great power comes with great responsibility.
This feature is not a simulation;
entering this mode will boot the user from their session,
and any actions you take
(responding to tickets, changing passwords,
logging hours worked)
will actually be performed from the user’s account.
(On the other hand, if the user logs back in, you’ll be booted, too.)
Hinweis
When finished,
use the Back to my view ✕ button at the top of the page.
If you try to exit by logging out,
the “hijacked” user session will be restored when you log back in.
If your organization has information about customers (or personnel)
already stored in a directory system that can export to CSV,
you can batch-import them into Zammad in just three steps.
Use the Import button to open the CSV import dialog.¶
Hinweis
CSV import provides one-off batch processing of user records.
For persistent, automated user synchronization,
consider integration with a third-party directory system
like LDAP / Active Directory
or Exchange.
With our LDAP integration, you can easily use existing authentication systems without having to update more than one source.
Also, e.g. password policies are ensured by your LDAP source - Zammad will always contact your LDAP server for authentications.
Bemerkung
The LDAP sync is one way: LDAP => Zammad. Changes to your users inside of Zammad might be overwritten by the LDAP Sync.
To configure LDAP integration, simply go to System -> Integrations -> LDAP in the admin panel.
Press „change“ and follow the wizard for adding the needed LDAP information to Zammad.
On the last step Zammad will ask you for your wanted LDAP mapping. By default, Zammad only Maps Login, First- and Lastname.
Technically you can map any LDAP object to a Zammad user object (this also works for Custom Objects!).
On this wizard step, you can also define the wanted LDAP-group-to-Zammad-role mapping.
Bemerkung
Please note that nested groups are currently not supported by Zammad.
If needed, you can also change the user filter for your LDAP query. The option „Users without assigned LDAP groups“ will by default assign the customer role
(default sign-up role) to any LDAP user, that doesn’t match to the above role mapping. After pressing Continue, Zammad will check if the configuration is okay.
You can then enable LDAP and start your first sync. The sync will then run hourly - if you need to change mappings, you can change the configuration at any time.
Bemerkung
You can use user filters to limit the search results Zammad gets. Also, you can hide deactivated Active Directory accounts (the users will be set to inactive within Zammad).
You can find further information for Active Directory Filters at the Website from Microsoft.
After the sync has finished, you can find the new LDAP users under „Users“. Zammad integrates them just normal users, the difference is the login name.
With our Exchange integration, you can easily use existing address books without having to update more than one source.
Bemerkung
The Exchange sync is one way: Exchange => Zammad. Changes to your users inside of Zammad might be overwritten by the Exchange Sync.
To configure Exchange integration, simply go to the System -> Integrations -> Exchange in the admin panel.
Press „change“ and follow the wizard for adding the needed Exchange information to Zammad.
On the last two step Zammad will ask you for the address book(s) and your wanted Attribute mapping. By default, Zammad only Maps email address, First- and Lastname.
Technically you can map any Exchange object to a Zammad user object (this also works for Custom Objects!).
Bemerkung
Please refrain from syncing all addresses, as the results may not be what you expect (Exchange collects huge amounts of addresses).
A central address book of your company to sync makes more sense, as you can ensure that Zammad gets only the data you need and want.
After pressing Continue, Zammad will check if the configuration is okay. You can then enable LDAP and start your first sync.
The sync will then run hourly - if you need to change mappings or the address book(s), you can change the configuration at any time.
After the sync has finished, you can find the new Exchange contacts under „Users“. Zammad integrates them just normal users.
Bemerkung
In some cases you might see unique IDs as „Login“ instead of the email address. This is normal and doesn’t affect the login or email mapping for that entry.
Bemerkung
😲 Customers get their own user accounts, too?
Yes! Unlike OTRS, Zammad needs to store accounts
for everyone who communicates through the system.
Why? It helps us do things like show all tickets from a certain customer.
How? Zammad checks the sender of every incoming message
at every inbox it monitors,
and if it doesn’t recognize the address,
✨ poof—new customer account!
(Your customers never need to set a password.
Of course, they can if they want to,
but the account will be there even if they never use it.)
Yes, administrators really do have the power to change other users’ passwords.
(Agents do not, though.)
🏢 Organization
Unternehmen are a way to group customers together
(usually, members of the same company).
This allows you to do things like view all tickets for that company
or set up special Triggers that fire only for those customers.
Hinweis
🚫 You can’t assign a customer
to an organization that doesn’t exist yet.
To add one, go to Manage > Organizations in the Admin Panel.
👑 VIP
This flag is a way for your team to indicate high-status customers.
Just as with organizations,
you can set up special Triggers, Scheduler jobs,
SLAs, and Overviews just for VIPs.
VIPs are displayed with a crown above their avatars.¶
📑 Note
Notes are visible to all staff members, including agents.
Hinweis
😵 Are you using the Note field
to keep track of your own “custom” user attributes?
Wish you could add your own fields to the New/Edit User dialog?
Disabling this flag is a soft alternative to deleting a user.
So what’s the difference?
There is no way to restore a deleted user;
inactive users can be reactivated at any time.
When a user is deleted, all their associated tickets are lost, as well;
deactivating a user keeps all associated tickets intact.
Inactive users still appear in search results:
A slashed-out 👤 icon indicates an inactive user.
In other cases, inactive users are greyed out.¶
🔓 Permissions
Under this heading, you can manage two separate (but related) user details:
Roles dictate what users can do in the system.
If you need to grant someone privileges to edit the knowledge base
or access part of the admin panel, roles are the answer.
Group Access Levels dictate which tickets
an agent can work with.
If someone’s not receiving notifications for incoming tickets
or can’t be assigned a ticket,
group access levels are likely to blame.
Top: A user’s roles decide what kinds of actions they can perform
and which groups they belong to.
Bottom: Group assignments can alternately be set on a per-user basis.¶
Hinweis
🤔 Huh? I don’t see the group access table…
The group access table is only visible in agent profiles,
when there is more than one active group in the system.
This is the group management area. From here you can edit existing groups and add new groups.
Groups in Zammad are similar to working groups that deal with different topics within a company. For example, the tickets relevant to the sales department might be available in the Sales group, while the tickets for the support department might be available in the Support group. These are just examples; how you structure your groups is up to you.
Tickets enter Zammad through various channels (e.g. via email) and are then sorted into these groups. The tickets (cases) are thus made available to the agents responsible for the group. Each ticket can only belong to one group, and you can decide via access levels (see below) what access your agents have in each group. For example, you might want set up a group Management for confidential tickets; with access levels, you can configure that only a few select agents will have access to these tickets.
For an additional way to categorize tickets, have a look at Tags.
Hinweis
Zammad users are global to the whole instance.
Restriction to specific groups is not possible.
Click on a group to edit it, or click on New group to create a new group.
There you can edit the following settings:
Name: choose a name for the group.
Assignment timeout: the time in minutes after which the ticket’s state will revert back to unassigned after the assigned agent hasn’t worked on the ticket.
Follow up possible: configure what happens when a customer replies to a closed ticket:
yes: the ticket will be reopened.
do not reopen ticket but create new ticket: the ticket will remain closed, and Zammad will instead create a new ticket for the customer’s reply.
Assign follow ups: configure whether a closed ticket that has been reopened due to a customer’s reply should remain assigned to the last agent:
yes: the ticket will remain to the last agent who owned it.
no: Zammad will unassign the ticket.
Email: choose which email address will be used as the sending address (From header) when agents reply to tickets in this group. Email addresses can be configured in Channels → Email → Accounts.
Signature: choose which signature to use when replying to tickets in this group.
Note: an internal note about the group that is only visible to people who can access the group management area.
Active: choose whether the group is enabled or not. Groups cannot be deleted, they can only be set to inactive.
⚖️ We recommend choosing one or the other;
things can get confusing if you use both at the same time.
So which one is right for you? Whichever one is less work.
If you’re trying to assign multiple agents
to the same group with the same access levels,
create a role for them to share—that’s what roles are for!
When a system only has one group,
this is the default access level assigned to all agents.
Unless you have special needs in mind, this is the way to go.
“The Supervisor”
Agents with all permissions except for “full” cannot be assigned tickets.
Otherwise, their privileges are identical to agents with “full” access.
Great for letting other people do the real work.
“The Meddler”
Agents with “read”, “change”, and “overview” access
can do everything except create tickets or be assigned to them.
Great for getting involved in other people’s business.
“The Intern”
Agents with only “create” access can do just that,
and nothing else—once they hit Save, they’ll never see that ticket again.
Great for taking phone calls for someone more important than you.
Hinweis
If the Group field does not appear in the ticket view, ensure that:
you have created more than one group
the current user has „change“ permissions to more than one group
This is necessary because Zammad automatically hides selection fields with only one option.
If you’re already using Zammad,
you’ll know that users can be admins, agents, or customers.
These are Zammad’s built-in roles, and they’re the tip of the iceberg
of its powerful, flexible, and fine-grained permission system.
Assign user privileges in the Admin Panel, under Manage > Roles.¶
Bemerkung
👀 What’s New in v3.5
Now, users can have both “agent” and “customer” roles at the same time!
Why would you want this?
Agents get overviews
of all the tickets they’re assigned to (among other things),
while customers get an overview of all the tickets they’ve opened.
But some teams use Zammad for both internal and public communication,
so their agents need both.
Having both roles also changes what you see in the ticket view,
depending on whether you’re the “customer” or not.
Tipp
💡 LDAP/Active Directory users:
Syncing your LDAP “groups” to Zammad roles
can make access management way easier.
To learn more, see LDAP / Active Directory.
tl;dr Some users can do things others can’t (like close a ticket).
Users have roles, roles have permissions,
and permissions are what make those actions possible.
So what exactly are permissions, then?
The admin.calendar permission gives you access
to the Manage > Calendars admin panel.¶
Simply put, permissions are names for all the different things
users might want to do throughout the system, such as:
chat.agent
respond to live chat messages
ticket.agent
update tickets
admin.user
access the Manage > Users admin panel
knowledge_base.editor
create/edit knowledge base articles
Zammad has dozens of these permissions,
which is a lot to keep track of.
So instead of saying “This user has permissions A, B, and C”,
Zammad says “The agent role has permissions A, B, and C,
and this user is an agent.”
This makes creating user accounts for new agents a whole lot simpler,
and it also makes it easier to invent a new permission D
and say “All existing agents can do that now, too.”
In short, roles are just collections of permissions that you can give to a user.
The built-in admin, agent, and customer roles are enough for many teams,
but Zammad gives you the freedom to custom-build your own.
And to do that, you’ll need to know what each permission does.
📁 Permissions are namespaced,
which is sort of like having files inside of folders.
The permissions listed on this page all belong to the admin namespace.
You can select them individually,
or you can just select admin to enable the whole bunch.
Admin permissions are shown at the top of the New Role dialog…¶
…and give users access to the pages of the Admin Panel.¶
Agents can access existing organizations
from the search bar, even without this permission.
They can even edit an organization’s name, domain, and notes!
As of Zammad 3.5, you can assign both agent and customer roles to the same user—but
but you can’t assign both ticket.agent and ticket.customerpermissions to the same role!
To make it work, you need two separate roles:
one with ticket.agent and the other with ticket.customer.
📁 Permissions are namespaced,
which is sort of like having files inside of folders.
The permissions listed on this page all belong to the user_preferences namespace.
You can select them individually,
or you can just select user_preferences to enable the whole bunch.
User preferences permissions are shown at the bottom of the New Role dialog…¶
…and give users access to the pages of their User Profile.¶
user_preferences.access_token
Generate API tokens to control Zammad via the REST API
Bemerkung
💡 Security Tip
Generated tokens will never have more permissions than the user that generated them.
user_preferences.avatar
Override the default Gravatar with a custom avatar
user_preferences.calendar
Configure the calendar feed
user_preferences.device
Manage device login sessions
Bemerkung
💡 Security Tip
Revoking this permission disables “Login detected from a new location” notification emails.
Customers can’t receive ticket notifications at all.
user_preferences.out_of_office
Designate a substitute for out-of-office hours
Bemerkung
💡 Security Tip
Designating a substitute does not grant that person
the permissions / group access levels
of the agent they’re replacing.
user_preferences.password
Change account password
Warnung
🔑 Third-party authentication / LDAP users:
Be sure to revoke this permission for all your users.
When using a third-party identity server (like LDAP),
the whole point is to let it take care of authentication
so that passwords never have to live in Zammad’s database.
Broadly speaking, there are four types of permissions:
Every new user must be assigned at least one role upon creation.
This attribute decides which role to give new users by default
(which usually happens when creating a new ticket for a new customer).
The default role is identified in the overview
of the Manage > Roles admin panel.¶
Warnung
🙅 Default roles should never provide admin/agent permissions.
Organizations allow you to group customers. This has two important advantages, among other things.
1.) As an agent you not only have the overview of a customer’s tickets, but also an overview of the entire organization.
For example, by searching for the organization, all the tickets for the organization are displayed and they can be opened easily by a click.
This overview appears as follows:
2.) As a customer, you can view and edit your colleagues‘ tickets (if the organization is a „shared organization“, you can set this as a parameter for each organization. See the Edit-Mask).
For example:
For a customer user who has only created one ticket himself, but whose entire organization has created 6, the overview would look like this:
In the organizations management area (Admin Interface –> Manage –> Organizations) you can manually add, edit or delete existing organizations. That’s the Edit-Mask:
Within the organization the following things can be set:
if it’s a shared organization (All customers who are assigned to this organization can view and edit the group tickets)
if the assignment is domain based (assign users based on domain)
With the import action (since Zammad 2.5) you can download a sample CSV file and upload your own CSV file.
To reduce the error rate of unwanted mass changes, a test import is carried out first and a summary appears at the end. If you agree with the summary, the CSV import will be executed.
You can provide overviews to your agents and customers. They can be used as a kind of worklist of tasks that the agent is supposed to work off.
You can also create individual reports for individual agents or agent groups.
In the Overview Management Area you can add new overviews, edit or delete them.
Warnung
Please note that Overviews can cause performance issues leading to no longer or less often refreshing overviews!
Whenever possible, try to use the same overviews for as many agents and groups as possible to keep the number of overviews
low. For best results, you might want to use between 15-20 overviews maximum. Also, any overview will only show a total of
2100 elements.
Bemerkung
Overviews will only show tickets to your users, that the user have rights on (group or role based).
The following attributes can be set when creating an overview:
Available for role / Available for user
Hinweis
Roles are assigned to users, per default there are agents, admins and customers. Further information about Roles.
With these settings you can choose whether to make the overviews available to an entire group of people (by selecting the role) or to specific users. The entries in both fields apply. This means that you can also select individual users in addition to sharing the overview for all role members.
Only available for users with shared organization
Hinweis
Shared organization is a setting in the organisations-management. See Unternehmen for more information.
This is only important if the available role is a customer. When deciding whether yes or no is selected, it must be considered to what extent this makes sense - for example, if a customer sees only his own tickets, many views are usually not necessary…
Bemerkung
Users also refers to the customer role in this case.
Available for users which are replacements for other users
This selection refers to the setting in the user preferences (profile-pic in the left corner –> profile –>) „out of office“. If this option is checked, this selection is only displayed if someone has been entered as a substitution.
For example: Agent A is on vacation and Agent B will take care of his tickets. Then an overview can be set up, which only shows Agent B all new tickets from Agent A for this period of time, without having to search for them separately.
What conditions should the listed tickets contain? (it is like a filter) You can add more than one condition. In the preview you have the possibility to double check if your entry of the conditions makes sense by directly displaying tickets that match your filtering.
ATTRIBUTES
Which attributes shall be shown in the overview? (column headers)
With this setting you can select the headlines of your overview. Depending on which information is important in this selection, it can be displayed individually. For this example „Unassigned and open“ the overview would look like this:
These settings can also be adjusted individually by admins at a later time (In the overview, top right: Options).
Bemerkung
Please note that overview column and sort settings are global settings which affect all users seeing those overviews.
Ordering, grouping and active
order: In which order should the tickets be displayed? (Sorted by the attributes)
direction: The direction of the order
group by: Should the tickets be displayed again grouped by a specific attribute within the list?
Text modules can be edited in the admin interface under Manage –> Text modules.
Here you will find text snippets already created in the standard version, which
can be extended as needed.
Here you can add new text modules, delete or edit them.
Creating keywords makes it easier to find the right text module.
If needed, you can restrict text modules to specific groups.
With this, you can easilly keep text module lists short and dedicate specific
texts to where they belong.
You can adjust the group memberships for text modules at any time.
This allows you to have the text module available globally (no groups selected)
or one or several specific groups.
To select placeholders from a list, just enter :: in the text block.
The list can be searched with the arrow keys after inputting keywords or
shortcuts. All text modules can be used in articles as well as in the chat.
Bemerkung
You can find more information on how to use text modules on our
User Documentation.
Tipp
If text modules are to be grouped, this can be done using shortcuts.
Example country codes:
Text modules are created for the group Germany as follows:
Ger_Textmodule1
Ger_Textmodule2
…
for Austrian-Snippets:
Aut_Textmodule1
Aut_Textmodule2
thus only the relevant text modules are displayed for each country.
The example text modules below use Variables to dynamically
insert information like the customer’s or agent’s names.
Often similar text modules have to be created or unnecessary ones deleted.
For these cases you can click on the 3 points in the text module overview on
the right side and select the corresponding action:
When cloning, text modules with all attributes are duplicated and can be edited
later.
With the import action (since Zammad 2.5) you can download a sample CSV file
and upload your own CSV file.
To reduce the error rate of unwanted mass changes, a test import is carried out
first and a summary appears at the end. If you agree with the summary, the CSV
import will be executed.
Makros sind 🖱️ ein Klick-Abkürzungen zum Hinterlegen von Änderungen an einem Ticket.
If you find yourself making the same changes to lots of tickets
(e.g., close-and-tag-as-spam or reassign-to-another-group),
you can store those changes in a macro for easy access:
Choose from the macros Close & Tag as Spam, Move to RMA,
and Reply & Close & Tag as Banana.¶
You can also apply macros in bulk (i.e., to many tickets all at once) via the Overviews page:
Select your desired tickets, then click-and-drag
to apply a macro to all of them.¶
You can create or edit macros on the Macros page of the admin panel:
To get you up and running quickly, here are some examples
of the kinds of one-click actions you can set up using macros.
Hinweis
If they don’t make sense to you, don’t worry—just skip ahead to
Wie funktionieren sie?
to learn about all the options in detail,
then come back here to see them in action.
If you deal with a lot of spam, you could set up a macro that applies
the following changes to a ticket:
Status
geschlossen
Tags
add spam
Besitzer
current user
Tipp
💡 Run this macro in a Scheduler
to periodically clean up unwanted tickets.
If you want to set a ticket’s state to pending reminder, it’s
usually a two-step process—first select the state, then select a date.
To always set a reminder for the same, fixed amount of time (say,
seven days later), you can bundle the whole change into a macro:
Note
“Postponing ticket for 7 days.” (🔒 internal visibility only)
set ticket attributes (priority, state, group, etc.)
add new notes to a ticket
There are no actions for:
sending a reply to the customer
Bemerkung
Unlike triggers, the scheduler, and text modules,
macro actions do not support the use of
Variables.
Warnung
If the ticket is missing a required attribute
and the macro doesn’t set it, then no actions will be
applied.
Once completed…
After running this macro, should Zammad remain on the current
tab, close it, or automatically switch to the next ticket?
(Does not apply when running macros “in bulk”.)
Note
What should other Zammad admins know about this macro?
(Visible only via the “Edit: Macro” dialog, Rails console, and API.)
You can list all the marked tickets by tag in different ways:
1. by providing an appropriate overview
Create a new overview and select „Tag contains …“ as condition.
You can find further information in Overviews
2. by a search-query
Enter e. g.: tags:banana in the search mask and you will receive all tickets that have been tagged accordingly. For a collected listing, click on „Show Search Details“ under the search box:
3. by clicking on the tag in the Tag Management Area
In the Tag Management you can find an overview of existing tags used in the system (and a counter how often they are used):
For more information about the individual tags, just click on the blue counter:
Select one of the tickets that appears below the search box or get a complete overview of all tickets by clicking on „Show Search Details“:
Here it can also (in addition to the overview - as described above) be set whether the agents are allowed to add tags themselves or not (in the left upper corner).
generate reports that only capture activity during business hours, or
set up time-sensitive triggers.
Define a „standard“-calendar which system-wide is valid. Only in the specified business hours, escalation notifications are sent to agents.
If you have customers for which you have to comply with different customer business hours, you can create several calendars. The allocation to the customer tickets can be adjusted via the SLAs.
And this is what it looks like:
All created calendars are displayed in the overview.
Here you can create a new calendar if agents or customers belong to another time zone.
Just push the delete-button to delete this specific calender - all SLAs assigned to this calendar are automatically assigned to the default calendar.
Pressing this button sets this calendar as the default calendar for the entire system.
Via this button you get to the edit-mask (same mask as in 1.):
–> determine a name, a time-zone, the business hours to be used for this calendar and special holidays. In addition, you can subscribe to the iCalendar, which will automatically load all holidays from Google (updated once a day) … and you can add a note.
Service levels and the respective agreements (service level agreements, SLAs) document quality pledges for IT services. SLAs are recorded and administered in here.
A calendar is required to calculate escalations or evaluations based on business hours.
Define a „standard“ calendar which is valid throughout the system. Only in the specified business hours, escalation notifications are sent to agents.
If you have customers for which you need to comply with different business hours, you can create multiple calendars. The customer tickets are allocated via the SLAs.
That’s how it works:
Give it a distinctive name
Specify the ticket groups for which the SLA is to apply (these can also be arbitrarily combined and thus specified)
In the preview you see the selection of the tickets and doublecheck wheather those are correct
Choose the business-calender
Define the SLA-Times:
First Response
Timeframe for the first response (external call, email)
Update Time
Timeframe for every following response (external call, email)
Solution Time
Timeframe for solving the problem (status: closed)
It is up to you if you set one, two or all three times. When the SLA time is reached, the ticket escalates. Now all agents get notifications, which have stored the corresponding setting in their own settings profile -> notifications. The information that a ticket is escalated can be selected in the triggers as an attribute, whereby a desired action can be followed.
Use triggers to set up all kinds of 🎛️ if-this-then-that automation workflows.
Hinweis
For ⏳ every-so-often automation workflows,
try schedulers instead.
The first thing to know about triggers is that you’re already using them.
From the moment you set up Zammad, it starts sending auto-replies
to all incoming emails. Recognize this line?
It means that the ticket is from an incoming customer email,
and that the customer received this message in response:
This auto-reply message is a trigger.
You can disable it, modify it, or create new ones
for all sorts of automation tasks on the Trigger page of the admin panel:
To get you up and running quickly, here are some examples
of the kinds of automation tasks you can set up with triggers.
Hinweis
If they don’t make sense to you, don’t worry—just skip ahead to
Wie funktionieren sie?
to learn about all the options in detail,
then come back here to see them in action.
Any time Jacob Smith creates a ticket, assign it to the Sales group:
Emma Taylor is responsible for all sales internally, so if a new ticket has
the word “order” in the subject, assign it to her and make sure it’s set
with a high priority:
Send an auto-reply email to any customer who responds to a ticket:
Bemerkung
📨 Not all automated messages come from triggers!
For instance, when agents receive a system email
about a newly created ticket,
that’s built into the system itself.
If you need to customize those,
you will have to manually edit files on your server.
Triggers consist of two parts: conditions and changes. Conditions
answer the question, “when should this trigger fire?” Changes answer the
question, “what should happen when it does?”
Triggers are evaluated in alphabetical order, by name.
In some situations triggers might be the wrong choice, see
Limitations for more information.
When creating a trigger, define your conditions here:
Trigger conditions are and-selectors and thus all conditions must apply as
configured for the trigger to fire. You can configure triggers to fire based on
the properties of:
The Ticket itself
e.g., Was this ticket newly created? Is the ticket currently open? When
was the last time we received contact from the customer on this ticket?
New Articles on the ticket
e.g., Was this article added by email? by phone? Was it created by an
agent, or a customer? Does the subject contain a certain set of words?
The Customer that created the ticket
e.g., What is the customer’s name? Is the customer a VIP? What department
does the customer work in?
The Organizations that the ticket’s customer belongs to
e.g., What is the name of the customer’s organization? Does it have a note
attached to it containing a certain set of words?
The Execution time the trigger is being triggered
e.g., Only send an auto-reply if the message was received outside of
regular business hours. (“Regular business hours” can be defined on
Calendars setting.)
Connect Zammad to another web service or application to give it live updates
about new tickets.
Add internal or public notes to the ticket
This allows you to help your agents with specific information if needed.
(e.g. automated changes a trigger applied to the ticket)
Bemerkung
In order to send emails with Triggers, you need to configure
an email address for the group the trigger is working in. If you
don’t, Zammad will skip the Trigger completely.
Hinweis
Certain actions (such as email, SMS and notes) support
Variables, which can be used to build
highly-customized message templates.
It’s important to understand when a trigger can be used and when it’s better to use e.g. Zammads
Scheduler or postmaster filter.
Triggers will fire during the following conditions:
Creation of a ticket
Updating a ticket
While the creation of tickets and triggering these actions is straight forward, updated of tickets are a bit trickier.
In terms of triggers, a ticket is only updated if you press the update button on the lower right of a ticket.
Adding tags to a ticket or switching articles visibility is no ticket update.
Also keep in mind that we’re always only working on the last article. This means you can’t trigger for past articles.
Triggers always handle the current ticket attributes and the article (if applicable) that cause the trigger to fire.
If your use case doesn’t fit in above possibilities, you might want to have a look at Zammads Scheduler.
System notifications can only be customized
on self-hosted installations.
System notifications are automated emails
sent by Zammad for critical system events,
such as account changes or SLA violations.
Unlike the automated emails you can set up
using Triggers or the Scheduler,
these notifications are built into Zammad itself:
if you need to customize them,
you will have to modify some of the files on your server.
Inside your Zammad directory (usually /opt/zammad), email templates for
various events are stored inside the /app/views/mailer directory, named
according to the language they’re written in. Thus,
is the German-language template used to notify agents whenever a new ticket is
created. To modify this template, create another file with the same name and
add a .custom suffix:
Webhooks are a way to integrate Zammad with other web services or applications,
allowing them to subscribe to live updates about tickets instead of having to
poll the Zammad server every n minutes.
Bemerkung
⌛ Webhooks may not arrive immediately.
Webhooks are sent out with the same priority and order as email triggers.
If webhook dispatch fails (e.g., because the receiving server is misconfigured),
Zammad will retry up to four times.
Under the hood, Zammad sends a POST request
to a third-party URL (“API endpoint”) you specify in the New Trigger dialog.
The application server behind this URL/endpoint
must be configured to receive messages from Zammad
and handle the attached data accordingly.
Webhook requests from Zammad contain the following JSON data about new/incoming tickets:
Webhooks are defined globally.
This allows you to use one specific endpoint on several triggers or schedulers.
Warnung
🦻 Zammad webhooks are specific
Keep in mind that the remote site has to be able to understand the
webhook Zammad is sending! Simply throwing Zammad payloads at webhook
endpoint may not have the desired result!
You can configure the following information to webhooks:
Name (mandatory)
This name will be displayed within trigger and scheduler selections.
Endpoint (mandatory)
Webhook endpoint Zammad sends its payload to.
Bemerkung
Zammad ignores basic authentication parameters.
HMAC SHA1 Signature Token
If set all sent webhooks contain a x-hub-signature header allowing
the remote site to verify the request.
Bemerkung
🔐 Security note
This does not encrypt the payload. Use HTTPs connections to
secure the communication. It contains a HMAC signature of the body
of the webhook request
Defaults to yes - if you’re using unsecure self signed certificates
set this option to no.
Note
If required you can leave useful information for other Zammad admins
to understand the webhook in question better.
Active
If set to inactive you can no longer select the webhook within
trigger or scheduler actions.
Warnung
Setting webhooks to inactive that are used by triggers or schedulers
will not run. If triggers or schedulers have other actions configured
as well they’ll still be executed.
{"ticket":{"article_count":1,"article_ids":[104],"create_article_sender":"Customer","create_article_sender_id":2,"create_article_type":"phone","create_article_type_id":5,"created_at":"2020-11-13T14:34:35.282Z","created_by":{"active":true,"created_at":"2020-11-13T12:57:47.679Z","created_by":"-","created_by_id":1,"email":"chris@chrispresso.com","firstname":"Christopher","id":3,"image":"7a6a0d1d94ad2037153cf3a6c1b49a53","lastname":"Miller","login":"chris@chrispresso.com","organization":"Chrispresso Inc.","organization_id":2,"out_of_office":false,"role_ids":[1,2],"roles":["Admin","Agent"],"updated_at":"2020-11-13T13:00:03.064Z","updated_by":"chris@chrispresso.com","updated_by_id":3,"verified":false,"vip":false,},"created_by_id":3,"customer":{"active":true,"address":"Bennelong Point\nSydney NSW 2000","created_at":"2020-11-13T12:57:48.779Z","created_by":"-","created_by_id":1,"email":"emily@example.com","firstname":"Emily","id":8,"image":"99ba64a89f7783c099c304c9b00ff9e8","lastname":"Adams","login":"emily@example.com","note":"did order café au lait, ask next time if the flavor was as expected","organization":"Awesome Customer Inc.","organization_id":3,"out_of_office":false,"phone":"0061 2 1234 7777","role_ids":[3],"roles":["Customer"],"updated_at":"2020-11-13T14:34:37.366Z","updated_by":"chris@chrispresso.com","updated_by_id":3,"verified":false,"vip":false,},"customer_id":8,"group":{"active":true,"created_at":"2020-11-13T12:57:47.498Z","created_by":"-","created_by_id":1,"follow_up_assignment":true,"follow_up_possible":"yes","id":3,"name":"Service Desk","updated_at":"2020-11-13T12:57:48.044Z","updated_by":"-","updated_by_id":1,"user_ids":[3,4,5],"users":["chris@chrispresso.com","jacob@chrispresso.com","emma@chrispresso.com"]},"group_id":3,"id":81,"last_contact_at":"2020-11-13T14:34:35.318Z","last_contact_customer_at":"2020-11-13T14:34:35.318Z","number":"10081","organization":{"active":true,"created_at":"2020-11-13T12:57:47.524Z","created_by":"-","created_by_id":1,"domain_assignment":false,"id":3,"member_ids":[8,6,7],"members":["emily@example.com","anna@example.com","samuel@example.com"],"name":"Awesome Customer Inc.","note":"Global distributor of communication and security products, electrical and electronic wire & cable.","shared":true,"updated_at":"2020-11-13T14:34:35.346Z","updated_by":"-","updated_by_id":1},"organization_id":3,"owner":{"active":true,"created_at":"2020-11-13T12:57:48.036Z","created_by":"-","created_by_id":1,"email":"emma@chrispresso.com","firstname":"Emma","id":5,"image":"b64fef91c29105b4a08a2a69be08eda3","lastname":"Taylor","login":"emma@chrispresso.com","organization":"Chrispresso Inc.","organization_id":2,"out_of_office":false,"role_ids":[2],"roles":["Agent"],"updated_at":"2020-11-13T12:57:48.072Z","updated_by":"-","updated_by_id":1,"verified":false,"vip":false,},"owner_id":5,"priority":{"active":true,"created_at":"2020-11-13T12:54:02.238Z","created_by":"-","created_by_id":1,"default_create":true,"id":2,"name":"2 normal","updated_at":"2020-11-13T12:54:02.238Z","updated_by":"-","updated_by_id":1},"priority_id":2,"state":"open","state_id":2,"ticket_time_accounting":[],"ticket_time_accounting_ids":[],"title":"Webhook-Test","updated_at":"2020-11-13T14:34:35.333Z","updated_by":{"active":true,"created_at":"2020-11-13T12:57:47.679Z","created_by":"-","created_by_id":1,"email":"chris@chrispresso.com","firstname":"Christopher","id":3,"image":"7a6a0d1d94ad2037153cf3a6c1b49a53","lastname":"Miller","login":"chris@chrispresso.com","organization":"Chrispresso Inc.","organization_id":2,"out_of_office":false,"role_ids":[1,2],"roles":["Admin","Agent"],"updated_at":"2020-11-13T13:00:03.064Z","updated_by":"chris@chrispresso.com","updated_by_id":3,"verified":false,"vip":false,},"updated_by_id":3},"article":{"attachments":[{"id":174,"filename":"image1.jpeg","size":"35574","preferences":{"Content-Type":"image/jpeg","Mime-Type":"image/jpeg","Content-ID":"81.969520479@zammad.example.com","Content-Disposition":"inline","resizable":true,"content_preview":true},"url":"https://zammad.example.com/api/v1/ticket_attachment/81/104/174"}],"body":"This is a simple Webhook Test.<div><br></div><div>\n<img style=\"max-width:100%;width: 849px;max-width: 100%;\" src=\"/api/v1/ticket_attachment/81/104/174?view=inline\"><br>\n</div>","content_type":"text/html","created_at":"2020-11-13T14:34:35.318Z","created_by":{"active":true,"created_at":"2020-11-13T12:57:47.679Z","created_by":"-","created_by_id":1,"email":"chris@chrispresso.com","firstname":"Christopher","id":3,"image":"7a6a0d1d94ad2037153cf3a6c1b49a53","lastname":"Miller","login":"chris@chrispresso.com","organization":"Chrispresso Inc.","organization_id":2,"out_of_office":false,"role_ids":[1,2],"roles":["Admin","Agent"],"updated_at":"2020-11-13T13:00:03.064Z","updated_by":"chris@chrispresso.com","updated_by_id":3,"verified":false,"vip":false,},"created_by_id":3,"from":"Emily Adams <emily@example.com>","id":104,"internal":false,"origin_by":"emily@example.com","origin_by_id":8,"sender":"Customer","sender_id":2,"ticket_id":81,"to":"Service Desk","type":"phone","type_id":5,"updated_at":"2020-11-13T14:34:35.318Z","updated_by":{"active":true,"created_at":"2020-11-13T12:57:47.679Z","created_by":"-","created_by_id":1,"email":"chris@chrispresso.com","firstname":"Christopher","id":3,"image":"7a6a0d1d94ad2037153cf3a6c1b49a53","karma_user_ids":[],"lastname":"Miller","login":"chris@chrispresso.com","organization":"Chrispresso Inc.","organization_id":2,"out_of_office":false,"role_ids":[1,2],"roles":["Admin","Agent"],"updated_at":"2020-11-13T13:00:03.064Z","updated_by":"chris@chrispresso.com","updated_by_id":3,"verified":false,"vip":false,},"updated_by_id":3,"accounted_time":0}}
Bemerkung
For better readability, all empty and null values
have been omitted from the sample payload above.
That means the webhooks you receive
will include additional fields not shown here.
Webhooks will also include fields for any relevant
custom objects defined in your system.
Attachments are not included; links to attachments are (authentication required).
None of the following user attributes are included:
The scheduler performs time-based automated actions. You can set up your own schedulers, configure at which points in time they should run, set up conditions to determine which tickets they should affect, and then configure the actions that you want to be executed on these tickets.
Bemerkung
Schedulers with Action: Delete are currently the only way in the Zammad front end to permanently delete tickets. This limitation is intentional as Zammad is designed to be revision-proof. A possible use case for such a scheduler is to delete spam tickets some time after creation (e.g. 30 days).
Warnung
While it is possible to delegate scheduler permissions to normal agents with the admin/scheduler permission, it is inadvisable to do so. Malicious agents could use a scheduler to access tickets in restricted groups (by moving them to a non-restricted group) or to delete arbitrary tickets.
Hinweis
Schedulers can be used to send periodic reminder emails. Use Variables to build highly-customized email templates.
When should the job run: choose the points in time using UTC timezone when the scheduler should run.
Conditions for affected objects: determine the ticket attributes (conditions) to limit on which tickets the actions configured in step 5 are to be performed.
Preview: this list previews some tickets that your conditions are matching and shows a total of how many tickets are being matched. Use this to double-check the entered conditions.
Execute changes on objects: determine the changes to be made to the ticket.
Disable notifications: by default, actions triggered by schedulers won’t send notifications. You can override this here by setting this to no.
Note: you can use the note field to describe the purpose of the scheduler. This is only visible to other admins when they are editing the scheduler. It is not a way to add notes to tickets.
Active: with this setting you can enable/disable the scheduler.
The scheduler shown in the screenshot would have the following effects:
Every workday (Monday to Friday) at 9:00 a.m. (UTC), all tickets which:
are not closed and
are assigned to the Sales group and
whose escalation was 30 minutes ago
will be:
assigned to Emma and
have their priority changed to 3 high.
As a supervisor in the Sales group, this enables Emma to intercept and process escalated tickets.
Emma will not receive notifications when the scheduler assigns her these tickets, and no note will be added to them.
Report profiles are used to restrict / filter report-results. The idea of the profiles is to limit the number of tickets and determine the type of tickets you want to analyze.
You can create any number of profiles in the Admin Interface in the „Report Profile“ area. The edit-mask looks like this:
This example shows the statistics of all tickets of the organization „Awesome Customer“ that were created in the last month.
The filters can be combined with each other as desired. The filters build on each other, which means that they are further restricted per additional attribute.
All configured filters are displayed in the statistics area and you can switch between them with one click:
The time period and time interval can be changed with one click (the graphic adapts itself directly):
You can filter the Create Channels (Phone, email, Twitter,…) and Communication (Phone, email, Twitter,…) and select metrics (choose from the menu bar in the upper left corner - currently Ticket Count, Create Channels, Communication). Here are all tickets with a certain metric of a profile evaluated.
The list below the graphic shows the tickets that have been filtered out. This can be downloaded as CSV and processed in a statistics program:
If you want to know how much time you need for your each project, you can enable time accounting (turn on the switch on the top left side of the page).
It can be set for which tickets the time accounting is activated - that means for which tickets you can enter, how much time was needed. It’s possible to set multiple conditions (these can also be arbitrarily combined and thus specified):
For all set cases (in this example, this is for each „Update“ of tickets that are not closed and in the group ‚Sales‘) the following field appears for entering the invested time:
In the admin area there are different possibilities to get an overview of the accounted times.
There is a monthly overview for all counted times. By clicking on the desired year and month you can see all corresponding tickets:
The tickets can be arranged according to customers and organization. All views can be downloaded as a CSV file (click on the down arrow).
This document describes how to ⚙ configure the knowledge base.
For details on how to ✍️ use and edit it, please refer to the
Zammad Agent docs.
By default, only admin users are permitted to create, edit, and manage knowledge base articles.
See Roles for details on how to grant write access to agents or other users.
Bemerkung
The knowledge base will not appear in the main menu until it has been
enabled in the admin panel.
🎨 Customize the appearance of the knowledge base.¶
Icon & Link Color
Applies to all category & article entries in
knowledge base menus, as well as hyperlinks in articles.
Header Color
Applies to the area surrounding the search bar.
Icon Set
Defines the selection of icons that may be used when
creating/editing categories.
Each category in the knowledge base must be given an icon.
Icons appear prominently in the main menu, like so:
Warnung
🤦♀️ Re-assigning icons on all of your categories is tedious work.
It’s advisable to explore your options early
to avoid having to change your mind down the road.
🌍 Add or remove locales, or reassign the default.¶
The knowledge base will automatically display the language matching each visitor’s locale.
Visitors may always manually switch to another language via a dropdown menu in the footer.
The default locale is displayed when the visitor’s locale is not supported.
Articles that have not yet been translated into a given language will be hidden from that locale.
Diese Funktion ist nur in selbst gehosteten Instanzen verfügbar.
📍 Relocate the knowledge base to the URL of your choosing.¶
By default, the knowledge base will appear
at the same domain as your Zammad instance, under /help.
If you wish to customize where it can be accessed,
enter your desired URL here and configure your web server as described
(instructions provided for Apache and NGINX only).
🗑️ Permanently delete the knowledge base and all the articles within it.¶
Use this panel to delete the knowledge base.
If you wish to unpublish it without deleting all its content,
simply disable it via the toggle button at the top of the window instead.
You can forbid customers to create tickets via the web interface.
This will remove the „➕“ button on the lower left.
Default: yes
Bemerkung
This does not forbid updating existing tickets via UI.
Group selection for Ticket creation
By default your customers may create tickets in all groups.
As this may be an issue, especially when having several support levels or
internal groups, you can always select a set of groups you want to be
available.
At the moment it is not possible to add more (or custom) fields to a Zammad Form.
Bemerkung
The form is currently limited to one form per instance.
Feedback or contact forms are quite often used on websites. Usually they will generate an email which will be sent to somebody who forwards it and so on. With Zammad it’s quite easy to integrate these forms into your website and directly generate tickets with them. In just 2 minutes.
Go to „Admin -> Channels -> Form“ and enable the switch for this feature. Below you can adapt your form settings.
In preview mode you can test if the form fits your needs (e. g. if it opens as modal dialog or if it’s shown inline on the website)
Just copy the JavaScript snippet and paste it into your website. That’s all. Just 2 minutes.
Finally, the forms will look as follows:
Voraussetzungen
Zammad form requires jQuery. If you don’t already use it on your website include it like this:
The Form function could be abused by sending a higher amount of messages / tickets to your Zammad instance.
If you do not use Zammad-Forms: disable them.
But don’t worry! Zammad does limit the maximum created tickets based on different criteria.
It also ensure that the email address being used is valid (with MX-Check on the email’s domain).
Another way to make it harder for bots to automate against your Zammad instance is to change the location of form.js
( /opt/zammad/assets/form/form.js ).
Please keep in mind if you change the location of form.js (by e.g. copying) that you need to ensure that your form.js stays up to date if you update Zammad.
Further more it’s not recommended to delete form.js from it’s location, but to forbid the access to it with your webserver configuration (if wanted).
Google is in the process of upgrading its security policies.
To stay up-to-date, do not add your account as an email channel—instead,
create a Google channel.
Microsoft 365 users:
Microsoft is in the process of upgrading its security policies.
To stay up-to-date, do not add your account as an email channel—instead,
create a Microsoft 365 channel.
If your account login/username is different from your email address,
use the Experts dialog (see below).
If your inbox receives mail for more than one email address,
be sure to add your alternate addresses
after account setup.
Passwort
Your account password.
If your email provider requires you to enter
a one-time passcode (sent via SMS) when logging in,
you’ll have to generate an app password to use with Zammad.
Your email server’s hostname or IP address (e.g.,imap.gmail.com).
Contact your email provider or system administrator if you don’t know.
Passwort
Your account password.
If your email provider requires you to enter
a one-time passcode (sent via SMS) when logging in,
you’ll have to generate an app password to use with Zammad.
SSL / STARTTLS
Enable encryption when fetching messages.
Choose from yes and no;
Zammad will detect which protocol to use.
Port
Your email server’s port (usu. 993 for IMAP, or 995 for POP3).
Contact your email provider or system administrator if you don’t know.
Folder
Specify which folder to fetch from, or leave empty to fetch from INBOX.
If specifying a nested folder, be sure to use the full path.
(Some systems use different path separators;
e.g.,Inquiries/Tech-Support vs. Inquiries.Tech-Support.
Contact your email provider or system administrator if you don’t know.)
Bemerkung
📥 Additional Steps Required
In the last step of the account setup process,
Zammad sends you an email from your own account,
then waits for it to appear in the folder specified here.
Account verification will not complete until
this test message has been received.
If this folder does not receive incoming messages automatically,
you may have to manually check your inbox during the verification step
and move Zammad’s test message there when it arrives.
Keep messages on server
Specify what happens to your emails after Zammad imports them:
no Zammad deletes all imported messages
yes Zammad marks imported messages as read
(With this option, Zammad will only import unread messages.
This means Zammad may miss messages if the mailbox is externally modified.)
Bemerkung
🤔 Why does Zammad delete messages by default?
If you never clean out your inbox,
it’ll eventually reach its storage limit,
and your mail server will start rejecting incoming messages.
Most Zammad users never even look at their inbox once it’s set up,
so they rely on Zammad to keep it clean for them.
If you choose yes here, remember that it’s your responsibility
to clean out your inbox from time to time
to keep it below its storage limit.
During the import process, Zammad treats all messages
(including ones you’ve already read from months or years ago)
as if they had been sent today:
senders will receive auto-replies saying
“your message has been received and we’ll get back to you within 24 hours,”
and tickets created for each message will be marked as “new”.
Use this option to disable this behavior for messages more than two weeks old.
Bemerkung
This option may not be shown if:
all messages in your inbox are less than two weeks old
you selected Keep messages on server: Yes
you selected Type: POP3
For more fine-grained control,
manually disable this and other triggers
before adding an email account,
then turn them back on once all your messages have been imported.
As a final step, Zammad sends a test email
from your own account, to your own account.
Once this test email is received, the new account setup process is complete! 🎉
Secondary addresses (also known as aliases) allow you to send emails
with a different “From:” address from the one on the account.
Once you add a secondary address,
you can configure a group to start sending emails with it.¶
Warnung
🙅 Do not abuse this feature.
If you use secondary addresses to impersonate other parties,
your IP is liable to get added to a spam blacklist.
Your email provider may also be set up to receive incoming messages
for many addresses in the same mailbox.
If this is the case, be sure to add your alternate inbox addresses here.
Display Name
The display name used for outgoing email.
A customer’s inbox with an auto-reply from Chrispresso Sales.¶
Disabling an account temporarily prevents Zammad from importing its messages.
This may be necessary during scheduled maintenance
or when migrating your installation to a new host.
Bemerkung
📮 Disabling an account disables outgoing messages for it, as well.
Delete
Deleting an account removes its configuration from Zammad entirely.
Bemerkung
🧹 Additional Steps Required
When an email account is deleted,
its email aliasesremain in the system.
Be sure to reassign or delete them manually.
Click on the address to assign it to another account, or click ✖ to delete it.¶
Groups need an assigned an address to send outgoing emails.
If you delete a group’s assigned address,
agents belonging to that group won’t be able to send emails
until you assign it a new one.
Postmaster filters allow you to match email headers (e.g. From, To, Subject, X-Spam-Flag etc.) and execute a set of actions whenever Zammad’s email parser encounters a matching email. The actions will be applied to the ticket that is created or updated by this email. Here are some examples of what is possible with filters:
Automatically dispatch tickets into certain groups:
For example, tickets from amazon.com could automatically be dispatched to the Purchasing group.
From: contains: regex:(\.|@)amazon\.com
Group: Purchasing
Bemerkung
Note that the Group action only has an effect when the matching email results in a new ticket. Zammad will not change the group of existing tickets.
Automatically increase the priority of tickets from a VIP customer:
From: contains: ourvipcustomer@example.com
Priority: 3 high
Bemerkung
Note that the Priority action only has an effect when the matching email results in a new ticket. Zammad will not change the priority of existing tickets.
Automatically tag and close spam tickets that have been marked as spam by an external spam filter (e.g. SpamAssassin):
X-Spam-Flag: contains: YES
Tag: add: spam
State: closed
Bemerkung
Note that the State action only has an effect when the matching email results in a new ticket. Zammad will not change the state of existing tickets. It will add the tag though if it missing, even if the mail is an update to an existing ticket.
The following actions are only effective when creating tickets: Group, State, Priority, Owner.
Different attributes of a filter can be combined with each other. Likewise, the following actions can be combined. The supported matches are „contains“ and „contains not“; for advanced matching, you can use regular expressions by prefixing the string with regex:.
Note that Zammad matches against the full header, e.g. for a mail with „From:DisplayName<display.name@example.com>“, the From condition will test against „DisplayName<display.name@example.com>“. This is especially important when using anchored regular expressions; regex:^display\.name@example.com$ would not match this mail!
It should be borne in mind that the combined attributes build on each other. If a filter is no longer needed, it can either be temporarily set inactive or deleted directly.
To individualize the signatures, it is possible to automatically load specific information into a signature via Variables. All information stored on the ticket, assigned customers or agents can be inserted. This makes it possible to design the signature individually. To load a list of available variables, enter two colons (::) into the Text box of the signature editor.
Hinweis
Please keep in mind that specific information might not be available during ticket creation. The best example here is the ticket number / id. Specific information are created with submitting the ticket and thus are not available before submitting.
Here is an example of a signature with variables and the result when you write a mail:
Notification Sender: Default value NotificationMaster<noreply@#{config.fqdn}>
This is the default sender address for Zammad that affects all mails but
those generated because of replies (like triggers or agent-based mails).
Your customers normally will not see this address. This email address does
not need to receive and can’t be assigned to a group.
Bemerkung
This address is relevant for agent notifications and password reset mails
(also affects customers).
Additional follow-up detection
In some situations the normal follow-up detection is not enough.
This might be due to missing references in the subject
(the ticket hook and number). These options can help to recognize follow-ups
to existing tickets.
Bemerkung
Please note that searching in attachment and body might lead to false
follow-up detections.
Maximum Email Size: Default value 10MB
This one is pretty obvious: It defines the maximum allowed size of an email
Zammad will fetch. Zammad will not fetch Mails that are bigger than this
option.
Hinweis
This technically also affects attachments for articles.
Send postmaster mail if mail too large: Default value yes(enabled)
Bemerkung
Upgraded installations will, by default, have the value set to
no(disabled).
Option set to yes
This setting will cause Zammad to automatically reply to mails that exceed
the above mail size limit with a postmaster style mail.
This will help your user to understand that his mail did not arrive and
won’t be reviewed by you.
Bemerkung
Zammad will still download and remove (if enabled) the mail from the
mailbox. Instead of importing it to the database, it will save the
affected mail to /opt/zammad/tmp/oversized_mail/.
Option set to no
If the option is set to no, Zammad will not reply to mails that are too
big. Your customer will not notice that the mail was too large!
Instead, Zammad will use the monitoring endpoint to alert its
administrators that it can’t fetch a too large mail.
Sender based on Reply-To header: Default value notset(-)
This setting decides how Zammad should recognize its customers from emails
that contain a Reply-To header. This comes in useful if you’re working
with contact forms that need to use reply to headers.
Option set to - or Takereply-toheaderassender/fromofemail
This setting will overwrite the initial FROM to the value used in
Reply-To completely.
Option set to Takereply-toheaderassender/fromofemailanduserealnameoforiginfrom
This setting will partially overwrite the initial FROM.
It uses the mail address from the Reply-To header and uses the given
name of the FROM header, if given.
Customer selection based on sender and receive list: Default value yes
This option decides how Zammad should react if an agent sends a email to it.
Option set to yes
The first user / email address from the recipient list will be used as
the ticket customer.
Option set to no
The agent will be set as ticket customer.
Bemerkung
Currently agents can’t be customers within the UI.
While Email communication works, agents can’t see their own tickets
(as a customer) if they don’t have access to the group.
Block Notifications
With the regex that can be defined here, you can ensure not to send any
notifications to specific systems. By default this especially affects typical
system addresses which can’t receive emails anyway.
The default value is:
(mailer-daemon|postmaster|abuse|root|noreply|noreply.+?|no-reply|no-reply.+?)@.+?
Sender Format: Default value Agent+FormatSeperator+SystemAddressDisplayName
This configures the display name used in the FROM header of mails
Zammad sends.
Bemerkung
This does not affect Notification mails (to agents) and password reset
mails. Emails that are not sent by agents
(e.g. trigger-based notifications) will always fallback to
SystemAddressDisplayName if needed.
Option set to Agent+FormatSeparator+SystemAddressDisplayName
This will cause Zammad to set the FROM header to agent name and the
channel’s display name, divided by a separator (configured below).
Example: ChristopherMillerviaChrispressoInc..
Option set to SystemAddressDisplayName
This will cause Zammad to always use the display name of the used channel
in the FROM header.
Example: ChrispressoInc.
Option set to AgentName
Zammad will use the agent’s name which is very personal.
Tipp
Usually you’d also want to remove the ticket slug from the subject
in those cases.
This is a can be a string you can freely choose. It divides the agent’s name
and the display name of the channel whenever needed.
Ticket Subject Forward: Default value FWD
The above string will be used on the subject if you forward an email from
Zammad.
Bemerkung
: will be automatically appended to the above string.
Ticket Subject Reply: Default value RE
The above string will be used on the subject if you reply to a mail from
Zammad.
Bemerkung
: will be automatically appended to the above string.
Ticket Subject Size: Default value 110
This setting enforces a maximum length for subjects when replying.
If the subject you’re using for your reply is too long, Zammad will
automatically truncate the length and insert [...] to show it has
shortened the subject.
Example: RE:Testsomew[...][Ticket#123456]
Bemerkung
This does not limit ticket titles within the UI, just the subjects
when replying to an email.
Some less relevant settings can be changed via rails console if needed.
As an example, Zammad allows you to send all outgoing communication to a BCC
address for archiving reasons if needed. You can find the needed commands
within the advanced customization settings.
Email header manipulation allows you to re-route or adjust tickets apart from
filters or triggers. Like an API call, but with emails.
Header checks are case insensitive.
Warnung
🛡 Trusted channels required 🛡
Below options are a potential risk with external communication and
thus require channels being set to trusted explicitly.
Tipp
Below headers are examples and –in our opinion– the most relevant ones.
However: You can adjust mostly any article or ticket attribute (yes, custom
ones as well) if you know the attribute’s exact name.
The name column within object’s management provides
easy access to objects attribute names. 🤓
Normally Zammad runs internal checks to see if an email is an automatic
response. In these cases Zammad will not send trigger based responses.
There may be use cases where this behavior may be in your way,
below options allow you to overcome this issue.
Bemerkung
In some cases combining below headers is crucial.
This is intentional but may be confusing.
x-zammad-send-auto-response
Set to false to disable trigger based responses.
If set to true Zammad will send a response.
Hinweis
This option does not work if e.g. precedence:list is set
unless you use below auto response header as well.
x-zammad-is-auto-response
Providing this header allows you to tell Zammad that the mail in question
is an auto generated response (true). This will cause email based
triggers to be skipped.
Set this header to false if you want to generate auto responses.
Tipp
This header allows you to overwrite auto detects for e.g.
precedence:list.
Zammad allows you to use headers to manipulate ticket creations or follow ups.
The manipulation can be used instead of triggers. Triggers are considered
after header settings and thus can still overrule.
Bemerkung
🔎 Zammad differentiates between ticket creation and follow up
For creations use: X-Zammad-Ticket-{AttributeName}
For follow ups use: X-Zammad-Ticket-FollowUp-{AttributeName}
This allows you to ensure the changes are only applied in the
required situation.
Warnung
🧐 About values
While headers are not case sensitive, values like e.g. priority names
are case censitive: 1low will work, but 1lOw will not!
When using attributes that require date / time values, ensure to use
Time Zoned Times. e.g. for 28th September 2021 on 8 am CEST, either use:
Maybe you want to add emails via Fetchmail or Procmail to Zammad.
To get this to work you need to pipe your emails to rails.
Bemerkung
If you installed Zammad through a package manager (rather than from source),
replace railsr with zammadrunrailsr below.
To learn more, see Administration via Console.
# --# Pipe all emails into Zammad# --PATH=/opt/zammad/bin:/opt/zammad/vendor/bundle/bin:/sbin:/bin:/usr/sbin:/usr/bin:SYS_HOME="/home/zammad"RAILS_ENV=productionGEM_PATH=/opt/zammad/vendor/bundle/ruby/2.4.1/LOGFILE="$SYS_HOME/procmail.log"#VERBOSE="on":0:|railsr'Channel::Driver::MailStdin.new(trusted: true)'
For the initial setup of this you need administrative rights on the Zammad machine (console).
If you try to configure only an outgoing email account
(as in, you do not wish to set up an incoming IMAP/POP3 account at all),
you will find that it’s simply not possible via the email channel setup wizard.
Instead, you will have to create it via the CLI.
(The wizard is designed to provide an idiot-proof email configuration process
for the average, non-technical user,
so certain advanced options and use cases have been deliberately omitted.)
To configure Zammad to use sendmail,
run the following command (you can use rails r […] if you installed Zammad from source):
Der Chat ist für den Unternehmens- und allgemeinen Kundensupport sehr wichtig geworden. Richtig eingesetzt, kann der Support per Chat eine echte Effizienzsteigerung darstellen. Ein Nachteil von Chats ist, wenn niemand antwortet oder ein Bot auf den Kunden antwortet.
Die Aufgabe ist klar: Arbeiten Sie an den Nachteilen eines regelmäßigen Support-Chats und verbessern Sie diese.
Unser Ansatz lautet wie folgt
Das Chat-Widget wird nur angezeigt, wenn mindestens ein Agent verfügbar ist und der Agent noch Kapazitäten hat.
Wenn kein Agent online ist oder die Agenten abwesend sind, wird der Chat nicht verfügbar sein
Wir setzen einen Agenten als inaktiv, wenn der Agent keine neuen Chat-Anfragen annimmt oder die WebApp offline ist. Auf diese Weise können Ihre Support-Mitarbeiter Pausen einlegen, ohne dass Ihre Kunden ewig auf eine Reaktion warten müssen (siehe Punkt oben)
Zammad antwortet nicht von sich aus auf Chat-Nachrichten, um sicherzustellen, dass es keine seltsamen Verzögerungen gibt. Zammad sendet eine (vom Agenten konfigurierbare) automatische Antwort, sobald der Agent die Chat-Anfrage annimmt.
Zammad wird versuchen, die Farben Ihrer Haupt-Website an den Chat anzupassen. Sie können diese Farben auch anpassen, so dass Sie den Chat in Ihre Website integrieren können, als ob er schon vorher da gewesen wäre.
Sie können Chat-Widgets für Ihre Webseiten erstellen, mit denen Besucher mit Ihnen chatten können.
Der Bereich zur Konfiguration des Chats befindet sich im Verwaltungsbereich unter Channels → Chat:
Sie können Chats für verschiedene Websites einrichten und diese unabhängig voneinander bearbeiten. Der integrierte Designer hilft dem Chat-Widget, sich an die Farbe der Website anzupassen. Wenn Ihnen das vorgeschlagene Design nicht gefällt, können Sie das Design manuell anpassen. Durch die verschiedenen Vorschaubilder haben Sie die Möglichkeit, direkt zu sehen, wie die Präsentation auf verschiedenen Geräten aussieht.
Nutzung
Fügen Sie den Widget-Code in den Quellcode jeder Seite ein, auf welcher der Chat sichtbar sein soll. Er sollte am Ende des Quellcodes der Seite vor dem schließenden </body>-Tag platziert werden.
Ergebnis
Das Endergebnis wird wie folgt aussehen:
Voraussetzungen
Der Zammad-Chat erfordert jQuery. Wenn Sie es nicht bereits auf Ihrer Website verwenden, fügen Sie es wie folgt ein:
Sie haben zwei Möglichkeiten, den Chat auf Ihrer Website zu implementieren:
Automatisch den Chat anzeigen (das ist die Standardeinstellung)
oder öffnen Sie den Chat manuell.
Chat-Einschränkungen
Sie bieten einen Chat für Ihre Zielgruppe an, möchten aber den Chat für bestimmte IP-Adressen oder Länder nicht freischalten? Dann haben Sie die Möglichkeit, die gewünschten IP-Adressen und Länder schnell und einfach über die Chat-Konfiguration im Admin-Panel zu sperren. Das Konfigurationspanel sieht wie folgt aus:
Weitere Informationen über die Chat-Anpassung finden Sie auch im Verwaltungsbereich.
Setting up a new Gmail / G Suite account?
Because of Google’s strict security policies,
it’s not as simple as entering your username and password.
First, you’ll have to connect Zammad to your Google account as an OAuth app
via the Google Developer settings panel.
Once that’s done, you’ll be able to connect as many Gmail accounts to Zammad as you want,
using only active Gmail browser sessions (no usernames or passwords required).
Bemerkung
🤔 What the heck is OAuth?
If you’ve ever used a website that lets you
“Sign in with Google/Facebook/Twitter”, you’ve used OAuth.
OAuth is a way for you to let a third-party website see a tiny slice
of your Google/Facebook/Twitter account data
without giving them your password (which would let them see everything).
When a third-party website wants to use OAuth,
it has to register with the provider first (i.e., Google).
This way, the provider knows who’s receiving its users’ data,
and can give users a way to revoke access if they change their minds.
In this case, Zammad is that third-party website.
That’s why adding a Gmail account is a two-stage process:
first, you have to register Zammad as a website that wishes to access Google user data;
then, you have to add yourself as a Google user who agrees to let Zammad fetch your email.
For the purposes of this guide, a “project” and an OAuth app are the same thing.
You may name it whatever you wish.
Enable & add the Gmail API
Use the ➕ Enable APIs and Services button to start your search.
Set up the OAuth consent screen
Configure who can use your app, what kind of access it’s asking for,
and a few fine print details (like a link to Zammad’s privacy policy).
This information will be displayed in the process of connecting a Gmail account to Zammad,
when users are redirected to Google for sign-in/confirmation.
User Type
This option is only available to G Suite users.
If you have the option, choose Internal
(unless you plan on creating channels for Gmail addresses
from outside your G Suite domain).
Scopes for Google APIs
Add Gmail API: https://mail.google.com.
Generate OAuth credentials
Click on ➕ Create credentials > OAuth client ID to begin.
If you’ve already added your Gmail account as a regular email channel,
you’ll have to convert it to a Google channel eventually:
Google is planning to end support for simple password authentication
in third-party email clients (like Zammad).
But there’s no rush just yet.
Upcoming versions of Zammad will feature an automated migration wizard
to help you make the switch, and it’ll be available
well before Google officially pulls the plug on password auth.
Hinweis
If you’d prefer not to wait, you can do it manually today—just
remember to delete the email channel for your Gmail account
(and all its associated aliases) before re-adding it here.
Make sure you don’t have any of these left over before creating your new Google channel.¶
Click Add Account to connect your Gmail / G Suite accounts to Zammad.
You will be redirected to a Google sign-in and confirmation page.
Any aliases registered in your Gmail settings will be imported automatically.
Bemerkung
Google has a stringent verification process
to protect users from third-party websites that use OAuth to access their data.
Since you are the third-party website here,
you can safely ignore this warning.
Specify which folder (or label) to fetch from,
or leave empty to fetch from INBOX.
If specifying a nested folder, be sure to use the full path;
e.g.,Inquiries/Tech-Support.
Keep messages on server
Specify what happens to your emails after Zammad imports them:
no Zammad deletes all imported messages
yes Zammad marks imported messages as read
(With this option, Zammad will only import unread messages.
This means Zammad may miss messages if the mailbox is externally modified.)
Bemerkung
🤔 Why does Zammad delete messages by default?
If you never clean out your inbox,
it’ll eventually reach its storage limit,
and your mail server will start rejecting incoming messages.
Most Zammad users never even look at their inbox once it’s set up,
so they rely on Zammad to keep it clean for them.
If you choose yes here, remember that it’s your responsibility
to clean out your inbox from time to time
to keep it below its storage limit.
Secondary addresses (also known as aliases) allow you to send emails
with a different “From:” address from the one on the account.
Once you add a secondary address,
you can configure a group to start sending emails with it.¶
Warnung
👀 Secondary addresses must be added and verified in your Gmail settings first.
Gmail has its own process for adding and verifying aliases
(under Settings > Accounts and Import > Send mail as).
If you add an alias here before adding it in your Gmail settings,
Google will refuse to dispatch it.
G Suite users may need to contact their administrators
in order to add aliases in their Gmail settings.
Your email provider may also be set up to receive incoming messages
for many addresses in the same mailbox.
If this is the case, be sure to add your alternate inbox addresses here.
Display Name
The display name used for outgoing email.
A customer’s inbox with an auto-reply from Chrispresso Sales.¶
Disabling an account temporarily prevents Zammad from importing its messages.
This may be necessary during scheduled maintenance
or when migrating your installation to a new host.
Bemerkung
📮 Disabling an account disables outgoing messages for it, as well.
Delete
Deleting an account removes its configuration from Zammad entirely.
Bemerkung
🧹 Additional Steps Required
Groups need an assigned an address to send outgoing emails.
If you delete a group’s assigned address,
agents belonging to that group won’t be able to send emails
until you assign it a new one.
(There’s no need to manage orphaned email addresses like you would on an
email channel. In Google channels, aliases are connected to your Gmail
account, which means they can be imported and purged automatically.)
Edit the configuration of existing accounts in the Accounts Panel.
Bemerkung
🤔 How do I use my Gmail account for outgoing system notifications?
On subscription/cloud-hosted instances, you can’t.
Notifications will always come from “Notification Master <noreply@your.zammad.domain>”.
On self-hosted instances, we still don’t recommend it.
Using a Gmail account for automated, outgoing messages is risky:
users who exceed Google’s email sending limits
can have their accounts suspended.
Postmaster filters allow you to match email headers (e.g. From, To, Subject, X-Spam-Flag etc.) and execute a set of actions whenever Zammad’s email parser encounters a matching email. The actions will be applied to the ticket that is created or updated by this email. Here are some examples of what is possible with filters:
Automatically dispatch tickets into certain groups:
For example, tickets from amazon.com could automatically be dispatched to the Purchasing group.
From: contains: regex:(\.|@)amazon\.com
Group: Purchasing
Bemerkung
Note that the Group action only has an effect when the matching email results in a new ticket. Zammad will not change the group of existing tickets.
Automatically increase the priority of tickets from a VIP customer:
From: contains: ourvipcustomer@example.com
Priority: 3 high
Bemerkung
Note that the Priority action only has an effect when the matching email results in a new ticket. Zammad will not change the priority of existing tickets.
Automatically tag and close spam tickets that have been marked as spam by an external spam filter (e.g. SpamAssassin):
X-Spam-Flag: contains: YES
Tag: add: spam
State: closed
Bemerkung
Note that the State action only has an effect when the matching email results in a new ticket. Zammad will not change the state of existing tickets. It will add the tag though if it missing, even if the mail is an update to an existing ticket.
The following actions are only effective when creating tickets: Group, State, Priority, Owner.
Different attributes of a filter can be combined with each other. Likewise, the following actions can be combined. The supported matches are „contains“ and „contains not“; for advanced matching, you can use regular expressions by prefixing the string with regex:.
Note that Zammad matches against the full header, e.g. for a mail with „From:DisplayName<display.name@example.com>“, the From condition will test against „DisplayName<display.name@example.com>“. This is especially important when using anchored regular expressions; regex:^display\.name@example.com$ would not match this mail!
It should be borne in mind that the combined attributes build on each other. If a filter is no longer needed, it can either be temporarily set inactive or deleted directly.
Bemerkung
Signatures in Google channels are just like signatures in email channels,
so this article is lifted verbatim from here.
To individualize the signatures, it is possible to automatically load specific information into a signature via Variables. All information stored on the ticket, assigned customers or agents can be inserted. This makes it possible to design the signature individually. To load a list of available variables, enter two colons (::) into the Text box of the signature editor.
Hinweis
Please keep in mind that specific information might not be available during ticket creation. The best example here is the ticket number / id. Specific information are created with submitting the ticket and thus are not available before submitting.
Here is an example of a signature with variables and the result when you write a mail:
Bemerkung
Settings in Google channels are just like settings in email channels,
so this article is lifted verbatim from here.
Notification Sender: Default value NotificationMaster<noreply@#{config.fqdn}>
This is the default sender address for Zammad that affects all mails but
those generated because of replies (like triggers or agent-based mails).
Your customers normally will not see this address. This email address does
not need to receive and can’t be assigned to a group.
Bemerkung
This address is relevant for agent notifications and password reset mails
(also affects customers).
Additional follow-up detection
In some situations the normal follow-up detection is not enough.
This might be due to missing references in the subject
(the ticket hook and number). These options can help to recognize follow-ups
to existing tickets.
Bemerkung
Please note that searching in attachment and body might lead to false
follow-up detections.
Maximum Email Size: Default value 10MB
This one is pretty obvious: It defines the maximum allowed size of an email
Zammad will fetch. Zammad will not fetch Mails that are bigger than this
option.
Hinweis
This technically also affects attachments for articles.
Send postmaster mail if mail too large: Default value yes(enabled)
Bemerkung
Upgraded installations will, by default, have the value set to
no(disabled).
Option set to yes
This setting will cause Zammad to automatically reply to mails that exceed
the above mail size limit with a postmaster style mail.
This will help your user to understand that his mail did not arrive and
won’t be reviewed by you.
Bemerkung
Zammad will still download and remove (if enabled) the mail from the
mailbox. Instead of importing it to the database, it will save the
affected mail to /opt/zammad/tmp/oversized_mail/.
Option set to no
If the option is set to no, Zammad will not reply to mails that are too
big. Your customer will not notice that the mail was too large!
Instead, Zammad will use the monitoring endpoint to alert its
administrators that it can’t fetch a too large mail.
Sender based on Reply-To header: Default value notset(-)
This setting decides how Zammad should recognize its customers from emails
that contain a Reply-To header. This comes in useful if you’re working
with contact forms that need to use reply to headers.
Option set to - or Takereply-toheaderassender/fromofemail
This setting will overwrite the initial FROM to the value used in
Reply-To completely.
Option set to Takereply-toheaderassender/fromofemailanduserealnameoforiginfrom
This setting will partially overwrite the initial FROM.
It uses the mail address from the Reply-To header and uses the given
name of the FROM header, if given.
Customer selection based on sender and receive list: Default value yes
This option decides how Zammad should react if an agent sends a email to it.
Option set to yes
The first user / email address from the recipient list will be used as
the ticket customer.
Option set to no
The agent will be set as ticket customer.
Bemerkung
Currently agents can’t be customers within the UI.
While Email communication works, agents can’t see their own tickets
(as a customer) if they don’t have access to the group.
Block Notifications
With the regex that can be defined here, you can ensure not to send any
notifications to specific systems. By default this especially affects typical
system addresses which can’t receive emails anyway.
The default value is:
(mailer-daemon|postmaster|abuse|root|noreply|noreply.+?|no-reply|no-reply.+?)@.+?
Sender Format: Default value Agent+FormatSeperator+SystemAddressDisplayName
This configures the display name used in the FROM header of mails
Zammad sends.
Bemerkung
This does not affect Notification mails (to agents) and password reset
mails. Emails that are not sent by agents
(e.g. trigger-based notifications) will always fallback to
SystemAddressDisplayName if needed.
Option set to Agent+FormatSeparator+SystemAddressDisplayName
This will cause Zammad to set the FROM header to agent name and the
channel’s display name, divided by a separator (configured below).
Example: ChristopherMillerviaChrispressoInc..
Option set to SystemAddressDisplayName
This will cause Zammad to always use the display name of the used channel
in the FROM header.
Example: ChrispressoInc.
Option set to AgentName
Zammad will use the agent’s name which is very personal.
Tipp
Usually you’d also want to remove the ticket slug from the subject
in those cases.
This is a can be a string you can freely choose. It divides the agent’s name
and the display name of the channel whenever needed.
Ticket Subject Forward: Default value FWD
The above string will be used on the subject if you forward an email from
Zammad.
Bemerkung
: will be automatically appended to the above string.
Ticket Subject Reply: Default value RE
The above string will be used on the subject if you reply to a mail from
Zammad.
Bemerkung
: will be automatically appended to the above string.
Ticket Subject Size: Default value 110
This setting enforces a maximum length for subjects when replying.
If the subject you’re using for your reply is too long, Zammad will
automatically truncate the length and insert [...] to show it has
shortened the subject.
Example: RE:Testsomew[...][Ticket#123456]
Bemerkung
This does not limit ticket titles within the UI, just the subjects
when replying to an email.
Some less relevant settings can be changed via rails console if needed.
As an example, Zammad allows you to send all outgoing communication to a BCC
address for archiving reasons if needed. You can find the needed commands
within the advanced customization settings.
Bemerkung
EMail header manipulation in Google channels work
just like in email channels, so this article is lifted verbatim from
here.
Email header manipulation allows you to re-route or adjust tickets apart from
filters or triggers. Like an API call, but with emails.
Header checks are case insensitive.
Warnung
🛡 Trusted channels required 🛡
Below options are a potential risk with external communication and
thus require channels being set to trusted explicitly.
Tipp
Below headers are examples and –in our opinion– the most relevant ones.
However: You can adjust mostly any article or ticket attribute (yes, custom
ones as well) if you know the attribute’s exact name.
The name column within object’s management provides
easy access to objects attribute names. 🤓
Normally Zammad runs internal checks to see if an email is an automatic
response. In these cases Zammad will not send trigger based responses.
There may be use cases where this behavior may be in your way,
below options allow you to overcome this issue.
Bemerkung
In some cases combining below headers is crucial.
This is intentional but may be confusing.
x-zammad-send-auto-response
Set to false to disable trigger based responses.
If set to true Zammad will send a response.
Hinweis
This option does not work if e.g. precedence:list is set
unless you use below auto response header as well.
x-zammad-is-auto-response
Providing this header allows you to tell Zammad that the mail in question
is an auto generated response (true). This will cause email based
triggers to be skipped.
Set this header to false if you want to generate auto responses.
Tipp
This header allows you to overwrite auto detects for e.g.
precedence:list.
Zammad allows you to use headers to manipulate ticket creations or follow ups.
The manipulation can be used instead of triggers. Triggers are considered
after header settings and thus can still overrule.
Bemerkung
🔎 Zammad differentiates between ticket creation and follow up
For creations use: X-Zammad-Ticket-{AttributeName}
For follow ups use: X-Zammad-Ticket-FollowUp-{AttributeName}
This allows you to ensure the changes are only applied in the
required situation.
Warnung
🧐 About values
While headers are not case sensitive, values like e.g. priority names
are case censitive: 1low will work, but 1lOw will not!
When using attributes that require date / time values, ensure to use
Time Zoned Times. e.g. for 28th September 2021 on 8 am CEST, either use:
If you’re already familiar with email channels,
you can skip most of this—but watch out for the “Accounts” section,
which has a few extra quirks due to Google’s strict security measures.
Setting up a new Microsoft365 / Outlook account?
Because of Microsoft’s strict security policies,
it’s not as simple as entering your username and password.
First, you’ll have to connect Zammad to your Microsoft account as an OAuth app
via the Microsoft Azure Portal.
Once that’s done, you’ll be able to connect as many Microsoft 365 accounts to Zammad as you want,
using only active Microsoft 365 browser sessions (no usernames or passwords required).
Bemerkung
🤔 What the heck is OAuth?
If you’ve ever used a website that lets you
“Sign in with Google/Facebook/Twitter”, you’ve used OAuth.
OAuth is a way for you to let a third-party website see a tiny slice
of your Microsoft/Facebook/Twitter account data
without giving them your password (which would let them see everything).
When a third-party website wants to use OAuth,
it has to register with the provider first (i.e., Microsoft).
This way, the provider knows who’s receiving its users’ data,
and can give users a way to revoke access if they change their minds.
In this case, Zammad is that third-party website.
That’s why adding a Microsoft account is a two-stage process:
first, you have to register Zammad as a website that wishes to access Microsoft user data;
then, you have to add yourself as a Microsoft user who agrees to let Zammad fetch your email.
Otherwise, an admin will have to approve your changes
before they can take effect.
Add an App Registration
Under App Registrations > ➕ New Registration,
use the following:
Supported account types
Choose the option that’s right for your organization
(or click Help me choose… if you’re not sure).
Accounts in this organizational directory only
(Default Directory only - Single tenant)
Accounts in any organizational directory
(Any Azure AD directory - Multitenant)
Accounts in any organizational directory
(Any Azure AD directory - Multitenant)
and personal Microsoft accounts (e.g. Skype, Xbox)
Bemerkung
🙅 The “Personal Microsoft accounts only” option is not supported.
Redirect URI
Web > E.g.,https://your-domain.com/api/v1/external_credentials/microsoft365/callback
Find it in the Zammad admin panel
under Channels > Microsoft 365 > Connect Microsoft 365 App > Your callback URL.
Add API permissions
Under API Permissions > ➕ Add a permission > Microsoft Graph > Delegated permissions, add the following:
OpenId permissions
email
offline_access
openid
profile
IMAP
IMAP.AccessAsUser.all
SMTP
SMTP.Send
Connect your Microsoft app in Zammad
Copy your new app registration’s Application (client) ID and
Directory (tenant) ID (found under Overview > Essentials)
into Zammad in the admin panel,
under Channels > Microsoft 365 > Connect Microsoft 365 App.
Then, create a new client secret
under Certificates and Secrets > ➕ New Client Secret
and copy that into the Zammad admin panel, as well.
🍾 Congratulations! Now you’re ready to connect Microsoft 365 or Outlook accounts to Zammad.
If you’ve already added your Microsoft 365 account as a regular email channel,
you’ll have to convert it to a Microsoft 365 channel eventually:
Microsoft is planning to end support for simple password authentication
in third-party email clients (like Zammad).
But there’s no rush just yet.
Upcoming versions of Zammad will feature an automated migration wizard
to help you make the switch, and it’ll be available
well before Microsoft officially pulls the plug on password auth.
Hinweis
If you’d prefer not to wait, you can do it manually today—just
remember to delete the email channel for your Microsoft account
(and all its associated aliases) before re-adding it here.
Make sure you don’t have any of these left over before creating your new Microsoft 365 channel.¶
Specify which folder (or label) to fetch from,
or leave empty to fetch from INBOX.
If specifying a nested folder, be sure to use the full path;
e.g.,Inquiries/Tech-Support.
Keep messages on server
Specify what happens to your emails after Zammad imports them:
no Zammad deletes all imported messages
yes Zammad marks imported messages as read
(With this option, Zammad will only import unread messages.
This means Zammad may miss messages if the mailbox is externally modified.)
Bemerkung
🤔 Why does Zammad delete messages by default?
If you never clean out your inbox,
it’ll eventually reach its storage limit,
and your mail server will start rejecting incoming messages.
Most Zammad users never even look at their inbox once it’s set up,
so they rely on Zammad to keep it clean for them.
If you choose yes here, remember that it’s your responsibility
to clean out your inbox from time to time
to keep it below its storage limit.
Secondary addresses in Microsoft 365 channels
work (almost) just like they do in email channels,
so this article is lifted (almost) verbatim
from here.
wählen Sie einen Benutzer unter Empfänger > Postfächer,
editieren Sie diesen (Doppelklick oder ✏️), und
fügen Sie einen neuen Alias unter E-Mail Adressen hinzu.
Kontaktieren Sie Ihre Administrator, falls Sie keinen Zugriff auf einen Administrator-Account haben.
Your email provider may also be set up to receive incoming messages
for many addresses in the same mailbox.
If this is the case, be sure to add your alternate inbox addresses here.
Display Name
The display name used for outgoing email.
A customer’s inbox with an auto-reply from Chrispresso Sales.¶
Disabling an account temporarily prevents Zammad from importing its messages.
This may be necessary during scheduled maintenance
or when migrating your installation to a new host.
Bemerkung
📮 Disabling an account disables outgoing messages for it, as well.
Delete
Deleting an account removes its configuration from Zammad entirely.
Bemerkung
🧹 Additional Steps Required
Groups need an assigned an address to send outgoing emails.
If you delete a group’s assigned address,
agents belonging to that group won’t be able to send emails
until you assign it a new one.
Edit the configuration of existing accounts in the Accounts Panel.
Bemerkung
🤔 How do I use my Microsoft 365 account for outgoing system notifications?
On subscription/cloud-hosted instances, you can’t.
Notifications will always come from “Notification Master <noreply@your.zammad.domain>”.
On self-hosted instances, we still don’t recommend it.
Using a Microsoft account for automated, outgoing messages is risky:
users who exceed Microsoft’s email sending limits
can have their accounts suspended.
Postmaster filters allow you to match email headers (e.g. From, To, Subject, X-Spam-Flag etc.) and execute a set of actions whenever Zammad’s email parser encounters a matching email. The actions will be applied to the ticket that is created or updated by this email. Here are some examples of what is possible with filters:
Automatically dispatch tickets into certain groups:
For example, tickets from amazon.com could automatically be dispatched to the Purchasing group.
From: contains: regex:(\.|@)amazon\.com
Group: Purchasing
Bemerkung
Note that the Group action only has an effect when the matching email results in a new ticket. Zammad will not change the group of existing tickets.
Automatically increase the priority of tickets from a VIP customer:
From: contains: ourvipcustomer@example.com
Priority: 3 high
Bemerkung
Note that the Priority action only has an effect when the matching email results in a new ticket. Zammad will not change the priority of existing tickets.
Automatically tag and close spam tickets that have been marked as spam by an external spam filter (e.g. SpamAssassin):
X-Spam-Flag: contains: YES
Tag: add: spam
State: closed
Bemerkung
Note that the State action only has an effect when the matching email results in a new ticket. Zammad will not change the state of existing tickets. It will add the tag though if it missing, even if the mail is an update to an existing ticket.
The following actions are only effective when creating tickets: Group, State, Priority, Owner.
Different attributes of a filter can be combined with each other. Likewise, the following actions can be combined. The supported matches are „contains“ and „contains not“; for advanced matching, you can use regular expressions by prefixing the string with regex:.
Note that Zammad matches against the full header, e.g. for a mail with „From:DisplayName<display.name@example.com>“, the From condition will test against „DisplayName<display.name@example.com>“. This is especially important when using anchored regular expressions; regex:^display\.name@example.com$ would not match this mail!
It should be borne in mind that the combined attributes build on each other. If a filter is no longer needed, it can either be temporarily set inactive or deleted directly.
Bemerkung
Signatures in Microsoft 365 channels are just like signatures in email channels,
so this article is lifted verbatim from here.
To individualize the signatures, it is possible to automatically load specific information into a signature via Variables. All information stored on the ticket, assigned customers or agents can be inserted. This makes it possible to design the signature individually. To load a list of available variables, enter two colons (::) into the Text box of the signature editor.
Hinweis
Please keep in mind that specific information might not be available during ticket creation. The best example here is the ticket number / id. Specific information are created with submitting the ticket and thus are not available before submitting.
Here is an example of a signature with variables and the result when you write a mail:
Bemerkung
Settings in Microsoft 365 channels are just like settings in email channels,
so this article is lifted verbatim from here.
Notification Sender: Default value NotificationMaster<noreply@#{config.fqdn}>
This is the default sender address for Zammad that affects all mails but
those generated because of replies (like triggers or agent-based mails).
Your customers normally will not see this address. This email address does
not need to receive and can’t be assigned to a group.
Bemerkung
This address is relevant for agent notifications and password reset mails
(also affects customers).
Additional follow-up detection
In some situations the normal follow-up detection is not enough.
This might be due to missing references in the subject
(the ticket hook and number). These options can help to recognize follow-ups
to existing tickets.
Bemerkung
Please note that searching in attachment and body might lead to false
follow-up detections.
Maximum Email Size: Default value 10MB
This one is pretty obvious: It defines the maximum allowed size of an email
Zammad will fetch. Zammad will not fetch Mails that are bigger than this
option.
Hinweis
This technically also affects attachments for articles.
Send postmaster mail if mail too large: Default value yes(enabled)
Bemerkung
Upgraded installations will, by default, have the value set to
no(disabled).
Option set to yes
This setting will cause Zammad to automatically reply to mails that exceed
the above mail size limit with a postmaster style mail.
This will help your user to understand that his mail did not arrive and
won’t be reviewed by you.
Bemerkung
Zammad will still download and remove (if enabled) the mail from the
mailbox. Instead of importing it to the database, it will save the
affected mail to /opt/zammad/tmp/oversized_mail/.
Option set to no
If the option is set to no, Zammad will not reply to mails that are too
big. Your customer will not notice that the mail was too large!
Instead, Zammad will use the monitoring endpoint to alert its
administrators that it can’t fetch a too large mail.
Sender based on Reply-To header: Default value notset(-)
This setting decides how Zammad should recognize its customers from emails
that contain a Reply-To header. This comes in useful if you’re working
with contact forms that need to use reply to headers.
Option set to - or Takereply-toheaderassender/fromofemail
This setting will overwrite the initial FROM to the value used in
Reply-To completely.
Option set to Takereply-toheaderassender/fromofemailanduserealnameoforiginfrom
This setting will partially overwrite the initial FROM.
It uses the mail address from the Reply-To header and uses the given
name of the FROM header, if given.
Customer selection based on sender and receive list: Default value yes
This option decides how Zammad should react if an agent sends a email to it.
Option set to yes
The first user / email address from the recipient list will be used as
the ticket customer.
Option set to no
The agent will be set as ticket customer.
Bemerkung
Currently agents can’t be customers within the UI.
While Email communication works, agents can’t see their own tickets
(as a customer) if they don’t have access to the group.
Block Notifications
With the regex that can be defined here, you can ensure not to send any
notifications to specific systems. By default this especially affects typical
system addresses which can’t receive emails anyway.
The default value is:
(mailer-daemon|postmaster|abuse|root|noreply|noreply.+?|no-reply|no-reply.+?)@.+?
Sender Format: Default value Agent+FormatSeperator+SystemAddressDisplayName
This configures the display name used in the FROM header of mails
Zammad sends.
Bemerkung
This does not affect Notification mails (to agents) and password reset
mails. Emails that are not sent by agents
(e.g. trigger-based notifications) will always fallback to
SystemAddressDisplayName if needed.
Option set to Agent+FormatSeparator+SystemAddressDisplayName
This will cause Zammad to set the FROM header to agent name and the
channel’s display name, divided by a separator (configured below).
Example: ChristopherMillerviaChrispressoInc..
Option set to SystemAddressDisplayName
This will cause Zammad to always use the display name of the used channel
in the FROM header.
Example: ChrispressoInc.
Option set to AgentName
Zammad will use the agent’s name which is very personal.
Tipp
Usually you’d also want to remove the ticket slug from the subject
in those cases.
This is a can be a string you can freely choose. It divides the agent’s name
and the display name of the channel whenever needed.
Ticket Subject Forward: Default value FWD
The above string will be used on the subject if you forward an email from
Zammad.
Bemerkung
: will be automatically appended to the above string.
Ticket Subject Reply: Default value RE
The above string will be used on the subject if you reply to a mail from
Zammad.
Bemerkung
: will be automatically appended to the above string.
Ticket Subject Size: Default value 110
This setting enforces a maximum length for subjects when replying.
If the subject you’re using for your reply is too long, Zammad will
automatically truncate the length and insert [...] to show it has
shortened the subject.
Example: RE:Testsomew[...][Ticket#123456]
Bemerkung
This does not limit ticket titles within the UI, just the subjects
when replying to an email.
Some less relevant settings can be changed via rails console if needed.
As an example, Zammad allows you to send all outgoing communication to a BCC
address for archiving reasons if needed. You can find the needed commands
within the advanced customization settings.
Bemerkung
EMail header manipulation in Microsoft 365 channels work
just like in email channels, so this article is lifted verbatim from
here.
Email header manipulation allows you to re-route or adjust tickets apart from
filters or triggers. Like an API call, but with emails.
Header checks are case insensitive.
Warnung
🛡 Trusted channels required 🛡
Below options are a potential risk with external communication and
thus require channels being set to trusted explicitly.
Tipp
Below headers are examples and –in our opinion– the most relevant ones.
However: You can adjust mostly any article or ticket attribute (yes, custom
ones as well) if you know the attribute’s exact name.
The name column within object’s management provides
easy access to objects attribute names. 🤓
Normally Zammad runs internal checks to see if an email is an automatic
response. In these cases Zammad will not send trigger based responses.
There may be use cases where this behavior may be in your way,
below options allow you to overcome this issue.
Bemerkung
In some cases combining below headers is crucial.
This is intentional but may be confusing.
x-zammad-send-auto-response
Set to false to disable trigger based responses.
If set to true Zammad will send a response.
Hinweis
This option does not work if e.g. precedence:list is set
unless you use below auto response header as well.
x-zammad-is-auto-response
Providing this header allows you to tell Zammad that the mail in question
is an auto generated response (true). This will cause email based
triggers to be skipped.
Set this header to false if you want to generate auto responses.
Tipp
This header allows you to overwrite auto detects for e.g.
precedence:list.
Zammad allows you to use headers to manipulate ticket creations or follow ups.
The manipulation can be used instead of triggers. Triggers are considered
after header settings and thus can still overrule.
Bemerkung
🔎 Zammad differentiates between ticket creation and follow up
For creations use: X-Zammad-Ticket-{AttributeName}
For follow ups use: X-Zammad-Ticket-FollowUp-{AttributeName}
This allows you to ensure the changes are only applied in the
required situation.
Warnung
🧐 About values
While headers are not case sensitive, values like e.g. priority names
are case censitive: 1low will work, but 1lOw will not!
When using attributes that require date / time values, ensure to use
Time Zoned Times. e.g. for 28th September 2021 on 8 am CEST, either use:
If you’re already familiar with email channels,
you can skip most of this—but watch out for the “Accounts” section,
which has a few extra quirks due to Microsoft’s strict security measures.
During the application process, you will be asked
to Describe in your own words what you are building.
You may use the answer below:
1. To manage customer service communications for our organization.
2. No.
3. Our use case involves posting original tweets in response to tweets and DMs we receive. We will not use the Twitter API to post or like “content”.
4. Our application will display individual tweets in their original form to authorized customer service agents of our organization only.
Add your new Twitter app under Channels > Twitter in the admin settings panel. You will need the keys, tokens, and dev environment label from Steps 4 and 5.¶
Below settings are only available to self hosted users.
In hosted environments we’re handling these settings for you to ensure
service stability.
Fully Qualified Domain Name
The URL of your Zammad installation.
This setting is used within Variables and notifications.
Bemerkung
This setting is automatically set by the Getting Started wizard.
Warnung
Changing this setting also changes callback URLs for your channels etc.
This setting can have negative affects on being able to login.
HTTP type
The HTTP type tells your installation how your clients connect.
This is relevant for authentication and cookie security.
This setting is used within Variables and notifications.
Bemerkung
This setting is automatically set by the Getting Started wizard.
Warnung
Changing this setting also changes callback URLs for your channels etc.
This setting can have negative affects on being able to login.
SystemID
This ID is being used within your ticket number.
In case you’re communicating with another ticket system with similar
ticket number schemes this ID greatly reduces the risk of false follow ups.
The SystemID is randomly selected upon installation of Zammad (1-99).
Warnung
Do not change this setting in a productive system!
Your Zammad installation may no longer recognize old ticket number based
follow ups upon change!
Below settings are only available to self hosted users.
In hosted environments we’re handling these settings for you to ensure
service stability.
Storage Mechanism
This tells Zammad where to store attachments for tickets and knowledge base.
By default we’re writing to the Database - you can switch to
Filesystem at any time. If you chose filesystem, your files are
written to /opt/zammad/storage/
Bemerkung
We strongly encourage you to use filesystem storage on busy instances.
This will greatly improve system performance (de-crease database load
and size).
Tipp
Moving attachments from Database to Filesystem can be run during
production use.
Send client stats/error message to central server to improve the usability.
Default: no (inactive)
Gefahr
This sends logging to our central logging server.
Log files of Zammad can contain very sensitive data like email addresses
and other. Do not enable this option unless we’re asking you to.
Client storage
Use client storage to cache data to enhance performance of application.
Default: no (inactive)
Core Workflow Ajax Modus
This setting allows administrators to enforce Core Workflows
to use Ajax-Calls instead of web sockets. You’ll usually only need this if
you experience serious issues as noted below.
Hinweis
🤓 Possible (technical) reasons
In some cases, your network structure (e.g. firewalls, proxies)
may disconnect long web socket connections. This leads to
select fields staying empty (e.g. owner selection after selecting
your group) or fields not shown / hidden (e.g. when switching to
or from pending states, the „pending till“ field not showing / hiding).
Please keep in mind that the Ajax fallback may cause serious
pressure on your application server. If you have the choice stick to
web sockets.
Activates the register as a new customer function on the login page.
If set to no only administrators or agents can create new accounts
manually.
Default setting: yes
Warnung
😖 This setting may be confusing
Deactivation of above function does not deactivate automatic account
creation! This means: If a user writes e.g. an email to Zammad and has no
account yet, Zammad will automatically create the account.
User accounts are a direct dependency of tickets and thus technically
mandatory.
Activates the lost password function on the login page.
If set to no only administrators may change the user’s password - users
may update their own password if they’re still logged in and they have the
required permission.
Default setting: yes
Tipp
😖 This function may be confusing
With third party authentications – but especially LDAP – you may want to
disable this function. Zammad will not change third party login
passwords and instead set or change the local password!
All settings below by default are set to 4weeks.
Session Timeout defines the life time of a users session.
As soon as it’s reached, Zammad will automatically log off the
session in question.
Zammad takes the highest value set assigned for the user based on
the permissions.
admin
ticket.agent
ticket.customer
default (fallback if user doesn’t have above permissions set)
All settings act independently from each other allowing you to disable the
timeouts for e.g. admins, but not agents.
Bemerkung
🤓 An example
Let’s suppose you configured the following session timeouts
default: 3 weeks
admin: 2 weeks
ticket.agent: 4 weeks
ticket.customer: 1 week
This results in the following situations
a user with admin permission will have a timeout of 2 weeks
a user with admin and ticket.agent permissions will
have a timeout of 2 weeks
a user with ticket.customer permission will have a timeout
of 1 week
a user with neither admin, ticket.agent nor
ticket.customer permissions will have a timeout of 3 weeks
This section allows you to define password requirements for the local user
accounts.
Bemerkung
Zammad does not allow you to change your LDAP password, instead, it will
set a password in its local database which might confuse your users. This
will be addressed in the future by
#1169.
Warnung
💪 Exception for strong passwords 💪
Please note that below password policies do not affect administrators
setting passwords on user accounts. While this seems strange and not safe
we believe that an administrator knowing an user’s password is insecure
as well.
The suggested workflow is either:
to use third party logins to not require local passwords at all
- or -
to require your user to reset the password upon first login.
This way administrators are not required to set a user’s password at all!
You can choose a value between 4 and 20. This defines how often a login
to a user account may fail until Zammad will lock it.
Your users can always use the „forgot password“ function to change their
password and unlock their account.
The default value is 10.
Bemerkung
Beside changing the user’s password, you can also unlock accounts via
Third party authentication is a great way to help your users to login to Zammad
more easily. If the account is yet unknown, Zammad will create a new user
automatically, without the user needed to interact (e.g. type in his name).
Another big advantage of this feature is that your user doesn’t need to remember
another password.
Navigate to „Admin -> Security -> Third Party Applications“ and enter the App ID and the App Secret. You can find this Key in the Dashbard of your Facebok app
Now you can link accounts via „Avatar -> Profile -> Link Accounts“ or login via Zammad login page.
First of all, we need to create a new project - you can skip this step if you already have one.
Hinweis
Use this link to create a new project: https://console.cloud.google.com/projectcreate
Now expand the menu, expand „APIs & Services“ and select „Credentials“.
Go to the tab „OAuth consent screen“ first and ensure to fill in the requested information - without doing so you can’t create credentials!
After filling in and savingthe consent screen information, you can change to „Credentials“ tab and
create new „OAuth client ID“-Credentials.
Fill in the neceassary information, for restrictions you need the following (replace zammad_host with your FQDN):
After creating the credentials, go to your Zammad installation and navigate to
„Admin -> Security -> Third Party Applications“ -> Google.
Enter your Client ID and Client secret here.
After submitting, the login via Google can be used.
Zammads Office 365 allows your users with Microsoft accounts to login.
This works for Azure users as well and can be an alternative to
LDAP / Active Directory.
Please note that Zammad only supports these account types (App dependent):
Accounts in this organizational directory only
(Default Directory only - Single tenant)
Accounts in any organizational directory
(Any Azure AD directory - Multitenant)
Accounts in any organizational directory
(Any Azure AD directory - Multitenant)
and personal Microsoft accounts (e.g. Skype, Xbox)
Avatars of signing in users:
Zammad currently ignores user avatars. If the user is registered with
e.g. Gravatar, Zammad will fetch the avatar from there if enabled.
See Zammad Image Service for more.
Login to the Microsoft Azure Portal
and navigate to App registrations to create a new app.
Provide the requested information as follows and register your app.
Name:
Any meaningful name fitting, this name will be displayed to users
trying to authenticate with this app.
Supported account types:
Choose one of the above mentioned account types (see Limitations).
Tipp
The correct account type depends on your use case.
If you want to use the authentication internal only, choose the first
option. If you’re unsure, use the „Help me choose…“ link.
Redirect URI (optional):
Select web and provide your callback url.
The callback url looks like this:
https://zammad.domain.tld/auth/microsoft_office365/callback
Within API permissions add the following permissions:
OpenId permissions
openid
Benutzer
User.Read
Contacts
Contacts.Read
You can find these permissions within Microsoft Graph → Delegated permissions.
Within Certificates & secrets create a new client secret.
Note down the returned secret value for later. Do not use the secret ID!
From Overview copy your apps Application (client) ID.
If you’re using a single tenant app, please also copy Directory (tenant) ID.
You now have all required information for Zammad.
Navigate to Security → Third-party Applications (Tab) within Zammads admin
settings. Scroll down to the section Authentication via Office 365 and
fill in the required information.
App ID:
This is your Application (client) ID.
App secret:
This is your client secret (value).
App Tenant ID:
optional only required for apps that use account type
Accounts in this organizational directory only
(Default Directory only - Single tenant).
Apply your settings by pressing submit and activate
Authentication via Office 365.
Connect your SAML identity provider as a single sign-on (SSO) method.
Bemerkung
🤷 What is SAML?
SAML is an open standard for SSO authentication (among other things).
Sign-ins are shared across multiple service providers
and managed by a central identity provider (IdP).
In this case, the service provider is Zammad,
and the IdP is a software service that you either host or subscribe to
(e.g.,Keycloak, Redhat SSO Server, ADFS, or Okta).
This guide assumes you are already using SAML within your organization (i.e., that your IdP is fully set up).
Zammad requests the following user attributes (or “properties”) from the IdP:
Email address (email)
Full name (name)
Given name (first_name)
Family name (last_name)
You may need to set up “mappers” (or “mappings”) to tell your IdP
how user attributes in SAML correspond to those in Zammad.
For a more detailed breakdown,
refer to the XML metadata file referenced in the previous section.
To add Zammad as a client,
save the XML configuration to disk
(https://your.zammad.domain/auth/saml/metadata)
and use Clients > Create > Import in the Keycloak admin panel.
To help Zammad match its own user accounts to Keycloak users,
create a user attribute (or “property”) mapper:
In the example above, we’re telling Zammad that
whenever it receives a SAML login request,
it should take the emailAddress property from Keycloak,
look for a Zammad user with the same email attribute,
and create a new session for that user.
If your Keycloak users’ email addresses are stored on another property
(e.g.,username), adjust accordingly.
Enable SAML and enter your IdP’s details in the Admin Panel under
Settings > Security > Third Party Applications > Authentication via SAML:
Bemerkung
🔏 For the IdP certificate / certificate fingerprint:
Provide only one or the other—do not provide both!
(Between the two, we recommend the signing certificate itself:
fingerprints use SHA-1, which has been broken for a while now.)
Keycloak users: Find your certificate in the Keycloak admin panel under
Realm Settings > Keys > RSA > Certificate.
In general there’s two possible options for Zammad on how to deal with
already known users as they try to authenticate against a third-party
application. By default, Zammad will not automatically link „unknown“
authentication providers to existing accounts.
This means that the user has to manually link authentication providers to their
accounts (for more about this
consult the user documentation).
Sometimes this doesn’t come in handy as this also means you’ll receive
error messages about „email address being in use already“ for (yet) unknown
third-party authentication methods.
If you want to allow your users to always be able to log in, no matter what,
you may want to enable Automaticaccountlinkoninitiallogon.
The identifier for a ticket; e.g., Ticket#, Call#, MyTicket#.
Ticket Hook Position (default: right)
With this setting you can decide (if) where to insert the ticket number.
Right
This setting will add the ticket reference on the right site of the subject.
Example: SomeSubject[Ticket#12345]
Left
This setting will add the ticket reference on the left site of the subject.
Example: [Ticket#12345]SomeSubject
None
This will completely remove ticket references from the subject.
Warnung
Please ensure to take a look at Einstellungen within the email channel to ensure you have at least one reference that helps Zammad to assign follow-ups correctly.
Disabling this and not setting up any further follow up search will lead to unexpected results!
Ticket Last Contact Behaviour (default: Lastcustomercontact(withconsiderationanagenthasrepliedtoit))
This setting changes the way Zammad updates the LastContact value of a ticket.
This is fairly important for overviews and what you expect upon ticket updates of a customer.
Last customer contact (with consideration an agent has replied to it)
If this option is chosen, Zammad will update the last updated value just once if a customer replies.
After that, Zammad will wait for an agent to react.
This comes in handy if you want to work tickets in the order of their first update. This will not change ticket orders if customers decide to „bumb“ the ticket affected.
Last customer contact (without consideration an agent has replied to it)
When setting this option, Zammad will always update the last updated value.
This means that if ordering by LastUpdate, ticket orders will change if customers „bump“ the ticket.
Ticket Number Format (default: Increment(SystemID.Counter))
This setting defines the way Zammads ticket number will look.
Changing this setting in production will cause follow up detection to fail.
Increment (SystemID.Counter)
The increment value contains the SystemID (automatically generated during installation) and a increment which counts up with every new Ticket. The increment will automatically get another digit if needed.
Examples: 1010138, 1010139
Date (Year.Month.Day.SystemID.Counter)
This version of the ticket number is fairly long. However, because it contains the date of ticket creation, it also allows you to see when the ticket has been created. You may feel familiar with this number format if you’ve worked with OTRS already.
Examples: 201206231010138, 201206231010139
OPTIONS
The below options allow you to further customize your ticket number. The availability of options differ depending of the chosen ticket number format above.
Checksum (default: no)
If set to yes, we’ll built a checksum to further „unique“ the ticket number of your system. If you’re dealing with many other ticket systems this might help to prevent false positive follow up detections on tickets.
This will also add another digit to the ticket number.
Min. size of Number (default: 5)
This setting defines the minimum length of your ticket number. If your counter is not yet high enough, Zammad will fill the number with zeros to ensure the wanted length.
Please note that the minimum length is 3 (SystemID + at least one digit if below 10). Also, if the length is no longer long enough, the number will automatically get one digit longer. Ticket-Numbers do not overflow, thus it’s save to keep it at 5 or set it lower if wanted.
Bemerkung
This option is only available if ticket number format is set to Increment!
In a larger Zammad environment, it happens that several agents open the same ticket at the same time. Although collision detection is then effective, the efficiency of processing can be increased by means of the automatic assignment of tickets when a ticket is opened.
Bemerkung
Auto Assignment only kicks in if the ticket has no owner yet. By default the agent can always reset the ticket owner to - if needed.
The automatic assignment of tickets can be activated and configured in the admin area under within Settings -> Ticket -> Auto assignment.
If you want to use this function for only specific tickets, you can configure the conditions accordingly to meet your requirenment.
By default the condition affects all tickets with the state open.
If you need to exclude users (e.g. a group leader), you can search and select the desired agents in the ExceptionUsers list.
Bemerkung
The search function in this area is only affective, if you have too many agents to display at once to help you with the configuration.
Your VoIP provider or telephony system is not listed?
Possibly your provider supports Zammad by using the generic CTI - if you’re
unsure ask your provider.
This integration enables Zammad to provide a caller log to your agents.
With this your agents can greet your customers by their name and are
supported by Zammad with automatically opening a new ticket dialogue or
the user profile.
If you want to learn more on how your agents can use this function, please
refer the user documentation.
Bemerkung
Automatically opening new ticket dialogues or user profiles requires
agent to extension mapping - see more below.
Please note the following limitations to reduce confusion later on:
CTI integrations provide caller log functions only.
This integration does not provide any VoIP functionalities;
you can’t make phone calls from within Zammad.
If your browser supports tel-URLs, you can click on phone numbers
for automatic dialing. This requires additional software / configuration
on your agent’s computers.
Click the button next to the CTI(generic) heading to activate or
deactivate this function.
Endpoint Settings
Zammad will list your generic CTI endpoint here.
It contains a unique token so ensure to keep this URL save.
You’ll need this endpoint for your PBX to talk to Zammad,
see CTI-API documentation.
Wichtig
All following options do not save automatically.
Always use the Save button on the lower end of the integration page!
Call Settings
Inbound
This option allows you to block specific incoming caller IDs.
It allows you to temporarily reject e.g. spam callers without having to
contact providers or PBX administrators.
Caller ID to block
Provide caller IDs to block in E.164 format.
Note
Provide a meaningful note for your fellow administrators to remind
yourself why you’ve chosen to block the number.
Bemerkung
Your telephony system has to support this function.
Zammad will send a reject response which will cause your telephony
system to hang up the call.
To callers this usually will feel like the line is busy.
Outbound
In many cases you may want to use a different caller ID depending on
the destination you’re calling. This may apply due to specific connection
rates to other countries or because you want your customer to feel you’re
calling from the same country.
Bemerkung
This option expects E.164 number formats.
Destination caller ID
The caller ID or number you’re trying to call.
Tipp
You can use wildcards for e.g. country specific outbound numbers like:
49* for Germany
4930* for Berlin / Germany landlines
33* for France
Set Outbound caller ID
The outbound caller ID to set (the number your customer sees on his
display) in E.164 number format.
Note
Provide a short description for fellow administrators.
Bemerkung
This option requires your PBX to send a specific request to Zammad
before dialing. Please consult the CTI API in case you’re not sure.
Other Settings
Below you can find all available additional settings for this CTI integration.
For your overview we’re sorting them by appearance and reference their
description first.
Default caller ID for outbound calls
In many cases you may want to use a different caller ID depending on
the destination you’re calling. This may apply due to specific connection
rates to other countries or because you want your customer to feel you’re
calling from the same country.
Bemerkung
This option expects E.164 number formats.
Bemerkung
This option requires your PBX to send a specific request to Zammad
before dialing. Please consult the CTI API in case you’re not sure.
Shown records in caller log
Allows you to set the number of shown caller log entries for all users.
You can choose from the following values:
60 (default)
120
180
240
300
Warnung
🥵 Potential performance issue
Setting this setting higher than 60 may cause serious performance issues
on very busy instances. Keep in mind that this setting causes Zammad to
poll and send up to 300 records to all active agent sessions in very
short time periods.
Caller Log Filter
This function allows you to provide call information based on e.g. queues
only to agents that really need the information.
Why? If you have a team for several countries or departments, you don’t want
to bug your agents from other departments. Leaving these options empty will
fallback to showing everything to everyone.
Destination caller ID or Queue
This depends on your PBX and usually is either a queue ID, phone number
or extension.
Agents
Select the agents that are responsible for the group.
These agents will then see caller log entries and call notifications
fitting to said queue.
With recent logs Zammad allows you to view the latest calls for the CTI
functionality. This usually comes in handy, when you’re looking for errors.
I’m just here to clear floats up.
By clicking on the entry of interest, Zammad will provide more details on
the call in question. You’ll see the payload it received and also the
response that was sent.
This configuration step requires a full administrative Placetel account.
You may receive forbidden error messages with Placetel in case your
permissions are not high enough.
Within Integrations, scroll down to Partner integrations and select
Zammad.
You can alternatively filter by „Ticket Systems“ to reduce
the number of entries on the page. You’ll still want to look for
Partner integrations. 🤓
Within the Zammad integration now press „Activate“.
A new tab API becomes available - open this tab.
Now tick „Enable Call Control / Notify API“ and paste the Placetel
endpoint from your Zammad instance into the field „URL of your API endpoint“.
Save to apply the settings
Step 2: Generate API Token for Placetel
Go back to the integrations page and scroll down to „Web API“.
Generate a new API token by using the „Create a new API token“ button.
Bemerkung
If you already generated a token either use your existing token or
reset it by using above mentioned button. Placetel will ask you to
conform this reset.
Please keep in mind that existing API scripts may no longer work
due to token resets!
Copy the provided API token and insert it into the „API Token“ field
within Zammads Placetel integration.
Apply your changes by using the „Save“ button on the bottom of the
Placetel integration page and activate the Placetel integration.
Step 3: Restrict the numbers to notify on
Having a lot of numbers that shouldn’t be used for notifying Zammad?
Within the the Integrations page of the Placetel web interface, go to
„Notify API“.
Lower on the page Placetel allows you to restrict the numbers to notify on.
You’ll find this within the „External routing API“ part.
Hinweis
This menu point also provides a API request log from Placetel view.
Just open „Recent responses of your API endpoint“ to learn more.
If you want to see Zammads perspective, use the „Recent Logs“ part from
within the Placetel integration page.
Step 4 (optional): Further configurations for Placetel
If needed, you can now configure Zammads Placetel integration in more detail.
You can learn more about your options here:
Placetel integration settings.
This integration enables Zammad to provide a caller log to your agents.
With this your agents can greet your customers by their name and are
supported by Zammad with automatically opening a new ticket dialogue or
the user profile.
If you want to learn more on how your agents can use this function, please
refer the user documentation.
Bemerkung
Automatically opening new ticket dialogues or user profiles requires
agent to extension mapping - see more below.
Please note the following limitations to reduce confusion later on:
CTI integrations provide caller log functions only.
This integration does not provide any VoIP functionalities;
you can’t make phone calls from within Zammad.
If your browser supports tel-URLs, you can click on phone numbers
for automatic dialing. This requires additional software / configuration
on your agent’s computers.
This endpoint will be required for the Zammad integration within the
Placetel web interface.
API Token
You’ll receive this token within the WebAPI menu.
Make sure to copy this value, it’s only shown once!
Call Settings
Inbound
This option allows you to block specific incoming caller IDs.
It allows you to temporarily reject e.g. spam callers without having to
contact providers or PBX administrators.
Caller ID to block
Provide caller IDs to block in E.164 format.
Note
Provide a meaningful note for your fellow administrators to remind
yourself why you’ve chosen to block the number.
Other Settings
Below you can find all available additional settings for this CTI integration.
For your overview we’re sorting them by appearance and reference their
description first.
Shown records in caller log
Allows you to set the number of shown caller log entries for all users.
You can choose from the following values:
60 (default)
120
180
240
300
Warnung
🥵 Potential performance issue
Setting this setting higher than 60 may cause serious performance issues
on very busy instances. Keep in mind that this setting causes Zammad to
poll and send up to 300 records to all active agent sessions in very
short time periods.
Phone Extension to Agent Mapping
By mapping your agents extension to their existing Zammad users,
Zammad can provide a new ticket dialogue or open the user profile for
the agent that picks up the call.
This speeds up ticket aiding, no matter if it’s for existing tickets or new
ones!
You can find your agents Placetel username combination required within
⚙️ PBX → VoIP destinations. Within the „Advanced settings“ section
you’re looking for „SIP user name“ and „SIP server“.
Combine these two like so: <sip-user-name>@<sip-server>.
With recent logs Zammad allows you to view the latest calls for the CTI
functionality. This usually comes in handy, when you’re looking for errors.
I’m just here to clear floats up.
By clicking on the entry of interest, Zammad will provide more details on
the call in question. You’ll see the payload it received and also the
response that was sent.
Sipgate has no english web interface which is why this documentation page
is mixing up languages badly.
Please also note that the availability of API addons highly depends on your
package trier. Usage of sipgate.io packages is not free, please check
their pricing page before!
Step 1: Book sipgate.io package
Hinweis
Skip to step 2 if you already have the package booked!
Login to an administrative Sipgate account and navigate to
Accountverwaltung. You’ll see several different options depending on
your booked packages. Select Verträge&Produkte to continue.
Scroll down to the section ZusätzlicheProduktebuchen and look for
sipgate.io - select this product by using the
Produkteanzeigen-Button.
On the next page select either one of the sipgate.io packages or
Push-APIPackageFree. Follow the dialogue by booking the addon.
You’ll be returned to your contract overview and now should see the selected
addon in your list.
Bemerkung
The availability for sipgate.io packages and their levels highly
depends on the overall account type and product you’ve booked with
Sipgate.
Step 2: Configure webhook for Zammad
Within your Accountverwaltung navicate to your product sipgate.io.
In the newly opened tab, switch from „Clients“ to „Webhooks“ and paste
the endpoint URLs from your Zammad instance like so:
Inbound endpoint to „Incoming“
Outbound endpoint to „Outgoing“
Bemerkung
Ensure to select at least one call group or phoneline within „Sources“.
Other wise Sipgate will not indicate any incoming or outgoing calls
to Zammad.
Step 3: Restrict the numbers to notify on
Having a lot of numbers that shouldn’t be used for notifying Zammad?
Within the Webhooks → URLs section of Sipgate you can select which sources
Sipgate should notify Zammad about in- and outgoing calls.
Use either specific phone lines or use the option
„Use for all phonelines and groups“ to notify Zammad about all existing
lines of your Sipgate account.
Hinweis
This section also allows you to enable a Debug log.
After enabling you can use the Debug log section to see all sent webhook
calls to Zammad. You’ll also can see the response.
Step 4 (optional): Further configurations for Sipgate
If needed, you can now configure Zammads Sipgate integration in more detail.
You can learn more about your options here:
Sipgate integration settings.
This integration enables Zammad to provide a caller log to your agents.
With this your agents can greet your customers by their name and are
supported by Zammad with automatically opening a new ticket dialogue or
the user profile.
If you want to learn more on how your agents can use this function, please
refer the user documentation.
Bemerkung
Automatically opening new ticket dialogues or user profiles requires
agent to extension mapping - see more below.
Please note the following limitations to reduce confusion later on:
CTI integrations provide caller log functions only.
This integration does not provide any VoIP functionalities;
you can’t make phone calls from within Zammad.
If your browser supports tel-URLs, you can click on phone numbers
for automatic dialing. This requires additional software / configuration
on your agent’s computers.
This endpoint is required for incoming call hooks.
Outbound
This endpoint is required for outgoing call hooks.
Wichtig
All following options do not save automatically.
Always use the Save button on the lower end of the integration page!
Call Settings
Inbound
This option allows you to block specific incoming caller IDs.
It allows you to temporarily reject e.g. spam callers without having to
contact providers or PBX administrators.
Caller ID to block
Provide caller IDs to block in E.164 format.
Note
Provide a meaningful note for your fellow administrators to remind
yourself why you’ve chosen to block the number.
Outbound
In many cases you may want to use a different caller ID depending on
the destination you’re calling. This may apply due to specific connection
rates to other countries or because you want your customer to feel you’re
calling from the same country.
Bemerkung
This option expects E.164 number formats.
Destination caller ID
The caller ID or number you’re trying to call.
Tipp
You can use wildcards for e.g. country specific outbound numbers like:
49* for Germany
4930* for Berlin / Germany landlines
33* for France
Set Outbound caller ID
The outbound caller ID to set (the number your customer sees on his
display) in E.164 number format.
Note
Provide a short description for fellow administrators.
Other Settings
Below you can find all available additional settings for this CTI integration.
For your overview we’re sorting them by appearance and reference their
description first.
Default caller ID for outbound calls
In many cases you may want to use a different caller ID depending on
the destination you’re calling. This may apply due to specific connection
rates to other countries or because you want your customer to feel you’re
calling from the same country.
Bemerkung
This option expects E.164 number formats.
Shown records in caller log
Allows you to set the number of shown caller log entries for all users.
You can choose from the following values:
60 (default)
120
180
240
300
Warnung
🥵 Potential performance issue
Setting this setting higher than 60 may cause serious performance issues
on very busy instances. Keep in mind that this setting causes Zammad to
poll and send up to 300 records to all active agent sessions in very
short time periods.
Phone Extension to Agent Mapping
By mapping your agents extension to their existing Zammad users,
Zammad can provide a new ticket dialogue or open the user profile for
the agent that picks up the call.
This speeds up ticket aiding, no matter if it’s for existing tickets or new
ones!
With recent logs Zammad allows you to view the latest calls for the CTI
functionality. This usually comes in handy, when you’re looking for errors.
I’m just here to clear floats up.
By clicking on the entry of interest, Zammad will provide more details on
the call in question. You’ll see the payload it received and also the
response that was sent.
With our Clearbit integration, you can easily enrich the information provided by Zammad.
If the customers or agents email address is known to Clearbit, it will share all information it has regarding the user with Zammad.
Those information can include the following:
Avatar
Address information
Website information
A BIO (as Note by default)
If needed, you can add further custom objects and add mappings to them, so the clearbit information can be filled within the database.
In general you can get any information from clearbit, as long as you have a mapping to an Zammad object.
Hinweis
Clearbit does have a Mapping of fields like LDAP and Exchange have, but does not „win“ against Zammad information. This means
that if you have e.g. the lastname field filled in already and Clearbit has other information on that, it will not be updated.
However: If let’s say the lastname has been set by Clearbit and Zammad notices that the lastname on the Clearbit source has changed, Zammad
will also update this value.
The configuration of clearbit is really easy and done fast! Just login to your Clearbit-Account, go to „API“ and copy the secret-API-Key.
Now change to your Zammad instance, go to Integrations (System) -> Clearbit in the admin panel.
Paste your API-Key into the API-Key-Field and decide if Zammad should create unknown Organizations automatically, if the user does not have one
yet (and Clearbit knows it). The shared option decides if the new organizations Zammad creates with Clearbit should be shared ones.
Bemerkung
If you’re unsure what option to choose, better stick with „no“. You can also learn more about Unternehmen.
The Mapping option works similar to the mapping within the Exchange and LDAP sync. You can add further mappings for e.g. custom fields if you need
more information that Clearbit can provide.
Bemerkung
If you want to add more Clearbit fields and want to learn more about available fields on their API, you can take a look at their API documentation .
If you’re happy with the above chosen Settings and your mapping, just save the changes and enable Clearbit integration. Zammad will now start polling the Clearbit API as users contact you.
Bemerkung
Zammad does not synchronize with Clearbit on a regular basis, but on demand if needed. This saves API calls.
Below the Settings and Mappings, you’ll find our Integration log. You can see what requests Zammad sent to Clearbit and also the APIs Response.
By the way, you can also view the API log on the Clearbit website - the information seen is basically the same.
To show you how fast information is added, we added a small Screencast below.
This shows the creation of the User Alex from Clearbit. As we already set the lastname of Alex to „X“, Zammad did not update it. What Zammad did was
to add further information it received from Clearbit. Really cool, right?
Please note that Zammad will distrust senders by default.
This means that you’re always required to provide certificate data, no matter
if for signing or encrypting.
Import public-key certificates for both your own organization and your contacts.
You can also add a bunch of certificates in one go by providing a single file
with all relevant certificates.
Warnung
🕵️ IMMER die Zertifikate persönlich oder telefonisch überprüfen!
The whole point of signatures is to alert you
when someone is trying to pretend to be someone they’re not.
Never accept a certificate from someone online without verifying it first.
Bemerkung
📇 What about trusted certificate authorities?
In some cases (e.g., when dealing with large enterprises),
you may be given a certificate for an entire CA,
rather than a single contact.
Add it here to trust all certificates issued by that CA.
Commercial CAs can usually be verified online.
Zammad does not include a list of built-in, trusted CAs.
Add Private Key
Once you’ve added a public-key certificate,
you can import its matching private key.
Private keys are for your own organization only;
never ask your contacts for their private keys.
A note is displayed on certificates with a matching private key (see line 2).¶
Bemerkung
📤 Certificates and private keys must be uploaded separately.
If your certificate and private key are bundled together
in the same file or PEM block, import it twice (once using each button).
Please note that bulk imports of private keys are not possible.
Downloading private keys that originally were encrypted with a passphrase
will also have this state after retrieval. Knowing the password is
mandatory to continue working with keys in question.
I received a signed/encrypted email before I set up S/MIME integration
No problem.
Once S/MIME has been enabled and the appropriate certificates have been added,
agents will be prompted to retry verification/decryption on matching emails.
Die 🔒 Verschlüsseln-Schaltfläche ist deaktiviert
Have you added the recipient’s certificate?
Are you sure the recipient’s certificate is valid?
Have you checked your production.log for more details?
Warnung
If encryption doesn’t work in the composer, it won’t work in
triggers or the scheduler either!
Die ✅ Signieren-Schaltfläche ist deaktiviert
Have you added both the certificate and private key for your organization?
Does the email address on the certificate match the email address of the agent/group composing the email?
Error: “Fingerprint already taken”
Are you sure you haven’t added this certificate already?
Error: “❌ invalid byte sequence in UTF-8”
Please ensure to provide PEM formatted certificate and keys.
Did you check if the provided file is a valid certificate or key?
S/MIME ist die am weitesten verbreitete Methode für sichere E-Mail-Kommunikation. Mit S/MIME können Sie signierte und verschlüsselte Nachrichten mit anderen austauschen.
Signieren
is proof that a message hasn’t been tampered with or sent by an impersonator.
Mit anderen Worten, es garantiert die Integrität und Authentizität einer Nachricht.
Verschlüsselung
verschlüsselt eine Nachricht so, dass sie nur vom gewünschten Empfänger entschlüsselt werden kann.
Mit anderen Worten, es garantiert Privatsphäre und Datensicherheit.
Once S/MIME has been enabled, 🔒 Encrypt and ✅ Sign buttons will appear in the ticket composer.¶
Checkmk is a powerful IT monitoring tool
that can send real-time status alerts to Zammad via email or REST API.
Set these alerts up in Checkmk,
and Zammad will automatically create, update, and close tickets
based on the health of your system:
Whenever the Checkmk integration is enabled,
Zammad listens for messages on its API and over email.
As long as those messages follow the required format,
Zammad will create new tickets (or find and update existing ones)
based on the message contents.
That means that “setting up Checkmk integration”
is simply a matter of adding configuration to your Checkmk site:
telling it when to send these messages and what to say.
To do that, you’ll need to create a new notification rule
(see Checkmk’s official docs
for help with that).
As part of this new rule, you’ll have to choose a notification method
(i.e., a script to execute whenever the rule is triggered).
This script will be written by you (samples below),
and contain the logic for sending API/email messages to Zammad:
Find your custom scripts in the Checkmk WATO under Notifications > New Rule > Notification Method.¶
Once you’re done setting up your new rule, you’re all set!
New tickets should start coming in and auto-updating
any time your rule is triggered.
(If you need help troubleshooting, be sure to check the Recent Logs.)
To add these scripts in the Checkmk WATO,
copy them into your Checkmk installation directory and make them executable.
(Be sure to replace the zammad.example.com callback URL
with the one found in your admin panel.)
Service notification
For updates on the status of the software running on your server
(e.g., postgres).
#!/bin/bash# /opt/omd/sites/<SITE>/local/share/check_mk/notifications/zammad-service
curl -X POST \
-F "event_id=$NOTIFY_SERVICEPROBLEMID"\
-F "host=$NOTIFY_HOSTNAME"\
-F "service=$NOTIFY_SERVICEDESC"\
-F "state=$NOTIFY_SERVICESTATE"\
-F "text=$NOTIFY_SERVICEOUTPUT"\
https://zammad.example.com/api/v1/... # see Admin Panel > System > Integrations > Checkmk > Usage
Host notification
For updates on the status of the server itself.
#!/bin/bash# /opt/omd/sites/<SITE>/local/share/check_mk/notifications/zammad-host
curl -X POST \
-F "event_id=$NOTIFY_HOSTPROBLEMID"\
-F "host=$NOTIFY_HOSTNAME"\
-F "state=$NOTIFY_HOSTSTATE"\
-F "text=$NOTIFY_HOSTOUTPUT"\
https://zammad.example.com/api/v1/... # see Admin Panel > System > Integrations > Checkmk > Usage
Bemerkung
🤔 What’s with all the env vars?
Whenever Checkmk runs these scripts,
it needs to provide some information
about the event that triggered the notification.
This information is passed in the form of
these $NOTIFY_* environment variables.
You can specify additional parameters to pass to the script
when you’re setting up your notification rule,
but the ones you see here are all provided by default.
🐞 There are known bugs in Zammad’s processing of email from Checkmk.
This section will be completed once they have been resolved.
(Learn more at GitHub issues #2377 & #2180.)
In the meantime, we encourage you to set up API alerts instead.
For most users,
the sample scripts from the Setup Guide
will do the job just fine.
But if you want more fine-grained control—for instance,
to create high- and low-priority tickets
for different types of system events—then
you’ll have to customize the data those scripts send to Zammad.
There are two kinds of data you can pass to the API,
both in the form of key-value pairs:
Checkmk parameters
are required, and make up the contents of the resulting tickets/articles.
They also determine whether an event creates a new ticket
or updates/closes an existing one.
These are the only values used in the sample scripts.
Use them as-is; technically, they can be customized,
but it’s hard to imagine a good reason for it.
Ticket Attribute
are optional, and can be used to adjust settings on newly created tickets
(e.g., set the owner, group, priority, or state).
If you want to customize your Checkmk alert script, do it with these.
Simply add an extra “form” option for each one (-F"key=value")
to your script’s curl command line, as in the example above.
Hinweis
💡 It’s just an API endpoint!
When using Checkmk integration, messages need to be formatted in a certain way,
but that doesn’t mean the messages actually have to come from Checkmk.
If you use another monitoring tool that’s not officially supported by Zammad,
there’s probably a way to make it work with your Checkmk callback URL.
Find a complete list of ticket attributes in the Object Manager.¶
Ticket attributes are entirely optional,
and can be used to customize the tickets that Checkmk creates.
(Note that these attributes will be ignored
if a new event belongs to an existing ticket.)
Why would you want to do this?
Maybe you have only one IT guy,
and all system monitoring issues should be automatically assigned to him.
Or, maybe you’re creating multiple notification rules
so that database outages take higher priority
than disk space warnings.
In most cases, you’ll probably want to set one of the following:
If you provide a value that Zammad doesn’t understand
(e.g.,-F"priority=high"), it’s not always clear what will happen.
In some cases, a ticket will be created with the default values instead—but
in others, it may not be created at all!
So what values does Zammad understand, then?
Well, it depends…
To set any other attributes, it helps to know your way around the
Rails console.
Valid values are those that you can set with a string:
# valid>>Ticket.first.update(note:"You're gonna need a bigger boat")=>true>>Ticket.first.note=>"You're gonna need a bigger boat">>Ticket::State.find_by(name:"open").id=>2>>Ticket.first.update(state_id:2)=>true>>Ticket.first.state.name=>"open"# invalid>>Ticket.first.update(preferences:"I'm a Checkmk ticket!")=>true>>Ticket.first.preferences=>{}
These values can then be passed directly to the API:
-F "note=You're gonna need a bigger boat"
-F "state_id=2"
Should Zammad automatically close tickets if a service has recovered on its own?
(Agents will receive notifications for such closures as appropriate.)
Auto close state
What ticket state should be applied when “auto-closing” a ticket?
(You may choose from the seven built-in ticket states,
but if you change this setting from the default,
you’ll more likely want to
define a new ticket state
for this purpose.
This can be especially useful for tracking tickets with
reports.)
This guide describes how to integrate your Zabbix 5.0 installation with
Zammad using the Zabbix webhook feature. This guide will provide
instructions on setting up a media type, a user and an action in Zabbix.
Use GitHub integration to track GitHub issues directly within Zammad tickets.
Add issue hyperlinks and get a live summary of metadata
like status (open/closed), assignee, labels, and more.
Bemerkung
GitHub integration does not support pull requests.
In your GitHub settings, create a new API token under
Developer settings > Personal access tokens > Generate new token.
Leave the Scopes section empty.
No. To link private repo issues, use thereposcope instead.
Bear in mind that the resulting token will have
lots of permissions that it doesn’t actually need,
which presents a security risk
if your token ever falls into the wrong hands.
Unfortunately, because of how GitHub’s OAuth token scopes are set up,
this is the only way to link issues on private repos.
Enter your new API token in Zammad and enable GitHub integration.
Hinweis
Leave the default API endpoint (https://api.github.com/graphql) as-is
unless you’re using GitHub Enterprise Server.
Once completed, a new GitHub issues tab will appear in the ticket pane. 🎉
Use GitLab integration to track GitLab issues directly within Zammad tickets.
Add issue hyperlinks and get a live summary of metadata
like status (open/closed), assignee, labels, and more.
Bemerkung
GitLab integration does not support merge requests.
If you’re already using Slack for your team communication, you’ll love this feature!
Our Slack integration can push ticket notifications about the last ticket article based on the following events:
on Ticket creation
on Ticket updates
on reached reminders
a Ticket has escalated
a Ticket is going to escalate
Zammad will provide the Ticket title, a direct link to the Ticket, the event type (creation, updated, escalation), the customer,
time and the last article that has triggered the notification. This will give you further options, as you can see e.g. escalating tickets
that are assigned to an agent that’s e.g. absent. You can interact faster, as you might see problems earlier (or even before the problem gets one).
If needed and wanted, you can even discuss directly about the topic before sending an answer to the customer. Another possible use case
would be a agent monitoring new agents and their answers to tickets.
First of all, please go to your slack workspace - go to administration => Manage Apps.
If you don’t have an app yet, you can simply add a new one - just search for `` Incoming WebHooks`` and customize the app to your needs.
Choose (or create) the channel Zamma should post it’s information to and press on „Add Incoming WebHooks integration“.
If you’re ready, copy the provided WebHook URL and go to your Zammad installation.
Hinweis
You need administrative rights on the Slack Workspace. The link to the app directory is normally https://[workspace-name].slack.com/apps .
To configure the slack integration, log in to Zammad and go to Integrations (System) => Slack in the admin panel.
Here you can choose on what evens Zammad should post information about a ticket to your Slack channel.
Next you need to device what groups shall be affected by this, as anybody with access to that specific Slack channel can read at least parts of the ticket
this might be a privacy issue, if you select the wrong groups. The username is simply the name that Zammad uses as display name inside the Slack chat.
The channel defines the Slack channel the information is being posted in. As last option, you can set a custom icon for posting to slack.
When you’re ready, just hit „Submit“ and enable the integration. Zammad will now post new ticket information based on the trigger you chose.
Below the options you have the recent log that shows the latest requests to Slack for debugging if needed.
Bemerkung
If you leave the icon URL empty, Zammad will use the Zammad logo instead. The icon should be a square PNG file.
The following figure shows how it will look if you choose to receive updates on created and updated tickets. On every post Zammad sends to the Slack channel, you can
create new threads to discuss about the new article.
If you just want to keep track of soon escalating or already escalated tickets, it will look the the following figure. Zammad changes the color in front of the post
so you can easily see the state of the ticket.
If you change the state, Zammad will also put information on what state the ticket gets and (if pending state) the date until it pends.
You’ll also recognize the color codes in front of posts on slack, as they are exact the same the ticket state colors you’ll see in Zammad!
i-doit is an open-source
configuration management database—in other words,
a tool for keeping tabs on every single piece
of your physical and digital infrastructure,
from network equipment to virtual machines
on down to the faceplates on your rack shelves and more.
What’s that got to do with Zammad?
Well, if you used tickets to track issues with all that hardware,
you might start wishing there was a way they could talk to each other.
The i-doit integration will appear under a new 🖨 tab in the ticket pane.¶
i-doit integration puts a new tab in Zammad’s ticket pane
where you can add links to existing i-doit devices
for easy reference.
(See our user documentation
to learn how it works in practice).
i-doit’s ticket system integration gives you a way to see
all the tickets for a given device without ever leaving i-doit.
(See our user documentation
to learn how it works in practice).
Enable this integration in the i-doit admin panel
under Interfaces / external data > Trouble Ticket System (TTS) > Configuration:
TTS-Type
Zammad
Username / Password
Login credentials for a Zammad agent.
Bemerkung
This agent must have read permission
for all groups that plan on using the i-doit integration.
You may even wish to create a dedicated agent account just for this integration.
(Otherwise, if the agent ever changes her password,
you will have to remember to update it here.)
Within this section we’re displaying the -in our opinion- most important
indexes for a Zammad instance.
Tipp
If you require all indexes or our listing is not good enough for you,
point your browser to the URL we’re providing and append
/_aliases?pretty=true. The result should look like so:
https://<URL>.zammad.com/_aliases?pretty=true.
Your browser will automatically ask for your credentials - you’ll then
see something like this:
In Zammad you can add your own fields to tickets, users, organizations and even
groups. This can be useful if you need to add further information to a ticket
that you don’t want to have in a note (you’ll find it easier).
Bemerkung
Try to avoid deleting objects (and disable them instead) as Zammad might run
into unexpected conditions if they are referenced somewhere.
Here’s an overview of the objects. On the upper right you can add new
Attributes. By default, there will be no custom fields - standard objects
will be grayed out, you can’t delete or change those.
Custom objects (will be displayed in black font and have a trash bin on
the right site to delete unnecessary objects.
By clicking on „custom objects“ you can edit them to suit your needs.
This function is restricted to Text and Select objects only.
Link-Templates are an amazing way to dynamically generate URLs.
They allow you to integrate other systems better without having to
manually copy data from Zammad if possible.
Bemerkung
Another great way of communicating with another system may be Zammad’s
Webhooks.
After filling a link-template enabled field, an URL icon will appear on its
right. Clicking on the icon opens a new tab.
Hinweis
Even though Zammad displays the link template within object edit and
create screens, the function is optional. It’s only active if you populate
the field.
Some of the possible permission and screen options for objects.¶
Whenever needed you can restrict access to objects based on the
user permission
(admin, ticket.agent & ticket.customer).
Tipp
🤓 Below is not set in stone 🤓
You can always adjust below settings with Core Workflows.
This also allows role based restriction. 👀
Bemerkung
In some situations, Zammad internally overrules below screen, requirement and
permission settings. This is because at some points you can’t set fields
which would mean we couldn’t create the ticket.
This currently affects:
merging
emails no matter of the originating channel (incoming)
Now that we know the different possible situations,
let’s talk about available options.
shown
Show or hide a field.
required
Set a field to mandatory. Forces users (via UI and API)
to populate the field.
Updating database after adding or editing objects¶
When adding or changing objects, Zammad will not apply the changes instantly,
but instead shows you the changed objects first.
If you’re ready to go, just click on „Update database“ to apply the changes
to Zammad. If you made a mistake or just want to discard your changes, click
„Discard changes“.
Warnung
After applying the object changes with „Update Database“ a restart of Zammad
is mandatory. If you don’t perform it, you may experience unexpected
behavior or even errors. You may want to do those kind of configurations
during maintenance windows.
Changes on objects require you to update the database
to apply these changes.¶
Tipp
🤓 Service restarts can be automated
Hosted environments automatically restart for you.
This is a very enhanced functionality and can cause unexpected UI behavior.
Please ensure to test your use cases after configuration to reduce surprises.
This page provides some of the ideas we had for Core Workflows.
Of course you can build much more complex workflows.
Hinweis
If they don’t make sense to you, don’t worry—just skip ahead to
Wie funktionieren sie? to learn about all the options in detail,
then come back here to see them in action.
All following workflows have the same base configurations.
The workflow may not use them all.
Gruppen
Sales
Support
2nd Level
Attributes
Category (Tree-Select, not mandatory, agents only)
Approved (Boolean, not mandatory, not shown, false as default)
Operating System (Text, not mandatory, not shown)
Software used (Select, not mandatory, not shown)
Group specific values and fields
This workflow set depends on the category field.
It reduces the available set of values based on the group selected.
This reduces the category options to 2ndLevel/*,
Internal/* and Others. It also sets further required
fields to mandatory and visible.
This reduces the category options to Support/*,
Internal/* and Others. It also sets further required
fields to visible.
This reduces the category options to Sales/*,
Internal/* and Others.
The Result
This is what the agent would experience with the above
workflows in place.
Approval process
In this case approved is visible to agents by default.
For this workflow, an additional role Approvalperson is required
(no further permissions).
Tipp
This workflow may work best in combination with a
trigger but technically, this is not required.
Select fields may be a better approach because they allow more
values than just a simple true or false.
The result
State dependent mandatory fields
This workflow sets Category to mandatory if the agent wants to set the
states closed or pendingclose to enforce categorization.
Core Workflows are evaluated by priority.
If 2 workflows have the same priority by alphabetical order by name.
Workflows are evaluated in alphabetical order, by name.
Because of the way Core Workflows works all changes to attributes
are checked with the application server – please see Limitations
for possible issues.
Below we’re talking about settings that have an impact and are not
self-explanatory.
Which actions should we run on the relevant fields?
The possible actions depend on the object type, however, usually
you can at least change the visibility and whether the field is mandatory.
Bemerkung
🚧 Actions are not available for relations
Let’s say you’re working in ticket context.
While you can have customer conditions, you can’t adjust objects with
actions in that scope.
That’s because this wouldn’t have any impact on the ticket dialogue.
All ticket attributes (state, owner, …) are available.
Warnung
Please also have a look at our Limitations to be safe
from surprises.
The availability of operators depends on the object type and scope.
Hinweis
🧐 Actions can cause confusion
Please note that actions may or may not restrict API based access to
attributes. We’re displaying the following icons for your overview
to understand these limits better. 👀
This icon indicates the action affects the API.
This icon indicates the action only affects the web interface.
show
Display the field in question. Allows setting of values.
hide
Hide the field in question however,
technically still allows setting the field.
Warnung
The field is not gone and still contains any value it provides!
You may want to consider remove instead.
remove
Entirely removes the field. The field value cannot be changed / set.
Warnung
This field’s value is being unset in case it’s set!
You may want to consider hide instead.
set mandatory
Sets the field to mandatory.
set optional
Sets the field to optional.
add option
Allows adding options to tree selects or selects.
Bemerkung
This requires options to be hidden beforehand (remove option).
It allows to use existing configured values.
remove option
Allows removing options from tree selects or selects.
Bemerkung
It allows to use existing configured values.
set fixed to
Reduces the available options by your selection.
Tipp
This may indirectly reduce your workflows in terms of
add option and remove option. 🤓
fill in
Allows population of string and integer fields with your value.
fill empty
Allows population of string and integer fields with your value
if the field is empty.
select
Select a specific value within a select, tree select or boolean fields.
auto select
Helps the user on tree selects and select fields:
If the field has one option to select only and has no value yet, the
value is automatically set.
Warnung
This option only works if you have one value and acts passively with more
options.
set readonly
Allows you to display an attribute as read only.
unset readonly
In case a workflow set the field in question to read only, you can
undo this with above option.
You decide at which point your workflow is evaluated.
Priorities are sorted descending – this means that a workflow matching
can stop matching in specific situations.
Please note that this is just an overview of available variables. It might be incomplete or variables might not be available within some functions.
If you’re missing variables or are not sure if something is not working as expected, feel free to ask over at the Community.
Variables can be called by typing :: (just like text modules in the frontend), as long as you’re in a supported text field within the Backend.
Zammad will show display all variables being available within this context and replace it to the variable as soon as you selected an entry.
Hinweis
You have an empty field which you referenced and it appears as -?
That’s currently working as designed - you might want to ensure that these fields always have a value (in text fields `` `` is a value!).
If you’re missing variables or are not sure if something is not working as expected, feel free to ask over at the Community.
Below you’ll find config related variables.
These hold useful configuration information that you can use within e.g. triggers to show necessary information to your customer.
The below list gives you an example what kind of data you can expect, it’s not intended to explain the data itself.
If you’re missing variables or are not sure if something is not working as expected, feel free to ask over at the Community.
Below you can find all available ticket article-based variables within Zammad.
These can be called via Triggers for example. If you’re unsure if Zammad does support variables at the point you’re at, you can try to type :: to check.
The below list gives you an example what kind of data you can expect, it’s not intended to explain the data itself.
If you’re missing variables or are not sure if something is not working as expected, feel free to ask over at the Community.
Below you can find all available ticket-based variables within Zammad.
These can be called via Triggers for example. If you’re unsure if Zammad does support variables at the point you’re at, you can try to type :: to check.
The below list gives you an example what kind of data you can expect, it’s not intended to explain the data itself.
Good point! Of course, we can’t predict what objects you might create, but we can give you a hint on how to put the puzzle together to get your custom values.
For this, we’ll talk about the inner part of the variable (so everything within #{}), please put the outer part around to have a valid variable.
The first part of the variable name consist of the object type. Currently these are:
Ticket (ticket)
User (user)
Organization (organization)
Group (group)
The second part is the name of the object. This is the name you define during object creation and can be found within the object menu at any time.
The first and second part of a variable is divided by a point, e.g.: ticket.number which will in total be #{ticket.number}.
Now, in some situations it’s possible that you’ll need to use a third part. The best example for such a situation would be a select or tree-select field which will by default return the key value, not it’s display name. For this, just extend your variable with .value. This will result in #{ticket.select.value}.
In Zammad (as admin) you can translate strings having typos or even not being translated.
You can always „Get last translations“ to ensure that you’re up to date before doing that.
Note: The language for translation is always the language you chose within your profile.
As Zammad’s main language is English, you can’t translate into English.
Translated strings are highlighted within Zammad.
If you’ve translated strings, you have two options:
You can send your changes to our central system, this will share your translation with other users. This is a great contribution.
If you don’t like your changes or want to start over, you can discard your changes at any time.
For compliance with GDPR and other data privacy laws,
you may wish to permanently delete users from the system,
along with all of their associated tickets.
The user deletion dialog lists some of the tickets
that will be removed from the system along with the user.¶
Bemerkung
🤔 Huh? I don’t see the Data Privacy panel…
Access to this panel requires admin.data_privacy permissions
(introduced in Zammad 3.5).
It may take up to ten minutes for the system to process your request,
so for each user you delete, a “deletion task” is added to the queue.
You can keep an eye on the status of these tasks in two places:
in the Activity Stream
For each deleted user, the Activity Stream will be updated twice—once when the task is created, and once when it’s complete.
Hinweis
These notifications are only visible to users with admin.data_privacy permissions.
🤓 What happens if I receive an email from a deleted customer?
Zammad automatically creates a new user account
whenever it receives a message from an unrecognized email address,
including deleted users.
Deleted users are never blocked from creating new tickets.
In the unlikely event that you receive an email
between the time that you click “Delete”
and the system has processed your request,
that ticket will be automatically removed.
The ticket number for the lost ticket will be displayed
in the Admin Panel under System > Data Privacy >
Completed Tasks > Delete User > Deleted Tickets.
🤔 What about user information stored in internal notes or other messages?
The deletion process removes user accounts and associated tickets only.
If there are references to a user’s name or information
stored elsewhere in the system,
that information will not be removed
because there is no way to safely determine
if it actually describes the user in question.
😵 I deleted an user and can still see a message they sent!
Tickets can only belong to a single customer,
but may contain messages (“articles”) from many people.
If you deleted a user but you’re still seeing articles they sent,
don’t worry—those articles are for a ticket that belongs to someone else,
and no longer contain any reference to the sender’s identity.
Please note: This is only available in self hosted instances, as we’re monitoring hosted instances and fix problems.
On the monitoring page you can see the current health state of Zammad.
This can be useful if you for example have the feeling that you don’t receive emails anymore, you can take a look here before logging onto your Server.
Besides the optical state of an event, you can also reset the access token for this module and get the monitoring URL for a monitoring system of your choice.
Example output to this can be:
Everything is OK (refer to image 2 for interface example):
Zammad has issue (whatever nature, refer to image 2 for interface example):
{"healthy":false,"message":"Channel: Twitter::Account in key:{\"id\"=\XXXXXXXXXXXXXXXXX, \"screen_name\"=\u003e\"Name\", \"name\"=\u003e\"Somewhat name\"}; Can't use stream for channel (42): #\u003cJSON::ParserError: 765: unexpected token at 'The Site Streams and User Streams endpoints have been turned off. Please migrate to alternate APIs. See https://t.co/usss'\u003e","issues":["Channel: Twitter::Account in key:{\"id\"=\XXXXXXX, \"screen_name\"=\u003e\"Name\", \"name\"=\u003e\"Somename\"}; Can't use stream for channel (42): #\u003cJSON::ParserError: 765: unexpected token at 'The Site Streams and User Streams endpoints have been turned off. Please migrate to alternate APIs. See https://t.co/usss'\u003e"],"actions":[],"token":"OgitXXXXXXXXXXXXXXXXXXXXXXNxo4ptCoQ"}
Use the Composer Settings to change the behavior of the new message editor.¶
Bemerkung
These settings apply on all tickets and to all users across the
entire system.
Note - default visibility (default: internal)
This setting decides what the default visbility of note articles is.
This affects only notes (default article on ticket answering).
The visibility of phone- and email article notes is not affected.
Email - subject field (default: no)
When setting this option to yes, Zammad will also display the subject
field when answering via email articles. It doesn’t matter if you click
on reply or switch to email article manually.
Warnung
Please note that if set to no, Zammad will automatically use the
tickets title as subject!
The subject can differ between title and mail subject if choosing yes.
Email - full quote (default: no)
Setting this option to yes will always add the content of the answered
article as quotation below your signature.
Bemerkung
This does not affect the „mark and quote“ functionality,
if you mark a text with this setting enabled,
we’ll use the marked text as quote instead.
Email - quote header (default: yes)
If you don’t want Zammad to add the date, time and name or the article you’re
quoting, set this to no.
When set to yes, this will add /CM (first character of first- and
lastname) to the bottom of every tweet answer you create.
This only affects tickets that come from the Twitter Channel.
This icon indicates the action affects the API.
This icon indicates the action only affects the web interface.
