Kobot

Kobot is a simple tool to automate the clock in or clock out operation on the web service provided by KING OF TIME by leveraging Selenium WebDriver, and with Google Gmail service email notifications can also be sent to notify the results.

It is meant for use only by one working under the discretionary labor system or flexible hours where the daily record is still required regardless of the actual start or end time of working, for example, software programmers or IT related engineers.

By being run in a periodic schedule system such as crontab, it eases the mental burden to one for trying not to forget the clock action, as well as reduces the application process for making up for the records when it was forgotten.

Installation

Environment

Tested on macOS Catelina and runs on Heroku platform so it works on unix-like systems.

Configuration

By default it uses ~/.kobot file locally to persist credentials for reuse, but all credentials can also be supplied or overridden by runtime environment variables, which is the recommended way of running as scheduled jobs on platforms like Heroku. When running for the first time, if neither the configuration file nor ENV satisfies all required credentials, an interactive prompt will be displayed for initial setting, so there is no need to manually prepare the file beforehand. The content looks something like:

kot_id=xxx
kot_password=xxx

Gmail account and password (or app password if MFA is on) are asked when notification is needed:

gmail_id=xxx
gmail_password=xxx

Note: use all upper-case letters for the above variables if using environment variables, e.g. KOT_ID.

Google Chrome browser

Make sure the latest version of Google Chrome is installed in system. On platforms like Heroku, the heroku-buildpack-google-chrome makes it extremely easy to get the browser ready.

Install the command line tool

Make sure a modern version of Ruby is available and run command below to install:

$ gem install kobot

Usage

Get help doc:

$ kobot -h
Usage: kobot [options]
    -c, --clock CLOCK                Required; the clock action option: in, out
    -l, --loglevel [LEVEL]           Specify log level: debug, info, warn, error; default is info
    -s, --skip [D1,D2,D3]            Specify dates to skip clock in/out with date format YYYY-MM-DD and
                                     multiple values separated by comma, such as: 2020-05-01,2020-12-31;
                                     weekends and public holidays in Japan will be skipped by default
    -a, --auto-skip                  Enable auto-skipping by reading schedule from the Time Card page
    -w [SCHEDULE],                   Skip today if the provided text is not contained in the schedule
        --auto-skip-without          column on the Time Card page of KOT; by default 裁量労働 is used;
                                     effective only if --auto-skip is passed to enable auto-skipping.
    -t, --to [TO]                    Email address to send notification to; by default it is sent to
                                     the same self email account used in SMTP config as the sender
    -n, --notify                     Enable email notification
    -d, --dryrun                     Run the process without actual clock in/out
    -f, --force                      Run the process forcibly regardless of weekends or public holidays;
                                     must be used together with --dryrun to prevent mistaken operations
    -x, --headless                   Start browser in headless mode
    -g, --geolocation                Allow browser to use geolocation
    -h, --help                       Show this help message
    -v, --version                    Show current version

Dryrun to try out:

$ kobot --clock in --notify --dryrun

Clock in/out with email notification

$ kobot --clock in --notify --headless
$ kobot --clock out --notify --headless

Run the task with crontab

# Weekend and public holidays will be skipped by default
30 09 * * * user kobot --cin -n -x
30 18 * * * user kobot --cout -n -x

# Skip for weekdays planned to take leave for example
30 09 * * * user kobot --cin -n -x -s 2020-09-01,2020-11-11
30 18 * * * user kobot --cout -n -x -s 2020-09-01,2020-11-11

On platforms like Heroku, an add-on called Heroku Scheduler makes running scheduled tasks much easier. Tips: either clock in or clock out task can be scheduled multiple times in case Scheduler misses to run due to Heroku system failures (which might occur very rarely in reality).

Dependency

Kobot is an opinionated tool for which the only purpose is to get the tedious process automated, and therefore Google Chrome is used as the supported browser and Google Gmail is chosen to be the email notification service because both simply just work to get the job done. The webdrivers gem is the only direct dependency and it is by intention to minimize the runtime gem dependency.

Development

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yuan-jiang/kobot. This project is intended tobe a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Kobot project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.