Escalator User Guide

1. Overview

Escalator is an app designed to help agents manage complex or multi-issue tickets by giving them an easy way to link, split or escalate tickets. It's been designed to be easy to use, while supporting a wide range of workflows, processes and business rules.

Escalator helps break down complex tickets into smaller, more manageable pieces. Agents can do this in one of two primary ways:

1. Escalations - Call in assistance from vendors, experts or even just specific agents using a separate, linked ticket.
2. Splitting tickets - Separate out specific sub-problems, so they can be handled independently of the main ticket.

Escalator also allow agents to link related tickets, whether from the same end-user or a different one. This can be helpful for highlighting previous solutions, earlier interactions, or adding any number of useful connections.

An example

ABC Widget Inc is a manufacturer that sells it's products online, though it's own website. It manage the content on the website internally, but contracted a separate company to build and support the website. One day they receive a ticket from a customer. The customer is getting an error while trying to place an order. They also mention some poorly worded product descriptions and would like help updating their address in the order system.

The assigned agent immediately sees that there are three separate problems. The agent is able to update the customer address, so she does that. The other two issues require additional help. The agent escalates the website error to the external developer who manages the website, asking them to look into it. The agent copies over the error message and a few other relevant details. She also creates a sub-ticket, assigning it to the Marketing department, notifying them of confusing wording. The agent then updates the customer, letting them know the address is corrected and she's waiting to hear back on the other issues.

The next day, as the agent is reviewing tickets, she sees both sub-tickets have been updated. She opens each linked ticket to see each issue has been resolved. She send a message to the customer, letting them know and marks the ticket as solved.

About the user guide

This guide is written based on version 2.2 of Escalator.

2. Installing Escalator

You can install Escalator via the Zendesk Apps Marketplace.

Once it's been installed, some additional setup is required before Escalator can be used. Specifically, you'll need to set up custom ticket field. This field is used for storing data and keeping track of escalations and sub-tickets for the current ticket.

Adding a data field

To create a custom ticket field, go to your Zendesk settings and click on Ticket Fields. On the next screen, click the Add field button on the right-hand side. Select Multi-line.

Under permissions, choose Agent only and enter a name in the Title shown to agents box. The field will be hidden from agents while the app is running, so the title is only used to help admins identify the field.

NOTE: If you have more than one ticket form set up, be sure to add this new field to each form.

After you've created the field and added it to add ticket forms, you'll need to reload the browser page before the field is visible on tickets and accessible to the app.

3. Basics

3.1 User interface

Working down from the top, you have:

Settings button
When logged in as an admin, you'll see this 'cog' icon, which is a button. Click on it to open the settings dialog.

Escalate drop down
This is the list of pre-configured escalations agents can use.

Linked tickets
Below the dropdown is the Linked tickets section. Depending on the relationships the current ticket has with other tickets, what is display will vary. For each associated ticket, the ticket id, status and subject are shown. Sometimes additional information is included, like the name of the escalation used. You can click on the ticket to open it.

• Parent Ticket - The current ticket is the result of an escalation or an agent using the sub-ticket dropdown.
• Sibling Tickets - This will be displayed if the current ticket has a parent ticket, but there are other sub-tickets off the parent ticket.
• Sub-tickets - These are sub-ticket created from or linked to the current ticket.

Sub-ticket dropdown
To the right of the sub-ticket heading is a button labelled + Add. This is a dropdown menu and will allow you to create sub-tickets or link existing tickets.

3.2 How to use

3.2.1 Difference between escalations and sub-tickets

While escalations and sub-tickets seems similar, and they are, there are a few important distinctions. First, escalations give admins more control over the properties and fields on the new sub-ticket. It also prompts the agent to select the comments and attachments to copy over. Sub-tickets are either blank to begin with or are a copy of the current ticket. Agents then must customize the ticket, depending on the purpose and assignee of the new ticket.

4. Escalating tickets

4.1 Selecting a target

To escalate a ticket, an agent simply chooses an escalation from the dropdown list in the app. When they do that, a new ticket tab is opened and a dialog appears, prompting the agent to select the comments and attachments they'd like to bring over. Once this has been done, the agent submits the new ticket and the process is complete.

4.2 Copying comments and attachments

To select individual comments to be included, click the circle to the right of the comment. Selected comments have a filled in circle with a checkmark, unselected comments have an empty circle. To quickly select or de-select all comments click the circle at the top, to the right of the x / y comments selected label.

If a comment has attachments, they'll be listed below the comment. To include attachments on the escalated ticket, select the comment and click the circle at the bottom right corner of the attachment. You can also select all/none using the link next to the Attachments heading.

5. Sub-tickets

