Create new TimeEntries

TimeEntries are the working time sequences spent by a user on any given day.

TimeEntries come in different units and submission modes that should match the timesheet configuration of a given owner on a given day.

About units & duration

Timmi Timesheet supports up to 3 different units when it comes to entering TimeEntries. These are:

• 0: Days In this case, the user does not enter the exact hours he/she started working, but rather the total duration spent as a fraction of a day. For example: "John worked half a day on Monday".
• 1: Hours In this case, the user still does not enter the exact hours, but only the duration spent in hours. For example: "John worked 7h30min yesterday".
• 2: Time In this unit, the user has to enter the actual time he/she started working, as well as the end time. For example: "John started working at 08:00 for 3 hours, thus ending at 11:00".

enum TimeEntryUnit:
{
    Days = 0,
    Hours = 1,
    Time = 2
}

Whichever the unit, the TimeEntry is mainly determined by three properties:

• (int) ownerId: The user it belongs to.
• (date-time) startsAt: The date and time when the user started working. In Days and Hours units, the time part can only be 00:00:00 for "morning" (AM) or 12:00:00 for the "afternoon" (PM).
• (duration) duration: The total time spent by the user from the time he/she started. In all units, this property is serialized as a string compliant with the Timespan formating: d.hh:mm:ss where d is the number of days (can be omitted if equal to zero which is in most cases), hh the number of hours, mm the number of minutes, and ss the number of seconds.

Some examples :

// TIME UNIT
// Case: "John (id: 416) worked between 09:45 and 12:15 on January, 1st 2021."
var timeEntry = {
  "ownerId": 416,
  "startsAt": "2021-01-01 09:45:00",
  "duration: "02:30:00",
  "unit": 2
};

// HOURS UNIT
// Case: "John (id: 416) spent 4h45min working on January, 1st 2021 in the morning"
var timeEntry = {
  "ownerId": 416,
  "startsAt": "2021-01-01 00:00:00",
  "duration: "04:45:00",
  "unit": 1
}

// DAYS UNIT
// Case: "John (id: 416) worked on the afternoon of January, 1st 2021"
var timeEntry = {
  "ownerId": 416,
  "startsAt": "2021-01-01 12:00:00",
  "duration: "12:00:00",
  "unit": 0
}

About submission modes

There are 2 submission modes in Timmi Timesheet:

• Attendance: the user is expected to enter the sequences of work without much detail.
• Activities: the user is expected to enter the time spent on each task / project / whatever.

Therefore, TimeEntries in activities mode have a supplementary property: the set of task / project / cost center / ... the user worked on. These analytical items are called AxisSections. More info here.

The TimeEntry is NOT determined by the axisSection[] it is associated with as a user can change the axisSection[].

{
  "ownerId": 416,
  "startsAt": "2021-01-01 00:00:00",
  "duration: "04:45:00",
  "unit": 1,
  "axisSections": [
    {
      "name": "R&D",
      "axis": {
        "name": "Cost centers"
      }
    },
    {
      "name": "My awesome project",
      "axis": {
        "name": "Projects"
      }
    },
    {
      "name": "Testing",
      "axis": {
        "name": "Tasks"
      }
    }
  ]
}

About time types

Each time-entry can reference a time type via its timeTypeId property.

Time types are a configured working time classification. It is generally used as a way of discriminating different types of working hours regarding compensation:

• Attendance
• Travels
• etc...

Time types can only be used on users that belong to a specific regulation (ie time and attendance policy) mode: timeTrackingMode: typed. Whenever it is not the case, the timeTypeId property should be left null.

Validation rules

Locked timeentries after timesheet submission

A TimeEntry cannot be modified if its startsAt date belongs to an already submitted or approved timesheet.

StartsAt and timezones

The startsAt date-time property must be considered a floating date-time. As such, no UTC offset should be sent when creating or editing a TimeEntry.

Max duration

A TimeEntry cannot have a duration longer than 24h00 (ie one full day).

Cut at midnight

A TimeEntry cannot overlap 2 different days (example startsAt = 18:00:00 and duration = 10:00:00). It should be two distinct TimeEntries cut at 00:00:00.

Mandatory axisSection on activity timesheets

A TimeEntry must have axisSection if the corresponding timesheet is in activity mode, and vice-versa.

Inactive axisSection

A TimeEntry cannot be modified if one of its axisSection is no longer active (active=false).

Incompatible axisSections

A TimeEntry cannot have nested axisSections that does not meet a correct parent-child tree structure.

Fields