Overview

Tickler brings the power of checklists to your Zendesk tickets, making it easy to manage tasks and processes right from the ticket sidebar. You can choose from three types of checklists to suit your needs: Ad-hoc lists for custom tasks, Saved lists for reusable templates, and Automatic lists that appear based on ticket tags for more efficient workflows.

Tickler versions

Tickler is available in two versions:

• Tickler

  Tickler's full version includes full functionality, such as automatic lists and shared lists, along with all the customization options.
  
  
  
  

• Tickler FREE

  Tickler's free, simplified version has basic checklist features, including ad-hoc lists but with limited functionality compared to the full version.
  
  
  
  

Types of lists

Tickler supports three types of lists:

• Ad-hoc lists

  Ad-hoc lists are created manually within a ticket by an agent. These lists are unique to each ticket, so they’re perfect for handling specific, one-off tasks that don’t need to be repeated elsewhere.
  
  

• Saved lists

  Saved lists are like templates that can be reused across multiple tickets. They can be created from ad-hoc lists or set up directly by admins. Admins can configure standard tasklists and share them with agents, making sure everyone follows the same steps and nothing gets missed. Agents can then quickly grab these shared lists from a dropdown and apply them to their tickets, saving time and keeping things consistent.
  
  

• Automatic lists

  Automatic lists are pre-configured by admins and show up automatically when a ticket has a specific tag. Tags can be added to tickets in different ways, triggering the right list to appear. It’s a great way to automate routine processes and ensure that the right tasks are being done for the right tickets.
  
  

Fresh installation & configuration

Tickler requires several custom fields to store checklist data and track progress. Some fields are mandatory for basic functionality, while others are optional and support additional features like progress tracking.

For a fresh installation of Tickler (not upgrading from Tickler Free), follow these steps:

Step 1. Create ticket and user fields to store checklist data

Before installing Tickler, ensure you have the required fields created for storing checklist data.

• Go to Zendesk Admin > Objects and rules > Fields to create a multi-line text field for storing ticket checklist data.
• Go to Zendesk Admin > People > User fields to create a multi-line text field for agent-specific preferences.

See Required data fields and Optional data fields for more information.

Step 2. Install the Tickler app

To install the full version, visit Lovestock & Leaf's Tickler page and click the blue Free trial button.



You can also go directly to the Tickler page on Zendesk Marketplace and click the purple Free trial button.

Step 3. Configure Tickler app settings

In the app configuration, enter the necessary field IDs and keys, then adjust the settings to enable features like ad-hoc, saved, and automatic lists. 

See App settings for more information.

Step 4. Set up automatic lists

If applicable, configure automatic lists using YAML/JSON or through the Lovely app for more complex workflows. 

See Automatic (tag-based) lists for more information.

Step 5. Test and validate settings

After completing the setup, test the app and validate your settings to ensure everything is functioning as expected.

Required data fields

Tickler requires two custom fields to store checklist data:

1. Ticket data field

This field stores all checklist data for each ticket.

1. Go to Zendesk Admin > Objects and rules > Fields.
2. Click Add field, then select Multi-line text.
3. Set the field name (e.g., "Tickler data").
4. Leave the description blank, set permissions to Agents can edit, and ensure Required to solve a ticket is unchecked. Click Save.
   
   
   
   
5. Search your display name, "Tickler data", in Objects and rules > Fields, then copy the field ID (a set of numbers) for later use.
   
   
   
   
6. Add this field to your ticket forms under Objects and rules > Forms.
   
   

2. User data field

This field is required to save agent-specific preferences and private ad-hoc lists.

1. Go to Zendesk Admin > People > Configuration > User fields.
2. Click Add field, then select Multi-line text.
3. Name the field (e.g., "Tickler user data").
4. Save the field and copy the field key for later use.
   
   

Optional data fields

Tickler supports exporting checklist progress to custom ticket fields, allowing agents to view real-time task status directly in ticket lists and views—without opening the ticket. You can track overall progress, the next step, or even a percentage completed.

You can add these field IDs in two places within Tickler settings:

• For saved ad-hoc lists, only the progress export (text) and progress export (percentage) fields are supported. These can be configured directly in the Saved ad-hoc list fields shown under Tickler settings via Zendesk Admin Center:
  
  
  
  

• For automatic lists, include the field IDs and placeholder content in your configuration under the Automatic lists section in Tickler settings via Zendesk Admin Center:
  
  
  

1. Progress export field (text)

This field displays a plain-text summary, such as the next task or overall progress.

1. Go to Zendesk Admin > Objects and rules > Fields.

2. Click Add field, then select Multi-line text.

3. Set the field name (e.g., Tickler progress text).

4. Set permissions to Customers can view if you want customers to track progress, and uncheck Required to solve a ticket.

5. Click Save, then copy the field ID for later use.

6. For automatic list, in your Tickler list config, use export_progress to populate the field. Example:

   your_list_name:
     export_progress:
       - fieldId: 12345678  # Replace with your field ID
         content: "{{list.progress.text}}"

2. Progress export (percentage) field

This field shows checklist completion as a numeric percentage.

1. Go to Zendesk Admin > Objects and rules > Fields.

2. Click Add field, then select Decimal.

3. Set the field name (e.g., Tickler progress percentage).

4. Set permissions to Customers can view if you want customers to track progress, and uncheck Required to solve a ticket.

5. Click Save, then copy the field ID for later use.

