Harvest Billables for Stream Deck

This Stream Deck plugin fetches data from Harvest and Forecast to let you know how much more billable time you have left for the day.

Getting Started

➡️ Install Plugin in Stream Deck Store

Generate API Credentials

You'll need to generate an API token in Harvest as well as finding your Harvest Account ID and Forecast Account ID. Both your Harvest and Forecast IDs can be found under the API token details after creating it. These two additional ids are necessary as they refer to your organization and not your user account.

You only need one API token for all buttons, but you must enter the credentials in every button.

The Buttons

Timer

The Timer button is a simple start/stop button and monitor for individual tasks. After entering your credentials in the settings, a list of available tasks should display in the Task dropdown. (If it doesn't, try clicking away to another button and clicking back.)

After selecting a task, the button should display a play ⏵ or pause ⏸ button along with the time tracked for that task for the current day. You can set a Title (looks best if position is "Align Top") to differentiate Task timers.

Billables Status

This button will only work if your organization also uses Forecast to track time. The purpose of this button is to keep you on track for hours for the week.

This display will compare your total weekly tracked hours to date to your assigned billable hours in forecast, and display the remaining hours you need to fulfill for the current day.

e.g. If you have 25 assigned hours in Forecast, logged 5 hours on Monday and 6 hours on Tuesday, and 1 tracked hour on Wednesday (and counting), your display for Wednesday will show you needing to log another 3 hours (15 hours total) to stay on track for the week, and the pie chart will be 80% full.

• 25 assigned hours / 5 work days = 5 hours per day
• 5 hours Monday + 6 hours Tuesday = 11 hours, 1 hour ahead of schedule
• 5 hours per day - 1 hour ahead of schedule = 4 remaining hours for Wednesday
• 4 remaining hours - 1 hour tracked = 3 hours remaining for the day
• Display shows: -3h, pie chart 80% full

You can track billable hours, non-billable hours, or both for each button/display.

Preview

Buttons

Stream Deck MK.2 w/ Peaceful Web Faceplate

Settings

Timer	Chart
Task Dropdown shows all available tasks, grouped by project.	Button action can refresh data, open Harvest timesheet, or open Forecast schedule.

Error Messages

Error	Details
EAUTH	Missing harvest token or account ids. Generate these and paste them in the settings window.
ETASK	No task selected. Make sure tasks are available for your user account, then select a task in the Timer button settings.
NOPRJ	No projects found in Forecast. In order for billable hours to display, there must be projects in Forecast that you are assigned to.
ETIM1	Error creating time entry.
ETIM2	Error restarting time entry.
ETIM3	Error stopping time entry.
H0001	Error response when fetching data from Harvest.
H1001	Error response when posting data to Harvest.
H2001	Error response when patching data on Harvest.
H#403	Invalid authentication for Harvest. Check token and account id.
H#404	Harvest endpoint not found (or invalid authentication). Check token and account id. *
H#422	Error processing Harvest request.
H#429	Harvest requests throttled.
H#500	Harvest server error.
H####	Other Harvest error.
F0002	Error response from Forecast.
F0403	Invalid authentication for Forecast. Check token and account id.
F0404	Forecast endpoint not found (or invalid authentication). Check token and account id. *
F0422	Error processing Forecast request.
F0429	Forecast requests throttled.
F0500	Forecast server error.
F####	Other Forecast error.
ERROR	Unhandled error. Details available in DevTools.

* The API has a bug where if authentication fails, it will sometimes respond with a 404 instead of a 401/403.

** The second digit in H#000 and F#000 errors refers to GET, POST, or PATCH (0, 1, or 2).

Install Manually

⬇️ Download Latest Release

Unzip and launch the *.streamDeckPlugin file and Stream Deck should install the plugin.

To install manually, download the build-*.zip file, unzip, and copy the me.reinii.harvest-billables.sdPlugin directory to ~/Library/Application Support/com.elgato.StreamDeck/Plugins/ on macOS or %appdata%\Elgato\StreamDeck\Plugins\ on Windows.