Tickler 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

This guide is written based on version 3+ of Tickler. You can find the user guides for Tickler FREE here:

• Tickler FREE User Guide

1.2 Types of lists

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

Ad-hoc lists

Ad-hoc lists can be created and edited on the fly within a ticket. The list will only exist within the ticket it was create in.

Saved lists

You have the option to save the adhoc-list, like templates, for reuse on other tickets. Then 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.

2 Installing & Configuring

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. Change Tickler app settings to set up automatic lists. See Section 3 for more info. (Alternatively: use Lovely -- the free companion app that can be downloaded on this page: Lovely - User Guide -- to manage Tickler app settings)
4. Set up shared ad-hoc lists from the ticket sidebar.
5. 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. 

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.

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.

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

Upgrading from the now discontinued 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.

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.

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

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

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

3 Tickler Configuration

The following section deals primarily with automatic tag-based lists. 

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

Replace alias with an arbitrary alpha-numeric name (no spaces) for 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
    alias: [tag3, tag4]
    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.
• alias: This allows you to add other tags that if present will cause the Tickler list to display. So in the example above, if tag1 OR tag3 OR tag4 are present, then the list will display.
• 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}}."

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]
            addTags: [tag1, tag2]
            removeTags: [tag3, tag4]
          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.
• addTags: Optional. Add the listed tag(s) to the ticket.
• removeTags: Optional. Remove the listed tag(s) from the ticket.
• 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.

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.

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.

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

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.

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

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.

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.

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.