Zendesk Integration

Overview of Zendesk Integration

This premium integration provides essential features for a complete developer support experience through the ability to promote questions to Zendesk cases via manual permissions-based event triggers. Note that this integration will only work with Zendesk support Enterprise edition. Once provisioned, the plugin will be available in the Disabled Plugins tab in the admin console and you will need to enable it.

The Zendesk plugin is a premium feature and is not part of the standard AnswerHub subscription. Please contact your CSM for details.

Personas and User Flows

Administrator

ADMIN VIEW

• A new menu called Case promotions in the admin console.
  • All questions promoted to case/ticket in one data grid.
• A new menu called Support Ticket Integration in the admin console to configure tickets.
• Your profile will show your questions promoted to Zendesk with a link to the question. The question page will show you the case number as a link to Zendesk, date of creation, and time of creation (UTC) under "Support Case" in the right side panel.

ADMIN CAPABILITIES

• Configure question extended properties to include extra fields for the user to fill in for each question (Navigate to Content > Node Structure > General Settings, click the MANAGE QUESTION PROPERTIES button under "Extended Properties").
  • Map the new question fields from AnswerHub to Zendesk custom fields when you build your ticket template in the Support Ticket Integrations page.
• Configure your integration in the Support Ticket Integrations page.
• Assign the ability to work with the integration by granting the Zendesk custom role permissions.

👍

Make Sure Appropriate Custom Role Permissions for Zendesk are Granted Accordingly:

There are three custom role permissions to choose from:

• Create Zendesk case: Allows the user to see a new area on the right sidebar labeled Forward to Case or Ticket with the CREATE TICKET button.
• View own Zendesk case: Allows a user acces to their questions promoted to Zendesk with a link to the question when they go to their profile.
• View Zendesk case: Allows a user to see the link to Zendesk from the case created.

Moderator

User with Zendesk Integration Access.

📘

NOTE:

The user with Zendesk integration access role is customizable in the admin console through custom role permissions.

MODERATOR VIEW

• User with Zendesk Integration access view.
• A new area on the right sidebar labeled "Forward to Case or Ticket" with the CREATE TICKET button.
• Click the CREATE TICKET button from any question and forward that question to Zendesk as a ticket.
  • The next time someone clicks on that question, a link to the Zendesk ticket, its creation date and time (UTC) will then display in the "Support Case" section in the right side panel.
  • The ticket number from Zendesk will display as a link to connect directly to Zendesk from AnswerHub.
• Your profile will show your questions promoted to Zendesk with a link to the question. The question page will show you the case number as a link to Zendesk, date of creation, and time of creation (UTC) under "Support Case" in the right side panel.

MODERATOR CAPABILITIES

• User with Zendesk Integration access capabilities.
• Create tickets from posted questions to forward to a case or ticket in Zendesk.
• Review the modal window displaying the ticket info to send to Zendesk.
  • All information will be auto-populated from the question.
    • The default information pulled from the question will pull for the name, email, company, subject, and the description.
    • Any custom fields configured by the admin will show in the question and will auto-populate into the ticket to send to Zendesk.
  • Have the option to click Submit to send the question to Zendesk or cancel by closing the modal window.
• Click on the case number link from the forwarded question to go directly to Zendesk.

Community User

COMMUNITY USER VIEW
Your profile will show your questions promoted to Zendesk with a link to the question. The question page will show you a statement under "Support Case" in the right side panel that "A Support Case Has Been Created."

COMMUNITY USER CAPABILITIES

• Post a question to AnswerHub.
• Cannot send cases to Zendesk.
• Select an accepted answer to their question even after it has forwarded to Zendesk.
  • The answer will mark as the accepted answer in AnswerHub. However, the case will not mark as solved in Zendesk automatically.

As an Admin...

The next few headings pertain to administrators until you get to the "As a Moderator" heading.

Setting Up A Zendesk Account And Obtaining Your API Token

Pre-requisites

• Register with Zendesk by creating an account.
• If you are using custom fields, you MUST have already created those fields in Zendesk to map to them when you configure your integration in the admin console.

Create a Zendesk Account

Register to create a username, password, and domain (Zendesk endpoint) using the following link: https://www.zendesk.com/register/

• Asks for you to create a username and password and suggests using your work email for the username.
• Follow the prompts from Zendesk and provide the requested information.
• Asks you to provide input or accept suggested domain (you will use this domain to fill in your Zendesk Endpoint text field on the Login page in "Support Ticket Integration" in your Admin console).
• The system will ask you to verify your email to get to your domain.

Creating a New API Token for Zendesk:

Navigate to the Zendesk Support Link to set up your new API token.

• Follow the instructions listed on that page; it walks you through where to go in the Zendesk domain you just created.

Remember to save your username, password, API Token, and the new domain you created for later steps.

Case Promotion and Escalation

Manual Permissions-based Promotion

