ConnectCloud Developers

Work entries (HR)

Work entries (Leistungen) are HR's record of worked time that can be billed. They live in the HR module (/api/hr/v1); desk books through them and reads spent time from HR's totals. Every operation is in the HR reference.

Book your own work

createWorkEntry (POST /work-entries, permission tenant:access, an active employee record, else 403 no_employee) books an entry that is a work day and a length (see below), a work kind and billing type (kind, billing), a description and a subject: the thing the work belongs to, e.g. a desk ticket, a forge item, a project or a customer interaction. updateWorkEntry and deleteWorkEntry change your own entries as long as they are not approved. listWorkEntries lists them, getWorkSummary gives the booked, billable and internal minutes of a day and getMyDay the whole day with attendance and what is not booked yet. createWorkEntry takes no Idempotency-Key: a retried create of the same span is refused with 409 overlap, so read the day before booking again.

The kinds and billing types and the tenant's rules are the work settings: getWorkEntrySettings (read) and setWorkEntrySettings (hr:work:manage).

Length, span and work date

An entry needs no clock times. Send one of: minutes (1–1440) with an optional workDate (default today in the tenant's time zone; a day in the future is 400 workDate), a span startedAt + endedAt (the minutes follow from it and a sent minutes is ignored; a workDate must be the start's day, for a span across midnight the end's day is allowed too), or a startedAt with minutes and no end. endedAt without startedAt is 400 startedAt, a start alone without minutes is 400 minutes. The work date is the day the work counts for. Entries without a span never overlap; only two spans of one person do (409 overlap). The response has workDate, minutes (what sums and billing use), durationSeconds (the exact length) and startedAt / endedAt, which may be null. There is no break: nothing is deducted. A list is ordered by work date, then start (entries with a start first), then creation. Without a customer in the request, the customer follows from the subject: the customer of a desk item or, for a forge item or project, the project's workCustomer (internal or a customer, set in forge). Work on a customer-only subject names the customer itself.

Stopwatch

startStopwatch, getStopwatch and stopStopwatch run one stopwatch per person; starting a new one stops the running one. Stopping it (optionally with endedAt and description) books an entry from the start to now or to endedAt; stopping with discard: true books nothing. The exact seconds are kept in durationSeconds. minutes are rounded once when the stopwatch stops, by the tenant's rounding in the work settings (direction up, down or nearest, stepMinutes 1, 5, 10, 15, 30 or 60; default nearest and 1; always returned by getWorkEntrySettings). An explicit endedAt and manual changes are not rounded. A run that rounds to 0 stays as a 0-minute entry; a stopwatch running longer than 24 hours stops only with an explicit endedAt (422 stopwatch_too_long). Starting a new stopwatch keeps the running one as an entry, also when it ran under a minute.

Subjects

An entry points to a subject <module>:<kind>:<id>: desk:item:<id>, forge:item:<id>, crm:activity:<id>, or a project desk:project:<id> / forge:project:<id> (empty for work on the customer only). HR checks it with its module before booking (422 subject_not_bookable, 503 subject_access_unavailable when the module cannot answer – nothing is booked); a call or appointment is the origin (comms:interaction:<id> or comms:calendar:<id>, the caller's own, 400 field origin) – never a subject – and is booked once (409 already_booked). listWorkEntries with subject= lists the entries on one subject. The totals desk and forge show as spent time come from HR through internal routes that API keys cannot call.

Approval

Line managers and deputies approve the entries of their team, hr:work:manage those of everyone: listApprovableWorkEntries (each entry with the person's employeeName), approveWorkEntries and unapproveWorkEntries. listEmployeeWorkEntries and getEmployeeMyDay show a team member's entries, getWorkEntry one entry (the owner's or one the caller decides for; 404 otherwise). An approved or billed entry is not edited; correctWorkEntry books a correction that refers to it.

Rates and billing

Rates (listWorkRates, createWorkRate, updateWorkRate, deleteWorkRate) are per default, customer, contract or project, and need hr:work:billing. With it, getWorkBilling shows the open billing units outside projects, createWorkBatch bills a unit's approved entries in a period and hands the batch to trade, sendWorkBatch sends a requested batch again, withdrawWorkBatch takes back one trade has not taken yet, and listWorkBatches / listProjectWorkBatches list them.

View as Markdown