- 1 Overview
- 2 Installing and configuring
- 3 Using the app
- 4 FAQ and troubleshooting
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:
- 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.
- 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.
- 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.
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.
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
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.
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
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.
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
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.
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
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.