6. Example configuration for automatic list:

   your_list_name:
     export_progress:
       - fieldId: 87654321  # Replace with your field ID
         content: "{{list.progress.percentage}}"

3. Display the next step in a ticket field

You can also surface just the next upcoming task for quick visibility in views:

your_list_name:
  export_progress:
    - fieldId: 11223344  # Replace with your field ID
      content: "{{list.progress.next}}"

4. Show the last completed task in a ticket field

Use this to show the most recently completed task:

your_list_name:
  export_progress:
    - fieldId: 44556677  # Replace with your field ID
      content: "{{list.progress.last}}"

5. Show progress without task statuses

Use this to display task names only, without status indicators like done or skipped:

your_list_name:
  export_progress:
    - fieldId: 99887766  # Replace with your field ID
      content: "{{list.progress.no_status}}"

6. HTML progress output

If you're using HTML rendering or want a formatted version of progress, use the HTML variant:

your_list_name:
  export_progress:
    - fieldId: 55443322  # Replace with your field ID
      content: "{{list.progress.html}}"

Supported placeholders for export_progress and setField:

List-specific placeholders:

• {{list.progress.text}}

• {{list.progress.next}}

• {{list.progress.last}}

• {{list.progress.html}}

• {{list.progress.no_status}}

• {{list.progress.percentage}}

Across all lists:

• {{all.progress.text}}

• {{all.progress.next}}

• {{all.progress.last}}

• {{all.progress.html}}

• {{all.progress.no_status}}

• {{all.progress.percentage}}

These placeholders allow dynamic population of field values and comments based on real-time list or task status.

App settings

Once the fields are created, you can configure the Tickler app settings.

1. Go to Zendesk Admin > Apps and integrations > Apps > Zendesk Support apps.
2. Find Tickler under Enabled apps, and hover then select Change settings from the dropdown menu.
   
   

Required fields that need to be added are:

Title - The label you'd like to appear for the app on Zendesk.

Ticket data field - The custom ticket field ID where Tickler is to store the data for lists. This is the field ID you saved from Step 1 of Fresh installation & configuration.

User data field - Enter the 'field key' for the custom user field where Tickler can store private agent lists and agent specific settings. If this value isn't valid, Tickler will attempt to use 'lldata_tickler' instead (Default: empty). You would have saved the field key too from Step 1 of Fresh installation & configuration.

Aside from the required fields above, the Tickler app settings includes optional fields and configuration options.

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

• Allow HTML in task comments (Automatic lists only) - Enabling this allows agents to use HTML formatting in task comments on automatic lists.
• Enable ad-hoc lists - This lets agents create, save, and reuse custom ad-hoc lists.
• Status order (Ad-hoc lists only) - This controls the order of statuses when toggling a task’s status. Use the first letter of each status in the order you'd like them to appear: n = None, p = Pending, s = Skip, d = Done. For example, enter nspd to display the order as None, Skip, Pending, Done.
• Save list progress using a "progress field" (Ad-hoc lists only) - If enabled, the current progress of the checklist will be saved as plain text to a second custom ticket field. You’ll also need to set the field ID below.
• Progress field setting: field ID (Ad-hoc lists only) - Enter the ID of the custom ticket field you want to use to store list progress. The field must be a "multi-line text" type.
• Progress field setting: Hide progress field  (Ad-hoc lists only) - Check this box to hide the progress field from agents.
• Progress (in percentage) field setting: field ID (Ad-hoc lists only) - Enter the custom ticket field ID where you’d like to store the checklist progress as a percentage. Leave as "0" to disable this feature.
• Progress (in percentage) field setting: Hide progress (in percentage) field (Ad-hoc lists only) - Check this box to hide the percentage progress field from agents.
• Print to comment by default - When this is enabled, the 'Add list as comment' option will be pre-selected whenever you click the print icon in the app.
• List descriptions and comments on print view (Automatic lists only) - If enabled, the list description and any comments on task items will be included in the print view.
• Incomplete items on print view - When enabled, this includes incomplete tasks in the print view, instead of only showing completed tasks.
• Field map (Automatic lists only) - This feature lets you give a label (or alias) to a custom ticket field, making the configuration easier to understand. For example, you can map field ID 1234567890 to shipping_method. This is used exclusively in the automatic lists configuration.
• Automatic lists (chunk x) - This section is for configuring automatic lists. Keep in mind the following:
  • Character limit: Zendesk limits each app setting to 50,000 characters. To stay within this limit, you can break your configuration into smaller chunks and spread them over multiple “Automatic lists” fields.
  • Valid YAML/JSON: Each “Automatic lists” field must contain valid YAML/JSON, or be left blank.
  • Don’t split lists over multiple fields: Doing this will likely break your configuration, causing none of the automatic lists to work.
  • Editing tips: We highly recommend using the companion Lovely app for updating this field. Its editor helps format YAML correctly and prevents you from saving invalid YAML back to the app, ensuring your configuration stays intact.
• Shared lists (Ad-hoc lists only) - This field contains a JSON version of shared to-do lists. It’s not recommended to edit this directly. Instead, update lists within the Tickler app or use the companion Lovely app.

Note: Although not required, we highly recommend using our free Lovely companion app for configuring Tickler. It offers enhanced support for YAML, which is essential for setting up automatic lists, and helps prevent errors by validating your configuration before saving it to Zendesk. Additionally, Lovely makes it easier to back up your settings for future use. For detailed installation and setup instructions, visit this page.

