Overview

Tickler brings checklists into Zendesk tickets, helping agents keep track of steps, handoffs, and repeatable processes without leaving the ticket. Whether you need a quick checklist for one ticket or a structured workflow that appears automatically, Tickler keeps the next step visible and makes progress easy to follow.

Use ad-hoc lists for one-off tasks, saved lists for reusable workflows, and automatic lists when the right checklist should appear based on ticket data. This guide starts with everyday use for agents, then covers admin setup, automatic-list configuration, advanced options, and troubleshooting.

Choose the right list type

Tickler supports three types of lists. Choose the type based on how the checklist should be created and reused.

Ad-hoc lists

Ad-hoc lists are created directly on a ticket for one-off tasks. They can later be saved as a reusable template if needed.

Saved lists

Saved lists are reusable templates. They can be personal to one agent or shared for wider use, making them useful for repeatable processes that still need to be selected manually.

Automatic lists

Automatic lists are configured by admins and appear when the ticket matches the configured tag or field criteria. They can also use guided mode, required task comments, field updates, macros, tags, and other actions.

Tickler versions

Tickler is available as the full Tickler app and the simplified Tickler FREE app.

Tickler

The full version of Tickler includes ad-hoc, saved, and automatic lists, together with the configuration and workflow features covered in this guide.

Tickler FREE

Tickler FREE provides basic checklist functionality and is limited to one ad-hoc list per ticket.

Back to contents

Using Tickler

Open Tickler from the Zendesk ticket sidebar, then use the controls below to work with lists and tasks.

Find Tickler in Zendesk

Tickler appears in Zendesk's right-hand app sidebar. The exact location depends on whether the app has been pinned.

If Tickler is not pinned

1. Click Apps in Zendesk's right sidebar.
2. Scroll through the available apps and select Tickler.

If Tickler is pinned

Click the Tickler icon in the right sidebar to open the app.

Understand the interface

The main Tickler controls let you select saved lists, manage templates, add tasks, work with the current list, view progress, and review history.

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.

 

Back to contents

Create and use lists

Tickler supports three ways of working with lists: create an ad-hoc list for one-off work, apply a saved list when you need a reusable checklist, or work through an automatic list when one appears based on the ticket.

Create an ad-hoc list

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.

Create and apply 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, set up by an admin).
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, set up by an admin).
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.

Use an automatic list

Automatic lists appear when a ticket matches the conditions configured by your admin, such as a ticket tag or field option value. You do not need to add the list manually.

1. Open the ticket: When the ticket matches the configured conditions, the automatic list appears in Tickler.
2. Work through the tasks: Update each task as you complete it and add comments where required.
3. Follow any workflow requirements: Depending on the configuration, tasks may need to be completed in order, a comment may be required before a task can be completed, or the ticket may be prevented from being solved while required tasks remain incomplete.

Back to contents

Managing tasks

Use task statuses and list controls to record progress, update checklist content, and review previous changes.

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

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

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

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

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

Set all tasks 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.



 

Back to contents

Saving & sharing lists

Save ticket-specific checklist changes, create or update reusable templates, add lists to comments, print them, and manage list properties from the list menu.

Saving a list to ticket

Changes to a checklist on a ticket are saved when the Zendesk ticket is submitted or updated. This saves the ticket-specific list without changing the original template.

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.

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.

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

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.



 

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.

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.
   
   

Back to contents

Set up Tickler

This section is for Zendesk admins setting up the full version of Tickler for the first time.

Step 1. Create the required data fields

Create the ticket and user fields described under Required data fields.

Step 2. Install Tickler

Install the full version from Lovestock & Leaf or the Zendesk Marketplace.

Step 3. Configure the app settings

Enter the ticket field ID and user field key, then enable the features your team needs. See Configure app settings.

Step 4. Configure automatic lists, if needed

If your team uses tag-based workflows, set up your lists under Configure automatic lists.

Step 5. Test the setup

Open a test ticket and confirm Tickler loads, checklist changes save correctly, and any saved or automatic lists behave as expected.

Create the 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.
   
   

Back to contents

Configure app settings

After creating the required fields, add their IDs to Tickler and configure the features your team needs.

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

Required settings

Optional settings reference

Back to contents

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.

Back to contents

Optional progress 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 field (percentage)

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.
 

Back to contents

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.

Back to contents

Configure automatic lists

Automatic lists are created by admins and appear when a ticket contains the configured tag or field option value. Agents do not need to add them manually.

Start with a simple automatic list

A basic automatic list needs a trigger name, a title, and at least one task. The trigger name usually matches a ticket tag or dropdown option value.

customer_refund:
  title: Customer refund
  tasks:
    - title: Check the customer's order
    - title: Confirm refund eligibility
    - title: Process the refund

When the ticket contains customer_refund, this checklist appears automatically.

How agents use 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.

Configuration basics

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 formatting

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.

 

