Generate status reports from Harvest time sheets
A tool to generate status reports from your Harvest timesheet.
With this tool you can produce client-specific status reports from the entries you make in your Harvest timesheet.
That’s the reason I created this tool: I produce weekly status reports for my clients. This is the first iteration, and because of this, it is tailored to my needs.
At the end of this document I’ll document the road map I have for this tool. Stay tuned.
You need a Harvest account, because this information is used to authenticate this tool against the Harvest V1 API.
WARNING: According to the API V1 Documentation, this API is deprecated but will still be available for ‘legacy’ applications. Upgrading to use Harvest V2 API is already in the Road Map. However, until then, I’m making note that I’m using the harvested gem to provide API access to the Harvest information.
In a configuration file (
'hammerhead.yml') you will specify:
subdomain: - Your Harvest subdomain username: - Your Harvest username password: - Your Harvest password
NOTE: This tool uses the Optional Project Code when displaying status reports.
TTY Toolkit provides the skeleton around which Hammerhead is built. It’s a wonderfully easy toolkit to use. I’m barely scratching the surface of its capabilities.
Add this line to your application’s Gemfile:
And then execute:
$ bundle install
Or install it yourself as:
$ gem install hammerhead
Use this command to obtain a list of your clients. The default behavior is to return ‘active’ clients.
Usage: hammerhead clients [OPTIONS] Options: -a, [--all], [--no-all] # Return all clients from Harvest -h, [--help], [--no-help] # Display usage information Description: Fetch list of clients from Harvest. The default behavior is to return 'active' clients, only. Add the --all flag to return entire list of clients.
Displayed in the console will be a table of your clients. The first column will be their numeric id; this is assigned by Harvest. The second column will be the name you assigned to them. The
status command, in its current form, requires the numeric id to be specified.
Use this command to obtain a status report for the specified client.
Usage: hammerhead status [OPTIONS] CLIENT Options: -s, [--short-cut], [--no-short-cut] # CLIENT value is a user-defined short-cut [--start-date=YYYY-MM-DD] # Start date of timesheet query [--end-date=YYYY-MM-DD] # End date of timesheet query -h, [--help], [--no-help] # Display usage information Description: Generate status report for specified client. The default behavior is to query up to a week's worth of timesheet entries for the specififed CLIENT. CLIENT can either be the Id or Name of one of your Harvest Clients. Obtain this information with the 'clients' command. It can also be a user-defined shortcut. Please see the README for details on creating shortcuts. However when used, you must pass the --short-cut flag. Start and end dates are automatically calculated. They are based on _your_ 'Start Week On' Setting. You can alter this behavior by specifying --start-date or --end-date. Constraints when specifying dates: - start-date must occur before end-date - start-date and end-date must be at least 1 day apart - both are optional - specifying start-date causes end-date to equal "tomorrow" - specifying end-date requies the presense of start-date
--end-date flags are currently not supported. Supporting them is already on the Road Map.
This is the heart of the Hammerhead tool. When passed the numeric id of a client, this command attempts to grab timesheet entries for active projects for the specified client. If there are no timesheet entries, or active projects, this command responds with an appropriate message in the console.
If you work on multiple projects for a client, the output will be grouped by project, by timesheet entry.
Again, this version is tailored to my needs and, as such, is a tiny bit complicated. My business weeks run from Monday to Sunday, therefore this tool attempts to figure out the start-date and end-date based on ‘Today’. If ‘Today’ is Monday, a report for the previous Monday to Sunday is generated, otherwise a report from Monday to ‘Today’ is generated.
These nicknames, or client name snippets, can be configured in
'hammerhead.yml'. In lieu of Client Name support you can use this to setup shortcuts for report generation.
$ hammerhead status -s <nickname>
Hammerhead requires the presense of a configuration file named:
'hammerhead.yml'. The tool will search the directory in which the command is executed and in your home directory. An error will be displayed when the file can not be located.
# REQUIRED harvest: subdomain: SET_ME username: SET_ME password: SET_ME # OPTIONAL clients: exclude: - <client id> shortcuts: <nickname>: id: <client id> name: <client name>
Because of the
harvested gem, and its use of Basic Authentication, you need to specify your credentials in order for the tool to authenticate itself against the Harvest V1 API. GUARD YOUR CREDENTIALS!
There are some optional configuration items that may prove useful to you. If you have a client, for whatever reason, you wish to exclude from any and all client listings, add their Client Id to the list that is
clients.exclude. Additionally, if you’d like an easy-to-remember nickname for one, or more, of your clients, you can define them under
clients.shortcuts. For example:
clients: shortcuts: acme: id: 999999999 name: ACME Co, Inc
$ hammerhead status -s acme
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake spec to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/juicyparts/hammerhead. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
Everyone interacting in the Hammerhead project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
Copyright (c) 2020 Juicy Parts Software, LLC. See MIT License for further details.