Access restrictions (role & group-based)

You can control which agents have access to the Tickler app by enabling role or group restrictions from your Zendesk Admin settings.

To configure access:

1. Go to Zendesk Admin > Apps and integrations > Apps > Zendesk Support apps.

2. Find Tickler in the list and click the gear icon to open its settings.
   
   
   
   

3. Scroll to the bottom and enable either or both:

   • Enable role restrictions – Choose which Zendesk roles can access the app. These roles are pulled directly from your Zendesk Support settings.

   • Enable group restrictions – Choose which Zendesk groups can access the app. This controls who can see Tickler, based on their group membership.
     
     Note: Group restrictions only control access to the app - they don’t assign or change any agent roles. Agents in a restricted group will still use the roles already assigned to them in Zendesk.
     
     
     
     

4. Click Update to save your changes.

Advanced configuration

The advanced configuration options in Tickler allow you to customize and integrate the app more deeply into your Zendesk environment. You can format checklists for end-users, automate checklist progress tracking in email notifications, and ensure a more cohesive and informative experience for both agents and customers. This section guides you through advanced setup, including adding code to your Guide template for checklist formatting and incorporating checklist progress into email notifications, helping you get the most out of Tickler and improve your support process.

Adding code to your Guide template for checklist formatting

To display the checklist properly for end-users in the Zendesk Guide, you'll need to add custom code to your Guide template. This step ensures that the checklist appears formatted and readable for customers. You can find detailed instructions and the necessary code in this article.

Adding checklist progress to email notifications

To automatically include checklist progress in your email notifications, simply add the progress ticket field to the message body. Typically, the template tag will be {{ticket.ticket_field_ID}}, where ‘ID’ is the custom field ID for the progress field.

Setting up email notifications with checklist progress

1. Triggers:

   • Go to Settings > Triggers under Business rules.
   • Create or edit the trigger you want to use.
   • Add the progress ticket field tag to the message body.
     
     

2. Automations:

   • Go to Settings > Automations under Business rules.
   • Create or edit the automation you want to use.
   • Add the progress ticket field tag to the message body.
     
     

3. CC Notifications:

   • Go to Settings > Email under Channels in the menu on the left.
   • Edit the CC notification settings as needed.
   • Add the progress ticket field tag to the message body.

For examples of how to add the progress field to notifications, please refer to this article.

Tips for formatting checklist notifications

• Include the progress field only in relevant notifications, such as those triggered by comments added to tickets.
• Avoid adding the field to reminders or automated notifications not directly related to checklist progress.

By following these steps, you can enhance your email notifications with real-time checklist progress, keeping stakeholders informed about ticket status changes.

Upgrading from the free version

If you're upgrading from Tickler FREE to the full version, follow these steps to ensure a smooth transition.

All custom fields set up for Tickler FREE can be reused in the full version, but you’ll need to update your app configuration settings.

Step 1. Verify existing fields

Before upgrading, verify that your Tickler Data and User Data fields are properly configured in Tickler FREE.

1. Go to Zendesk Admin > Objects and Rules > Fields to check the field ID for the Tickler data field.
2. Go to Zendesk Admin > People > User Fields to verify the user data field.
   
   

Step 2. Install the full version of Tickler

To install the full version, visit Lovestock & Leaf's Tickler page and click the blue Free trial button.



You can also go directly to the Tickler page on Zendesk Marketplace and click the purple Free trial button.

Step 3. Update field settings

1. Go to Zendesk Admin > Apps and integrations > Apps > Zendesk Support apps.
2. Find Tickler under Enabled apps, and hover then select Change settings from the dropdown menu.
3. Complete the required fields:
   • Ticket data field ID: Use the same field ID from Tickler FREE.
   • User data field key: Enter the same field key used in Tickler FREE.
     
     

Step 4. Remove Tickler FREE

After configuring the full version, uninstall Tickler FREE to avoid conflicts.

Important notes:

• Avoid running Tickler FREE and the full version on the same tickets simultaneously, as this may cause data corruption.
• Double-check that each app is using the correct custom fields to avoid conflicts.
  
  

Getting started

Get familiar with the Tickler app's functionality and features, making your ticket management and task organization more efficient. This section will guide you through accessing the app, understanding its interface, and utilizing key features to streamline your workflow in Zendesk.

Locating the app

The Tickler app is located in Zendesk's right-hand app sidebar for easy access from any ticket. Depending on your Zendesk setup, the app may appear differently. Use the steps below to locate Tickler, whether pinned to your sidebar or within the Apps menu, and start managing your tasks efficiently.

Not pinned to sidebar:

1. Click Apps in Zendesk's right sidebar menu.



2. A new tab will appear showing all available apps. Scroll to find the Tickler app.

Pinned to sidebar:

1. Click the Tickler icon in Zendesk's right sidebar menu. A new tab will appear showing the Tickler app.

Navigating the interface

Once you’ve accessed Tickler, it’s important to understand the layout and features available. This section walks you through the main components of the Tickler interface, including the Saved Lists dropdown, Manage Lists options, and task management tools, so you can make the most of the app's capabilities in organizing and tracking your ticket tasks.

Saved lists

This dropdown menu allows you to access and apply previously saved tasklists.



If no lists have been saved, the dropdown will be empty. Once you’ve saved personal or shared lists, clicking the dropdown will display all available options. You can select a list from the Personal or Shared categories to quickly add it to your current ticket.

