Submit a request

Support Centre

Tickler 3 User Guide

1 Overview

Tickler adds powerful checklists to Zendesk tickets. Tickler gives you the ability to manage tasks and processes via checklists, from a Zendesk app in the ticket app panel. Tickler supports free form 'ad-hoc' style lists, saved ad-hoc lists and pre-configured automatic tag-based lists.

1.1 Tickler Versions

Tickler 3 is a paid upgrade for all previous versions of Tickler: FREE, PLUS and PRO. 

This guide is written based on version 3.0.11 of Tickler. You can find the user guides for the previous versions of Tickler below:

1.2 Types of lists

Tickler 3 supports three types of lists: ad-hoc lists, saved lists and automatic (tag-based) lists.

Ad-hoc lists

If you've used Tickler FREE or PLUS, you'll be familiar with ad-hoc lists. Ad-hoc lists can be created and edited on the fly without leaving a ticket. You can then save them, like templates, for reuse on other tickets. Agents can quickly add a saved list to a ticket by selecting one from a dropdown. 

Automatic lists

Automatic tag-based lists are pre-configured by admins and are displayed automatically when a ticket has the tag or tags associated with a list. Because tags can be added in a variety of ways, you can create powerful workflows around these types of lists. For example, you could set up a Zendesk trigger that tags a ticket for a return checklist, based on what a customer enters on your ticket submission form.

  Ad-hoc lists Saved lists Automatic lists
Description Added to ticket by an agent manually creating tasks. Ad-hoc list that has been saved for re-use later on other tickets. Added to ticket based on the tags a ticket has.
Lists can be created and edited by agents. Yes Yes No
Lists can be saved as private or shared. Yes Yes No
Lists can be selected from a dropdown and added to a ticket. No Yes No
Lists can be automatically added to a ticket, without any action from an agent. No No Yes
Multiple lists can be displayed on a single ticket. No No Yes 
Comments can be added to tasks. No No Yes 
Tasks can be configured to update a field or run a macro. No No Yes
List can be inserted into comments Yes Yes Yes
Can prevent a ticket from being solved if there are incomplete tasks No Yes Yes

2 Installing Tickler

The installation process can vary depending on what features you plan on using and whether or not you're migrating from a previous version of Tickler. A fresh installation typically requires the following steps:

  1. Create ticket and user fields to store Tickler data.
  2. Install the app:
    • Enter the field ids/key from the first step into the app settings
    • Configure other app settings and features.
  3. Install the free companion app, Lovely*.
  4. Use Lovely to set up automatic lists.
  5. Set up shared ad-hoc lists from the ticket sidebar.
  6. Validate and test the settings to ensure the app is working correctly and doing what you need.

Lovestock & Leaf also provides configuration services for all of our apps. Please get in touch to set up a consultation. 

*Lovely is our configuration helper app. It was designed to help set up apps that support advanced configurations, like Tickler and Field Marshall.

2.1 Data fields

In order to associate lists to tickets and track list progress, Tickler requires a custom ticket field to store data (the data field). Tickler also requires a custom user field for storing private ad-hoc agent lists. These are the only two fields required for Tickler to operate. 

Tickler also supports selectively syncing list data to other ticket fields. You may or may not need create these fields, depending on which features you decide to use.

All fields should be multi-line text. If you have more than one ticket form, you'll need to add all Tickler fields to all ticket forms. Most Tickler fields, including the user field, are hidden while the app is active. This is so agents don't lose data by accidentally editing their contents.

2.1.1 Ticket fields

Clean (or fresh) install

If you're not upgrading or would like to start fresh, you'll need to create a main data field. Without it, Tickler cannot operate. For the data field and other optional ticket fields, the process is essentially the same. 

To create a new custom ticket field, go to your Zendesk Settings and click Ticket Fields. Click the Add Field button on the top right. On the next screen, choose Multi-line. 

settings-ticket-fields.png

For the data field, use the following settings:

  • Description - Leave blank.
  • Permissions - Select Agent only
  • Title shown to agents - Something like "Tickler_Data".
    • Note: This field is hidden while the app is active, it's unlikely agents will see the title.
  • Required to solve ticket - Leave unchecked.

Click Save. On the following screen, locate the field and copy it's Field ID.

If you're using the progress field, you'll need slightly different settings for the field:

  • Description - Not required, but it might be useful to explain to agents what this field is for.
  • Permissions - Select Read-only for end-users
  • Title shown to agents - Something like "Checklist progress"
  • Title shown to end-users - Depending on what kind of lists you'll be sharing with end-users, you may want to name it "Progress" or "Status"
  • Description shown to end-users - Optionally add a description. This is sometimes displayed below the field.
  • Required to solve ticket - Leave unchecked.

