Problem/Motivation

Follow-up to #3196825: Quantity types

We need a way to record time spent by users on a given log, including the ability to "clock in/out" on tasks. This is discussed in detail in #2402943: [META] Time tacking and https://farmos.discourse.group/t/additional-log-time-features-any-intere...

Proposed resolution

With the addition of "Quantity types/bundles" (via #3196825: Quantity types) it becomes possible to model these requirements using Quantity entities.

I propose we add a new "Time" Quantity type with 3 additional fields:

  • User - A user reference field to indicate who is clocking time on the Log.
  • Start - A timestamp indicating when the clock was started.
  • End - A timestamp indicating when the clock was stopped.

By referencing a "user" with each Time Quantity separately, it enables multiple people to work on the same Log, and track time spent individually.

Using multiple Time Quantities on a single log also enables people to work on it in separate chunks, or across multiple days. This allows very granular tracking. It also expands upon the single "timestamp" that Logs normally have, allowing them to represent "durations", which wasn't possible before.

The normal "value" field of the Quantity can be used to store the final "duration" of the tracked time, which is ultimately the canonical data needed. The "start" and "end" fields are ONLY necessary for the "clock in/out" feature, and once the user clocks out the duration should be automatically calculated and stored/updated in the "value" field. This enables both use-cases:

  • "I want to be able to manually enter how many hours were spent" (without clocking in/out, and therefore without knowing the actual start/end timestamps).
  • "I want to clock in when I start, and clock out when I stop" (and have the duration calculated for me automatically.

Note that this issue is NOT going to focus at all on the "next steps" surrounding time tracking more generally, including the UI for "clocking in/out" - it simply focuses on the "Time" quantity type, which can serve as the underlying data architecture to support time tracking features in farmOS and Field Kit.

Remaining tasks

TBD

User interface changes

Additional "Price Quantity" option when adding a Quantity to a Log.

API changes

Additional quantity--time JSON:API resource type.

Data model changes

Additional "Time Quantity" type.

CommentFileSizeAuthor
#5 time_demo.png45.94 KBpaul121

Issue fork farm-3196844

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

  • 2.x-time-qty Comparecompare
  • 3196844-time-quantities Comparecompare

Comments

m.stenta created an issue. See original summary.

m.stenta’s picture

Issue summary: View changes

If a user needs to "clock in/out" multiple times on a Log, we can potentially provide two choices:

  1. Create a separate Time Quantity.
  2. Start a new timer, and when it ends, ADD the new duration to the previous total value.

These are perhaps choices for any UI or Field Module that implements the "clock in/out" UI functionality. I just want to mention here that there are different ways that could be represented and still end up with the same results.

m.stenta’s picture

Worth noting: since we won't actually be adding any UI for "clocking in/out" at first, we could consider waiting to add the "start" and "end" fields - since that is the only place they would be used.

So a "Time" quantity would only need the additional "User reference" field to start.

Another idea: maybe we want a dedicated "Notes" field, which would allow more than the "Label" field? This would be a way to comment on what was done during the particular session of clocked time.

paul121 made their first commit to this issue’s fork.

paul121’s picture

Status: Active » Needs review
StatusFileSize
new45.94 KB

Created a time quantity as proposed above.

I started this with just the user field. It wasn't explicitly specified above, but I made this a multi-reference so multiple users could be added to the same time quantity.

Additional commits add the start and end and notes fields. I agree they all seem useful - it was simple to add these so I went ahead! The start/end fields are valuable aside from the clocking in/out UI. IMO we should include them now.

I added a simple template for these fields but I more could be done (see attached). The main issue is that the notes textfield can't be displayed inline, and our current approach to quantity templates/styles is to keep everything on a single line. Maybe the notes could be displayed in a popup/hover if any are specified?

m.stenta’s picture

Status: Needs review » Needs work

I dusted this off and pushed an updated 2.x-time-qty branch to the fork. It takes the branch that @paul121 started 2 years ago and just makes a few small changes (for consideration):

  • Updated the module description to make it clear that this is designed for time tracking.
  • Updated the module dependencies to bring them in line with recent changes in farmOS core to our other quantity type modules.
  • Removed the "Notes" field from time quantities. I suggest we punt on this for now and consider it in a follow-up if there is a need for it in practice. Easier to add to this data model in the future than remove from it, so let's start simple. Perhaps the label field will be sufficient to start.
  • Removed the time quantity template. We refactored some of the way this works since this branch was created, and none of the other core types provide a template anymore (they used to). It might be worth considering it again, but it seems OK without the extra code to start.
  • Hide the start and end time fields in both the form and view displays. In my mind these really should only be used internally for storing the current state of clock-in/out, and ideally wouldn't be exposed to the end-user. They are necessary for UI to be built that allows for clocking-in/out, but exposing them directly in the form/view display UI only makes these quantities more confusing and prone to data issues I think. Ultimately the quantity value is the important piece of information, and will store the total time tracked, which will be calculated by the start/end in cases where the user clocked-in/out. But without that auto-calculation logic in place, I don't think it makes sense to expose these to the user.... not yet at least.

I think overall this probably still needs some minimal UI/UX work before we merge it. We may want to consider hiding the "Measure" field and setting it to time automatically. We did something similar with price quantities, and had some core logic to make that easier, but then removed it here IIRC: #3324839: Refactor price quantity data architecture

We may also want to add the quantity value auto-calculation logic at the data level... so that if a time quantity is saved, and start and end times are provided, the value is filled in automatically. Or we could defer that to UI/UX level logic. Up for debate... and the answer to this might become more clear once we have some UI starting to be built out that uses this data model.

m.stenta’s picture

Version: 2.x-dev » 3.x-dev
m.stenta’s picture

Version: 3.x-dev » 4.x-dev