haunts 0.4.0

How it works

What haunts does depends on the --action parameter.

In its default configuration (if --action is omitted, or equal to sync), the command will try to access a Google Spreatsheet you must own (write access required), specifically it will read a single sheet at time inside the spreadsheet.

Alternatively you can use the report value. In this case it just access the Google Spreadsheet to collect data on its content.

Sheet definition

The referenced sheet must contains a set of columns. Headers names are important but orders matters not. Any additional columns will be ignored.

An example sheet is provided.

The partition in multiple sheets is designed to keep every month in a separate sheet, but this is not strictly checked.

Every sheet should contains following headers:

Date

(date)

The day where the event will be created

Start time

(time string in format HH:MM or empty) - optional column

If provided, the current event will start at given time. This will influence also events defined after this row

Spent

(number or empty)

How long the event will last. Leave empty to create a full-day event

Project

(string)

Project name as it’s named in the config sheet (see below)

Activity

(string)

Summary of the event

Details

(string, optional)

Additional text for the event description

Event id

(string)

Leave this empty. It will be filled with the id of the generated event

Link

(text)

Leave this empty. It will be filled with a link to the event inside Google Calendar

Action

(char)

See below. If empty: it will be filled with an I when an event is created

How events will be filled

Let says you run something like this:

haunts --day=2021-07-08 July

haunts will access the sheet named July in the spreadsheet configured in the .ini file. Only rows where the Date filed will match the --day parameter will be considered (if this param is not provided: the full sheet content is analyzed).

For every rows that match, haunts will:

• Generate a new event, starting from a default time (this can be configured in the .ini). The event will last for Spent hours

• The next event will start where the previous ended

• If the event will be successfully created, an “I” will be placed in the Action column. This will make future executions to ignore the line.

• Other columns will be read or filled as described above.

Actions

Possible values you can find (or put yourself) in the Action column:

• I

  Ignore: execution will just ignore this line

• D

  Delete: execution will clear Action, Event id and Link cells for this row, and delete the related calendar event. So: next execution will likely fill this line again (this is a poor-man-edit)

Reporting feature

Using haunts -a report <SHEET_NAME> will read the source Spreadsheet to collect statistical data.

Both -p and -d parameters are allowed.

The resulting table can be something like the following:

Date        Project      Total
----------  ---------  -------
2022-11-20  Calendar1        2
2022-11-20  Calendar2        1
2022-11-21  Calendar2        5
2022-11-21  Calendar3        3
2022-11-23  Calendar1       10
2022-11-24  Calendar1        8
2022-11-26  Calendar4        9
2022-11-27  Calendar4        8
2022-11-27  Calendar5        1
----------  ---------  -------
                            47

For every calendar and day found in the sheet, it report a total of hours spent.

Full day events are taken into account, and the overwork is also supported by configuring both OVERTIME_FROM and WORKING_HOURS (default is 8).

OK, but why “haunts”?!

An haunt is a monster from Dungeons&Dragons, which is translated in the italian version of the game as “Presenza”.

But “presenza” is the same term used in italian for “participation”, so how we call our worklogs.

And filling worklogs haunt us.

0.4.0 (2022-12-01)

• Added -p parameter, to just act on specific project(s)

• Added --action, and implemented report action (credits to @gcammarota)

• More detailed logging when deleting events with action D

0.3.1 (2022-11-21)

• bugfix: if a row uses an I action, everything there is ignored

• When a project is not found: do not stop haunts but skip the line and report that when execution ends. Closes #14

• Empty lines now supported. Closes #12

• Human readable error message when the sheet is not found. Closes #11

0.3.0 (2022-05-02)

• Fixed: START_TIME default was not used. Closes #4

• New: new action: D

• New: added “Start time” feature. Closes #7

• Fix: reduces number of writes. Closes #6

• Fix: do not fail badly when max number of requests per minutes is reached. See #1

• New: added “–config” for initial env configuration, improved documentation

0.2.1 (2022-02-10)

• Fixed full day criteria

0.2.0 (2021-07-29)

• Added support for full-day event

0.1.0 (2021-07-10)

• Initial release