Click Save. Like before, locate the new field on the next screen and copy it's Field ID.

Upgrading from another version of Tickler

If upgrading from another version of Tickler, you can re-use your existing data field. It's likely you'll need to re-enter the field id into Tickler, though. You can find this by going to Ticket Fields in your Zendesk Settings. The id for each field is listed to the right of its title.

settings-custom-ticket-field-id.png

IMPORTANT: We don't recommend having more than one copy of Tickler using the same data field at the same time. Each app will try to overwrite the other apps changes, which can often result in list data being corrupted or lost.

NOTE: When re-using a field, we recommend you do a bit of testing to ensure existing list data is preserved. You can do this by setting role or group restrictions on Tickler so only you or a small group of users have access to it.

Ticket forms

As mentioned earlier, if you have more than one Zendesk ticket form, be sure to add all fields to all of your ticket forms. This includes forms where you don't think you'll need Tickler. Tickler runs on all forms and will display an error message if the data field is not present on the ticket.

2.1.2 User field

The user field is needed so agents can save their own custom ad-hoc lists to their profile. You'll need to set this up, even if you don't use ad-hoc lists, as Tickler will display an error if it's not found.

Clean install

To add a user, go to your Zendesk Settings and click User Fields on the list. On that screen, click on Multi-line text on the right side of the screen. 

Use the following settings:

  • Title - This can be anything you want, but we suggest something that will make it easy to identify what the field is for when Tickler isn't active. For example, Tickler User Data
  • Field key - We recommend using 'lldata_user_field'. This is the default for the app.
  • Description - You can leave this blank or add some information about the field. This won't be visible unless the app is disabled.

settings-new-custom-user-field.png

Copy the Field key. The Field key, not the title is what you enter in the Tickler settings.

Upgrading from Tickler PLUS

If upgrading from Tickler PLUS, you can re-use the same user field you configured with it. You'll need to enter the Field key in the settings. If Tickler PLUS is still installed, you can find the key in it's settings. If it isn't, you get the key from the User fields area of your Zendesk settings. To get the key, locate the field and click on it. On the right side, copy the value under Field key.

settings-custom-user-field-key.png

If you want to create a new field or start from scratch, follow the instructions for Clean install above. 

2.2 Configuring Tickler

Lovely App

While not required, we recommend using our free Lovely companion app to configure Tickler. It includes better support for YAML (which is used to configure automatic lists) and will prevent some problems by validating the configuration before saving it to Zendesk. It also allows you to more easily backup your settings. You can find instructions on how to install and set up Lovely on this page.

zd-app-settings-cropped.png

Note, the screenshot above has been cropped, so not all of the settings are visible. Click here to see the full screenshot.

Below you'll find a full list of the app settings, as well as a brief description of what each field does:

  • Ticket data field - The custom ticket field ID where Tickler is to store the data for lists.
  • User data field - The 'field key' for the custom user field where Tickler can store private agent lists and agent specific settings. If this isn't a valid key, Tickler will attempt to use lldata_user_field instead.
  • Allow HTML in Task Comments (Automatic lists only) - Allow agents to use HTML in task comments on automatic lists.
  • Enable ad-hoc lists - Allow agents to create, save and re-use custom ad-hoc lists (like with Tickler FREE and PLUS).
  • Status order (Ad-hoc lists only) - This is the order of statuses when toggling an items' status. Put the first letter for each status, in the order you'd like them to appear: n = Nothing, p = Pending,s = Skip, d = Done. For example, to change the order to None, Skip, Pending, Done, you'd enter nspd.
  • Save list progress using a "progress field" (Ad-hoc lists only) - If enabled, the current progress of the checklist will be saved to a second custom ticket field in plain text. You'll need to also set the field id below.
  • Progress field setting: field id (Ad-hoc lists only) - The id for the custom ticket field you like list progress to be sync'd to. The custom field needs to be "multi-line text".
  • Progress field setting: Hide progress field  (Ad-hoc lists only) - If checked, the progress field will be hidden from agents.
  • Progress (in percentage) field setting: field id (Ad-hoc lists only) - The custom ticket field ID to store the progress (in percentage) done of the Tickler list. Leave as "0" to not use this feature.
  • Progress (in percentage) field setting: Hide progress (in percentage) field (Ad-hoc lists only) - If checked, the progress (in percentage) field will be hidden.
  • Print to comment by default - When enabled, the 'add list as comment' options will be pre-selected when you click the 'print icon' in the app.
  • List Descriptions and Comments on Print View (Automatic lists only) - When enabled, the list description and any comments on task items will be included on the print view.
  • Incomplete Items on Print View - When enabled, incomplete items are included on the print view instead of just completed items.
  • Field map (Automatic lists only) - Allows you to give a label (or alias) to a custom ticket field. i.e., field id 1234567890 -> shipping_method. The is currently only used in the Automatic lists configuration and is used to make the configuration easier to understand and work with. 
  • Automatic lists (chunk x) - This is the configuration for automatic lists. Some important information about these fields:
    • Zendesk limits the size of an individual app setting to 50,000 characters. To overcome this limit (or to organize your lists), you can break your configuration into smaller chunks and spread it over multiple Automatic lists fields.
    • It's very important that each of the Automatic lists fields must contain valid YAML/JSON or is left blank.
    • Tickler doesn't support splitting a list over more than one field. Doing this will most likely break your configuration, resulting in none of automatic lists working.
    • As mentioned earlier, we strongly recommend using the companion Lovely app for updating this field. It's editor will help you format YAML correctly. The app also prevents you from saving invalid YAML back to the app, as a safeguard.
  • Shared Lists (Ad-hoc lists only) - JSON formatted version of shared to-do lists. We don't recommend you edit this directly. Instead you should either update lists within the app or use the companion Lovely app.