5.1 New ticket

To create a completely empty sub-ticket, click the sub-ticket dropdown and choose New ticket. A new ticket will open. The only value populated is the ticket subject. Fill in the fields you'd like and click the Submit button to complete the process.

IMPORTANT: This is probably obvious to most people, but the association isn't created until the new ticket is submitted. Don't forget to submit the new ticket!

5.2 New ticket (copy fields)

To create a new ticket, copying values from the current ticket, click the sub-ticket dropdown and choose New ticket (copy field). Like the previous option, a new ticket will open, but this time some all the fields on the parent ticket with values, will be copied over to the new ticket.

To customize which field values are copied to the new ticket, use the Copy only the fields listed below and Fields to copy or exclude options in the app settings.

Note: changes made by agent but have not been saved will not be used to copy. Please prefer to 5.3 New Ticket (copy unsaved fields) below if want to use these changed fields when copy.

5.3 New ticket (copy unsaved fields)

This is same as 5.2 New ticket (copy fields) option. However, if the fields have been changed on screen, they will be used to copy (for subticket creation), instead of using the saved ticket data for copy.

5.4 Existing tickets

To link an existing ticket, click the sub-ticket dropdown and choose Existing ticket. A dialog will then appear. By default, recent and bookmarked tickets are displayed.

NOTE: You can manage bookmarked tickets using the Quickie PLUS app, also available in the Zendesk App Marketplace.

If you know the id of the ticket you want to link, enter it in the Keyword or Ticket ID: field. If you don't have that, you can use the same box to search for a specific ticket. After a short delay, the ticket listing below the box will update with up to 20 matching tickets.

To select a ticket, click on it. The Keyword or Ticket ID: box will update to display the ticket id. You can easily identify the currently selected ticket by it's green border. To clear the selection, remove the ticket id from the Keyword or Ticket ID: box.

When you've selected the ticket you want to link, click the Add ticket button and the association will be created. Click Cancel to dismiss the dialog without creating a link.

5.4 Unlinking

You can't unlink parent tickets or sibling tickets, only sub-tickets. To do that, simply click the 'X' to the right of it's subject. A confirmation dialog will appear where you can cancel the action or proceed.

Unlinking removes the connection between the tickets. There's no undo, but you can restore the link using the Existing ticket option on the sub-ticket dropdown.

6 Configuration

6.1 Overview

The recommended way to update the app settings is using the built-in settings dialog. Only admin users have access to it.

6.2 Settings dialog

To open the settings dialog, log in as an admin user, open a ticket and then click the 'cog' icon near the top of the app.

The dialog is split into two columns. On the left are the general app settings. On the right are escalations.

6.2.1 App settings

• App name - The is the name of the app, displayed at above the main interface in the ticket sidebar and at the top of dialogs.
• App Data field - This is the custom ticket field used to track sub-tickets and escalations for a ticket.
• Escalator Data Field (optional) - If you have an older version of Escalator installed, you can add the field id here so that Escalator will import the old data for tickets that have it.
• For "New ticket (copy fields/copy unsaved fields)" feature - This option is used together with Fields to copy or exclude field below it. It allows you to dictate whether the fields in the Fields to copy or exclude setting are to be copied or excluded, when an agent adds a New ticket (copy fields) (not an escalation). When Copy only the following fields is selected, only the field ids listed in the Fields to copy or exclude setting are copied. When Copy all fields, except for the following fields is selected, every field is copied when creating a new ticket, except for the field ids listed in Fields to copy or exclude setting.
• Fields to copy or exclude - Fields to copy or exclude when an agent adds a "New ticket (copy fields)" (not an escalation). Supported values are: assignee, group, requester, priority, tags, type, problem_id, description and custom field ID. Separated by commas.
• Include ticket attachments on subticket creation - If ticked, the attachments of the ticket (first comment), will be automatically added as links upon subticket creation
• Enable attachments selection on subticket creation - If ticked, upon subticket creation, a popup to select attachments (to include as links on the subticket) will present
• Default Tags - In this group of fields (New sub-ticket, Exisiting sub-ticket, Parent of new sub-ticket, Parent of exisiting sub-ticket) you can specify tags to be added when create new sub-tickets or linking existing tickets.
• Do not open app tray automatically - By default, Escalator will open the ticket apps tray when loading, if the apps tray is closed. Check this option to disable this behavior.

6.2.2 Escalations / Sub-tickets

In this column is a list of configured escalations and sub-tickets.

The Default escalation - These are fields and values you want used with every escalation. Other escalations can override these, but if they don't, these defaults will be used. You can edit this, but not delete it.

6.3 Adding/Editing Escalations

