Submit a request

Support Centre

Time Tracker User Guide

1 Overview

Time Tracker is a modern, easy to use, full-featured time tracking app. This guide is written based on version 1.0.0 of Time Tracker.

For a complete history of changes to the app, please refer to the Release Notes.

Note: This user guide is still very much a work in progress. Check back often, as it'll likely see a lot of updates over the coming weeks and months.

2 Installing Tickler

The installation process can vary depending on what features you plan on using. Installation typically requires the following steps:

  1. Create a ticket field to store Time Tracker data.
    • You may need to create additional ticket field if you decide to sync time tracking data to other fields.
  2. Install and configure the app:
    • Enter the field id(s) from the first step into the app settings
    • Configure other app settings and features.
    • Set role or group permissions to limit access to the app until you're ready to roll out to all agents.
    • Validate and test the settings. If needed, come back and adjust settings to ensure the app is working correctly and doing what you need.
  3. Roll out app to agents.

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

2.1 Ticket field(s)

Timer Tracker uses a custom ticket field (data field) to store it's data. This is the only required field. If you'd like to sync time tracking data to other ticket fields, you will likely need to create those as well.

Note: The data field is hidden while the app is active, so agents don't lose data by accidentally editing it.

Copy or write down the ticket field id(s) after you're done creating them. You'll need to enter it/them in the app settings.

2.1.1 Ticket field types

Consult the table below for the type of field to create for each app setting. The only required field is the data field and it must be 'multi-line text' type ticket field.

Field and description Field type Optional
Data Field Multi-line text No
Total Time Spent Field Text or number Yes
Latest Time Spent Field Text or number Yes
Last Updater Name Field Text Yes
Last Updater ID Field Text or number Yes
Last Updater Email Field Text  Yes 
Last Updater Role Field Text  Yes 
Prepaid Time Field Text or number  Yes 
Prepaid Time Remaining Field Text or number  Yes 

Note: Any field you create and plan to use should be added to all ticket forms. This needed because all ticket sidebar apps run on all ticket it forms. If a field is missing, it may cause errors.

2.1.2 Creating a custom ticket field

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

settings-ticket-fields.png

For the data field, use the following settings:

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

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

If you'd like to share any fields with customers via the Guide portal, you'll need slightly different settings for the field:

  • Description - Not required.
  • Permissions - Select Read-only for end-users
  • Title shown to agents - Something descriptive.
  • Title shown to end-users - This will be visible in the Guide, so you'll want to make it something clear from the end-users perspective.
  • Description shown to end-users - Optionally add a description. This is usually displayed below the field.
  • Required to solve ticket - Leave unchecked.

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

Repeat this process for all fields you're creating. If you have more than one Zendesk ticket form, you'll need to make sure you add all of the fields you create to all ticket forms. Even on those where Time Tracker won't be used. This is because the app runs on all tickets. If a field or fields are missing, agents will likely see errors while using the app.

2.2 Installation

To install the app, first locate it in the Zendesk App Marketplace. On the app page, click Install button on the right-hand side. Choose the Zendesk subdomain you'd like to install the app to from the dropdown list, then click the Install button. 

When you're prompted to update the app settings, you can enter the field ids for the custom ticket fields, if you have those available. If you don't have them available or you haven't created the fields yet, you can leave the app setting fields as-is and return and update them later.

We recommend setting role and/or group permissions for the app to just a small group initially. Once you've finished configuring the app and it's working like you want, you can then remove the restrictions to make the app available to all agents.

2.3 App settings

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

  • Data Field - (Required) The ID of a custom multiline field that will hold the data of the app.
  • Display timelogs to agents - When checked, agents can see timelog activity on tickets. Default: Checked.
  • Hide the app from agents - When checked, the app will not be shown to agents who do not have the 'Admin' role. This also prevents them from being able to see & edit the time upon submission. Default: Unchecked.
  • Auto pause - When enabled, the timer automatically pauses when the agent navigates away from the ticket. Time tracking automatically resumes when the agent returns to the ticket. Default: Checked.
  • Display timer controls - Display controls so agents can manually pause, resume or reset the timer. Default: Checked.
  • Reset current time - When checked, agents can reset the current time spent on a ticket. Default: Checked.
  • Edit time submission - Agents can review and edit their time before submitting the ticket. Default: Checked.
  • Simplified time submission - When enabled, agents are prompted to confirm the time spent on tickets before submitting the ticket. Default: Checked.
  • Enable Prepaid Hours - When enabled, prepaid hours can be added to a ticket. Remaining prepaid hours are displayed, based on the amount of time spent on a ticket. Default: Unchecked.
  • Total Time Spent Field - (Optional) The ID of a custom text/number field to store the total time spent in seconds on the ticket. Default: "0"
  • Latest Time Spent Field - (Optional) The ID of a custom text/number field to store the latest time spent in seconds on the ticket. Default: "0"
  • Last Updater Name Field - (Optional) The ID of a text field to store the name of the last updater. Default: "0"
  • Last Updater ID Field - (Optional) The ID of a text/numeric field to store the ID of the last updater. Default: "0"
  • Last Updater Email Field - (Optional) The ID of a text field to store the email of the last updater. Default: "0"
  • Last Updater Role Field - (Optional) The ID of a text field to store the role of the last updater. Default: "0"
  • Prepaid Time Field - (Optional) The ID of a text/numeric field to store the prepaid time in hours set on the ticket. Default: "0"
  • Prepaid Time Remaining Field - (Optional) The ID of a text field to store the prepaid time remaining in seconds on the ticket. Default: "0"