2.2.1 Supported HTML

Tickler supports HTML for some automatic list properties. This includes list and task descriptions. You can also optionally enable HTML for task comments. Below you can find the list of supported HTML tags and tag attributes.

Supported HTML tags

h3, h4, h5, h6, blockquote, p, a, ul, ol, li, b, i, strong, em, strike, hr, br

Supported HTML tag attributes

bgcolor, border, class, color, href, id, lang, rel, src, style, target, title, valign

3 Tickler Configuration

Please note, the following section deals primarily with automatic tag-based lists. Ad-hoc lists are managed from within the app, in the ticket sidebar. For information on setting up and using a progress field with ad-hoc lists, you can find complete instructions in the Tickler PLUS user guide.

YAML

You can use either YAML or JSON when configuring Tickler. For most people, YAML is much easier to read and understand, so this is what we recommend you build the configuration.

In YAML the configuration nesting levels are defined with spaces and new lines, so a new Tickler list of items is always started off with a tag positioned at col1 of a new line in the config.  Further nested settings for each level 1 tag are then each added on a new line, preceded with a set number of spaces (in multiples of 2 or 4, for example) for each nested level.  

It is important to ensure that all nested levels settings of the same type are preceded with the exact same multiple of spaces, otherwise your configuration file will be invalid.  (An easy way to ensure this is to copy and paste the pre-loaded example for each tag, and edit that section.)

3.1 Field Map (optional)

The field map is a way of providing 'friendly' names or aliases for fields. The generic form of the field map is shown below:

alias: 1234567

The alias is the name of the field you will refer to in the task list, and the number is the custom ticket field ID. An example field map is shown below.

delayedStatus: 21695474
returnEnquiry: 21695444
orderWithin3Days: 21853930

Ticket field IDs can be found easily via the ID Viewer feature of the Lovely app.

This is only used to specify fields that need to be updated when a specific Tickler item is ticked (e.g. done, paused etc).  Examples to follow.

3.2 Automatic Lists

The task lists is where the Tickler lists are defined.  An example tasklist is as below. This tasklist will show when ticket has tag "test_tag" (or when a dropdown field is selected with option having value test_tag)

test_tag:
    title: This is an example task list
    tasks:
      - title: "Step 1. Call the customer"
      - title: "Step 2. Write down date & time the customer wants to switch"
      - title: "Step 3. Call the tech department and lodge a switch"
      - title: "Step 4. Set ticket due date to the date advised by the tech department"

 

The full supported options of a task list is shown below.

tag1:
    title: Some title
    name: Some name
    description: Some description
    taskTitlePrefix: "{{number}}."
    preventSolve: true
    tasks:
        ...

ll_combination_1:
    title: Some title
    combination: [tag2, tag5]
    preventSolve: true
    tasks:
       ...