Click the Add escalation button to create a new escalation. Click on the edit button on the right side of the escalation table to edit an existing configuration.

On the screen that appears, set any fields or ticket properties you want used with the new escalation. You have access to most fields that would appear on a ticket.

6.3.1 Required fields

There are only 3 required fields:

• Escalation Name - The name of the escalations, as it appears in the dropdown in the ticket sidebar, as well as the settings dialog.
• Escalation Tag - The tag is an internal id used by the app for each escalation. It's also added to the sub-ticket, prefixed with vendor_ticket_. i.e., If the tag for the escalation was microsoft, the tag added to the sub-ticket would be vendor_ticket_microsoft. This makes it easy to identify escalated tickets using it's tag.
• Requester - Set this to the person you want to escalate to. While this seems counter-intuitive, it allows you to escalate tickets to people who aren't agents in your Zendesk, like external vendors.

6.3.2 Special escalation options

There are a few additional options that you won't find on a ticket

• Allow public comments to be included - Public comments on the parent ticket can be copied to the sub-ticket
• Allow private comments to be included - Private comments on the parent ticket can be copied to the sub-ticket
• Allow comment attachments to be included - Attachments on the parent ticket can be copied to the sub-ticket
• Vendor ticket to have same fields as original ticket - Fields from the parent ticket are copied to the sub-ticket, unless overridden.
• Vendor ticket to have same tags as original ticket - Tags from the parent ticket are copied to the sub-ticket, unless overridden.
• Allow vendor ticket to be escalated again - Limit or allow sub-tickets from being escalated further.

6.3.3 Placeholder values

When setting the subject or description on sub-ticket, Escalator allows you to insert values from the parent ticket. You use placeholders to indicate what values should be inserted. To use a placeholder, put the value inside double curly brackets. For example:

This is a subticket of {{ticket.id}}
The original ticket subject was: {{ticket.subject}} 
assigned to {{ticket.assignee.name}}

The app supports all Zendesk ticket placeholders (except satisfaction rating).

Full list of supported placeholders can be found here: https://support.zendesk.com/hc/en-us/articles/203662156-Zendesk-Support-placeholders-reference

7 Auto-update parent ticket from child ticket

7.1 Overview

Sometimes we may want to change parent ticket if a child ticket has been changed. For example, solve the parent ticket if the child ticket is solved.

Escalator makes it possible by using Trigger, Webhook and Escalator export function.

• Escalator exports Parent Ticket ID into a ticket field of the child ticket
• Trigger runs on the child ticket, picks up that Parent Ticket ID, then calls webhook to update the parent ticket via API.

7.2 Set up

Remember to replace [subdomain] to your Zendesk subdomain in the below instruction.

7.2.1 Add custom field and enable Export parent Ticket ID feature