3 Using the app

3.1 Tracking time

For the most part, time tracking is automatic and doesn't require very much input from agents. The app starts counting as soon as the ticket is opened and time totals are automatically updated when the ticket is saved.

3.1.1 Basic timer controls

app-overview.png

With the default settings, agents will see three buttons for controlling time tracking:

  • Start - When a ticket is opened, time tracking starts automatically. The start (or play) button allows agents to resume time tracking if it's been paused.
  • Pause - If an agents needs to step away, they can use the pause button to stop the timer. To resume time tracking, they just click the start button.
  • Reset - The reset button will allow agents to reset the current time that's been tracked. This can be useful if an agent switches tasks, but forgets to pause the timer.

If you'd like to hide the start and pause buttons, uncheck the Display timer controls app setting. This setting controls both buttons as a group. To hide the reset button, you can uncheck the Reset current time app setting.

3.1.2 Auto-pause

By default, the app will automatically pause the timer if the agent switches to another ticket or another part of Zendesk. The app will auto-resume timing when the ticket is returned to. This feature allows agents to have multiple tickets open at the same time, while preventing problems caused by agents having to remember to manually start and stop timers. 

You can easily disable this feature by unchecking the Auto pause app settings.

3.1.3 Submitting time

modal-edit-time.png

When saving or updating a ticket, agents are prompted to confirm the time they spent on a ticket. This gives them the opportunity to adjust it if needed. Agents must either click Cancel or Submit time within 20 seconds or the ticket update will be cancelled. A countdown is provided so agents can see how much time they have left to make changes.

Note: For technical reasons related to the Zendesk App Framework, an app dialog cannot delay a ticket update more than approximately 30 seconds. 20 seconds provides a safe buffer so Zendesk has enough time to process the agents' response and complete other processes related to updating a ticket.

By default, time must be entered in the format of "hours:minutes:seconds". To allow agents to edit time in whole minutes, you check the Simplified time submission app setting.

To disable this prompt completely, uncheck the Edit time submission option in the app settings.

3.2 Timelogs

app-timelog.png

Agents and admins can access the time tracking log by clicking the gray bar at the bottom of the app. When expanded, you'll see an entry for each ticket update where time was logged. The timelog also lets you know when the ticket status changed and if any changes were made to prepaid hours, including prepaid comments.

To hide the timelog from agents, uncheck the Display timelogs to agents option in the app settings. Note that even after unchecking this option, the timelog will remain visible to admins.

3.3 Prepaid hours

app-prepaid-hours.png

The Time Tracker app supports prepaid hours. Prepaid hours allow you to set a maximum amount of time agents should spend on a ticket, across all ticket updates. Remaining time is displayed prominently, so agents can easily monitor it. Both agents and admins have the ability to add and edit prepaid hours or add a prepaid time comment. 

Note: This feature is disabled by default, but can be enabled by checking the Enable Prepaid Hours option in the app settings.

Note: When prepaid time runs out, agents aren't prevented from working on or updating a ticket. This feature only provides a convenient way to monitor time spent against a preset value.

modal-edit-prepaid.png

To edit prepaid time, click the Update button to the right of the Prepaid Hours label (near the top of the app). A dialog will open, providing an interface to make changes:

  • Hours - The hours field will accept any positive number. To remove prepaid hours, leave the field blank.
  • The Comment field allows you to include a message with the prepaid hours. You can use it to explain what the hours are for or add additional relevant information like who to contact when the time runs out.

Changes to both the prepaid hour value and the comment are recorded to the timelog when the ticket is updated.

4 FAQ and troubleshooting

Because the "Prepaid Time Remaining Field" is recorded in seconds, you may wish to convert this value to minutes or hours so you can report it in a user friendly manner back to your customer or within your company. Zendesk supports Liquid Markup in macros/triggers/automations which can be used to do the seconds to hours/minutes conversion for you, or other calculations. Liquid Markup is an extension to the placeholder code.

The code to use in your macro/trigger/automation to convert from seconds to hours looks like this:

{{ticket.ticket_field_XXX | divided_by: 3600.0 | round: Z}}

Where "XXX" is the ID of the "Prepaid Time Remaining Field", which in your case appears to be 360000155176.

The value "3600.0" is used to convert to hours. If you wish to convert to minutes, then use "60.0" instead.

And "Z" is the number of decimal points you wish to round to.

If you don't want to have any decimal points then you can use the following code instead (notice 3600 is used instead of 3600.0:

{{ticket.ticket_field_XXX | divided_by: 3600}}

This always rounds down to the nearest integer. eg. 1.8 becomes 1

If you want to round (up or down) to the nearest integer (1.3 becomes 1 and 1.8 becomes 2), then use the following code:

{{ticket.ticket_field_XXX | divided_by: 3600.0 | round}}


When entering placeholders, Zendesk's macro editor tries to be helpful with a popup and autocomplete for placeholders. When writing liquid markup it can cause problems, and mess up what you're trying to enter. It's often easiest to type your code into a plain text editor and then copy paste it in.

If you need to type in the code directly, we suggest typing in every character, and don't select anything from the helper popup or let it autocomplete.

Full information on using Liquid Markup can be found here: https://shopify.github.io/liquid/basics/introduction/

 

4.1 Troubleshooting

Coming soon! In the meantime, feel free to submit a ticket if you run into any problems installing, configuring or using the Time Tracker app.

Have more questions? Submit a request

Comments

Powered by Zendesk