Manage lists

Click this icon to view and manage your saved lists. This helps in organizing your workflows by customizing and updating tasklists as required.



You can create a new list and specify the name, accessibility (personal or shared), and the list items. This is useful for setting up templates that can be reused across multiple tickets.



You can also switch between Shared and Personal tabs and find list options to modify configurations, create duplicates for easier management, or remove lists that are no longer needed. This feature helps in maintaining and updating tasklists efficiently.

Add a new item

This button allows you to start creating an ad-hoc list directly within a ticket by adding tasks one by one. As you add each item, the list begins to build, and you can continue adding tasks as needed. Once your list is complete, you have the option to save it as a template for future use, making it easy to apply the same set of tasks to other tickets.

Selected list

This area displays the currently selected list, whether created ad-hoc or picked from saved lists, and allows you to modify the tasks. Click on individual tasks to edit them, use the drag handle (three horizontal lines) to reorder, or click the trash icon to delete a task.

List actions

This menu provides additional actions for the selected list, such as appending the list to a comment, printing, viewing list properties, saving the list as a template, appending a saved list, or emptying the list.

Progress indicator

This indicator displays the percentage of tasks completed within the active list. As agents mark tasks as complete, the percentage increases, providing a visual representation of progress. Once all tasks in the list are marked as complete, the indicator shows 100%, indicating that the checklist is fully completed.

View history

This button allows agents to view the changes to the checklist, including task additions, deletions, and status changes. This feature helps track the evolution of the checklist and maintain an audit trail of actions taken.



Read more about this in the View history section.

Configuring & using lists

In Tickler, lists are essential for organizing tasks within tickets. Whether you need to manually create one-off tasks with ad-hoc lists, use pre-configured templates with saved lists, or automate task creation with tag-based lists, Tickler provides flexible options to streamline your workflow. Here's how to configure and use each type of list effectively:

Ad-hoc lists

Ad-hoc lists are created manually within a ticket and are perfect for handling tasks that are specific to that particular ticket. You can build these lists on-the-fly, making them ideal for managing unique situations. Once you've created an ad-hoc list, you can also save it as a template for future use, ensuring consistency across similar tickets.

1. Open the Tickler app: In the ticket sidebar, click the Tickler icon to open the app.
2. Create a new item: Click the Add a new item button and type your task. Press Enter to add it to the list.
3. Build your list: Continue adding tasks as needed by typing in the Add a new item field and pressing Enter.
4. Submit the ticket: When your list is complete, submit the ticket. The list will be automatically added to the ticket.
5. Save as a template (optional): To reuse the list in other tickets, click the Manage button, select Save list..., name the list, and save it for future use.

Saved lists

Saved lists are reusable templates that can be created from ad-hoc lists or directly configured by administrators. Admins can set up standard tasklists and share them with their agents, ensuring consistency and efficiency across multiple tickets. Agents can quickly access these shared lists through a dropdown menu and apply them to tickets as needed, simplifying their workflow with pre-defined tasks.

There are two ways to create saved lists:

Create from an ad-hoc list

1. Open the Tickler app: In the ticket sidebar, click the Tickler icon to open the app.
2. Create an ad-hoc list: Click the Add a new item button and type your task. Press Enter to add it to the list. Continue adding tasks until your list is complete.
3. Save the list: Click the Manage button, then select Save list... from the menu.
4. Name the list: Enter a name that describes the list’s purpose.
5. Choose visibility: Select Personal (for your own use) or Shared (for all agents).
6. Additional options (optional):
   • Prevent solve: Check this box if you want agents to complete all tasks before solving the ticket.
   • Don't allow changes: Check this box to prevent agents from modifying the list, adding/removing tasks, or reordering items.
7. Assign a tag: Enter a tag that will be added to the ticket when this list is used.
   Note: Changing the tag later may affect existing reports based on the previous tag.
8. Save: Click Save to store the list as a reusable template.
   
   

Create through the Manage Lists section

1. Open the Manage Lists section: In the Tickler app, click the Manage lists icon.
2. Create a new list: Click + Add list to start a new saved list.
3. Name the list: Enter a name that describes the list’s purpose.
4. Add tasks: Click Add a new item and type your task. Press Enter to add it to the list. Continue adding tasks until your list is complete.
5. Choose visibility: Select Personal (for your own use) or Shared (for all agents).
6. Additional options (optional):
   • Prevent solve: Check this box if you want agents to complete all tasks before solving the ticket.
   • Don't allow changes: Check this box to prevent agents from modifying the list, adding/removing tasks, or reordering items.
7. Assign a tag: Enter a tag that will be added to the ticket when this list is used.
   Note: Changing the tag later may affect existing reports based on the previous tag.
8. Save: Click Save to store the list as a reusable template.
   
   

Using saved lists

1. Access saved lists: In the Tickler app, click on the Saved lists dropdown menu to view all available saved lists.
2. Select a list: Choose the desired list from the dropdown to apply it to the current ticket.
3. Modify tasks (if needed): Once applied, you can modify the tasks within the list as needed for the specific ticket.

By using saved lists, you can ensure that your agents have a consistent set of tasks to follow for different ticket types, saving time and maintaining standard operating procedures.

Automatic (tag-based) lists

Automatic lists are pre-configured by administrators and are displayed automatically when a ticket has a tag associated with the list. Tags can be added to tickets in various ways, triggering workflows that auto-apply tasklists based on specific criteria. This is especially useful for standardizing processes across similar types of tickets.