Automatic list 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
    guidedMode: 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.
• guidedMode: If this is set to true, agents must work through the tasks in sequence. A task cannot be completed until the tasks before it have been completed or skipped.
• 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:
        ...

Configure tasks and task actions

Each task in a tasklist can be configured with additional options and actions that run when its status changes.

Actions can be triggered when a task is marked as:

• Done
• Pending
• Skipped

You can also define actions at the list level, which trigger based on the overall checklist state.

Example 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"
          requireComment: true
          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.
• requireComment: Optional. If this is set to true, the agent must add a comment before the task can be marked as Done or Skipped.
• 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. Update ticket field.
• setUserField: Optional. Update field on the ticket’s requester (user).
• setOrgField: Optional. Update field on the ticket’s organization.
• 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.

Guided mode helps agents follow a structured workflow by requiring tasks in an automatic list to be handled in sequence. Add guidedMode: true at the list level to enable it.

You can also require a comment on individual tasks. Add requireComment: true to any task where the agent must record information before marking it as Done or Skipped. This can be useful for capturing details such as a call reference number, the reason a step was skipped, or confirmation of an agreed outcome.

The following example uses both settings:

customer_callback:
  title: "Customer Callback"
  guidedMode: true
  tasks:
    - title: "Call the customer"
      requireComment: true
    - title: "Confirm the agreed outcome"
    - title: "Update the ticket"

In this example, agents must work through the tasks in order. They must also add a comment to Call the customer before that task can be completed or skipped. The remaining tasks do not require comments.

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.

Field updates

Field update actions (setField, setUserField, setOrgField) all follow the same structure:

• First value → field key (or alias from Field Map)
• Second value → value to be set

Example:

onDone:
  setField:
    - [status_field, "Completed"]
  setOrgField:
    - ["contract_details", "Offboarded"]

These can be used within onDone, onPending, or onSkip, and combined with other actions.

Task-level vs list-level actions

You can define actions at two levels depending on when they should run.
 

Task level
Triggers when an individual task changes status.

- title: "Step 1"
  onDone:
    setField:
      - [status_field, "Step 1 complete"]

List level
Triggers when the overall checklist reaches a state (e.g. fully completed).

offboarding:
  title: Offboarding/Churn
  onDone:
    setOrgField:
      - ["contract_details", "Offboarded"]
  tasks:
    - title: "Task 1"
    - title: "Task 2"

When to use each:

• Use task-level actions when each step needs its own outcome
• Use list-level actions when the entire checklist should trigger a single update

Example:

• Task-level → update progress, tags, or internal fields per step
• List-level → mark a customer as offboarded once everything is completed

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.

Use multiple automatic checklists on one 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.

Back to contents

Advanced configuration and integrations

Use these options when you need to show checklist progress outside the Tickler sidebar, such as in Zendesk Guide or email notifications.

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.

Email notification tips

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

Back to contents

Troubleshooting

Start with the symptom you are seeing, then check the most common causes below.

Common issues

Lists not saving

Make sure the ticket data field is included on the relevant ticket forms. Checklist changes are saved when the ticket is submitted or updated.

Missing fields

Confirm the required custom fields exist and that the correct IDs or field key have been entered in Tickler app settings.

Greyed-out lists

Double-check the app settings and custom field configuration. Each required or progress-export field must use a unique ticket field ID.

Changes are not appearing after updating settings

Browser caching can prevent new Tickler settings from appearing immediately. Perform a hard refresh:

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

Validate YAML or JSON configuration

If automatic lists are not behaving as expected, validate the configuration before saving it back to Tickler.

1. Paste YAML into the YAML validator, or JSON into the JSON validator.
2. Correct any reported formatting errors.
3. Save the corrected configuration to Tickler and hard refresh Zendesk if needed.

Back to contents

Best practices

Use these recommendations to keep Tickler lists easy for agents to follow and simpler for admins to maintain over time.

Choose the right list type

• Ad-hoc list: Use for one-off tasks that are specific to a ticket.
• Saved list: Use when agents need to apply the same reusable checklist to different tickets.
• Automatic list: Use for repeatable workflows that should appear based on ticket tags or field values.

Save frequently used ad-hoc lists as templates

If agents repeatedly create the same tasks, save the list as a template instead. This reduces manual work and keeps the process consistent.

Use automatic lists for repeatable workflows

Use automatic lists when a defined process should apply consistently whenever a ticket meets the configured criteria.

Keep automatic-list configuration manageable

• Keep related list configurations together and use additional chunks only when needed for the 50,000-character setting limit.
• Do not split one list across different chunks.
• Use Lovely or a YAML/JSON validator before saving large configuration changes.
• Test changes on suitable test tickets before rolling them into normal workflows.

Use unique field IDs

Do not reuse the same ticket field ID for Tickler data and different progress outputs. Each configured output should use the correct, unique field.

Back to contents