Zammad

1. Overview

Zammad is a web-based, open-source helpdesk and customer support system designed to manage customer communication from various channels like email, phone, and social media.

With the GoInsight Zammad node, you can seamlessly integrate your customer support operations into your automated workflows. This allows you to manage the entire lifecycle of key Zammad resources, including:

• Tickets: Create, retrieve, and delete support tickets.
• Users: Manage user accounts, including creation, retrieval, updates, and deletion.
• Groups: Organize your support agents by creating, listing, updating, and deleting groups.
• Organizations: Manage customer organizations within your Zammad instance.

2. Prerequisites

Before using this node, you need to have a valid Zammad account. You may also need administrator or specific permissions to generate the API credentials required for authentication.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node provides comprehensive operations for managing the core resources within your Zammad instance, such as Groups, Organizations, Tickets, and Users.

Operation Details

Create a Group

Create a new group in Zammad using API token authentication. Supports optional parameters for group configuration including active status, assignment timeout, follow-up settings, and notes.

Input Parameters:

• Name: Group name

Options:

• Active: Whether the group is active
• AssignmentTimeout: Assignment timeout in minutes (0 means no timeout)
• FollowUpPossible: Whether follow-up is possible: yes or no
• Note: Group note/description

Output:

• Group (object): Created group information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Delete a Group

Delete a group from Zammad using API token authentication. This action cannot be undone.

Input Parameters:

• GroupId: Group ID to delete

Output:

• Deleted (bool): Whether the group was successfully deleted
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get a Group

Get a group from Zammad by ID using API token authentication. Returns complete group information including name, active status, assignment timeout, follow-up settings, and notes.

Input Parameters:

• GroupId: Group ID to retrieve

Output:

• Group (object): Group information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Groups

Get multiple groups from Zammad with pagination support. Returns a list of groups based on the specified limit and offset parameters.

Options:

• Limit: Maximum number of groups to retrieve per page
• Offset: Number of groups to skip for pagination

Output:

• Groups (object-array): List of group information objects
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Update a Group

Update an existing group in Zammad using API token authentication. Supports updating group configuration including name, active status, assignment timeout, follow-up settings, and notes.

Input Parameters:

• GroupId: Group ID to update

Options:

• Name: Group name
• Active: Whether the group is active
• AssignmentTimeout: Assignment timeout in minutes (0 means no timeout)
• FollowUpPossible: Whether follow-up is possible: yes or no
• Note: Group note/description

Output:

• Group (object): Updated group information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Create an Organization

Create a new organization in Zammad using API token authentication. Supports optional parameters for organization configuration including shared status, domain, and notes.

Input Parameters:

• Name: Organization name

Options:

• Shared: Whether the organization is shared
• Domain: Organization domain
• Note: Organization note/description

Output:

• Organization (object): Created organization information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Delete an Organization

Delete an organization from Zammad using API token authentication. This action cannot be undone.

Input Parameters:

• OrganizationId: Organization ID to delete

Output:

• Deleted (bool): Whether the organization was successfully deleted
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get an Organization

Get an organization from Zammad by ID using API token authentication. Returns complete organization information including name, shared status, domain, and notes.

Input Parameters:

• OrganizationId: Organization ID to retrieve

Output:

• Organization (object): Organization information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Organizations

Get multiple organizations from Zammad with pagination and search support. Returns a list of organizations based on the specified limit, offset, and optional search keyword parameters.

Options:

• Limit: Maximum number of organizations to retrieve per page
• Offset: Number of organizations to skip for pagination
• Search: Search keyword to filter organizations

Output:

• Organizations (object-array): List of organization information objects
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Update an Organization

Update an existing organization in Zammad using API token authentication. Supports updating organization configuration including name, shared status, domain, and notes.

Input Parameters:

• OrganizationId: Organization ID to update

Options:

• Name: Organization name
• Shared: Whether the organization is shared
• Domain: Organization domain
• Note: Organization note/description

Output:

• Organization (object): Updated organization information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Create a Ticket

Create a new ticket in Zammad using API token authentication. Supports creating tickets with title, group assignment, customer information, article content, priority, and state configuration.

Input Parameters:

• Title: Ticket title
• GroupId: Group ID to assign the ticket to
• CustomerId: Customer ID who created the ticket
• ArticleSubject: Article subject
• ArticleBody: Article body/content

Options:

• ArticleType: Article type (email, note, phone, chat, web, sms, etc.)
• ArticleInternal: Whether the article is internal (only visible to agents)
• PriorityId: Priority ID (1=low, 2=normal, 3=high, 4=urgent)
• StateId: State ID (1=new, 2=open, 3=pending reminder, 4=pending close, 5=closed, 6=merged)

Output:

• Ticket (object): Created ticket information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Delete a Ticket

Delete a ticket from Zammad using API token authentication. This action cannot be undone.

Input Parameters:

• TicketId: Ticket ID to delete

Output:

• Deleted (bool): Whether the ticket was successfully deleted
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get a Ticket