In the above example:

  • tag: This is substituted with either a drop-down field option tag, or a tag that will be added to the ticket manually or via inheritance from the user or organisation, via trigger or automation, etc. This causes this Tickler list to be displayed
  • title: This is the title of the Tickler list. The value after the colon is what is presented to the end user.
  • name: This is the name of the Tickler list. The value after the colon is not currently used, and should be set to the same as the title field.
  • description: This is the description to appear below the title.
  • tasks: This is the container for all the tasks or items for the particular Tickler list.
  • taskTitlePrefix: This is the text which appears before the the task item. This is explained further below.
  • preventSolve: If this is set to true, all task items must be completed if the ticket is set to solved.
  • ll_combination_x: This text is used as is (with x substituted with a number from 1 upwards), and identifies a Tickler list that must be displayed when 2 or more tags are all present on the ticket.
  • combination: An array of drop-down ticket field values and/or tags that trigger the this task list. This is only used in combination with "ll_combination_X". This will be discussed further below.
  • hideWhen: a list of IDs (tags) to indicate that the list should not be showing if the other list(s) is already showing. This is only available in version 3.0.5 onward.

taskTitlePrefix

The "taskTitlePrefix" directive tells Tickler what text to put before a task item title. The "taskTitlePrefix" can contain markers, which are replaced with different counters. The values that will be replaced are:

  • number = use numbers (1, 2, 3, 4, ...)
  • upper-alpha = use uppercase letters (A, B, C, D, ...)
  • lower-alpha = use lowercase letters (a, b, c, d, ...)
  • upper-roman = use roman numerals (I, II, III, IV, ...)
  • lower-roman = use roman numerals (i, ii, iii, iv, ...)

An example of a task title prefix for numbers is shown below:

taskTitlePrefix: "{{number}}."

list-config-numbering-example.png

The marker must be inside the double curly brackets. Any text that you have outside of the marker is included as it is.

Line Breaks in Task Description:

To add multiple lines for the task description, start the description with a pipe. The following code snippet shows an example of this.  Be sure to use your YAML preceding spacing multiples before each line of this level of the config.

tag:
    title: Some title
    name: Some name
    description: |
        Some description
        and line two
        and line three

Tag Combinations:

To have Tickler triggered from two or more drop-down ticket field values and/or tags, use "ll_combination_X" where X is a unique number. The tags are defined in the "combination" setting which has the list of the combination of tags that should display the list.

ll_combination_1:
    title: Some title
    combination: [tag2, tag5]
    tasks:
        ... ll_combination_2: title: Some other title combination: [tag2, tag4]
hideWhen: [ll_combination_1] tasks:
        ...

3.2.1 Task List Items

Each task in the task list can be configured separately and it can also be configured to perform some actions when it is ticked as Done, Pending or Skipped.

A full example is as below, with 2 task items "Investigate request" and "Enter Order number into...."

order_morethan_3days:
    title: Delayed Delivery
    name: Delayed Delivery
    tasks:
        - title: Investigate request
          comment: "Agent comment: add your comment here"
description: "Look into delay and process corrective action"
onDone: setField: - [delayedStatus, Investigated]
applyMacro: [12345, 45678] onPending: setField: - [delayedStatus, Pending Investigation] onSkip: setField: - [delayedStatus, Investigation Skipped] - title: "Enter Order number into dispatch system to identify where stock is."
pending: false

In the above example the newly added settings are:

  • onDone: Optional. To specify actions when task is checked as Done.
  • onPending: Optional. To specify actions when the task has been checked as Pending.
  • onSkip: Optional. To specify actions when the task has been checked as Skipped.
  • comment: Optional. Default value for the comment for the task item.
  • description: Optional. Will be presented as a tool tip.
  • pending: Optional. If this is set to false, this task cannot be set to Pending. The default (if not set) is true.
  • setField: Optional. Set a specific value on a field.
  • applyMacro: Optional. Apply a macro to the current ticket.

The "setField" action is configured in the following way:

tasks:
  - title: "Task 1"
    onDone:
      setField:
        - [friendlyFieldName, fieldValue]

In the above example the field from the Field Map called "friendlyFieldName" is assigned the value "fieldValue".

The "applyMacro" action is configured in the following way:

tasks:
  - title: "Task 1"
    onDone:
      applyMacro: [12345]

In the above example, the ID for the macro you want to apply is 12345. This can be found in the "ID Viewer" in the "Lovely" app. If you want to apply more than one macro, then you add each subsequent macro separated by a comma.

4 Using the Tickler app

4.1 Using ad-hoc lists

For the most part, ad-hoc lists work and behave the same as they do with Tickler PLUS. For information on using ad-hoc lists, we suggest consulting the Tickler PLUS user guide.

Note: Tickler is currently under active development. We plan on better integrating ad-hoc lists into the app. As we do that, this guide will be update to reflect ad-hoc lists as the work with Tickler.

4.2 Using automatic lists

