Submit a request

Support Centre

Tickler PRO User Guide

1 Overview

Tickler introduces checklists to Zendesk tickets.

For a brief description of the Tickler app, and the differences between the FREE, PLUS and PRO versions, see the following link:

http://www.lovestockleaf.com/zendesk/zendesk-apps/tickler.html

This guide is written based on version 0.8.7 if Tickler PRO.

Tickler PRO gives you the ability to manage standard tasks/procedures with pre-configured checklists (AKA todo lists, or Tickler lists in this guide) that are loaded in the Apps panel when a ticket is viewed.

Tickler lists are pre-configured to be triggered by specified tags on a ticket, and/or by specified dropdown custom field options.  Typically Tickler PRO will be pre-configured with checklists relating to common issues that the agent has to address, e.g. a New Staff Member ticket will have Tickler items for the tasks that relate to adding the new staff member to internal systems, setting up an email account, allocating a desk, etc. 

Tickler list items can also be configured to set tags and field values on the ticket when these specific items are ticked.  When using Tickler PRO in conjuction with our Fork app, this may in turn trigger the Fork app to automatically create sub-tickets. By combining Fork and Tickler you can build powerful workflows.

2 Installing Tickler

Installing tickler can either be done by us or through our installer (docs). After you have complete the steps you will have two new apps on your Zendesk, namely  "Tickler PRO" and "Lovely".

Lovely is our configuration helper app that has built-in features to make configuring some of our apps more simple.

2.1 Data Field

During the installation process the Tickler Data Field would have been created and automatically linked to Tickler.  

The Data Field is a custom ticket field (field type: multi-line text) which is used by the Tickler app to store the status of the Tickler items on the ticket.  The ID of the Data Field (referred to as the "Data Field ID") can be found on the page that is loaded when editing the field, or via the ID Viewer on our "Lovely" configuration app.

If you have more than one Zendesk ticket form, the onus is on you to add this field to all your ticket forms.  We suggest that you add the field to all your forms, even on those where Tickler lists will not be required, as Tickler runs on all forms and will display an error message on ticket load if the field is not present on the current form used on the ticket.

Please note that this field will be hidden by the app when viewing a ticket. 

If this field doesn't exist, please create a new custom multi-line text field and make a note of the ID of this field.

2.2 Configuring Tickler

Tickler should ideally be configured using the "Lovely" app which would have been installed at the same time as Tickler PRO. The "Lovely" app is found on the left hand side menu bar and has a "cloud" icon.

Within the "Lovely" app, click on "Tickler PRO" in the "Zendesk apps" section on the left.  The following page will be loaded:

This screen has the following input fields:

  • Title: The name of the app as it appears in the apps list.
  • Field Map: Optional. A list of field aliases used to map field IDs to 'friendly names' when you want to configure Tickler to set a ticket field when a specified Tickler item is ticked.
  • Data Field ID: The custom ticket field where the Tickler data is stored. This is usually set up as a field called "LL_Data_Tickler", or similar. This field is hidden in the Agent view.
  • List Descriptions and Comments on Print View - When printing lists, enabling this option will include task descriptions and comments.
  • Incomplete Items on Print View - By default, all checklist tasks are shown when printing. Disabling this option will hide incomplete tasks when printing.
  • Task Lists: Use this field to set up the Tickler configuration based on your specific requirements.  We recommend setting up your config in YAML format, so ensure that the YAML button on the top menu is selected before editing the config.  This field is pre-loaded with a test Tickler list.
  • Allow HTML in Task Comments: Enabling this option will allow agents to use some basic HTML in task titles, descriptions, and comments. See below for a list of supported tags and attributes.
  • Do not open app tray automatically: If the app tray on the ticket page is hidden, Tickler will open it if there's checklist for the current ticket. Enabling this option will disable this behaviour. 

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

2.3 Test Run

Refresh your Zendesk and open a new ticket tab. In the ticket field section, add a tag called 'my_tasklist'. Tickler should now show the task list.

3 Tickler Config

Please note that the configuration examples below are all in YAML format.  When setting up your configuration, ensure that you are on the YAML config page.  (Click on the YAML button top right.)

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 Task 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.

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}}."

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] tasks:
        ...

3.3 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 checklists

The Tickler app is found in the right-hand ticket sidebar for new and existing tickets.

The screenshot above is when there are no tickler lists to action. When your custom drop-down ticket field has a nominated value, then the following screen will show.

This displays the Tickler list based on the current form settings. To mark an item, you hover your mouse over the "tick" icon and you have the following choices:

  • Tick = task item is complete
  • Hourglass = task item is marked as pending
  • Cross = task item is skipped
  • Speech Bubble = leave a comment with the task item

The following screenshot shows you how the Tickler list looks when you have marked some items.

From top to bottom the task items have been marked as Done, Pending, Skipped, Leave a comment. The progress bar below the list title provides a simple visual representation of how many tasks are in each group.

4.2 Printing checklists

In the top right corner of the Tickler PRO 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.

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.

Print to comment

When inserting your checklist as a comment, Tickler PRO 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.

Below is how the checklist might look when Markdown support is enabled.

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