Get a ticket from Zammad by ID using API token authentication. Returns complete ticket information including title, group assignment, customer information, state, priority, and timestamps.

Input Parameters:

• TicketId: Ticket ID to retrieve

Output:

• Ticket (object): Ticket information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Tickets

Get multiple tickets from Zammad with pagination and filtering support. Returns a list of tickets based on the specified limit, offset, state, and priority parameters.

Options:

• Limit: Maximum number of tickets to retrieve per page
• Offset: Number of tickets to skip for pagination
• State: Filter tickets by state (e.g., new, open, closed)
• Priority: Filter tickets by priority

Output:

• Tickets (object-array): List of ticket information objects
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Create a User

Create a new user in Zammad using API token authentication. Supports required parameters for user creation including firstname, lastname, email, and password. Optional parameters include role_ids and active status.

Input Parameters:

• Firstname: User's first name
• Lastname: User's last name
• Email: User's email address (must be unique)
• Password: User's password

Options:

• RoleIds: Comma-separated list of role IDs (e.g., "1,2,3")
• Active: Whether the user is active

Output:

• User (object): Created user information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Delete a User

Delete a user from Zammad using API token authentication. This action cannot be undone.

Input Parameters:

• UserId: User ID to delete

Output:

• Deleted (bool): Whether the user was successfully deleted
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get a User

Get a user from Zammad by ID using API token authentication. Returns complete user information including name, email, role assignments, active status, and timestamps.

Input Parameters:

• UserId: User ID to retrieve

Output:

• User (object): User information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Current User

Get the currently logged-in user from Zammad using API token authentication. Returns complete user information including name, email, role assignments, active status, and timestamps.

Output:

• User (object): Current user information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Users

Get multiple users from Zammad with pagination and search support. Returns a list of users based on the specified limit, offset, and search parameters.

Options:

• Limit: Maximum number of users to retrieve per page
• Offset: Number of users to skip for pagination
• Search: Search keyword to filter users

Output:

• Users (object-array): List of user information objects
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Update a User

Update an existing user in Zammad using API token authentication. Supports updating user information including firstname, lastname, email, role_ids, active status, and password.

Input Parameters:

• UserId: User ID to update

Options:

• Firstname: User's first name
• Lastname: User's last name
• Email: User's email address
• RoleIds: Comma-separated list of role IDs (e.g., "1,2,3")
• Active: Whether the user is active
• Password: User's password (for updating password)

Output:

• User (object): Updated user information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

5. Example Usage

This section will guide you through creating a simple workflow to automatically create a new ticket in Zammad whenever the workflow is triggered.

The workflow will consist of three nodes: Start -> Zammad: Create a Ticket -> Answer.

1. Add the Zammad Node

• In your workflow canvas, click the + button to add a new node.
• Select the "Tool" tab in the pop-up panel.
• Find and select "Zammad" from the list of tools.
• From the list of supported operations for Zammad, click on "Create a Ticket" to add the node to your canvas.

2. Configure the Node

• Click on the newly added "Create a Ticket" node to open its configuration panel on the right.
• Credentials: In the "Credentials" field, click the dropdown menu and select your pre-configured Zammad credentials.
• Parameters: Fill in the required input parameters for creating a ticket.
  • Title: Enter a title for the new ticket, for example, New Customer Inquiry.
  • GroupId: Provide the numerical ID of the group you want to assign this ticket to. For instance, 1 for the "Users" group.
  • CustomerId: Enter the numerical ID of the customer who is reporting the issue. For example, 3.
  • ArticleSubject: Provide a subject for the initial article (message) of the ticket, such as Details of the inquiry.
  • ArticleBody: Write the main content of the ticket. For example, The customer reported an issue with their recent order..

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
• Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the ticket was created successfully.

After completing these steps, your workflow is fully configured. When run, it will create a new ticket in your Zammad instance with the specified details.

6. FAQs

Q: Why am I getting a 401 Unauthorized error?

A: This error typically indicates an issue with your credentials. Please check the following:

• Ensure your API token is correct and has not expired.
• Verify that the user associated with the API token has the necessary permissions in Zammad to perform the requested action (e.g., create tickets, manage users).

Q: How do I find the GroupId, CustomerId, or PriorityId?

A: These are numerical IDs specific to your Zammad instance. You can find them in a couple of ways:

• From the Zammad UI: Navigate to the specific item (e.g., a group or a user) in your Zammad dashboard. The ID is often visible in the URL of your browser.
• Using GoInsight: You can use the Get Many Groups or Get Many Users operations in a preceding step of your workflow to fetch a list of available resources and their corresponding IDs. You can then use the output of that node to dynamically provide the ID to the next node.

Q: My 'Create a Ticket' action is failing without a clear error. What should I check?

A: First, ensure all required fields (Title, GroupId, CustomerId, ArticleSubject, ArticleBody) are filled with valid data. A common issue is providing a GroupId or CustomerId that does not exist in your Zammad instance. Double-check that these IDs are correct and correspond to active groups and users.

7. Official Documentation

For more in-depth information about the Zammad API and its capabilities, please refer to the Zammad Official API Documentation.