Contrib.social

Time quantities

Open on Drupal.org →
Created on 5 February 2021, about 4 years ago
Updated 27 February 2023, about 2 years ago

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.

✨ Feature request
Status

Needs work

Version

2.0

Component

Miscellaneous

Created by

🇺🇸United States m.stenta

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment about 2 years ago →
    🇺🇸United States m.stenta

    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.

  • Comment over 1 year ago →
    🇺🇸United States m.stenta
  • Comment 4 days ago →
    🇺🇸United States m.stenta
contrib.social Blog FAQ Discussions
Production build 0.71.5 2024