• Permissions to promote own question to a case, or to promote other’s questions to a case (typically moderator or support agent permission).
• Follow the ticket escalation instructions as follows:
  Ticket escalation handles manually through user and group permissions:
  • Navigate to Users & Groups > Manage.
  • Select either a specific User or Group(s) of users to provide Zendesk Custom Role permissions.
  • Click the WRENCH icon.
  • Select Permissions from the menu.
  • On the Permissions page, select the wrench in the "Site Permissions" section.
  • Select Advanced.
  • Select Custom Roles.
  • Select the appropriate Zendesk permissions.
• Once the user has obtained the appropriate permissions to escalate cases and create tickets, they will be able to manually promote questions.
  • The user will need to manually go to each question and click the CREATE TICKET button and submit the ticket to Zendesk.

👍

Read About Question Extended Properties Before Creating a Ticket Template!

As an admin, you will need to understand the question extended properties in the AnswerHub admin console before navigating to the support ticket integration menu to create your ticket template for questions.

Learning About Question Extended Properties

To create a new question extended property, follow these steps:

1. Navigate to Content > Node Structure > General Settings.
   Result: Extended Properties pane displays on the right-hand side of the page.
2. Click the MANAGE QUESTION PROPERTIES button.
   Result: The Question Extended Properties page display.
3. Click the CREATE NEW PROPERTY button.
   Result: The "New Extended Property" modal window will appear.
4. In the Main tab, enter the required information in the following fields (we do not support dashes in the text fields):
   a. Name
   b. Label
   c. Weight

📘

NOTE:

Heavier weight implies more importance, pushing that property field to the top of the list in the AnswerHub User Interface (UI).

5. Select the Content tab.
   Result: The Content tab displays.
6. Click the Type drop-down menu and select the new extended property type from the following:

• Simple text: The system adds a field for a single line of text to the Question UI.
  • If selected, the Minimum length and Maximum length fields display.
    • For Minimum length, enter the minimum characters a user can enter in this field.
    • For Maximum length, enter the maximum characters a user can enter in this field.
• Multiline text: The system adds a field for multiple lines of text to the Question UI.
  • If selected, the Minimum length and Maximum length fields display.
    • For Minimum length, enter the minimum characters a user can enter in this field.
    • For Maximum length, enter the maximum characters a user can enter in this field.
• Number: The system adds a number field to the Question UI.
  • If selected, the Minimum length and Maximum length fields display.
    • For Minimum length, enter the minimum characters a user can enter in this field.
    • For Maximum length, enter the maximum characters a user can enter in this field.
• Date: The system adds a date field to the Question UI.
• Boolean (true/false): The system adds a Boolean (true or false) checkbox to the Question UI.
• Value selection: The system adds a single-selection drop-down menu to the Question UI.
  • If selected, the Selections field displays. Enter the values that user can select in this menu (one value per line).
• Multiple Value selection:" The system adds a multiple-selection drop-down menu to the Question UI.
  • If selected, the Selections field displays. Enter the values that user can select in this menu (one value per line).

7. For all the options:
   a. Select the Versioned checkbox to allow users to revert to previous revisions.
   b. To make the new property required before a user can submit a question, select the Required checkbox.
8. Select the Security tab to specify who can view or modify the extended property.
   Result: The Security tab displays.
   a. Click the Permissions to view the field drop-down menu and choose from the following:
   - Deny: Users cannot view this field.
   - Must be logged in: Only logged in users can view this field.
   - Must have role: Only users with a specific role can view this field.
   - If selected, a second drop-down menu with a list of all the permissions for your AnswerHub site displays.
   - Select the permission a user must have to view this field.
   b. Click the Permissions to edit the field drop-down menu and choose from the following:
   - Deny: Users cannot edit this field.
   - Must be logged in: Only logged in users can view this field.
   - Must have role: Only users with a specific role can view this field.
   - If selected, a second drop-down menu with a list of all the permissions for your AnswerHub site displays.
   - Select the permission a user must have to edit this field.
9. Click the OK button.
   Result: A green bar that reads "Extended property added successfully" displays at the top of the Question Extended Properties page. The extended property displays on the table, with its position determined by the weight of the property. The property displays in the Question UI for users who have the selected permissions setting.

📘

NOTE:

If you couldn't successfully create an extended property, check to make sure you do not have any dashes in any names entered in the text fields.

Configuring Support Tickets As An Admin in AnswerHub

1. Navigate to Plugins > Support Ticket Integrations
2. Navigate to Support Ticket Integrations Area. You will configure the integration here.
   Result: You will automatically arrive at the login page.
3. Select the Zendesk icon.
4. On the Login Page: Enter your username, API Token and Zendesk Endpoint.
5. On the Settings Page: Follow the ticket escalation instructions.
6. On the Template Page: Customize your ticket by adding up to six additional custom fields.