Configuration guidelines

When setting up automatic lists, it's important to structure your configuration correctly. Use either YAML or JSON to define your list settings, and utilize features like the field map to simplify references to custom fields. 



In the above example, the configurations are separated in their own chunks, but remember that multiple list configurations can be included in a single chunk, as long as you stay within the character limit of 50,000 characters.

For this example, the tag that triggers the first list to appear in a ticket is new_customer, and the tag that triggers the second list to appear in a ticket is dispatch_tasks. If a ticket has both tags, then both checklists will appear for the ticket.

YAML and JSON configuration:

You can use either YAML or JSON to configure your automatic lists. YAML is often preferred due to its readability and simplicity. In YAML, the configuration structure uses indentation and line breaks to define nesting levels, making it easier to understand and manage.

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

Base configuration with tickler_base_list:

Define a common base configuration that can be applied to all your automatic lists, ensuring consistency and saving time. For example, common settings like taskListPrefix and export_progress can be set once and reused across multiple lists.

When using tickler_base_list, configurations are not combined but overridden. If the base config has settings not specified in a list's config, those settings will be inherited, but any setting defined in the list’s config will override the corresponding base setting.

Field map (optional):

The field map allows you to assign friendly names (aliases) to custom ticket fields. This helps make your configuration more readable.

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 tasklist, and the number is the custom ticket field ID. An example field map is shown below.

delayedStatus: 21695474
returnEnquiry: 21695444
orderWithin3Days: 21853930

Use the Lovely app's ID Viewer feature to find these field IDs.

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.

Configurations in chunks

When setting up automatic lists, it’s important to remember that you can add multiple list configurations within a single chunk (e.g., Automatic lists (chunk 1)). You don't need to use a separate chunk for each list. You can include as many list configurations as you need in chunk 1, as long as you stay within the 50,000-character limit.

Tasklist options

The tasklists 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 tasklist
    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 tasklist 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:

• tag1: 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 tasklist. 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:
        ...

Tasklist items

Each task in the tasklist 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.

Placeholders can also now be used at the tasklist level.

test_list1:
    title: This is a test List
    tasks:
        - title: item 1
        - title: item 2
        - title: item final
          onDone:
             setField:
                - [123456, "{{list.progress.text}}"]

Data export options

With the new export_progress configuration, you can automate the export of list data to other fields within Zendesk, controlling the content and format dynamically.

new_customer:
  export_progress:
    - fieldId: 123456
      content: "{{all.progress.text}}"
    - fieldId: 9362145
      content: "This is next task: {{list.progress.next}}"

Enhanced field actions with placeholders

Tickler supports the use of placeholders within task and list configurations, allowing for dynamic data insertion based on task or list status. This means that instead of hard coding values, you can insert dynamic content that reflects the current state of the task or list.

For example, previously, setting a field on task completion required specifying a static value:

- title: item final
  onDone:
     setField:
        - [123456, "a value"]

Now, you can use placeholders to dynamically populate fields based on the progress within the list:

- title: item final
  onDone:
     setField:
        - [123456, "{{list.progress.text}}"]

These placeholders can be used within the setField and content configurations to dynamically reflect task or list status:

• {{all.progress.text}}: Represents the progress of all lists in the current ticket.

• {{all.progress.next}}: Represents the next task to be completed in any list.

• {{all.progress.last}}: Represents the last completed task in any list.

• {{all.progress.html}}: Provides an HTML format of the current progress.

• {{all.progress.no_status}}: Shows progress without task statuses

• {{all.progress.percentage}}: Represents the overall progress percentage across all lists on the ticket.
  
  

• {{list.progress.text}}: Represents the progress of the current list only.

• {{list.progress.next}}: Represents the next task to be completed in the current list.

• {{list.progress.last}}: Represents the last completed task in the current list.

• {{list.progress.html}}: Provides an HTML format of the list progress.

• {{list.progress.no_status}}: Shows list progress without task statuses.

• {{list.progress.percentage}}: Provides the completion percentage of the current list.

These placeholders enable flexible configurations, allowing the system to adapt and respond according to the current state of tasks and lists.

The all. prefix aggregates data from all lists displayed on screen, while the list. prefix focuses only on the current list. The .percentage postfix is used to populate numeric values, presenting data in decimal format instead of a textual representation.

Automating ticket comments through task actions

Alongside the setField action, Tickler now allows appending messages directly to the ticket's comment box via onDone, onPending, and onSkip actions. This feature ensures that significant task completions or updates are automatically communicated in the ticket thread without manual intervention.

For instance, upon completing a task, you can configure Tickler to add a custom message to the ticket comments:

- title: item final
  onDone:
     setField:
        - [123456, "Task completed"]
        - ["comment", "Hi team, the tasklist has been completed"]

This automation streamlines communication and ensures that all relevant stakeholders are updated about important changes or milestones within the ticket.

Note that this feature is only available for automatic lists, as saved ad-hoc lists do not support onDone, onPending, or onSkip configurations.

Using automatic lists

The Tickler app is located in the right-hand ticket sidebar for both new and existing tickets. When no tag-based or ad-hoc checklists are enabled, the app will appear blank. Here's an example view with no lists enabled:

As described in earlier sections, you don't manually select automatic lists to add them to a ticket. Instead, they appear automatically when the ticket has the relevant tags associated with them. Below is an example of an automatic list that has not been started yet:

How automatic lists are displayed

Automatic lists will appear at the top of the Tickler app, before any ad-hoc lists. Each automatic list has a title, a progress bar near the top, and individual tasks listed below. Both lists and tasks can have descriptions, providing additional context for agents handling the ticket.

Information on updating task status for automatic lists (and other types of lists) can be found in the Changing task status section.

Multiple checklists per ticket

Automatic lists in Tickler enable the configuration of multiple checklists that automatically appear in a ticket based on specific tags. This setup is invaluable for tickets that require varied task management protocols depending on their categorization or issue type.

Setting up automatic lists for multiple checklists

1. Define checklist triggers:

   • As an admin, identify which tags will trigger the appearance of each checklist. This setup requires aligning these tags with distinct operational processes or types of tickets your team handles.
     
     

2. Configure automatic lists:

   • Access the Tickler settings within Zendesk and proceed to the automatic list management area. For a detailed guide on setting up automatic lists, refer to the Automatic (tag-based) lists section.
     
     
     
     
   • Employ YAML or JSON to articulate the conditions under which each list should appear. Ensure your code is correctly formatted and logical to prevent functionality issues (refer to YAML and JSON validation section for validation tools).
     
     

3. Tag configuration examples:

   • Single tag trigger example:
     
     
     
     This configuration triggers the checklist when a ticket is tagged with new_customer.
     
     

   • Multiple tags trigger example:

     • Scenario: A ticket requires different sets of tasks when tagged as both new_customer and urgent.

     
     
     In this scenario, if a ticket is tagged with both new_customer and urgent, it will display two distinct checklists catering to both contexts.
     
     

4. Deploy and test:

   • Deploy these configurations within your Zendesk environment.
   • Conduct tests by creating tickets with the specified tags to ensure that the appropriate checklists appear correctly and function as expected.
     
     

Managing multiple checklists in a ticket

• Interactivity: Once set up, multiple checklists will manifest in the ticket's Tickler panel based on the active tags. Agents can interact with each checklist independently, addressing tasks suited to the ticket's specific needs.
• Progress tracking: Progress for each checklist is tracked independently, offering clear and direct feedback on task completion within the ticket.
  
  

Best practices for using multiple checklists

• Consistent tagging: Maintain consistent tagging practices to ensure that the correct checklists appear for the appropriate tickets.
• Continuous updates: Periodically review and update checklist configurations to adapt to changes in operational procedures or to enhance the checklists based on agent feedback.
• Agent training: Educate your support agents about how automatic lists operate and the critical nature of completing checklists to comply with internal standards and processes.

Using multiple checklists per ticket through automatic lists ensures that all necessary tasks are addressed efficiently. Adjust and refine these lists to keep up with your team’s needs.

Tips for list management

Effectively managing lists in Tickler ensures that tasks are organized and workflows remain consistent across different ticket types. Whether you're dealing with one-off tasks, standard operating procedures, or automated processes triggered by specific ticket tags, choosing the right type of list and utilizing best practices can significantly improve your team's efficiency and accuracy. Below are some key tips to help you get the most out of Tickler's list management features.

• Choose the right list type: Use ad-hoc lists for unique tasks, saved lists for reusable templates, and automatic lists for standardized workflows.
• Save ad-hoc lists as templates: If you frequently use the same set of tasks, save them as a template for easy application to other tickets.
• Use automatic lists for standard processes: Set up automatic lists to ensure that common processes are followed for tickets meeting specific criteria.
  
  When using automatic lists:
• Keep configurations organized by breaking them into smaller chunks if necessary.
• Use the Lovely app to update and manage configurations, as it provides tools for formatting and validation.
• Test configurations thoroughly before deploying them to a live environment.

By combining the flexibility of ad-hoc and saved lists with the automation of tag-based lists, you can efficiently manage and track tasks within Zendesk tickets, ensuring all necessary actions are taken to resolve tickets effectively.

Managing tasks

This section covers all the essential features available for handling checklist items within Tickler, enabling agents to efficiently track and update their progress. This includes changing the status of tasks with options like “Done,” “Pending,” “Skipped,” or adding comments to keep everyone informed. Agents can also reorder tasks to prioritize actions, edit task details as needed, or clear the entire list if necessary. These tools help maintain an organized and flexible approach to managing ticket workflows, ensuring that agents can adapt to changes and keep the ticket resolution process smooth and structured.

Changing task status

Tickler allows agents to effectively manage tasks by providing various status options for each item in a checklist. Admins can choose to enable or disable these statuses to control which options are available for agents in the App settings, and agents can then change the status of each task directly within the ticket by hovering over the checkbox. 

 


This feature helps agents easily track progress and update tasks based on their current state. The available statuses include:

• Done (checkmark icon): Marks the task as complete.
  
  
  
  
• Pending (hourglass icon): Indicates the task is awaiting action or in progress.
  
  
  
  
• Skipped (cross icon): Shows the task has been skipped and is not required for completion.
  
  
  
  
• Comment (speech bubble icon): Allows agents to add a comment to the task if the "Enable comment for task item" setting is enabled by the admin. 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.
  
  
  
  
  
  

As you update the status of tasks, the progress bar for that list will update. The percentage value on the right is the sum of skipped and completed tasks. Each colored bar represents the percentage of tasks for each status, relative to the total.