• Open your Ticket Fields list (https://[subdomain].zendesk.com/admin/objects-rules/tickets/ticket-fields) then add a Numeric custom ticket field. Note down the ID of this newly created field in the list for later use in trigger. Remember to add it to every ticket form if your Zendesk has multiple ticket forms. As an example, let's call the field "Parent Ticket ID".
  
  
• Then reload your Zendesk webpage, open Escalator App settings to set (Optional) Export parent Ticket ID to field  to the field just created above
   
  
   
   
  Note: Zendesk may take a bit of time to make the field available after it is created. May need to wait and reload the browser page a few times before you see it in the drop-down.

7.2.2 Add API token and webhook to update ticket

• Open Zendesk API management (https://[subdomain].zendesk.com/admin/apps-integrations/apis/zendesk-api/settings) and add a new API token, remember to note the newly created API token to be used in Webhook below.
• Open Webhook management page (https://[subdomain].zendesk.com/admin/apps-integrations/webhooks/webhooks) and create a new webhook with the following details:

  Name: Escalator - Update parent ticket
  Endpoint URL: https://[subdomain].zendesk.com/api/v2/tickets/update_many.json   (<----- replace [subdomain] with your ZD subdomain)
  Method: PUT
  Request format: JSON
  Authentication: Basic Authentication
  Username: [email]/token    (<---- with [email] = the email address of an admin who has power to update all tickets on your Zendesk)
  Password: [apiToken]     (<---- with [apiToken] = token created from above)

An example webhook is as below:

 

7.2.3 Add trigger to update parent ticket

This is the last step, set up a trigger to run on child ticket when condition is met, so that the trigger will call the webhook to update the parent ticket.

In this example we'll auto-solve parent ticket when the child ticket has tag autoSolve_parent.

A. Trigger conditions:

B. Trigger actions:

When the conditions above met, the trigger should call the Webhook with JSON data targeting the parent ticket to update the parent ticket.

In the below example, we simply set the status of parent ticket to Solved. Remember to replace 360001799895 in the example to correct field ID created at step 7.2.1

C. Outcome:

With the above trigger setup, when we add tag autoSolve_parent to a child ticket, its parent will be solved (and the tag is instantly removed off the child ticket so we cannot see it).

Instead of solving parent ticket, we can perform other actions (e.g. change ticket field, change assignee, group...etc) by changing the JSON data structure of the trigger action.

See API Batch Updates https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#update-many-tickets and https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#update-ticket for more info.

(Or we can set JSON data to add a tag to the ticket. And have trigger to perform actions based on that tag, rather than set everything in the JSON data structure)

Contact us if you are unsure how to setup the JSON data.

8 Auto-update child tickets from parent ticket

8.1 Overview

Sometimes we may want to perform actions on all child tickets of the current ticket. For example, solve all child tickets when parent ticket is soved.

Escalator makes it possible by using Trigger, Webhook and Escalator export function.

• Escalator exports Child Ticket IDs into a ticket field of the parent ticket
• Trigger runs on the parent ticket, picks up these Child Ticket IDs, then calls webhook to update all these child tickets.

8.2 Set up

Remember to replace [subdomain] to your Zendesk subdomain in the below instruction.

In Escalator, there are 2 type of child tickets:

• Sub tickets: are those that created via the Add+ button of Escalator app
• Escalated tickets: are those that created via the dropdown Escalation list of Escalator app (this list is setup by admin)

Important: In the below example, we only action on the Sub tickets. If we need to action on both subtickets and escalated tickets, please make sure 2 fields are created at step 8.2.1

8.2.1 Add custom field and enable Export SubTicket IDs feature

• Open your Ticket Fields list (https://[subdomain].zendesk.com/admin/objects-rules/tickets/ticket-fields) then add a Text custom ticket field. Note down the ID of this newly created field in the list for later use in trigger. Remember to add it to every ticket form if your Zendesk has multiple ticket forms. As an example, let's call the field "Escalator's subtickets IDs".

Then reload your Zendesk webpage, open Escalator App settings to set (Optional) Export sub ticket IDs to field  to the field just created above

 
 
Note:

• If you also want to action on escalated tickets instead of sub tickets, you will need to create another field for use with setting (Optional) Export escalated ticket IDs to field. Never use same field for these 2 settings, otherwise they will overwrite each other.
• Zendesk may take a bit of time to make the field available after it is created. May need to wait and reload the browser page a few times before you see it in the drop-down.

8.2.2 Add API token and webhook to update ticket

• Open Zendesk API management (https://[subdomain].zendesk.com/admin/apps-integrations/apis/zendesk-api/settings) and add a new API token, remember to note the newly created API token to be used in Webhook below.
• Open Webhook management page (https://[subdomain].zendesk.com/admin/apps-integrations/webhooks/webhooks) and create a new webhook with the following details:

  Name: Escalator - Update parent ticket
  Endpoint URL: https://[subdomain].zendesk.com/api/v2/tickets/update_many.json?ids={{ticket.ticket_field_24380055}}   (<----- replace [subdomain] with your ZD subdomain, replace 24380055 to the field ID created at step 8.2.1 to target the subtickets ids)
  Method: PUT
  Request format: JSON
  Authentication: Basic Authentication
  Username: [email]/token    (<---- with [email] = the email address of an admin who has power to update all tickets on your Zendesk)
  Password: [apiToken]     (<---- with [apiToken] = token created from above)

An example webhook is as below:

Note: repeat this step and change to correct field ID in Endpoint URL if you want to update escalated tickets

 

8.2.3 Add trigger to update children tickets

This is the last step, set up a trigger to run on parent ticket when condition met, so that the trigger will call the webhook to update its child tickets.

In this example we'll auto-solve child tickets when parent ticket has tag solve_children.

A. Trigger conditions:

B. Trigger actions:

When the conditions above met, the trigger should call the Webhook with JSON data to update the child tickets.

In the below example, we simply set the status of all child tickets to Solved.

C. Outcome:

With the above trigger setup, when we add tag solve_children to a parent ticket, its child tickets will be solved (and the tag is instantly removed off the parent ticket so we cannot see it).

Instead of solving the child tickets, we can perform other actions (e.g. change ticket field, change assignee, group...etc) by changing the JSON data structure of the trigger action.

See API Bulk Updates https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#update-many-tickets and https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#update-ticket for more info.
(Or we can set JSON data to add a tag to the ticket. And have trigger to perform actions based on that tag, rather than set everything in the JSON data structure)

Contact us if you are unsure how to setup the JSON data.