• If you click on the QUESTION MARK icon, you will see the modal window pop up with instructions on how to "Build Your Ticket Template."
• The default information on the left-hand side will pull the name, email, company, subject, and the description from the question.
• Configure your custom field mappings between AnswerHub and Zendesk fields. The system handles configuration through question extended properties in AnswerHub and mapped to custom_fields in the Zendesk ticketing API.

7. Modify the ticket template by following instructions on the first modal window. Click the addition sign (+) to add additional custom fields if necessary, and then press Continue.

• For your convenience, below are the instructions on the first modal window:
  • Preview your ticket template showing the default AnswerHub information to send to Zendesk upon case creation. In addition, add up to six custom Zendesk fields.
    1. Open the "Preview and Build Your Ticket Template" by clicking the addition sign (+) and map your fields. The system will add your selections to the form in the question interface.
    2. Use the delete icon and custom settings icon for the following:
       a. Click on the DELETE icon, to delete a field.
       b. Click the GEAR icon, to specify the type of information presented in the custom fields.
       • Note, this is where you will create the mapping for AnswerHub properties to already created Zendesk custom fields.

8. On the Publish page: You will see your newly created ticket template and have the option to either EDIT it or PUBLISH it by clicking one of those two buttons at the bottom of the page.

Admin Console View of the Case Promotions

Provides the ability to see all questions promoted to cases in the admin console; this is permission controlled.

1. If the admin wants to see the case promotions in the admin console, they navigate to Content > Case Promotion.
2. The default case promotion page is a tabular view with five columns of information:
   • First Column: Promoted question description
   • Second Column: Status of the case
   • Third Column: Date/Time (UTC time)
   • Fourth Column: Case number in Zendesk
3. There is a search feature on the top right-hand side above the table on the default case promotion page.
   • The search feature on the case promotion page only works for Zendesk promoted question descriptions.

Community Interface View of the Case Promotions as an Admin

The Community Interface provides the ability to see your own questions promoted to cases in your user profile.

As an Administrator:

1. Click the BACK TO SITE button if you are in the admin console and go to your profile:
   a. Click on your Avatar drop-down to get to your profile.
   b. You can view the number of case promotions listed next to My Subscriptions by clicking on the Case Promoted link.
   • You will see the case number, the question description as a link to the question, and the date/time (UTC) created for each submitted question to Zendesk.
2. Under "Your Activity" in your profile, select the escalated question link:

• The system will direct you to the question. Under the right side panel, you will see "Support Case" which displays the case number as a link, the date and time (UTC). The case number is clickable and directs you to Zendesk to see more information.

As a Moderator...

The next few headings pertain to moderators until you get to the "As a Community User" heading.

Create a Support Ticket from the User Interface

1. Navigate to the question you want to create a support ticket from.

• You will see a modal form called "Create a Support Ticket from this Question" with text fields for Name, Email, Company, Subject, and Description on the left-hand side, and any additional created custom fields on the right-hand side.

2. Click Submit once you have reviewed all the auto-populated fields.

Community Interface View of the Case Promotions as a Moderator

The Community Interface provides the ability to see your own questions promoted to cases in your user profile.

As a Moderator:

1. Click on your Avatar drop-down to get to the profile.

• You can view the number of case promotions listed next to "My Subscriptions" by clicking on the Case Promoted link.
  • You will see the case number, the question description as a link to the question, and the date/time (UTC) created for each submitted question to Zendesk.

2. Under "Your Activity" in your profile, select the escalated question link:
   • The system will direct you to the question. Under the right side panel, you will see "Support Case" which displays the case number as a link, the date and time (UTC). The case number is clickable and directs you to Zendesk to see more information.

As a Community User...

The next few headings pertain to community users.

New Interactions for Community Users in the AnswerHub Community

• You can still create questions, but you may notice additional text fields to enter information about your question. (This will be the case if your admin adds additional text fields).
  • If you do not fill out all the text fields, you cannot post your question.
• You will see a statement under "Support Case" in the right side panel that "A Support Case Has Been Created" when a moderator creates a case from your questions and sends it to Zendesk.
• You can select an accepted answer to questions even after it has forwarded to Zendesk.
  • The answer will mark as the accepted answer in AnswerHub. However, the case will not mark as solved in Zendesk automatically.

Community Interface View of the Case Promotions as a Community User

The Community Interface provides the ability to see your own questions promoted to cases in your user profile.

As a Community User:

1. Click on your Avatar drop-down to get to your profile.

• You can view the number of case promotions listed next to "My Subscriptions" by clicking on the Case Promoted link.
  • You will see the case number, the question description as a link to the question, and the date/time (UTC) created for each submitted question to Zendesk.

2. Under "Your Activity" in your profile, select the escalated question link:

• The system will direct you to the question. Under the right side panel, you will see "Support Case" which displays a statement that "A Support Case Has Been Created."