• Green = Complete
• Orange = Pending
• Red = Skipped
• Gray = Not started

Below are examples for both Automatic list and Ad-hoc/Saved list. The screenshot illustrates what a partially complete list might look like.

Reordering tasks

Agents can reorder tasks by dragging the task using the drag handle (three horizontal lines) that appears on the right side of the task when hovered over.

Editing a task

To edit a task, click on the task label to enter the edit mode. Make the necessary changes and press Enter to save the updates.

Deleting a task

To delete a specific task, click on the trash bin icon that appears on the right side of the task when you hover over it. This action will immediately remove the task from the checklist. Deleting tasks helps agents keep their lists organized and free of unnecessary items, ensuring that only relevant tasks remain.

Clearing all tasks

To clear the entire checklist, click on the three dots menu at the top-right corner of the list and select Empty this list. You will be prompted to confirm this action before all tasks are permanently deleted. This feature is useful for quickly resetting the checklist when starting a new workflow or when all tasks are no longer needed for the current ticket.

Setting all to Done

This feature allows agents to mark all tasks in the active list as complete with a single click. This is particularly useful when agents need to quickly acknowledge that all steps in a process have been completed.

1. Click the three dots at the top-right corner of the checklist.
2. Select Set all to Done to mark every task in the list as complete.

View history

Tickler keeps a detailed log of checklist changes so you can track what’s been completed, when, and by whom. This feature supports auditing, handovers, and visibility across teams.

To view the change history:

For automatic lists:

• Click the three-dot menu at the top-right of the automatic checklist

• Select View history

For ad-hoc lists or saved ad-hoc lists:

• Click the clock icon at the top-right of the checklist

A pop-up will appear showing a timeline of changes.

What the history panel shows:

• Task status changes (Done, Pending, Skipped)

• Task additions and deletions

• List creation and removal

• Agent name responsible for each action

• Timestamp of each change

Filtering option:

By default, the history panel shows the combined history for all checklists on the ticket, regardless of which list you accessed it from. If you'd like to narrow it down, use the “Show records for” dropdown at the top of the panel to filter changes by a specific checklist.

Print option:
Click the Print button at the bottom of the panel to save or export the full history for record-keeping or audit purposes.

Saving & sharing lists

This section provides comprehensive guidance on managing, saving, and sharing your tasklists within Tickler. Whether you need to save changes to a list for a specific ticket, create new templates, or update existing ones, these features help ensure organized and consistent workflows across multiple tickets.

Saving a list to ticket

Saving list changes in Tickler ensures that any modifications made to a checklist within a ticket are preserved and can be revisited or updated later. Changes made to a checklist—such as adding, removing, or editing tasks—are automatically saved to the ticket when the ticket itself is submitted or saved. This keeps the checklist current and accurate for that particular ticket.

Purpose: Keeps the checklist up-to-date and accurate for the specific ticket it is used in.

When to use: Use this when you want to save changes made to a checklist for a particular ticket without affecting other tickets or the template itself.

Saving as a new list template

Saving a checklist as a new list template allows you to create standardized checklists that can be applied to multiple tickets, ensuring consistency and efficiency in handling similar tasks or processes. This is particularly useful for maintaining uniform workflows or for quickly setting up checklists tailored to specific scenarios.

1. Create or select a checklist:
   For ad-hoc lists: Create the list by adding tasks directly within the ticket.
   For existing saved lists: Select a saved list from the Saved lists dropdown, make the necessary changes, and proceed to the next step.
2. Click the three dots at the top-right corner of the checklist.
3. Select Save list….
   
   
   
   
4. Choose New list as the save option.
   
   
   
   
5. Enter a name for the list. Choose a unique name to differentiate it from other templates and specify whether it should be a personal or shared template.
6. Click Save to store the checklist as a new template for future use.

Purpose: Creates a reusable template that can be applied to multiple tickets, ensuring standardized processes across your team.

When to use: Use this when you want to save a checklist as a new template that can be applied to other tickets, either as-is or with modifications.

Saving to an existing list template

You can save modifications to an existing list template, allowing you to update the template with any new changes made to a checklist.

1. Open the checklist you want to save.
2. Click the three dots at the top-right corner of the checklist.
3. Select Save list….
   
   
   
   
4. Choose Existing list as the save option.
   
   
   
   
5. Select the template you want to update from the dropdown menu.
6. Click Save to update the existing template with the changes.

Purpose: Updates an existing template to reflect any changes made to a checklist, ensuring that the most current process is standardized.

When to use: Use this when you want to update a previously saved list template with new tasks or modifications.

Adding a list to comment

Adding a list to a comment in Tickler allows agents to seamlessly share checklist progress within a ticket. By selecting the option to append the list, agents can include the full checklist in ticket comments for easy reference and collaboration.

1. Open the checklist in the ticket.
2. Click the three dots at the top-right corner of the checklist.
3. Select Append list to comment to add the checklist to the ticket as a 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.

Purpose: Communicates the checklist progress to other agents or stakeholders, making it easy to track and review tasks directly within the ticket conversation.

When to use: Use this when you want to document the current state of a checklist within the ticket’s comment thread, allowing others to view, understand, and follow up on the progress made.

Printing a list

Printing a list in Tickler makes it easy to create a physical or digital copy of your checklist. This is useful for record-keeping, sharing outside the system, or creating a reference document for agents who prefer a hard copy.

