Zendesk-Kognitos Integration Manual

This manual is divided into several sections, each focusing on a specific aspect of the Zendesk-Kognitos integration.

Introduction

The integration of Zendesk with Kognitos offers a powerful and intuitive way to interact with Zendesk data and functionalities. This integration enables users to perform a wide range of operations on Zendesk tickets, including creating, updating, assigning, and deleting tickets, as well as managing comments and automating processes, all through the use of Kognitos’ natural language processing capabilities. This section provides an overview of the Zendesk-Kognitos integration and outlines the prerequisites for using Zendesk on Kognitos.

Prerequisites for Using Kognitos with Zendesk

Before you can start using Kognitos to interact with Zendesk, there are several prerequisites that need to be met:

Zendesk Account: You need to have an active Zendesk account. If you do not have one, you can sign up for a Zendesk trial account to get started.
API Access: Ensure that your Zendesk account has API access enabled. API access is required for Kognitos to communicate with Zendesk.
Zendesk Subdomain: Obtain your Zendesk subdomain, which is part of your Zendesk URL (e.g., https://<subdomain>.zendesk.com).
Zendesk Email: The email address associated with your Zendesk account.
Zendesk Token or Password: You will need either an API token or your Zendesk account password to authenticate API requests.

Once these prerequisites are met, you are ready to start leveraging the power of Kognitos to enhance your Zendesk experience, making it more accessible, efficient, and customizable.

Setting Up Zendesk Connection

Connecting to Zendesk

To interact with Zendesk using Kognitos, establishing a secure connection to your Zendesk instance is the first critical step. This section outlines the credentials required for this connection and provides a detailed, step-by-step guide to connect successfully.

Required Credentials

To connect to Zendesk, you will need the following credentials:

Zendesk Subdomain: The subdomain of your Zendesk instance. This is part of your Zendesk URL and typically follows the format https://<subdomain>.zendesk.com.
Zendesk Email: The email address associated with your Zendesk account.
Zendesk Token and Password: The account's API token and your Zendesk account password. API tokens can be generated in your Zendesk settings under "API".

Step-by-Step Connection Process

Gather Credentials: Ensure you have all the required credentials: Zendesk Subdomain, Email, API Token and Password.
Navigate to the Departments tab of Kognitos and search for Microsoft Outlook
Click on + New Book button on the right of the Departments page
Search for Zendesk and then click on the book which is shown

Add in the credentials when you are prompted

Connection Established: Once the connection is successfully established, you are ready to perform various operations on Zendesk. You can now fetch data, create new tickets, update existing ones, delete tickets, and more.

Working with Zendesk Tickets

Interacting with Zendesk tickets is a core functionality when integrating Zendesk with Kognitos. This section covers how to create, update, assign, and delete Zendesk tickets.

Creating a Ticket in Zendesk

To create a new ticket in Zendesk, you need to specify the ticket details such as subject, comment, and priority.

Example:

the ticket is
    the subject is "New Support Request"
    the comment is "Customer is experiencing issues with logging in."
    the priority is "High"
create the ticket in zendesk

This command creates a new ticket with the specified subject, comment, and priority.

Updating a Ticket in Zendesk

To update an existing Zendesk ticket, you must identify the ticket by its ID and specify the fields you want to update.

Example:

the ticket's ID is "12345"
change the ticket's status to "Open" in zendesk

This command updates the status of the specified ticket to "Open".

Assigning a Ticket in Zendesk

To assign a ticket to a specific agent, you need to specify the ticket ID and the assignee.

Example:

the ticket's ID is "12345"
assign the ticket to "[email protected]" in zendesk

This command assigns the specified ticket to the given agent.

Deleting a Ticket in Zendesk

To delete a specific Zendesk ticket, you need to specify the ticket ID.

Example:

the ticket's ID is "12345"
delete the ticket in zendesk

This command deletes the ticket with the specified ID.

Getting a Ticket in Zendesk

To retrieve details of a specific Zendesk ticket, you need to specify the ticket ID.

Example:

the ticket's ID is "12345"
get the ticket in zendesk

This command fetches the details of the specified ticket.

Field Metadata and Validation

The metadata dictionary defines the structure and validation requirements for various ticket fields, such as comment, requester, satisfaction_rating, etc., including their types (str, int, bool, list) and options for fields with predefined values (e.g., priority, status, type).

Example Metadata

Comment: str
Requester: str
Satisfaction Rating: int
Priority: str (options: "Low", "Normal", "High", "Urgent")
Status: str (options: "New", "Open", "Pending", "Hold", "Solved", "Closed")

Validation Example

The ZendeskProxy class encapsulates methods for interacting with Zendesk, including validation and conversion of field values.

Example:

validate_and_convert_value("priority", "High")

This method validates and converts the value for the priority field.

Error Handling and Exceptions

The code includes examples of raising exceptions (ValueError, RuntimeError, RecordNotFoundException, ParserError) in various scenarios, such as invalid field values, attempting to assign a ticket to a non-agent, or when required data is missing or incorrect.

Example Error Handling

if not is_valid_priority(priority):
    raise ValueError("Invalid priority value")

This snippet checks if the priority value is valid and raises a ValueError if it is not.

Glossary of Terms

API (Application Programming Interface): A set of rules and protocols for building and interacting with software applications. Zendesk API allows external services like Kognitos to communicate with Zendesk to retrieve or modify data.
CRM (Customer Relationship Management): A technology for managing all your company's relationships and interactions with customers and potential customers. Zendesk is a leading CRM platform.
Zendesk Ticket: A record in Zendesk representing a customer support request or issue.
Zendesk Subdomain: The unique identifier for your Zendesk instance, part of your Zendesk URL.

By following these guidelines, you can effectively manage Zendesk tickets in Kognitos, from creating and updating records to assigning and deleting them as needed.