The Tickler app is found in the right-hand ticket sidebar for new and existing tickets. With no tag based or ad-hoc checklists enabled, the app will look similar to below.

app-no-lists.png

As mentioned elsewhere, you don't select automatic lists to add them to a ticket. Instead, they'll appear automatically, based on the tags a ticket has. Below is an example of what an un-started automatic list might look like.

tickler-pro-tag-based-list-not-started.png

Automatic lists appear before any ad-hoc list. Each automatic lists has a title, progress bar near the top and tasks. Lists and tasks can also have descriptions. 

To update the status of a task or add a comment, hover over the icon to the left of the task title. A small popup will appear with several icons.

tickler-pro-task-status-hover.png

  • Tick/Checkmark = task is complete
  • Hourglass = task is marked as pending
  • Cross/X = task is skipped
  • Comment Bubble = Add a comment to a task (or edit the current task comment).

Click on the Tick, Hourglass or Cross icons to update the task status. To clear the status, click the icon for the current status. 

tickler-pro-inline-comment-editor.png

Clicking on the comment icon will reveal an small comment editor. To clear a comment, click the small 'trash can' icon on the right. Clicking Ok updates the comment, while clicking Cancel discards any changes.

tickler-pro-updated-task-comment.png

Note: Status changes and comments aren't saved until the ticket is updated. 

tickler-pro-progress-bar.png

As you update the status of tasks, the progress bar for that list will update. Each colored bar represents the percentage of tasks for each status, relative to the total:

  • Green = complete
  • Orange = pending
  • Red = skipped
  • Gray = not started

The percentage value on the right is the sum of skipped and completed tasks.

tickler-pro-tag-based-list-partially-complete.png

The screenshot illustrates what a partially complete list might look like.

4.3 Outputting lists

In the top right corner of the Tickler panel, you'll find a print icon. Clicking on it will provide you with a couple different options for printing your task lists.

  • Print list - Pop opens a new window with a print-friendly version of your checklists and prompts you to print.
  • List in comment - Inserts your checklists as an unsaved comment on the ticket.

List in comment

When inserting your checklist as a comment, Tickler will do it's best to format the checklist appropriately for the style of comments that are enabled on your Zendesk. For example, below is how a checklist might look on a Zendesk with 'Rich' comments enabled.

tickler-pro-list-added-as-comment.png

Print friendly format

When you first open the print-friendly view, you'll be prompted to print it. If you'd like to review the list before printing, you can cancel the print dialog. When you're ready to print, simply click the 'Print' button at the top of the screen.

Below is an example of a checklist in the print friendly format.

tickler-pro-print-friendly-popup.png

Have more questions? Submit a request

Comments

  • Avatar
    Justin Graves

    3 questions:

    1) How can I create tasks which are un-numbered next to tasks which are numbered? I see this in the final screenshot here and also a more complex version of this in the tall screenshot for "DELAYED DELIVERY"

    2) How can I insert a return or line break within a task or a task's description. I'd love to make a task for "collect all info to do this request" with a list below the task reminding the agent of the items to be collected.

    3) How can I get a nice progress indicator like the one included at the top of Tickler Free? I'd like to have the features of the PRO version but also the progress indicator from the free version. Is that possible?

    Thanks!
    Justin

  • Avatar
    Justin Graves

    One more question- Is there a way to show a tickler when a tag is NOT present. My use case is that I want to show a tickler in tickets where a certain custom user checkbox field is not checked. I'm open to work-arounds and hacks too :)

  • Avatar
    Cody Foss

    Hey Justin. Great questions!

    "1) How can I create tasks which are un-numbered next to tasks which are numbered?..."

    In the example above, the tasks are just numbered manually. i.e., the numbers are part of the tasks' title.

    "2) How can I insert a return or line break within a task or a task's description...."

    The current version of Tickler PRO (v0.8.7) should respect line breaks. We also recently added support for basic HTML in list descriptions and in task titles, descriptions and comments. If you enabled this (in the settings), you can simply add a 'br' tag to insert a line-break.

    "3) How can I get a nice progress indicator like the one included at the top of Tickler Free?..."

    Another thing we recently added. It's not as fancy as the one in Tickler FREE/PLUS. It's just a simple horizontal bar graph, but hopefully it'll do the trick for most people.

    "One more question- Is there a way to show a tickler when a tag is NOT present..."

    Tickler PRO relies on the presence of tags to determine whether or not to show a list. One idea is you could set up a couple Triggers: one to add a specific tag (that's associated with a checklist) when the custom user checkbox is unchecked and a second one to remove the same tag when the checkbox is checked.

Powered by Zendesk