1. Click the three dots at the top-right corner of the checklist.
2. Select Print list to generate a print-friendly version of the checklist.
   
   

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.

Purpose: Provides a tangible or digital copy of the checklist for use outside the system or for archival purposes.

When to use: Use this when you need to share a checklist with stakeholders who do not have access to the system, or if you prefer to work with a physical document for tracking or review purposes.

List properties

The List properties feature allows you to view and edit the settings of a saved list. You can rename the list, change its permissions (personal or shared), and adjust other properties. This is useful for ensuring that the list settings are appropriate for your current needs.

1. Click the three dots at the top-right corner of the checklist.
2. Select List properties to view and edit the list's settings.
   
   
   
   
3. You can modify the following options:
   
   
   • List heading: Update the name of the list to reflect its purpose.
   • Prevent solve: Agents can only solve the ticket after all items in the list are complete. This helps ensure that all tasks are addressed before a ticket is marked as resolved.
   • Don't allow changes: Prevents agents from changing the list, such as adding or removing items, appending another list, or reordering tasks. Admins can still make changes if needed by going to the menu for an individual list within a ticket and selecting "Unlock list edit for me."
   
   
   
   
4. Click Save after making changes to the list properties.
5. Don't forget to submit the ticket for the changes to apply.

Purpose: Customizes the list's properties without modifying the tasks themselves.

When to use: Use this when you need to update the list name, restrict task management options for agents, or modify list permissions and rules.

Appending a saved list

Appending a saved list allows you to combine multiple checklists into one comprehensive list. This feature is useful when you need to apply multiple tasklists to a ticket or merge steps from different processes into a single checklist.

1. Click the three dots at the top-right corner of the checklist.
2. Select Append a saved list and choose the desired list to merge into the current list.
   
   

Purpose: Merges multiple saved lists into one, allowing for comprehensive task tracking within a single checklist.

When to use: Use this when you need to combine different saved lists into one checklist for more complex workflows.

Troubleshooting

When using Tickler, you may encounter some common issues related to list saving, field setup, or browser caching. This section provides troubleshooting tips to help you resolve these problems quickly. Additionally, guidance on validating YAML and JSON configurations ensures your automatic lists function correctly. Follow these steps to address common errors and keep your workflow running smoothly.
 

Common issues

• Lists not saving

  Ensure that the ticket data field is correctly added to your ticket forms and that all field IDs are unique.

• Missing fields

  Confirm that the custom fields have been added to Zendesk and the correct IDs are entered into the Tickler app settings.

• Greyed-out lists

  This issue may occur if the fields are not set up properly. Double-check your app settings and custom field configuration, and ensure you do not use the same field ID for the required ticket data field, optional progress export field, and optional progress export (percentage) field. 

Browser caching

Changes to the Tickler app settings may not apply immediately due to browser caching. To resolve this, perform a hard refresh:

• Chrome/Firefox: Press Ctrl + F5 (Windows) or Cmd + Shift + R (macOS).
• Safari: Hold Shift and click the reload button.

YAML and JSON validation

If you encounter issues with configuration, use the following validators to check your YAML/JSON setup:

• YAML Validator: Online YAML Validator
• JSON Validator: Online JSON Validator
  
  

1. Paste your configuration into the relevant validator.
2. Review the feedback and correct any errors indicated.
3. Once errors are resolved, update your Tickler app settings accordingly.
   
   

Best practices

Following best practices helps ensure that you maximize the efficiency and effectiveness of Tickler. Whether you're managing tasks manually or automating processes, these tips will help you get the most out of your configurations and maintain a smooth workflow.

Choose the right list type

Selecting the appropriate list type is crucial for managing tasks effectively:

• Ad-hoc lists: Ideal for unique, one-off tasks specific to individual tickets. Use these when flexibility and customization are needed on a per-ticket basis.
• Saved lists: Great for creating reusable templates that can be applied across multiple tickets. Save frequently used ad-hoc lists as templates to ensure consistency and save time.
• Automatic lists: Perfect for standardizing processes across similar ticket types. Use these for tickets that require a specific set of tasks based on defined criteria, such as tags or field values.
  
  

Optimize your use of automatic lists

Automatic lists can be a powerful tool for enforcing consistent workflows. To get the most out of them:

• Consolidate configurations: Place multiple list configurations within a single chunk to optimize space and manageability. Use separate chunks only when you reach the 50,000-character limit.
• Leverage the Lovely app: Use the companion Lovely app for updating and managing your configurations. Its built-in formatting and validation tools help prevent errors and ensure your YAML/JSON syntax is correct.
• Test before deployment: Thoroughly test your configurations in a staging environment before deploying them live. This helps catch any issues early and avoids disruptions in your support process.
  
  

Maintain unique field IDs

When setting up custom fields for Tickler, ensure that each field used for storing data, progress reports, and progress percentages has a unique ID. This prevents conflicts and ensures that Tickler can accurately track and display the information.

Save frequently used ad-hoc lists as templates

If you find yourself creating the same ad-hoc list repeatedly, save it as a template. This allows you to quickly apply it to new tickets, ensuring a consistent approach and saving time.

Use automatic lists for repeatable workflows

For tickets that follow a standardized process, configure automatic lists. These lists automatically apply the necessary tasks based on ticket criteria, ensuring that important steps aren’t missed before a ticket is resolved.

By following these best practices, you can improve your task management in Tickler, reduce errors, and ensure that your support processes are both effective and efficient.